3 * \brief Binary Loader Definitions
4 * \author John Hodge (thePowersGang)
11 * \brief Representation of a page in a binary file
13 * Tells the binary loader where the page data resides on disk and where
14 * to load it to (relative to the binary base). Once the data is read,
15 * the \a Physical field contains the physical address of the page.
17 typedef struct sBinaryPage
20 * \brief Physical address, or file offset
22 * Physical address of this page or, when the file is not yet
23 * loaded, this is a file offset (or -1 for uninitialised data)
26 tVAddr Virtual; //!< Virtual load address
27 Uint16 Size; //!< Number of bytes to load from the file
28 Uint16 Flags; //!< Load Flags
29 } __attribute__ ((packed)) tBinaryPage;
32 * \brief Flags for ::tBinaryPage.Flags
33 * \name Binary Page Flags
37 #define BIN_PAGEFLAG_RO 0x0001
39 #define BIN_PAGEFLAG_EXEC 0x0002
45 * \brief Defines a binary file
47 * This structure defines and maintains the state of a binary during and
49 * Before the binary is loaded into memory (when it has just been returned
50 * from tBinaryType.Load) the \a Pages array will contain the file offsets
51 * to the page data in the \a Physical fields (or -1 for uninitialised
52 * data) and the \a Size fields define how much data is stored in-file
53 * for the page (to allow partial pages to be loaded from disk)
54 * Once the binary is loaded (NOTE: Drivers do not need to know about this,
55 * it is here for information only) the \a Physical fields now contain the
56 * physical addresses of the pages filled with the data. The \a Virtual
57 * fields contain the preferred virtual address of the pages (a given
58 * process may have these pages mapped to a different location).
60 typedef struct sBinary
62 struct sBinary *Next; //!< Pointer used by the kernel
64 * \brief True path of the file
65 * \note Used to uniquely identify the loaded binary to reduce in-memory
70 * \brief Interpreter used to load the file
71 * \note This can be either requested by the individual file, or a per-driver option
75 * \brief Entrypoint of the binary (at requested base);
79 * \brief File's requested load base
83 * \brief Number of times this binary has been mapped
87 * \brief Number of pages defined in the file
91 * \brief Array of pages defined by this binary
92 * \note Contains \a NumPages entries
98 * \brief Binary type definition
100 * This structure is used to define a loader for a specific binary type
101 * so that the kernel's core binary loader can understand that type.
102 * The tBinaryType.Relocate and tBinaryType.GetSymbol need only be non-NULL
103 * if the binary type is to be used for kernel modules, otherwise it will
104 * only be able to load binaries for user space.
106 typedef struct sBinaryType
109 * \brief Pointer used by the kernel
110 * \note Should not be touched by the driver (initialise to NULL)
112 struct sBinaryType *Next;
114 * \brief Identifying DWord
116 * If he first 32-bits of the file match this value (when ANDed with
117 * tBinaryType.Mask), this binary loader will be used to load the file.
120 Uint32 Mask; //!< Mask value for tBinaryType.Ident
121 char *Name; //!< Name of this executable type (for debug purpouses)
123 * \brief Read a binary from a file
124 * \param FD VFS File handle to file to load
125 * \return Pointer to a ::tBinary that describes how to load the file
127 * This function reads a binary file and returns a ::tBinary pointer
128 * that tells the core binary loader how to read the data from the file
129 * and where to map it to.
131 tBinary *(*Load)(int FD);
134 * \brief Prepares a mapped binary for execution at this address
135 * \param Base Binary loaded in memory
136 * \return Boolean Success
137 * \note This pointer can be NULL, but then the binary cannot be used
138 * to load a kernel module.
140 * tBinaryType.Relocate takes a binary that was loaded according to
141 * tBinaryType.Load and prepares it to run at the address it is
142 * loaded to, attempting to satisfy any external unresolved symbols
143 * required, if a symbol cannot be located, the function will return
146 int (*Relocate)(void *Base);
149 * \brief Gets a symbol's address from a loaded binary
150 * \note The binary pointed to by \a Base may not have been through
151 * tBinaryType.Relocate at this time, so the driver should
154 int (*GetSymbol)(void *Base, char *Name, Uint *Dest);
158 * \brief Registers an interpreter path with the binary loader
159 * \param Path Path to the requested interpreter (need not be a "true" path)
160 * \return Pointer to the cached string
162 * Speeds up checking if the intepreter is loaded in the kernel by allowing
163 * the search to use pointer comparisons instead of string comparisons.
165 extern char *Binary_RegInterp(char *Path);
168 * \brief Registers a binary type with the kernel's loader
169 * \param Type Pointer to the loader's type structure
170 * \return Boolean success
171 * \note The structure \a Type must be persistant (usually it will be a
172 * constant global variable)
174 * This function tells the binary loader about a new file type, and gives
175 * it the functions to read the type into a ::tBinary structure, relocate
176 * it and to find the value of symbols defined within the binary.
178 extern int Binary_RegisterType(tBinaryType *Type);