Kernel/include/binary.h

   1 /**
   2  * \file binary.h
   3  * \brief Binary Loader Definitions
   4  * \author John Hodge (thePowersGang)
   5  */
   6 #ifndef _BINARY_H
   7 #define _BINARY_H
   8
   9 // === TYPES ===
  10 /**
  11  * \brief Representation of a section in a binary file
  12  *
  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.
  16  */
  17 typedef struct sBinarySection
  18 {
  19         Uint64  Offset;
  20         tVAddr  Virtual;        //!< Virtual load address
  21         size_t  FileSize;       //!< Number of bytes to load from the file
  22         size_t  MemSize;        //!< Number of bytes in memory
  23         Uint    Flags;  //!< Load Flags
  24 }       tBinarySection;
  25
  26 /**
  27  * \brief Flags for ::tBinarySection.Flags
  28  * \name Binary Section Flags
  29  * \{
  30  */
  31 //! \brief Read-only
  32 #define BIN_SECTFLAG_RO         0x0001
  33 //! \brief Executable
  34 #define BIN_SECTFLAG_EXEC       0x0002
  35 /**
  36  * \}
  37  */
  38
  39 /**
  40  * \brief Defines a binary file
  41  *
  42  * This structure defines and maintains the state of a binary during and
  43  * after loading.
  44  * Before the binary is loaded into memory (when it has just been returned
  45  * from tBinaryType.Load) the \a Pages array will contain the file offsets
  46  * to the page data in the \a Physical fields (or -1 for uninitialised
  47  * data) and the \a Size fields define how much data is stored in-file
  48  * for the page (to allow partial pages to be loaded from disk)
  49  * Once the binary is loaded (NOTE: Drivers do not need to know about this,
  50  * it is here for information only) the \a Physical fields now contain the
  51  * physical addresses of the pages filled with the data. The \a Virtual
  52  * fields contain the preferred virtual address of the pages (a given
  53  * process may have these pages mapped to a different location).
  54  */
  55 typedef struct sBinary
  56 {
  57         struct sBinary  *Next;  //!< Pointer used by the kernel
  58
  59         tMount  MountID;
  60         tInode  Inode;
  61
  62         /**
  63          * \brief Interpreter used to load the file
  64          * \note This can be either requested by the individual file, or a per-driver option
  65          */
  66         const char      *Interpreter;
  67         /**
  68          * \brief Entrypoint of the binary (at requested base);
  69          */
  70         tVAddr  Entry;
  71         /**
  72          * \brief File's requested load base
  73          */
  74         tVAddr  Base;
  75         /**
  76          * \brief Number of times this binary has been mapped
  77          */
  78          int    ReferenceCount;
  79         /**
  80          * \brief Number of sections defined in the file
  81          */
  82          int    NumSections;
  83         /**
  84          * \brief Array of sections defined by this binary
  85          * \note Contains \a NumSections entries
  86          */
  87         tBinarySection  LoadSections[];
  88 }       tBinary;
  89
  90 /**
  91  * \brief Binary type definition
  92  *
  93  * This structure is used to define a loader for a specific binary type
  94  * so that the kernel's core binary loader can understand that type.
  95  * The tBinaryType.Relocate and tBinaryType.GetSymbol need only be non-NULL
  96  * if the binary type is to be used for kernel modules, otherwise it will
  97  * only be able to load binaries for user space.
  98  */
  99 typedef struct sBinaryType
 100 {
 101         /**
 102          * \brief Pointer used by the kernel
 103          * \note Should not be touched by the driver (initialise to NULL)
 104          */
 105         struct sBinaryType      *Next;
 106         /**
 107          * \brief Identifying DWord
 108          *
 109          * If he first 32-bits of the file match this value (when ANDed with
 110          * tBinaryType.Mask), this binary loader will be used to load the file.
 111          */
 112         Uint32  Ident;
 113         Uint32  Mask;   //!< Mask value for tBinaryType.Ident
 114         const char      *Name;  //!< Name of this executable type (for debug purpouses)
 115         /**
 116          * \brief Read a binary from a file
 117          * \param FD    VFS File handle to file to load
 118          * \return Pointer to a ::tBinary that describes how to load the file
 119          *
 120          * This function reads a binary file and returns a ::tBinary pointer
 121          * that tells the core binary loader how to read the data from the file
 122          * and where to map it to.
 123          */
 124         tBinary *(*Load)(int FD);
 125
 126         /**
 127          * \brief Prepares a mapped binary for execution at this address
 128          * \param Base  Binary loaded in memory
 129          * \return Boolean Success
 130          * \note This pointer can be NULL, but then the binary cannot be used
 131          *       to load a kernel module.
 132          *
 133          * tBinaryType.Relocate takes a binary that was loaded according to
 134          * tBinaryType.Load and prepares it to run at the address it is
 135          * loaded to, attempting to satisfy any external unresolved symbols
 136          * required, if a symbol cannot be located, the function will return
 137          * zero.
 138          */
 139          int    (*Relocate)(void *Base);
 140
 141          /**
 142           * \brief Gets a symbol's address from a loaded binary
 143           * \note The binary pointed to by \a Base may not have been through
 144           *       tBinaryType.Relocate at this time, so the driver should
 145           *       accomodate this.
 146           */
 147          int    (*GetSymbol)(void *Base, const char *Name, Uint *Dest);
 148 } tBinaryType;
 149
 150 /**
 151  * \brief Registers an interpreter path with the binary loader
 152  * \param Path  Path to the requested interpreter (need not be a "true" path)
 153  * \return Pointer to the cached string
 154  *
 155  * Speeds up checking if the intepreter is loaded in the kernel by allowing
 156  * the search to use pointer comparisons instead of string comparisons.
 157  */
 158 extern char     *Binary_RegInterp(char *Path);
 159
 160 /**
 161  * \brief Registers a binary type with the kernel's loader
 162  * \param Type  Pointer to the loader's type structure
 163  * \return Boolean success
 164  * \note The structure \a Type must be persistant (usually it will be a
 165  *       constant global variable)
 166  *
 167  * This function tells the binary loader about a new file type, and gives
 168  * it the functions to read the type into a ::tBinary structure, relocate
 169  * it and to find the value of symbols defined within the binary.
 170  */
 171 extern  int     Binary_RegisterType(tBinaryType *Type);
 172
 173 #endif