Kernel/include/tpl_drv_common.h

   1 /**
   2  * \file tpl_drv_common.h
   3  * \brief Common Driver Interface Definitions
   4  * \author John Hodge (thePowersGang)
   5  *
   6  * \section Introduction
   7  * There are two ways Acess drivers can communicate with userspace
   8  * applications, both are through the VFS. The first is by exposing a
   9  * device as a file buffer, the second is by sending commands via the
  10  * ioctl() system call.
  11  * All drivers in Acess must at least conform to the specifcation in this
  12  * file (even if it is just implementing eTplDrv_IOCtl.DRV_IOCTL_TYPE and
  13  * returning eTplDrv_Type.DRV_TYPE_NULL, however, doing so is discouraged)
  14  *
  15  * \section ioctls Core IOCtl calls
  16  * As said, the core Acess driver specifcation defines specific IOCtl calls
  17  * that all drivers should implement. The four core IOCtls (defined in
  18  * ::eTplDrv_IOCtl) allow another binary (wether it be a user-mode application
  19  * or another driver) to tell what type of device a driver provides, the
  20  * basic identifcation of the driver (4 character ID and BCD version number)
  21  * and be able to use externally standardised calls that may not have
  22  * standardised call numbers.
  23  * NOTE: All ioctl calls WILL return -1 if the driver ran into an error
  24  * of its own fault while executing the call. If the user was at fault
  25  * (e.g. by passing a bad buffer) the call will return -2.
  26  *
  27  * \section types Driver Types
  28  * When the eTplDrv_IOCtl.DRV_IOCTL_TYPE call is made, the driver should
  29  * return the relevant entry in the ::eTplDrv_Type enumeration that describes
  30  * what sub-specifcation (and hence, what device type) it implements.
  31  * These device types are described in their own files, which are liked
  32  * from their entries in ::eTplDrv_Type.
  33  */
  34 #ifndef _TPL_COMMON_H
  35 #define _TPL_COMMON_H
  36
  37 /**
  38  * \enum eTplDrv_IOCtl
  39  * \brief Common IOCtl Calls
  40  */
  41 enum eTplDrv_IOCtl {
  42         /**
  43          * ioctl(...)
  44          * \brief Get driver type
  45          * \return The relevant entry from ::eTplDrv_Type
  46          */
  47         DRV_IOCTL_TYPE,
  48
  49         /**
  50          * ioctl(..., char *dest[32])
  51          * \brief Get driver identifier string
  52          * \return 0 on no error
  53          *
  54          * This call sets the 32-byte array \a dest to the drivers 31 charater
  55          * identifier. This identifier must be unique to the driver series.
  56          */
  57         DRV_IOCTL_IDENT,
  58
  59         /**
  60          * ioctl(...)
  61          * \brief Get driver version number
  62          * \return 24-bit BCD version number (2.2.2)
  63          *
  64          * This call returns the 6-digit (2 major, 2 minor, 2 patch) version
  65          * number of the driver.
  66          */
  67         DRV_IOCTL_VERSION,
  68
  69         /**
  70          * ioctl(..., char *name)
  71          * \brief Get a IOCtl call ID from a symbolic name
  72          * \return ID number of the call, or 0 if not found
  73          *
  74          * This call allows user applications to not need to know the ID numbers
  75          * of this driver's IOCtl calls by taking a string and returning the
  76          * IOCtl call number associated with that method name.
  77          */
  78         DRV_IOCTL_LOOKUP
  79 };
  80
  81 //! \brief eTplDrv_IOCtl.DRV_IOCTL_LOOKUP names for the core IOCtls
  82 //! These are the official lookup names of the core calls
  83 #define DRV_IOCTLNAMES  "type", "ident", "version", "lookup"
  84
  85 #define BASE_IOCTLS(_type, _ident, _version, _ioctls)   \
  86         case DRV_IOCTL_TYPE:    LEAVE('i', (_type));    return (_type);\
  87         case DRV_IOCTL_IDENT: {\
  88                 int tmp = ModUtil_SetIdent(Data, (_ident));\
  89                 LEAVE('i', tmp);        return tmp;\
  90                 }\
  91         case DRV_IOCTL_VERSION: LEAVE('x', (_version)); return (_version);\
  92         case DRV_IOCTL_LOOKUP:{\
  93                 int tmp = ModUtil_LookupString( (char**)(_ioctls), (char*)Data );\
  94                 LEAVE('i', tmp);\
  95                 return tmp;\
  96                 }
  97
  98 /**
  99  * \enum eTplDrv_Type
 100  * \brief Driver Types returned by DRV_IOCTL_TYPE
 101  */
 102 enum eTplDrv_Type {
 103         DRV_TYPE_NULL,          //!< NULL Type - Custom Interface
 104         DRV_TYPE_MISC,          //!< Miscelanious Compilant - Supports the core calls
 105         DRV_TYPE_TERMINAL,      //!< Terminal - see tpl_drv_terminal.h
 106         DRV_TYPE_VIDEO,         //!< Video - see tpl_drv_video.h
 107         DRV_TYPE_SOUND,         //!< Audio
 108         DRV_TYPE_DISK,          //!< Disk - see tpl_drv_disk.h
 109         DRV_TYPE_KEYBOARD,      //!< Keyboard - see tpl_drv_keyboard.h
 110         DRV_TYPE_MOUSE,         //!< Mouse
 111         DRV_TYPE_JOYSTICK,      //!< Joystick / Gamepad
 112         DRV_TYPE_NETWORK        //!< Network Device - see tpl_drv_network.h
 113 };
 114
 115 #endif