2 * \file api_drv_common.h
3 * \brief Common Driver Interface Definitions
4 * \author John Hodge (thePowersGang)
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)
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.
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.
34 #ifndef _API_DRV_COMMON_H
35 #define _API_DRV_COMMON_H
37 #include <acess/devices.h>
40 * \brief eTplDrv_IOCtl.DRV_IOCTL_LOOKUP names for the core IOCtls
41 * These are the official lookup names of the core calls
43 #define DRV_IOCTLNAMES "type", "ident", "version", "lookup"
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
55 * Usage: (Id is the IOCtl call ID)
59 * BASE_IOCTLS(DRV_TYPE_MISC, "Ident", 0x100, csaIOCtls)
60 * // Your IOCtls go here, starting at index 4
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;\
70 case DRV_IOCTL_VERSION: LEAVE('x', (_version)); return (_version);\
71 case DRV_IOCTL_LOOKUP:{\
72 int tmp = ModUtil_LookupString( _ioctls, (const char*)Data );\