KernelLand/Kernel/include/api_drv_common.h

   1 /**
   2  * \file api_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 _API_DRV_COMMON_H
  35 #define _API_DRV_COMMON_H
  36
  37 #include <acess/devices.h>
  38
  39 /**
  40  * \brief eTplDrv_IOCtl.DRV_IOCTL_LOOKUP names for the core IOCtls
  41  * These are the official lookup names of the core calls
  42  */
  43 #define DRV_IOCTLNAMES  "type", "ident", "version", "lookup"
  44
  45 /**
  46  * \brief Helper macro for the base IOCtl calls
  47  * \param _type Type number from eTplDrv_Type to return
  48  * \param _ident        String of max 32-characters that identifies this driver
  49  * \param _version      Driver's 8.8.8 BCD version number
  50  * \param _ioctls       Pointer to the IOCtls string array
  51  * \warning If you have DEBUG enabled in the calling file, this function
  52  *          will do LEAVE()s before returning, so make sure that the
  53  *          IOCtl function is ENTER()ed when using debug with this macro
  54  *
  55  * Usage: (Id is the IOCtl call ID)
  56  * \code
  57  * switch(Id)
  58  * {
  59  * BASE_IOCTLS(DRV_TYPE_MISC, "Ident", 0x100, csaIOCtls)
  60  * // Your IOCtls go here, starting at index 4
  61  * }
  62  * \endcode
  63  */
  64 #define BASE_IOCTLS(_type, _ident, _version, _ioctls)   \
  65         case DRV_IOCTL_TYPE:    LEAVE('i', (_type));    return (_type);\
  66         case DRV_IOCTL_IDENT: {\
  67                 int tmp = ModUtil_SetIdent(Data, (_ident));\
  68                 LEAVE('i', tmp);        return tmp;\
  69                 }\
  70         case DRV_IOCTL_VERSION: LEAVE('x', (_version)); return (_version);\
  71         case DRV_IOCTL_LOOKUP:{\
  72                 int tmp = ModUtil_LookupString( _ioctls, (const char*)Data );\
  73                 LEAVE('i', tmp);\
  74                 return tmp;\
  75                 }
  76
  77 #endif