Big Changes - See commit details

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

diff --git a/Kernel/include/tpl_drv_common.h b/Kernel/include/tpl_drv_common.h
index e1bdd3e..f20539a 100644 (file)
--- a/Kernel/include/tpl_drv_common.h
+++ b/Kernel/include/tpl_drv_common.h
@@ -1,10 +1,35 @@
-/*
- * Acess2
- * - Common Driver Interface
- */
 /**
  * \file tpl_drv_common.h
  * \brief Common Driver Interface Definitions
+ * \author John Hodge (thePowersGang)
+ * 
+ * \section Introduction
+ * There are two ways Acess drivers can communicate with userspace
+ * applications, both are through the VFS. The first is by exposing a
+ * device as a file buffer, the second is by sending commands via the
+ * ioctl() system call.
+ * All drivers in Acess must at least conform to the specifcation in this
+ * file (even if it is just implementing eTplDrv_IOCtl.DRV_IOCTL_TYPE and
+ * returning eTplDrv_Type.DRV_TYPE_NULL, however, doing so is discouraged)
+ * 
+ * \section ioctls Core IOCtl calls
+ * As said, the core Acess driver specifcation defines specific IOCtl calls
+ * that all drivers should implement. The four core IOCtls (defined in
+ * ::eTplDrv_IOCtl) allow another binary (wether it be a user-mode application
+ * or another driver) to tell what type of device a driver provides, the
+ * basic identifcation of the driver (4 character ID and BCD version number)
+ * and be able to use externally standardised calls that may not have
+ * standardised call numbers.
+ * NOTE: All ioctl calls WILL return -1 if the driver ran into an error
+ * of its own fault while executing the call. If the user was at fault
+ * (e.g. by passing a bad buffer) the call will return -2.
+ * 
+ * \section types Driver Types
+ * When the eTplDrv_IOCtl.DRV_IOCTL_TYPE call is made, the driver should
+ * return the relevant entry in the ::eTplDrv_Type enumeration that describes
+ * what sub-specifcation (and hence, what device type) it implements.
+ * These device types are described in their own files, which are liked
+ * from their entries in ::eTplDrv_Type.
  */
 #ifndef _TPL_COMMON_H
 #define _TPL_COMMON_H
@@ -14,16 +39,47 @@
  * \brief Common IOCtl Calls
  */
 enum eTplDrv_IOCtl {
-       /// \brief Driver Type - Return an ::eTplDrv_Type value
+       /**
+        * ioctl(...)
+        * \brief Get driver type
+        * \return The relevant entry from ::eTplDrv_Type
+        */
        DRV_IOCTL_TYPE,
-       /// \brief Get driver identifier - (char *dest[4])
+       
+       /**
+        * ioctl(..., char *dest[4])
+        * \brief Get driver identifier string
+        * \return 0 on no error
+        * 
+        * This call sets the 4-byte array \a dest to the drivers 4-byte
+        * identifier. This identifier must be unique to the driver series.
+        */
        DRV_IOCTL_IDENT,
-       /// \brief Get driver version - (int *ver)
+       
+       /**
+        * ioctl(...)
+        * \brief Get driver version number
+        * \return 24-bit BCD version number (2.2)
+        * 
+        * This call returns the 6-digit (2 major, 2 minor, 2 patch) version number
+        * of the driver.
+        */
        DRV_IOCTL_VERSION,
-       /// \brief Get a IOCtl from a symbolic name
+       
+       /**
+        * ioctl(..., char *name)
+        * \brief Get a IOCtl call ID from a symbolic name
+        * \return ID number of the call, or 0 if not found
+        * 
+        * This call allows user applications to not need to know the ID numbers
+        * of this driver's IOCtl calls by taking a string and returning the
+        * IOCtl call number associated with that method name.
+        */
        DRV_IOCTL_LOOKUP
 };
 
+//! \brief eTplDrv_IOCtl.DRV_IOCTL_LOOKUP names for the core IOCtls
+//! These are the official lookup names of the core calls
 #define        DRV_IOCTLNAMES  "type", "ident", "version", "lookup"
 
 /**
@@ -33,14 +89,14 @@ enum eTplDrv_IOCtl {
 enum eTplDrv_Type {
        DRV_TYPE_NULL,          //!< NULL Type - Custom Interface
        DRV_TYPE_MISC,          //!< Miscelanious Compilant - Supports the core calls
-       DRV_TYPE_TERMINAL,      //!< Terminal
-       DRV_TYPE_VIDEO,         //!< Video - LFB
+       DRV_TYPE_TERMINAL,      //!< Terminal - see tpl_drv_terminal.h
+       DRV_TYPE_VIDEO,         //!< Video - see tpl_drv_video.h
        DRV_TYPE_SOUND,         //!< Audio
-       DRV_TYPE_DISK,          //!< Disk
-       DRV_TYPE_KEYBOARD,      //!< Keyboard
+       DRV_TYPE_DISK,          //!< Disk - see tpl_drv_disk.h
+       DRV_TYPE_KEYBOARD,      //!< Keyboard - see tpl_drv_keyboard.h
        DRV_TYPE_MOUSE,         //!< Mouse
        DRV_TYPE_JOYSTICK,      //!< Joystick / Gamepad
-       DRV_TYPE_NETWORK        //!< Network Device
+       DRV_TYPE_NETWORK        //!< Network Device - see tpl_drv_network.h
 };
 
 #endif