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