Kernel - Fixed screen not updating in VT framebuffer mode
[tpg/acess2.git] / KernelLand / 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;         //!< File offset of the section
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;        //!< Mount ID
60         tInode  Inode;          //!< Inode (Used for fast reopen)
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

UCC git Repository :: git.ucc.asn.au