Driver Signatures
Detailed Description
These macros will define the entry point signatures for interrupt handlers; driver initialization and shutdown; device open/close; etc.
There are two versions of each macro for a given Driver Entry Point. The first version is used to define a function and its implementation in the driver.c file, e.g. OS_DEV_INIT().
The second form is used whenever a forward declaration (prototype) is needed. It has the letters _DCL
appended to the name of the defintion function, and takes only the first two arguments (driver_name and function_name). These are not otherwise mentioned in this documenation.
There is a third form used when a reference to a function is required, for instance when passing the routine as a pointer to a function. It has the letters _REF
appended to it, and takes only the first two arguments (driver_name and function_name). These functions are not otherwise mentioned in this documentation.
(Note that these two extra forms are required because of the possibility/likelihood of having a 'wrapper function' which invokes the generic function with expected arguments. An alternative would be to have a generic function which isn't able to get at any arguments directly, but would be equipped with macros which could get at information passed in.
Example:
(in a header file)
(in an implementation file)
These macros will define the entry point signatures for interrupt handlers; driver initialization and shutdown; device open/close; etc. They are to be used whenever the Kernel will call into the Driver. They are not appropriate for driver calls to other routines in the driver.
There are three versions of each macro for a given Driver Entry Point. The first version is used to define a function and its implementation in the driver.c file, e.g. OS_DEV_INIT().
The second form is used whenever a forward declaration (prototype) is needed. It has the letters _DCL
appended to the name of the definition function. These are not otherwise mentioned in this documenation.
There is a third form used when a reference to a function is required, for instance when passing the routine as a pointer to a function. It has the letters _REF
appended to the name of the definition function (e.g. DEV_IOCTL_REF).
Note that these two extra forms are required because of the possibility of having an invisible 'wrapper function' created by the os-specific header file which would need to be invoked by the operating system, and which in turn would invoke the generic function.
Example:
(in a header file)
(in an implementation file)
Define Documentation
#define OS_DEV_CLOSE |
( |
function_name |
|
) |
|
Define a function which will close the device - opposite of OS_DEV_OPEN()
- Parameters:
-
| function_name | The name of the driver close() function |
- Returns:
- A call to os_dev_close_return()
#define OS_DEV_CLOSE |
( |
function_name |
|
) |
static int function_name(struct inode* inode_p_, struct file* file_p_) |
Define a function which will close the device - opposite of OS_DEV_OPEN()
- Parameters:
-
| function_name | The name of the driver close() function |
- Returns:
- A call to os_dev_close_return()
#define OS_DEV_CLOSE_DCL |
( |
function_name |
|
) |
OS_DEV_CLOSE(function_name); |
Declare prototype for an close() function
- Parameters:
-
| function_name | The name of the driver close() function. |
#define OS_DEV_CLOSE_REF |
( |
function_name |
|
) |
function_name |
#define OS_DEV_INIT |
( |
function_name |
|
) |
|
Define a function which will handle device initialization
This is tne driver initialization routine. This is normally where the part would be initialized; queues, locks, interrupts handlers defined; long-term dynamic memory allocated for driver use; etc.
- Parameters:
-
| function_name | The name of the portable initialization function. |
- Returns:
- A call to os_dev_init_return()
#define OS_DEV_INIT |
( |
function_name |
|
) |
|
Value:module_init(function_name); \
static int __init function_name (void)
Define a function which will handle device initialization
This is tne driver initialization routine. This is normally where the part would be initialized; queues, locks, interrupts handlers defined; long-term dynamic memory allocated for driver use; etc.
- Parameters:
-
| function_name | The name of the portable initialization function. |
- Returns:
- A call to os_dev_init_return()
#define OS_DEV_INIT_DCL |
( |
function_name |
|
) |
static int __init function_name (void); |
Make declaration for driver init function.
- Parameters:
-
#define OS_DEV_INIT_REF |
( |
function_name |
|
) |
function_name |
Generate a function reference to the driver's init function.
- Parameters:
-
- Returns:
- A function pointer.
#define OS_DEV_IOCTL |
( |
function_name |
|
) |
|
Define a function which will handle a user's ioctl() request
- Parameters:
-
| function_name | The name of the driver ioctl() function |
- Returns:
- A call to os_dev_ioctl_return()
#define OS_DEV_IOCTL |
( |
function_name |
|
) |
|
Value:static int function_name(struct file *file_p_, \
unsigned int cmd_, unsigned long data_)
Define a function which will handle a user's ioctl() request
- Parameters:
-
| function_name | The name of the driver ioctl() function |
- Returns:
- A call to os_dev_ioctl_return()
#define OS_DEV_IOCTL_DCL |
( |
function_name |
|
) |
OS_DEV_IOCTL(function_name); |
#define OS_DEV_IOCTL_REF |
( |
function_name |
|
) |
function_name |
#define OS_DEV_ISR |
( |
function_name |
|
) |
|
Define a function which will handle an interrupt
No arguments are available to the generic function. It must not invoke any OS functions which are illegal in a ISR. It gets no parameters, and must have a call to os_dev_isr_return() instead of any/all return statements.
Example:
- Parameters:
-
| function_name | The name of the driver ISR function |
- Returns:
- A call to os_dev_isr_return()
#define OS_DEV_ISR |
( |
function_name |
|
) |
static irqreturn_t function_name(int N1_, void* N2_) |
Define a function which will handle an interrupt
No arguments are available to the generic function. It must not invoke any OS functions which are illegal in a ISR. It gets no parameters, and must have a call to os_dev_isr_return() instead of any/all return statements.
Example:
- Parameters:
-
| function_name | The name of the driver ISR function |
- Returns:
- A call to os_dev_isr_return()
#define OS_DEV_ISR_DCL |
( |
function_name |
|
) |
OS_DEV_ISR(function_name); |
Declare prototype for an ISR function.
- Parameters:
-
| function_name | The name of the driver ISR function. |
#define OS_DEV_ISR_REF |
( |
function_name |
|
) |
function_name |
Generate a function reference to the driver's interrupt service routine
- Parameters:
-
- Returns:
- A function pointer.
Referenced by rng_setup_interrupt_handling().
#define OS_DEV_MMAP |
( |
function_name |
|
) |
|
Define a function which will handle a user's mmap() request
The mmap() function requests the driver to map some memory into user space.
- Parameters:
-
| function_name | The name of the driver mmap() function |
- Returns:
- A call to os_dev_mmap_return()
#define OS_DEV_MMAP |
( |
function_name |
|
) |
int function_name(struct file* file_p_, struct vm_area_struct* vma_) |
Define a function which will handle a user's mmap() request
- Parameters:
-
| function_name | The name of the driver mmap() function |
- Returns:
- A call to os_dev_ioctl_return()
#define OS_DEV_OPEN |
( |
function_name |
|
) |
|
Define a function which will open the device for a user.
- Parameters:
-
| function_name | The name of the driver open() function |
- Returns:
- A call to os_dev_open_return()
#define OS_DEV_OPEN |
( |
function_name |
|
) |
static int function_name(struct inode* inode_p_, struct file* file_p_) |
Define a function which will open the device for a user.
- Parameters:
-
| function_name | The name of the driver open() function |
- Returns:
- A call to os_dev_open_return()
#define OS_DEV_OPEN_DCL |
( |
function_name |
|
) |
OS_DEV_OPEN(function_name); |
Declare prototype for an open() function.
- Parameters:
-
#define OS_DEV_OPEN_REF |
( |
function_name |
|
) |
function_name |
#define OS_DEV_READ |
( |
function_name |
|
) |
|
Define a function which will handle a user's read() request
- Parameters:
-
| function_name | The name of the driver read() function |
- Returns:
- A call to os_dev_read_return()
#define OS_DEV_READ_DCL |
( |
function_name |
|
) |
OS_DEV_READ(function_name); |
Declare prototype for an read() function.
- Parameters:
-
| function_name | The name of the driver read function. |
#define OS_DEV_READ_REF |
( |
function_name |
|
) |
function_name |
Generate a function reference to the driver's read() routine
- Parameters:
-
- Returns:
- A function pointer.
#define OS_DEV_SHUTDOWN |
( |
function_name |
|
) |
|
Define a function which will handle device shutdown
This is the reverse of the OS_DEV_INIT() routine.
- Parameters:
-
| function_name | The name of the portable driver shutdown routine. |
- Returns:
- A call to os_dev_shutdown_return()
#define OS_DEV_SHUTDOWN |
( |
function_name |
|
) |
|
Value:module_exit(function_name); \
static void function_name(void)
Define a function which will handle device shutdown
This is the inverse of the OS_DEV_INIT() routine.
- Parameters:
-
| function_name | The name of the portable driver shutdown routine. |
- Returns:
- A call to os_dev_shutdown_return()
#define OS_DEV_SHUTDOWN_DCL |
( |
function_name |
|
) |
static void function_name(void); |
Generate a function reference to the driver's shutdown function.
- Parameters:
-
| function_name | Name of the OS_DEV_HUSTDOWN() function. |
- Returns:
- A function pointer.
#define OS_DEV_SHUTDOWN_REF |
( |
function_name |
|
) |
function_name |
Generate a reference to driver's shutdown function
- Parameters:
-
| function_name | Name of the OS_DEV_HUSTDOWN() function. |
#define OS_DEV_TASK |
( |
function_name |
|
) |
|
Define a function which will operate as a background task / bottom half.
The function implementation must be structured in the following manner:
OS_DEV_TASK(widget_task)
{
OS_DEV_TASK_SETUP(widget_task);
while OS_DEV_TASK_CONDITION(widget_task) }
};
}
- Parameters:
-
| function_name | The name of this background task function |
#define OS_DEV_TASK |
( |
function_name |
|
) |
static void function_name(unsigned long data_) |
Define a function which will operate as a background task / bottom half.
Tasklet stuff isn't strictly limited to 'Device drivers', but leave it this namespace anyway.
- Parameters:
-
| function_name | The name of this background task function |
- Returns:
- A call to os_dev_task_return()
#define OS_DEV_TASK_DCL |
( |
function_name |
|
) |
|
Value:OS_DEV_TASK(function_name); \
DECLARE_TASKLET(function_name ## let, function_name, 0);
Declare prototype for a background task / bottom half function
- Parameters:
-
| function_name | The name of this background task function |
#define OS_DEV_TASK_REF |
( |
function_name |
|
) |
(function_name ## let) |
Generate a reference to an OS_DEV_TASK() function
- Parameters:
-
| function_name | The name of the task being referenced. |
#define OS_DEV_WRITE |
( |
function_name |
|
) |
|
Define a function which will handle a user's write() request
- Parameters:
-
| function_name | The name of the driver write() function |
- Returns:
- A call to os_dev_write_return()
#define OS_DEV_WRITE |
( |
function_name |
|
) |
|
Value:static ssize_t function_name(struct file* file_p_, char* user_buffer_, \
size_t count_bytes_, loff_t* file_position_)
Define a function which will handle a user's write() request
- Parameters:
-
| function_name | The name of the driver write() function |
- Returns:
- A call to os_dev_write_return()
#define OS_DEV_WRITE_DCL |
( |
function_name |
|
) |
OS_DEV_WRITE(function_name); |
Declare prototype for an write() function.
- Parameters:
-
| function_name | The name of the driver write function. |
#define OS_DEV_WRITE_REF |
( |
function_name |
|
) |
function_name |
Generate a function reference to the driver's write() routine
- Parameters:
-
- Returns:
- A function pointer.