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 Defines a binary file
  12  *
  13  * This structure defines and maintains the state of a binary during and
  14  * after loading.
  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).
  25  */
  26 typedef struct sBinary
  27 {
  28         struct sBinary  *Next;  //!< Pointer used by the kernel
  29         /**
  30          * \brief True path of the file
  31          * \note Used to uniquely identify the loaded binary to reduce in-memory
  32          *       duplication.
  33          */
  34         char    *TruePath;
  35         /**
  36          * \brief Interpreter used to load the file
  37          * \note This can be either requested by the individual file, or a per-driver option
  38          */
  39         char    *Interpreter;
  40         /**
  41          * \brief Entrypoint of the binary (at requested base);
  42          */
  43         Uint    Entry;
  44         /**
  45          * \brief File's requested load base
  46          */
  47         Uint    Base;
  48         /**
  49          * \brief Number of times this binary has been mapped
  50          */
  51          int    ReferenceCount;
  52         /**
  53          * \brief Number of pages defined in the file
  54          */
  55          int    NumPages;
  56         /**
  57          * \brief Array of pages defined by this binary
  58          * \note Contains \a NumPages entries
  59          */
  60         struct {
  61                 /**
  62                  * \brief Physical address, or file offset
  63                  *
  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)
  66                  */
  67                 tPAddr  Physical;
  68                 tVAddr  Virtual;        //!< Virtual load address
  69                 Uint16  Size;   //!< Number of bytes to load from the file
  70                 Uint16  Flags;  //!< Load Flags
  71         }       Pages[];
  72 }       tBinary;
  73
  74 /**
  75  * \brief Binary type definition
  76  *
  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.
  82  */
  83 typedef struct sBinaryType
  84 {
  85         /**
  86          * \brief Pointer used by the kernel
  87          * \note Should not be touched by the driver (initialise to NULL)
  88          */
  89         struct sBinaryType      *Next;
  90         /**
  91          * \brief Identifying DWord
  92          *
  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.
  95          */
  96         Uint32  Ident;
  97         Uint32  Mask;   //!< Mask value for tBinaryType.Ident
  98         char    *Name;  //!< Name of this executable type (for debug purpouses)
  99         /**
 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
 103          *
 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.
 107          */
 108         tBinary *(*Load)(int FD);
 109
 110         /**
 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.
 116          *
 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
 121          * zero.
 122          */
 123          int    (*Relocate)(void *Base);
 124
 125          /**
 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
 129           *       accomodate this.
 130           */
 131          int    (*GetSymbol)(void *Base, char *Name, Uint *Dest);
 132 } tBinaryType;
 133
 134 /**
 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
 138  *
 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.
 141  */
 142 extern char     *Binary_RegInterp(char *Path);
 143
 144 #endif