* 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).
* 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).
* 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
# 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))\
{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
MODULE_ERR_NOTNEEDED, //!< Module not needed
MODULE_ERR_MALLOC, //!< Error with malloc/realloc/calloc
- MODULE_ERR_MAX
+ MODULE_ERR_MAX //!< Maximum defined error code
};
/**
* 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
/**
* \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);
git.ucc.asn.au / tpg / acess2.git / commitdiff
UCC git Repository :: git.ucc.asn.au