3 * \brief Binary Loader Definitions
4 * \author John Hodge (thePowersGang)
11 * \brief Defines a binary file
13 * This structure defines and maintains the state of a binary during and
15 * Before the binary is loaded into memory (when it has just been returned
16 * from tBinaryType.Load) the \a Pages array will contain the file offsets
17 * to the page data in the \a Physical fields (or -1 for uninitialised
18 * data) and the \a Size fields define how much data is stored in-file
19 * for the page (to allow partial pages to be loaded from disk)
20 * Once the binary is loaded (NOTE: Drivers do not need to know about this,
21 * it is here for information only) the \a Physical fields now contain the
22 * physical addresses of the pages filled with the data. The \a Virtual
23 * fields contain the preferred virtual address of the pages (a given
24 * process may have these pages mapped to a different location).
26 typedef struct sBinary
28 struct sBinary *Next; //!< Pointer used by the kernel
30 * \brief True path of the file
31 * \note Used to uniquely identify the loaded binary to reduce in-memory
36 * \brief Interpreter used to load the file
37 * \note This can be either requested by the individual file, or a per-driver option
41 * \brief Entrypoint of the binary (at requested base);
45 * \brief File's requested load base
49 * \brief Number of times this binary has been mapped
53 * \brief Number of pages defined in the file
57 * \brief Array of pages defined by this binary
58 * \note Contains \a NumPages entries
62 * \brief Physical address, or file offset
64 * Physical address of this page or, when the file is not yet
65 * loaded, this is a file offset (or -1 for uninitialised data)
68 tVAddr Virtual; //!< Virtual load address
69 Uint16 Size; //!< Number of bytes to load from the file
70 Uint16 Flags; //!< Load Flags
75 * \brief Binary type definition
77 * This structure is used to define a loader for a specific binary type
78 * so that the kernel's core binary loader can understand that type.
79 * The tBinaryType.Relocate and tBinaryType.GetSymbol need only be non-NULL
80 * if the binary type is to be used for kernel modules, otherwise it will
81 * only be able to load binaries for user space.
83 typedef struct sBinaryType
86 * \brief Pointer used by the kernel
87 * \note Should not be touched by the driver (initialise to NULL)
89 struct sBinaryType *Next;
91 * \brief Identifying DWord
93 * If he first 32-bits of the file match this value (when ANDed with
94 * tBinaryType.Mask), this binary loader will be used to load the file.
97 Uint32 Mask; //!< Mask value for tBinaryType.Ident
98 char *Name; //!< Name of this executable type (for debug purpouses)
100 * \brief Read a binary from a file
101 * \param FD VFS File handle to file to load
102 * \return Pointer to a ::tBinary that describes how to load the file
104 * This function reads a binary file and returns a ::tBinary pointer
105 * that tells the core binary loader how to read the data from the file
106 * and where to map it to.
108 tBinary *(*Load)(int FD);
111 * \brief Prepares a mapped binary for execution at this address
112 * \param Base Binary loaded in memory
113 * \return Boolean Success
114 * \note This pointer can be NULL, but then the binary cannot be used
115 * to load a kernel module.
117 * tBinaryType.Relocate takes a binary that was loaded according to
118 * tBinaryType.Load and prepares it to run at the address it is
119 * loaded to, attempting to satisfy any external unresolved symbols
120 * required, if a symbol cannot be located, the function will return
123 int (*Relocate)(void *Base);
126 * \brief Gets a symbol's address from a loaded binary
127 * \note The binary pointed to by \a Base may not have been through
128 * tBinaryType.Relocate at this time, so the driver should
131 int (*GetSymbol)(void *Base, char *Name, Uint *Dest);
135 * \brief Registers an interpreter path with the binary loader
136 * \param Path Path to the requested interpreter (need not be a "true" path)
137 * \return Pointer to the cached string
139 * Speeds up checking if the intepreter is loaded in the kernel by allowing
140 * the search to use pointer comparisons instead of string comparisons.
142 extern char *Binary_RegInterp(char *Path);