Driver Signatures

Defines

#define OS_DEV_INIT(function_name)
#define OS_DEV_INIT_DCL(function_name)   static int __init function_name (void);
#define OS_DEV_INIT_REF(function_name)   function_name
#define OS_DEV_SHUTDOWN(function_name)
#define OS_DEV_SHUTDOWN_DCL(function_name)   static void function_name(void);
#define OS_DEV_SHUTDOWN_REF(function_name)   function_name
#define OS_DEV_OPEN(function_name)   static int function_name(struct inode* inode_p_, struct file* file_p_)
#define OS_DEV_OPEN_DCL(function_name)   OS_DEV_OPEN(function_name);
#define OS_DEV_OPEN_REF(function_name)   function_name
#define OS_DEV_IOCTL(function_name)
#define OS_DEV_IOCTL_DCL(function_name)   OS_DEV_IOCTL(function_name);
#define OS_DEV_IOCTL_REF(function_name)   function_name
#define OS_DEV_MMAP(function_name)   int function_name(struct file* file_p_, struct vm_area_struct* vma_)
#define OS_DEV_READ_DCL(function_name)   OS_DEV_READ(function_name);
#define OS_DEV_READ_REF(function_name)   function_name
#define OS_DEV_WRITE(function_name)
#define OS_DEV_WRITE_DCL(function_name)   OS_DEV_WRITE(function_name);
#define OS_DEV_WRITE_REF(function_name)   function_name
#define OS_DEV_CLOSE(function_name)   static int function_name(struct inode* inode_p_, struct file* file_p_)
#define OS_DEV_CLOSE_DCL(function_name)   OS_DEV_CLOSE(function_name);
#define OS_DEV_CLOSE_REF(function_name)   function_name
#define OS_DEV_ISR(function_name)   static irqreturn_t function_name(int N1_, void* N2_)
#define OS_DEV_ISR_DCL(function_name)   OS_DEV_ISR(function_name);
#define OS_DEV_ISR_REF(function_name)   function_name
#define OS_DEV_TASK(function_name)   static void function_name(unsigned long data_)
#define OS_DEV_TASK_DCL(function_name)
#define OS_DEV_TASK_REF(function_name)   (function_name ## let)
#define OS_DEV_INIT(function_name)
#define OS_DEV_SHUTDOWN(function_name)
#define OS_DEV_OPEN(function_name)
#define OS_DEV_IOCTL(function_name)
#define OS_DEV_READ(function_name)
#define OS_DEV_WRITE(function_name)
#define OS_DEV_MMAP(function_name)
#define OS_DEV_CLOSE(function_name)
#define OS_DEV_ISR(function_name)
#define OS_DEV_TASK(function_name)

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)

 OS_DEV_INIT_DCL(widget, widget_init);

(in an implementation file)

 OS_DEV_INIT(widget, widget_init)
 {
     os_dev_init_return(TRUE);
 }

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)

 OS_DEV_INIT_DCL(widget_init);
 OS_DEV_ISR_DCL(widget_isr);

(in an implementation file)

 OS_DEV_INIT(widget, widget_init)
 {

     os_register_interrupt("widget", WIDGET_IRQ, OS_DEV_ISR_REF(widget_isr));

     os_dev_init_return(OS_RETURN_NO_ERROR_S);
 }

 OS_DEV_ISR(widget_isr)
 {
     os_dev_isr_return(TRUE);
 }

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

Generate a function reference to the driver's close function.

Parameters:
function_name Name of the OS_DEV_CLOSE() function.
Returns:
A function pointer.

Referenced by OS_DEV_INIT(), and shw_setup_user_driver_interaction().

#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:
function_name foo
#define OS_DEV_INIT_REF ( function_name   )     function_name

Generate a function reference to the driver's init function.

Parameters:
function_name Name of the OS_DEV_INIT() function.
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);

Boo.

#define OS_DEV_IOCTL_REF ( function_name   )     function_name

Generate a function reference to the driver's ioctl() function.

Parameters:
function_name Name of the OS_DEV_IOCTL() function.
Returns:
A function pointer.

Referenced by OS_DEV_INIT(), rng_test_setup_user_driver_interaction(), and shw_setup_user_driver_interaction().

#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:

 OS_DEV_ISR(widget, widget_isr, WIDGET_IRQ_NUMBER)
 {
     os_dev_isr_return(1);
 }
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:

 OS_DEV_ISR(widget)
 {
     os_dev_isr_return(1);
 }
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:
function_name Name of the OS_DEV_ISR() function.
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:
function_name The name of the OS_DEV_OPEN() function.
#define OS_DEV_OPEN_REF ( function_name   )     function_name

Generate a function reference to the driver's open() function.

Parameters:
function_name Name of the OS_DEV_OPEN() function.
Returns:
A function pointer.

Referenced by OS_DEV_INIT(), and shw_setup_user_driver_interaction().

#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:
function_name Name of the OS_DEV_READ() function.
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:
function_name Name of the OS_DEV_WRITE() function.
Returns:
A function pointer.
footer
©  Freescale Semiconductor, Inc., 2007.  All rights reserved.
Freescale Confidential Proprietary
NDA Required
doxygen