Kernel/include/modules.h

   1 /*
   2  * AcessOS 2
   3  * - Module Loader
   4  */
   5 /**
   6  * \file modules.h
   7  * \brief Module Handling and Loader Definitions
   8  * \author John Hodge (thePowersGang)
   9  *
  10  * This file serves two pourposes. First it defines the format for native
  11  * Acess2 modules and the functions to create them.
  12  * Second, it defines the structure and register function for new module
  13  * loaders, allowing Acess to understand many different module / driver
  14  * formats.
  15  *
  16  * Modules are defined by including this file in the module's main source
  17  * file and using the ::MODULE_DEFINE macro to create the module header.
  18  *
  19  * To register a new module loader with the kernel, the loader module must
  20  * create and populate an instance of ::tModuleLoader then pass it to
  21  * ::Module_RegisterLoader
  22  */
  23 #ifndef _MODULE_H
  24 #define _MODULE_H
  25
  26 /**
  27  * \brief Module header magic value
  28  */
  29 #define MODULE_MAGIC    ('A'|('M'<<8)|('D'<<16)|('\2'<<24))
  30
  31 /**
  32  * \def MODULE_ARCH_ID
  33  * \brief Architecture ID
  34  */
  35 // IA32 - Architecture 1
  36 #if ARCHDIR == x86
  37 # define MODULE_ARCH_ID 1
  38 // IA64 - Architecture 2
  39 #elif ARCHDIR == x86_64
  40 # define MODULE_ARCH_ID 2
  41 #else
  42 # error "Unknown architecture when determining MODULE_ARCH_ID ('" #ARCHDIR "')"
  43 #endif
  44
  45 /**
  46  * \brief Define a module
  47  * \param _flags        Module Flags
  48  * \param _ver  Module Version
  49  * \param _ident        Unique Module Name
  50  * \param _entry        Module initialiser / entrypoint
  51  * \param _deinit       Module cleanup / unloader
  52  * \param _deps NULL terminated list of this's module's dependencies
  53  *              Contains the identifiers of the required modules.
  54  */
  55 #define MODULE_DEFINE(_flags,_ver,_ident,_entry,_deinit,_deps...) \
  56         const char *EXPAND_CONCAT(_DriverDeps_,_ident)[]={_deps};\
  57         tModule __attribute__ ((section ("KMODULES"),unused))\
  58         EXPAND_CONCAT(_DriverInfo_,_ident)=\
  59         {MODULE_MAGIC,MODULE_ARCH_ID,_flags,_ver,NULL,EXPAND_STR(_ident),\
  60         _entry,_deinit,EXPAND_CONCAT(_DriverDeps_,_ident)}
  61
  62 /**
  63  * \brief Module header
  64  * \note There is no reason for a module to touch this structure beyond
  65  *       using ::MODULE_DEFINE to create it.
  66  */
  67 typedef struct sModule
  68 {
  69         Uint32  Magic;  //!< Identifying magic value (See ::MODULE_MAGIC)
  70         Uint8   Arch;   //!< Achitecture ID (See ::MODULE_ARCH_ID)
  71         Uint8   Flags;  //!< Module Flags
  72         Uint16  Version;        //!< Module Version in Major.Minor 8.8 form
  73         struct sModule  *Next;  //!< Next module in list (not to be touched by the driver)
  74         const char      *Name;  //!< Module Name/Identifier
  75          int    (*Init)(char **Arguments);      //!< Module initialiser / entrypoint
  76         void    (*Deinit)(void);        //!< Cleanup Function
  77         const char      **Dependencies; //!< NULL terminated list of dependencies
  78 } PACKED tModule;
  79
  80 /**
  81  * \brief Return values for tModule.Init
  82  */
  83 enum eModuleErrors
  84 {
  85         MODULE_ERR_OK,  //!< No Error
  86         MODULE_ERR_MISC,        //!< Misc Error
  87         MODULE_ERR_NOTNEEDED,   //!< Module not needed
  88         MODULE_ERR_MALLOC,      //!< Error with malloc/realloc/calloc
  89
  90         MODULE_ERR_BADMODULE,   //!< Bad module (only used by loader)
  91         MODULE_ERR_MAX  //!< Maximum defined error code
  92 };
  93
  94 /**
  95  * \brief Module Loader definition
  96  *
  97  * Allows a module to extend the loader to recognise other module types
  98  * E.g. EDI, UDI, Windows, Linux, ...
  99  */
 100 typedef struct sModuleLoader
 101 {
 102         struct sModuleLoader    *Next;  //!< Kernel Only - Next loader in list
 103         char    *Name;  //!< Friendly name for the loader
 104          int    (*Detector)(void *Base);        //!< Simple detector function
 105          int    (*Loader)(void *Base);  //!< Initialises the module
 106          int    (*Unloader)(void *Base);        //!< Calls module's cleanup
 107 } PACKED tModuleLoader;
 108
 109 /**
 110  * \brief Registers a tModuleLoader with the kernel
 111  * \param Loader        Pointer to loader structure (must be persistent)
 112  * \return Boolean Success
 113  */
 114 extern int      Module_RegisterLoader(tModuleLoader *Loader);
 115
 116 /**
 117  * \brief Initialises (if needed) a named module
 118  * \param Name  Module name to initialise
 119  * \return -1 on not existing, 0 if the module initialised (or if it was already initialised)
 120  */
 121 extern int      Module_EnsureLoaded(const char *Name);
 122
 123 #endif