Kernel - Fixed screen not updating in VT framebuffer mode
[tpg/acess2.git] / 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 /**
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 First non-reserved IOCtl number for driver extension
82          */
83         DRV_IOCTL_USERMIN = 0x1000,
84 };
85
86 /**
87  * \brief eTplDrv_IOCtl.DRV_IOCTL_LOOKUP names for the core IOCtls
88  * These are the official lookup names of the core calls
89  */
90 #define DRV_IOCTLNAMES  "type", "ident", "version", "lookup"
91
92 /**
93  * \brief Helper macro for the base IOCtl calls
94  * \param _type Type number from eTplDrv_Type to return
95  * \param _ident        String of max 32-characters that identifies this driver
96  * \param _version      Driver's 8.8.8 BCD version number
97  * \param _ioctls       Pointer to the IOCtls string array
98  * \warning If you have DEBUG enabled in the calling file, this function
99  *          will do LEAVE()s before returning, so make sure that the
100  *          IOCtl function is ENTER()ed when using debug with this macro
101  * 
102  * Usage: (Id is the IOCtl call ID)
103  * \code
104  * switch(Id)
105  * {
106  * BASE_IOCTLS(DRV_TYPE_MISC, "Ident", 0x100, csaIOCtls)
107  * // Your IOCtls go here, starting at index 4
108  * }
109  * \endcode
110  */
111 #define BASE_IOCTLS(_type, _ident, _version, _ioctls)   \
112         case DRV_IOCTL_TYPE:    LEAVE('i', (_type));    return (_type);\
113         case DRV_IOCTL_IDENT: {\
114                 int tmp = ModUtil_SetIdent(Data, (_ident));\
115                 LEAVE('i', tmp);        return tmp;\
116                 }\
117         case DRV_IOCTL_VERSION: LEAVE('x', (_version)); return (_version);\
118         case DRV_IOCTL_LOOKUP:{\
119                 int tmp = ModUtil_LookupString( _ioctls, (const char*)Data );\
120                 LEAVE('i', tmp);\
121                 return tmp;\
122                 }
123
124 /**
125  * \enum eTplDrv_Type
126  * \brief Driver Types returned by DRV_IOCTL_TYPE
127  */
128 enum eTplDrv_Type {
129         DRV_TYPE_NULL,          //!< NULL Type - Custom Interface
130         DRV_TYPE_MISC,          //!< Miscelanious Compilant - Supports the core calls
131         DRV_TYPE_TERMINAL,      //!< Terminal - see api_drv_terminal.h
132         DRV_TYPE_VIDEO,         //!< Video - see api_drv_video.h
133         DRV_TYPE_SOUND,         //!< Audio
134         DRV_TYPE_DISK,          //!< Disk - see api_drv_disk.h
135         DRV_TYPE_KEYBOARD,      //!< Keyboard - see api_drv_keyboard.h
136         DRV_TYPE_MOUSE,         //!< Mouse
137         DRV_TYPE_JOYSTICK,      //!< Joystick / Gamepad
138         DRV_TYPE_NETWORK        //!< Network Device - see api_drv_network.h
139 };
140
141 #endif

UCC git Repository :: git.ucc.asn.au