X-Git-Url: https://git.ucc.asn.au/?a=blobdiff_plain;f=Kernel%2Finclude%2Fbinary.h;h=c94a1b09a96b0ab5a6ade168c0af3c62468467a5;hb=05c5d7098a054591d75113ecc3503979cc5754c9;hp=e02fc2dc731605829d4338439f7b3fafd81f4d1b;hpb=8bc40333b1401d7616b225945fee53d972c2f418;p=tpg%2Facess2.git diff --git a/Kernel/include/binary.h b/Kernel/include/binary.h index e02fc2dc..c94a1b09 100644 --- a/Kernel/include/binary.h +++ b/Kernel/include/binary.h @@ -1,41 +1,173 @@ -/* +/** + * \file binary.h + * \brief Binary Loader Definitions + * \author John Hodge (thePowersGang) */ #ifndef _BINARY_H #define _BINARY_H // === TYPES === /** - * \struct sBinary + * \brief Representation of a section in a binary file + * + * Tells the binary loader where the page data resides on disk and where + * to load it to (relative to the binary base). Once the data is read, + * the \a Physical field contains the physical address of the page. + */ +typedef struct sBinarySection +{ + Uint64 Offset; //!< File offset of the section + tVAddr Virtual; //!< Virtual load address + size_t FileSize; //!< Number of bytes to load from the file + size_t MemSize; //!< Number of bytes in memory + Uint Flags; //!< Load Flags +} tBinarySection; + +/** + * \brief Flags for ::tBinarySection.Flags + * \name Binary Section Flags + * \{ + */ +//! \brief Read-only +#define BIN_SECTFLAG_RO 0x0001 +//! \brief Executable +#define BIN_SECTFLAG_EXEC 0x0002 +/** + * \} + */ + +/** * \brief Defines a binary file + * + * This structure defines and maintains the state of a binary during and + * after loading. + * Before the binary is loaded into memory (when it has just been returned + * from tBinaryType.Load) the \a Pages array will contain the file offsets + * to the page data in the \a Physical fields (or -1 for uninitialised + * data) and the \a Size fields define how much data is stored in-file + * for the page (to allow partial pages to be loaded from disk) + * Once the binary is loaded (NOTE: Drivers do not need to know about this, + * it is here for information only) the \a Physical fields now contain the + * physical addresses of the pages filled with the data. The \a Virtual + * fields contain the preferred virtual address of the pages (a given + * process may have these pages mapped to a different location). */ -typedef struct sBinary { - struct sBinary *Next; - char *TruePath; - char *Interpreter; - Uint Entry; - Uint Base; - int NumPages; +typedef struct sBinary +{ + struct sBinary *Next; //!< Pointer used by the kernel + + tMount MountID; //!< Mount ID + tInode Inode; //!< Inode (Used for fast reopen) + + /** + * \brief Interpreter used to load the file + * \note This can be either requested by the individual file, or a per-driver option + */ + const char *Interpreter; + /** + * \brief Entrypoint of the binary (at requested base); + */ + tVAddr Entry; + /** + * \brief File's requested load base + */ + tVAddr Base; + /** + * \brief Number of times this binary has been mapped + */ int ReferenceCount; - struct { - Uint Physical; - Uint Virtual; - Uint16 Size, Flags; - } Pages[]; -} tBinary; + /** + * \brief Number of sections defined in the file + */ + int NumSections; + /** + * \brief Array of sections defined by this binary + * \note Contains \a NumSections entries + */ + tBinarySection LoadSections[]; +} tBinary; /** - * \struct sBinaryType + * \brief Binary type definition + * + * This structure is used to define a loader for a specific binary type + * so that the kernel's core binary loader can understand that type. + * The tBinaryType.Relocate and tBinaryType.GetSymbol need only be non-NULL + * if the binary type is to be used for kernel modules, otherwise it will + * only be able to load binaries for user space. */ -typedef struct sBinaryType { +typedef struct sBinaryType +{ + /** + * \brief Pointer used by the kernel + * \note Should not be touched by the driver (initialise to NULL) + */ struct sBinaryType *Next; + /** + * \brief Identifying DWord + * + * If he first 32-bits of the file match this value (when ANDed with + * tBinaryType.Mask), this binary loader will be used to load the file. + */ Uint32 Ident; - Uint32 Mask; - char *Name; + Uint32 Mask; //!< Mask value for tBinaryType.Ident + const char *Name; //!< Name of this executable type (for debug purpouses) + /** + * \brief Read a binary from a file + * \param FD VFS File handle to file to load + * \return Pointer to a ::tBinary that describes how to load the file + * + * This function reads a binary file and returns a ::tBinary pointer + * that tells the core binary loader how to read the data from the file + * and where to map it to. + */ tBinary *(*Load)(int FD); + + /** + * \brief Prepares a mapped binary for execution at this address + * \param Base Binary loaded in memory + * \return Boolean Success + * \note This pointer can be NULL, but then the binary cannot be used + * to load a kernel module. + * + * tBinaryType.Relocate takes a binary that was loaded according to + * tBinaryType.Load and prepares it to run at the address it is + * loaded to, attempting to satisfy any external unresolved symbols + * required, if a symbol cannot be located, the function will return + * zero. + */ int (*Relocate)(void *Base); - int (*GetSymbol)(void *Base, char *Name, Uint *Dest); + + /** + * \brief Gets a symbol's address from a loaded binary + * \note The binary pointed to by \a Base may not have been through + * tBinaryType.Relocate at this time, so the driver should + * accomodate this. + */ + int (*GetSymbol)(void *Base, const char *Name, Uint *Dest); } tBinaryType; +/** + * \brief Registers an interpreter path with the binary loader + * \param Path Path to the requested interpreter (need not be a "true" path) + * \return Pointer to the cached string + * + * Speeds up checking if the intepreter is loaded in the kernel by allowing + * the search to use pointer comparisons instead of string comparisons. + */ extern char *Binary_RegInterp(char *Path); +/** + * \brief Registers a binary type with the kernel's loader + * \param Type Pointer to the loader's type structure + * \return Boolean success + * \note The structure \a Type must be persistant (usually it will be a + * constant global variable) + * + * This function tells the binary loader about a new file type, and gives + * it the functions to read the type into a ::tBinary structure, relocate + * it and to find the value of symbols defined within the binary. + */ +extern int Binary_RegisterType(tBinaryType *Type); + #endif