com32/include/sys/module.h

   1 /**
   2  * syslinux/module.h
   3  *
   4  * Dynamic ELF modules definitions and services.
   5  */
   6
   7
   8 #ifndef MODULE_H_
   9 #define MODULE_H_
  10
  11 #include <stdio.h>
  12 #include <elf.h>
  13 #include <stdint.h>
  14 #include <setjmp.h>
  15 #include <stdbool.h>
  16 #include <linux/list.h>
  17
  18 /*
  19  * The maximum length of the module file name (including path), stored
  20  * in the struct module descriptor.
  21  */
  22 #define MODULE_NAME_SIZE                256
  23
  24 /*
  25  * Some common information about what kind of modules we're dealing with
  26  */
  27 #define EXEC_MODULE                     0
  28 #define LIB_MODULE                      1
  29
  30 #define MAX_NR_DEPS                     64
  31
  32 /*
  33  * Initialization and finalization function signatures
  34  */
  35
  36 /**
  37  * module_main_t - pointer to an entry routine
  38  *
  39  * The entry routine is present only in executable modules, and represents
  40  * the entry point for the program.
  41  */
  42 typedef int (*module_main_t)(int, char**);
  43
  44 /**
  45  * module_ctor_t - pointer to a constructor or destructor routine
  46  *
  47  * A module may have multiple routines that need to be executed before
  48  * or after the main routine. These are the constructors and
  49  * destructors, respectively.
  50  */
  51 typedef void (*module_ctor_t) (void);
  52
  53 /**
  54  * struct elf_module - structure encapsulating a module loaded in memory.
  55  *
  56  * Each SYSLINUX ELF module must have an associated struct elf_module descriptor
  57  * that keeps track of memory allocations, symbol information, and various other
  58  * resources needed by the module itself or by other modules that depend on it.
  59  *
  60  * There are two types of modules:
  61  *  - regular modules, which are actual memory images of a loaded & linked shared
  62  *  object (ELF file). Memory is reserved for the struct elf_module structure itself
  63  *  and for the object loadable sections read from the file.
  64  *  - shallow modules, which are not associated with an ELF shared object, but contain
  65  *  metainformation about a memory region already present and containing the
  66  *  actual code and data. One particular usage of shallow modules is to access
  67  *  symbol information from the root COM32 module loaded by the SYSLINUX core.
  68  *  As their name suggests, memory is reserved only for the elf_module structure
  69  *  itself and optionally for a usually small memory region containing metainformation
  70  *  (symbol information).
  71  *
  72  *  Module descriptors are related to each other through dependency information. A module
  73  *  can depend on symbols from other modules, and in turn it can provide symbols used
  74  *  by other dependant modules. This relationship can be described as a directed
  75  *  acyclic graph (DAG). The graph is stored using double linked lists of
  76  *  predecessors and successors. There is also a global linked list containing all
  77  *  the modules currently loaded.
  78  */
  79 struct atexit;
  80 struct elf_module {
  81         char                            name[MODULE_NAME_SIZE];                 // The module name
  82
  83         bool                    shallow;        // Whether the module contains any code
  84
  85         struct list_head        required;               // Head of the required modules list
  86         struct list_head        dependants;             // Head of module dependants list
  87         struct list_head        list;           // The list entry in the module list
  88
  89         module_ctor_t           *ctors;         // module constructors
  90         module_ctor_t           *dtors;         // module destructors
  91         module_main_t           main_func; // The main function (for executable modules)
  92
  93         void                            *module_addr; // The module location in the memory
  94         Elf32_Addr                      base_addr;      // The base address of the module
  95         Elf32_Word                      module_size; // The module size in memory
  96
  97         Elf32_Word                      *hash_table;    // The symbol hash table
  98         Elf32_Word                      *ghash_table;   // The GNU style hash table
  99         char                            *str_table;             // The string table
 100         void                            *sym_table;             // The symbol table
 101         void                            *got;                   // The Global Offset Table
 102         Elf32_Dyn                       *dyn_table;             // Dynamic loading information table
 103
 104         Elf32_Word                      strtable_size;  // The size of the string table
 105         Elf32_Word                      syment_size;    // The size of a symbol entry
 106         Elf32_Word                      symtable_size;  // The size of the symbol table
 107
 108
 109         union {
 110                 // Transient - Data available while the module is loading
 111                 struct {
 112                         FILE            *_file;         // The file object of the open file
 113                         Elf32_Off       _cr_offset;     // The current offset in the open file
 114                 } l;
 115
 116                 // Process execution data
 117                 struct {
 118                         jmp_buf         process_exit;   // Exit state
 119                         struct atexit  *atexit_list;    // atexit() chain
 120                 } x;
 121         } u;
 122
 123         // ELF DT_NEEDED entries for this module
 124         int                             nr_needed;
 125         Elf32_Word                      needed[MAX_NR_DEPS];
 126 };
 127
 128 /**
 129  * struct module_dep - structure encapsulating a module dependency need
 130  *
 131  * This structure represents an item in a double linked list of predecessors or
 132  * successors. The item contents is a pointer to the corresponding module descriptor.
 133  */
 134 struct module_dep {
 135         struct list_head        list;           // The list entry in the dependency list
 136
 137         struct elf_module       *module;        // The target module descriptor
 138 };
 139
 140
 141 /**
 142  * Unload all modules that have been loaded since @name.
 143  *
 144  * Returns the struct elf_module * for @name or %NULL if no modules
 145  * have been loaded since @name.
 146  */
 147 extern struct elf_module *unload_modules_since(const char *name);
 148
 149 extern FILE *findpath(char *name);
 150
 151
 152 #ifdef DYNAMIC_MODULE
 153
 154 /*
 155  * This portion is included by dynamic (ELF) module source files.
 156  */
 157
 158 #define MODULE_INIT(fn) static module_init_t __module_init \
 159         __used __attribute__((section(".ctors_modinit")))  = fn
 160
 161 #define MODULE_EXIT(fn) static module_exit_t __module_exit \
 162         __used __attribute__((section(".dtors_modexit")))  = fn
 163
 164 #else
 165
 166 /*
 167  * This portion is included by the core COM32 module.
 168  */
 169
 170 /*
 171  * Accepted values for various ELF header parameters found in an ELF dynamic
 172  * object.
 173  */
 174 #define MODULE_ELF_CLASS                ELFCLASS32              // 32-bit modules
 175 #define MODULE_ELF_CLASS_SIZE           32                      // Size of a word value
 176 #define MODULE_ELF_DATA                 ELFDATA2LSB             // Word endianess
 177 #define MODULE_ELF_VERSION              EV_CURRENT              // Object version
 178 #define MODULE_ELF_TYPE                 ET_DYN                  // Executable type (shared object - .so)
 179 #define MODULE_ELF_MACHINE              EM_386                  // Target architecture
 180
 181 /**
 182  * Names of symbols with special meaning (treated as special cases at linking)
 183  */
 184 #define MODULE_ELF_INIT_PTR             "__module_init_ptr"     // Initialization pointer symbol name
 185 #define MODULE_ELF_EXIT_PTR             "__module_exit_ptr"     // Finalization pointer symbol name
 186 #define MODULE_ELF_MAIN_PTR             "__module_main_ptr" // Entry pointer symbol name
 187
 188 /**
 189  * modules_head - A global linked list containing all the loaded modules.
 190  */
 191 extern struct list_head modules_head;
 192
 193
 194 /**
 195  * for_each_module - iterator loop through the list of loaded modules.
 196  */
 197 #define for_each_module(m)      list_for_each_entry(m, &modules_head, list)
 198
 199 /**
 200  * for_each_module - iterator loop through the list of loaded modules safe against removal.
 201  */
 202 #define for_each_module_safe(m, n)                              \
 203         list_for_each_entry_safe(m, n, &modules_head, list)
 204
 205 /**
 206  * module_current - return the module at the head of the module list.
 207  */
 208 static inline struct elf_module *module_current(void)
 209 {
 210         struct elf_module *head;
 211
 212         head = list_entry((&modules_head)->next, typeof(*head), list);
 213         return head;
 214 }
 215
 216 /**
 217  * modules_init - initialize the module subsystem.
 218  *
 219  * This function must be called before any module operation is to be performed.
 220  */
 221 extern int modules_init(void);
 222
 223
 224 /**
 225  * modules_term - releases all resources pertaining to the module subsystem.
 226  *
 227  * This function should be called after all module operations.
 228  */
 229 extern void modules_term(void);
 230
 231
 232 /**
 233  * module_alloc - reserves space for a new module descriptor.
 234  * @name:       the file name of the module to be loaded.
 235  *
 236  * The function simply allocates a new module descriptor and initializes its fields
 237  * in order to be used by subsequent loading operations.
 238  */
 239 extern struct elf_module *module_alloc(const char *name);
 240
 241
 242 /**
 243  * module_load - loads a regular ELF module into memory.
 244  * @module:     the module descriptor returned by module_alloc.
 245  *
 246  * The function reads the module file, checks whether the file has a
 247  * valid structure, then loads into memory the code and the data and performs
 248  * any symbol relocations. A module dependency is created automatically when the
 249  * relocated symbol is defined in a different module.
 250  *
 251  * The function returns 0 if the operation is completed successfully, and
 252  * a non-zero value if an error occurs. Possible errors include invalid module
 253  * structure, missing symbol definitions (unsatisfied dependencies) and memory
 254  * allocation issues.
 255  */
 256 extern int module_load(struct elf_module *module);
 257
 258
 259 /**
 260  * module_unload - unloads the module from the system.
 261  * @module: the module descriptor structure.
 262  *
 263  * The function checks to see whether the module can be safely
 264  * removed, then it executes any destructors and releases all the
 265  * associated memory. This function can be applied both for standard
 266  * modules and for shallow modules.
 267  *
 268  * A module can be safely removed from the system when no other modules reference
 269  * symbols from it.
 270  */
 271 extern int module_unload(struct elf_module *module);
 272
 273 /**
 274  * _module_unload - unloads the module without running destructors
 275  *
 276  * This function is the same as module_unload(), except that the
 277  * module's destructors are not executed.
 278  */
 279 extern int _module_unload(struct elf_module *module);
 280
 281 /**
 282  * module_unload - unloads the module from the system.
 283  * @module: the module descriptor structure.
 284  *
 285  * This function returns the type of module we're dealing with
 286  * either a library module ( LIB_MODULE ), executable module ( EXEC_MODULE ),
 287  * or an error ( UNKNOWN_MODULE ). The way it checks teh type is by checking to see
 288  * if the module has its main_func set ( in which case it's an executable ). In case
 289  * it doesn't it then checks to see if init_func is set ( in which case it's a
 290  * library module. If this isn't the case either we don't know what it is so bail out
 291  */
 292 extern int get_module_type(struct elf_module *module);
 293
 294 /**
 295  * module_unloadable - checks whether the given module can be unloaded.
 296  * @module: the module descriptor structure
 297  *
 298  * A module can be unloaded from the system when no other modules depend on it,
 299  * that is, no symbols are referenced from it.
 300  */
 301 extern int module_unloadable(struct elf_module *module);
 302
 303 /**
 304  * module_find - searches for a module by its name.
 305  * @name: the name of the module, as it was specified in module_alloc.
 306  *
 307  * The function returns a pointer to the module descriptor, if found, or
 308  * NULL otherwise.
 309  */
 310 extern struct elf_module *module_find(const char *name);
 311
 312 /**
 313  * module_find_symbol - searches for a symbol definition in a given module.
 314  * @name: the name of the symbol to be found.
 315  * @module: the module descriptor structure.
 316  *
 317  * The function searches the module symbol table for a symbol matching exactly
 318  * the name provided. The operation uses the following search algorithms, in this
 319  * order:
 320  *  - If a GNU hash table is present in the module, it is used to find the symbol.
 321  *  - If the symbol cannot be found with the first method (either the hash table
 322  *  is not present or the symbol is not found) and if a regular (SysV) hash table
 323  *  is present, a search is performed on the SysV hash table. If the symbol is not
 324  *  found, NULL is returned.
 325  *  - If the second method cannot be applied, a linear search is performed by
 326  *  inspecting every symbol in the symbol table.
 327  *
 328  *  If the symbol is found, a pointer to its descriptor structure is returned, and
 329  *  NULL otherwise.
 330  */
 331 extern Elf32_Sym *module_find_symbol(const char *name, struct elf_module *module);
 332
 333 /**
 334  * global_find_symbol - searches for a symbol definition in the entire module namespace.
 335  * @name: the name of the symbol to be found.
 336  * @module: an optional (may be NULL) pointer to a module descriptor variable that
 337  * will hold the module where the symbol was found.
 338  *
 339  * The function search for the given symbol name in all the modules currently
 340  * loaded in the system, in the reverse module loading order. That is, the most
 341  * recently loaded module is searched first, followed by the previous one, until
 342  * the first loaded module is reached.
 343  *
 344  * If no module contains the symbol, NULL is returned, otherwise the return value is
 345  * a pointer to the symbol descriptor structure. If the module parameter is not NULL,
 346  * it is filled with the address of the module descriptor where the symbol is defined.
 347  */
 348 extern Elf32_Sym *global_find_symbol(const char *name, struct elf_module **module);
 349
 350 /**
 351  * module_get_absolute - converts an memory address relative to a module base address
 352  * to its absolute value in RAM.
 353  * @addr: the relative address to convert.
 354  * @module: the module whose base address is used for the conversion.
 355  *
 356  * The function returns a pointer to the absolute memory address.
 357  */
 358 static inline void *module_get_absolute(Elf32_Addr addr, struct elf_module *module) {
 359         return (void*)(module->base_addr + addr);
 360 }
 361
 362 /**
 363  * syslinux_current - get the current module process
 364  */
 365 extern struct elf_module *__syslinux_current;
 366 static inline const struct elf_module *syslinux_current(void)
 367 {
 368         return __syslinux_current;
 369 }
 370
 371
 372 #endif // DYNAMIC_MODULE
 373
 374 #endif // MODULE_H_