Driver Function Signatures


Defines

#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. 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_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_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_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_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_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_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_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_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_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()

footer
©  Freescale Semiconductor, Inc., 2007.  All rights reserved.
Freescale Confidential Proprietary
NDA Required
doxygen