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 page 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 sBinaryPage
  18 {
  19         /**
  20          * \brief Physical address, or file offset
  21          *
  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)
  24          */
  25         tPAddr  Physical;
  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;
  30
  31 /**
  32  * \brief Flags for ::tBinaryPage.Flags
  33  * \name Binary Page Flags
  34  * \{
  35  */
  36 //! \brief Read-only
  37 #define BIN_PAGEFLAG_RO         0x0001
  38 //! \brief Executable
  39 #define BIN_PAGEFLAG_EXEC       0x0002
  40 /**
  41  * \}
  42  */
  43
  44 /**
  45  * \brief Defines a binary file
  46  *
  47  * This structure defines and maintains the state of a binary during and
  48  * after loading.
  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).
  59  */
  60 typedef struct sBinary
  61 {
  62         struct sBinary  *Next;  //!< Pointer used by the kernel
  63         /**
  64          * \brief True path of the file
  65          * \note Used to uniquely identify the loaded binary to reduce in-memory
  66          *       duplication.
  67          */
  68         char    *TruePath;
  69         /**
  70          * \brief Interpreter used to load the file
  71          * \note This can be either requested by the individual file, or a per-driver option
  72          */
  73         char    *Interpreter;
  74         /**
  75          * \brief Entrypoint of the binary (at requested base);
  76          */
  77         Uint    Entry;
  78         /**
  79          * \brief File's requested load base
  80          */
  81         Uint    Base;
  82         /**
  83          * \brief Number of times this binary has been mapped
  84          */
  85          int    ReferenceCount;
  86         /**
  87          * \brief Number of pages defined in the file
  88          */
  89          int    NumPages;
  90         /**
  91          * \brief Array of pages defined by this binary
  92          * \note Contains \a NumPages entries
  93          */
  94         tBinaryPage     Pages[];
  95 }       tBinary;
  96
  97 /**
  98  * \brief Binary type definition
  99  *
 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.
 105  */
 106 typedef struct sBinaryType
 107 {
 108         /**
 109          * \brief Pointer used by the kernel
 110          * \note Should not be touched by the driver (initialise to NULL)
 111          */
 112         struct sBinaryType      *Next;
 113         /**
 114          * \brief Identifying DWord
 115          *
 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.
 118          */
 119         Uint32  Ident;
 120         Uint32  Mask;   //!< Mask value for tBinaryType.Ident
 121         char    *Name;  //!< Name of this executable type (for debug purpouses)
 122         /**
 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
 126          *
 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.
 130          */
 131         tBinary *(*Load)(int FD);
 132
 133         /**
 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.
 139          *
 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
 144          * zero.
 145          */
 146          int    (*Relocate)(void *Base);
 147
 148          /**
 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
 152           *       accomodate this.
 153           */
 154          int    (*GetSymbol)(void *Base, char *Name, Uint *Dest);
 155 } tBinaryType;
 156
 157 /**
 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
 161  *
 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.
 164  */
 165 extern char     *Binary_RegInterp(char *Path);
 166
 167 /**
 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)
 173  *
 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.
 177  */
 178 extern  int     Binary_RegisterType(tBinaryType *Type);
 179
 180 #endif