From 3a0833fe87ee8735ee5dc99375ee55c656a2ac67 Mon Sep 17 00:00:00 2001 From: John Hodge Date: Sat, 13 Mar 2010 22:56:14 +0800 Subject: [PATCH] Work on documentation --- Kernel/Doxyfile.api | 1 + Kernel/include/apidoc_mainpage.h | 64 ++++++++++++++++------------ Kernel/include/modules.h | 72 ++++++++++++++++++++++++++------ 3 files changed, 98 insertions(+), 39 deletions(-) diff --git a/Kernel/Doxyfile.api b/Kernel/Doxyfile.api index 7957e58d..319804c2 100644 --- a/Kernel/Doxyfile.api +++ b/Kernel/Doxyfile.api @@ -568,6 +568,7 @@ WARN_LOGFILE = INPUT = include/apidoc_mainpage.h \ include/binary.h \ + include/modules.h \ include/vfs.h include/vfs_ext.h \ include/fs_devfs.h \ include/iocache.h include/ diff --git a/Kernel/include/apidoc_mainpage.h b/Kernel/include/apidoc_mainpage.h index 98a5e40a..29a6c007 100644 --- a/Kernel/include/apidoc_mainpage.h +++ b/Kernel/include/apidoc_mainpage.h @@ -11,36 +11,39 @@ * The documentation covers filesystem drivers, binary formats and the * various device driver interface standards. * - * \section VFS - * The core of Acess is the VFS, or Virtual File System. The VFS abstracts - * away from the user the differences between different filesystems, - * network protocols and types of hardware. - * The core of the VFS is the concept of a VFS Node (represented by the - * ::tVFS_Node type). A node defines a file (either a normal file, directory - * or some device abstraction), it's attributes (size, flags, timestamps) - * and the functions used to access and modify it. - * - * \subsection filesystems Filesystem Drivers - * Acess filesystems register themselves with the VFS by calling - * ::VFS_AddDriver with a ::tVFS_Driver structure that defines the driver's - * name, flags and mount function. - * Filesystem drivers take the - * - * \section binfmt Binary Formats - * See binary.h - * - * \section drivers Device Drivers + * \section index "Sections" + * - \ref modules.h "Module Definitions" + * - Describes how a module is defined in Acess + * - \ref binary.h "Binary Formats" + * - Explains how to register a new binary format with the kernel + * - \ref vfs.h "VFS - The Virtual File System" + * - The VFS is the core of Acess's driver architecture + * - \ref drivers "Device Drivers" + * - Describes how drivers should use the VFS to expose themselves to the + * user. + * - Drivers for specific types of hardware must behave in the specific + * way described here. + * + * \page drivers Device Drivers + * + * \section toc Contents + * - \ref drvintro "Introduction" + * - \ref drv_misc "Miscelanious Devices" + * - \ref drv_video "Video Drivers" + * + * \section drvintro Introduction * All Acess2 device drivers communicate with user-level (and other parts * of the greater kernel) via the VFS. They register themselves in a similar * way to how filesystem drivers do, however instead of registering with * the VFS core, they register with a special filesystem driver called the - * DevFS (fs_devfs.h). DevFS exports the ::DevFS_AddDevice function that - * takes a ::tDevFS_Driver structure as an agument that defines the - * driver's name and the VFS node of it's root. This root is used to - * provide the user access to the driver's function via IOCtl calls and - * by Read/Write calls. Drivers are also able to expose a readonly buffer - * by using ProcDev, usually to provide state information (such as usage - * statistics and other misc information) + * \ref fs_devfs.h "Device Filesystem" (devfs). The DevFS provides the + * ::DevFS_AddDevice function that takes a ::tDevFS_Driver structure as + * an agument. This structure specifies the driver's name and its root + * VFS node. This node is used to provide the user access to the + * driver's functions via IOCtl calls and Reading or Writing to the driver + * file. Drivers are also able to expose a readonly buffer by using + * \ref fs_proc.h ProcDev, usually to provide state information or device + * capabilities for the the user. * * The device driver interfaces are all based on the core specifcation * in tpl_drv_common.h (Common Device Driver definitions). @@ -50,6 +53,15 @@ * IOCtl calls and/or files (where allowed by the type specifcation) to * their device's VFS layout. * + * \subsection drv_misc Miscelanious Devices + * If a device type does not have a specifcation for it, the driver can + * identify itself as a miscelanious device by returning DRV_TYPE_MISC + * from \ref DRV_IOCTL_TYPE. + * A misc device must at least implement the IOCtl calls defined in the + * \ref tpl_drv_common.h "Common Device Driver definitions", allowing it + * to be identified easily by the user and for interfacing programs to + * utilise the DRV_IOCTL_LOOKUP call. + * * \subsection drv_video Video Devices * Video drivers are based on a framebuffer model (unless in 3D mode, * which is not yet fully standardised, so should be ignored). diff --git a/Kernel/include/modules.h b/Kernel/include/modules.h index 8dc720a3..8862112c 100644 --- 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); -- 2.20.1