Work on documentation

[tpg/acess2.git] / Kernel / include / modules.h

diff --git a/Kernel/include/modules.h b/Kernel/include/modules.h
index 8dc720a..8862112 100644 (file)
--- a/Kernel/include/modules.h
+++ b/Kernel/include/modules.h
@@ -2,11 +2,36 @@
  * AcessOS 2
  * - Module Loader
  */
+/**
+ * \file modules.h
+ * \brief Module Handling and Loader Definitions
+ * \author John Hodge (thePowersGang)
+ * 
+ * This file serves two pourposes. First it defines the format for native
+ * Acess2 modules and the functions to create them.
+ * Second, it defines the structure and register function for new module
+ * loaders, allowing Acess to understand many different module / driver
+ * formats.
+ * 
+ * Modules are defined by including this file in the module's main source
+ * file and using the ::MODULE_DEFINE macro to create the module header.
+ * 
+ * To register a new module loader with the kernel, the loader module must
+ * create and populate an instance of ::tModuleLoader then pass it to
+ * ::Module_RegisterLoader
+ */
 #ifndef _MODULE_H
 #define _MODULE_H
 
+/**
+ * \brief Module header magic value
+ */
 #define MODULE_MAGIC   ('A'|('M'<<8)|('D'<<16)|('\2'<<24))
 
+/**
+ * \def MODULE_ARCH_ID
+ * \brief Architecture ID
+ */
 // IA32 - Architecture 1
 #if ARCHDIR == x86
 # define MODULE_ARCH_ID        1
@@ -17,6 +42,16 @@
 # error "Unknown architecture when determining MODULE_ARCH_ID ('" #ARCHDIR "')"
 #endif
 
+/**
+ * \brief Define a module
+ * \param _flags       Module Flags
+ * \param _ver Module Version
+ * \param _ident       Unique Module Name
+ * \param _entry       Module initialiser / entrypoint
+ * \param _deinit      Module cleanup / unloader
+ * \param _deps        NULL terminated list of this's module's dependencies
+ *                     Contains the identifiers of the required modules.
+ */
 #define MODULE_DEFINE(_flags,_ver,_ident,_entry,_deinit,_deps...) \
        char *EXPAND_CONCAT(_DriverDeps_,_ident)[]={_deps};\
        tModule __attribute__ ((section ("KMODULES"),unused))\
@@ -24,18 +59,27 @@
        {MODULE_MAGIC,MODULE_ARCH_ID,_flags,_ver,NULL,EXPAND_STR(_ident),\
        _entry,_deinit,EXPAND_CONCAT(_DriverDeps_,_ident)}
 
-typedef struct sModule {
-       Uint32  Magic;
-       Uint8   Arch;
-       Uint8   Flags;
-       Uint16  Version;
-       struct sModule  *Next;
-       char    *Name;
-        int    (*Init)(char **Arguments);
-       void    (*Deinit)();
-       char    **Dependencies; // NULL Terminated List
-} __attribute__((packed)) tModule;
+/**
+ * \brief Module header
+ * \note There is no reason for a module to touch this structure beyond
+ *       using ::MODULE_DEFINE to create it.
+ */
+typedef struct sModule 
+{
+       Uint32  Magic;  //!< Identifying magic value (See ::MODULE_MAGIC)
+       Uint8   Arch;   //!< Achitecture ID (See ::MODULE_ARCH_ID)
+       Uint8   Flags;  //!< Module Flags
+       Uint16  Version;        //!< Module Version in Major.Minor 8.8 form
+       struct sModule  *Next;  //!< Next module in list (not to be touched by the driver)
+       char    *Name;  //!< Module Name/Identifier
+        int    (*Init)(char **Arguments);      //!< Module initialiser / entrypoint
+       void    (*Deinit)();    //!< Cleanup Function
+       char    **Dependencies; //!< NULL terminated list of dependencies
+} PACKED tModule;
 
+/**
+ * \brief Return values for tModule.Init
+ */
 enum eModuleErrors
 {
        MODULE_ERR_OK,  //!< No Error
@@ -43,7 +87,7 @@ enum eModuleErrors
        MODULE_ERR_NOTNEEDED,   //!< Module not needed
        MODULE_ERR_MALLOC,      //!< Error with malloc/realloc/calloc
        
-       MODULE_ERR_MAX
+       MODULE_ERR_MAX  //!< Maximum defined error code
 };
 
 /**
@@ -52,7 +96,8 @@ enum eModuleErrors
  * Allows a module to extend the loader to recognise other module types
  * E.g. EDI, UDI, Windows, Linux, ...
  */
-typedef struct sModuleLoader {
+typedef struct sModuleLoader
+{
        struct sModuleLoader    *Next;  //!< Kernel Only - Next loader in list
        char    *Name;  //!< Friendly name for the loader
         int    (*Detector)(void *Base);        //!< Simple detector function
@@ -63,6 +108,7 @@ typedef struct sModuleLoader {
 /**
  * \brief Registers a tModuleLoader with the kernel
  * \param Loader       Pointer to loader structure (must be persistent)
+ * \return Boolean Success
  */
 extern int     Module_RegisterLoader(tModuleLoader *Loader);