include/tpl_drv_common.h File Reference

Detailed Description

Common Driver Interface Definitions.

Author:: John Hodge (thePowersGang)

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)

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.

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.

Go to the source code of this file.

Defines
#define	DRV_IOCTLNAMES "type", "ident", "version", "lookup"
	eTplDrv_IOCtl.DRV_IOCTL_LOOKUP names for the core IOCtls These are the official lookup names of the core calls
#define	BASE_IOCTLS(_type, _ident, _version, _ioctls)
	Helper macro for the base IOCtl calls.
Enumerations
enum	eTplDrv_IOCtl { DRV_IOCTL_TYPE, DRV_IOCTL_IDENT, DRV_IOCTL_VERSION, DRV_IOCTL_LOOKUP }
	Common IOCtl Calls. More...
enum	eTplDrv_Type { DRV_TYPE_NULL, DRV_TYPE_MISC, DRV_TYPE_TERMINAL, DRV_TYPE_VIDEO, DRV_TYPE_SOUND, DRV_TYPE_DISK, DRV_TYPE_KEYBOARD, DRV_TYPE_MOUSE, DRV_TYPE_JOYSTICK, DRV_TYPE_NETWORK }
	Driver Types returned by DRV_IOCTL_TYPE. More...

Define Documentation

#define BASE_IOCTLS	(	_type,
		_ident,
		_version,
		_ioctls	)

Value:

case DRV_IOCTL_TYPE:    LEAVE('i', (_type));    return (_type);\
    case DRV_IOCTL_IDENT: {\
        int tmp = ModUtil_SetIdent(Data, (_ident));\
        LEAVE('i', tmp);    return tmp;\
        }\
    case DRV_IOCTL_VERSION: LEAVE('x', (_version)); return (_version);\
    case DRV_IOCTL_LOOKUP:{\
        int tmp = ModUtil_LookupString( (char**)(_ioctls), (char*)Data );\
        LEAVE('i', tmp);\
        return tmp;\
        }

Helper macro for the base IOCtl calls.

Parameters:

	_type	Type number from eTplDrv_Type to return
	_ident	String of max 32-characters that identifies this driver
	_version	Driver's 8.8.8 BCD version number
	_ioctls	Pointer to the IOCtls string array

Warning:: If you have DEBUG enabled in the calling file, this function will do LEAVE()s before returning, so make sure that the IOCtl function is ENTER()ed when using debug with this macro

Usage: (Id is the IOCtl call ID)

 switch(Id)
 {
 BASE_IOCTLS(DRV_TYPE_MISC, "Ident", 0x100, csaIOCtls)
 // Your IOCtls go here, starting at index 4
 }

Enumeration Type Documentation

enum eTplDrv_IOCtl

Common IOCtl Calls.

Enumerator:

DRV_IOCTL_TYPE	Get driver type. ioctl(...) Returns: The relevant entry from eTplDrv_Type
DRV_IOCTL_IDENT	Get driver identifier string. ioctl(..., char dest[32]) Returns:* 0 on no error This call sets the 32-byte array dest to the drivers 31 charater identifier. This identifier must be unique to the driver series.
DRV_IOCTL_VERSION	Get driver version number. ioctl(...) Returns: 24-bit BCD version number (2.2.2) This call returns the 6-digit (2 major, 2 minor, 2 patch) version number of the driver.
DRV_IOCTL_LOOKUP	Get a IOCtl call ID from a symbolic name. ioctl(..., char name) Returns:* 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.

enum eTplDrv_Type

Driver Types returned by DRV_IOCTL_TYPE.