KernelLand/Kernel/include/apidoc_mainpage.h

   1 /**
   2  * \file apidoc_mainpage.h
   3  * \brief API Documentation Home Page
   4  * \author John Hodge (thePowersGang)
   5  *
   6  * \mainpage Acess 2 Kernel API Documentation
   7  *
   8  * \section intro Introduction
   9  * These documents attempt to describe the standard Acess 2 (and hopefully
  10  * future versions) Kernel mode API.
  11  * The documentation covers filesystem drivers, binary formats and the
  12  * various device driver interface standards.
  13  *
  14  * \section index       "Sections"
  15  * - \ref modules.h "Module Definitions"
  16  *  - Describes how a module is defined in Acess
  17  * - \ref binary.h      "Binary Formats"
  18  *  - Explains how to register a new binary format with the kernel
  19  * - \ref vfs.h "VFS - The Virtual File System"
  20  *  - The VFS is the core of Acess's driver architecture
  21  * - \ref drivers       "Device Drivers"
  22  *  - Describes how drivers should use the VFS to expose themselves to the
  23  *    user.
  24  *  - Drivers for specific types of hardware must behave in the specific
  25  *    way described here.
  26  *
  27  * \page drivers Device Drivers
  28  *
  29  * \section toc Contents
  30  * - \ref drvintro      "Introduction"
  31  * - \ref drv_misc "Miscelanious Devices"
  32  * - \ref drv_video     "Video Drivers"
  33  * - \ref drv_disk      "Storage Devices"
  34  *
  35  * \section drvintro    Introduction
  36  * All Acess2 device drivers communicate with user-level (and other parts
  37  * of the greater kernel) via the VFS. They register themselves in a similar
  38  * way to how filesystem drivers do, however instead of registering with
  39  * the VFS core, they register with a special filesystem driver called the
  40  * \ref fs_devfs.h "Device Filesystem" (devfs). The DevFS provides the
  41  * ::DevFS_AddDevice function that takes a ::tDevFS_Driver structure as
  42  * an agument. This structure specifies the driver's name and its root
  43  * VFS node. This node is used to provide the user access to the
  44  * driver's functions via IOCtl calls and Reading or Writing to the driver
  45  * file. Drivers are also able to expose a readonly buffer by using
  46  * \ref fs_sysfs.h "ProcDev", usually to provide state information or device
  47  * capabilities for the the user.
  48  *
  49  * The device driver interfaces are all based on the core specifcation
  50  * in api_drv_common.h (Common Device Driver definitions).
  51  * The following subsections define the various specific types of driver
  52  * interfaces. These definitions only define the bare minimum of what the
  53  * driver must implement, if the driver author so wants to, they can add
  54  * IOCtl calls and/or files (where allowed by the type specifcation) to
  55  * their device's VFS layout.
  56  *
  57  * \subsection drv_misc Miscelanious Devices
  58  * If a device type does not have a specifcation for it, the driver can
  59  * identify itself as a miscelanious device by returning DRV_TYPE_MISC
  60  * from \ref DRV_IOCTL_TYPE.
  61  * A misc device must at least implement the IOCtl calls defined in the
  62  * \ref api_drv_common.h "Common Device Driver definitions", allowing it
  63  * to be identified easily by the user and for interfacing programs to
  64  * utilise the DRV_IOCTL_LOOKUP call.
  65  *
  66  * \subsection drv_video Video Devices
  67  * Video drivers are based on a framebuffer model (unless in 3D mode,
  68  * which is not yet fully standardised, so should be ignored).
  69  * The driver will contain only one VFS node, that exposes the video
  70  * framebuffer (this may not be the true framebuffer, to allow for double-buffering)
  71  * to the user. See the full documentation in api_drv_video.h for the
  72  * complete specifcation.
  73  *
  74  * \subsection drv_disk Disk/Storage Devices
  75  * Storage devices present themselves as a linear collection of bytes.
  76  * Reads and writes to the device need not be aligned to the stated block
  77  * size, but it is suggested that users of a storage device file align
  78  * their accesses to block boundaries.
  79  * The functions DrvUtil_ReadBlock and DrvUtil_WriteBlock are provided
  80  * to storage drivers to assist in handling non-alinged reads and writes.
  81  *
  82  * \see api_drv_common.h Common Spec.
  83  * \see api_drv_video.h Video Device Spec.
  84  * \see api_drv_keyboard.h Keyboard Device Spec.
  85  * \see api_drv_disk.h Disk/Storage Device Spec.
  86  * \see api_drv_network.h Network Device Spec.
  87  * \see api_drv_terminal.h Virtual Terminal Spec.
  88  */