Driver-to-Kernel Operations

Defines

#define os_register_interrupt(driver_name, interrupt_id, function)   request_irq(interrupt_id, function, 0, driver_name, NULL)
#define os_deregister_interrupt(interrupt_id)   free_irq(interrupt_id, NULL)
#define os_driver_init_registration(handle)   os_drv_do_init_reg(&handle)
#define os_driver_add_registration(handle, name, function)   do {handle.fops.name = (void*)(function); } while (0)
#define os_driver_register_power_suspend(handle, function)   handle.dd.suspend = function
#define os_driver_register_resume(handle, function)   handle.dd.resume = function
#define os_driver_complete_registration(handle, major, driver_name)   os_drv_do_reg(&handle, major, driver_name)
#define os_driver_get_major(handle)   (handle.reg_complete ? MAJOR(handle.dev) : -1)
#define os_driver_remove_registration(handle)   os_drv_rmv_reg(&handle)
#define os_register_to_driver(driver_information)   driver_register(driver_information)
#define os_unregister_from_driver(driver_information)   driver_unregister(driver_information)
#define os_register_a_device(device_information)   platform_device_register(device_information)
#define os_unregister_a_device(device_information)   platform_device_unregister(device_information)
#define os_printk(...)   (void) printk(__VA_ARGS__)
#define os_create_task(function_name)   OS_ERROR_OK_S
#define os_dev_schedule_task(function_name)   tasklet_schedule(&(function_name ## let))
#define os_dev_stop_task(function_name)
#define os_alloc_memory(amount, flags)   (void*)kmalloc(amount, flags)
#define os_free_memory(location)   kfree(location)
#define os_alloc_coherent(amount, dma_addrp, flags)   (void*)dma_alloc_coherent(NULL, amount, dma_addrp, flags)
#define os_free_coherent(size, virt_addr, dma_addr)   dma_free_coherent(NULL, size, virt_addr, dma_addr
#define os_map_device(start, range_bytes)   (void*)ioremap_nocache((start), range_bytes)
#define os_unmap_device(start, range_bytes)   iounmap((void*)(start))
#define os_copy_to_user(to, from, size)   ((copy_to_user(to, from, size) == 0) ? 0 : OS_ERROR_BAD_ADDRESS_S)
#define os_copy_from_user(to, from, size)   ((copy_from_user(to, from, size) == 0) ? 0 : OS_ERROR_BAD_ADDRESS_S)
#define os_read8(register_address)   __raw_readb(register_address)
#define os_write8(register_address, value)   __raw_writeb(value, register_address)
#define os_read16(register_address)   __raw_readw(register_address)
#define os_write16(register_address, value)   __raw_writew(value, (uint32_t*)(register_address))
#define os_read32(register_address)   __raw_readl((uint32_t*)(register_address))
#define os_write32(register_address, value)   __raw_writel(value, register_address)
#define os_read64(register_address)   ERROR_UNIMPLEMENTED
#define os_write64(register_address, value)   ERROR_UNIMPLEMENTED
#define os_mdelay   mdelay
#define os_va   __va
#define os_pa   __pa
#define os_lock(lock_handle)   spin_lock(lock_handle)
#define os_unlock(lock_handle)   spin_unlock(lock_handle)
#define os_lock_save_context(lock_handle, context)   spin_lock_irqsave(lock_handle, context)
#define os_unlock_restore_context(lock_handle, context)   spin_unlock_irqrestore(lock_handle, context)
#define os_lock_deallocate(lock_handle)   kfree(lock_handle)
#define os_get_process_handle()   current
#define os_send_signal(proc, sig)   send_sig(sig, proc, 0);
#define os_get_random_bytes(buf, count)   get_random_bytes(buf, count)
#define os_sleep(object, condition, atomic)
#define os_wake_sleepers(object)   wake_up_interruptible(&(object##_qh));

Functions

static int os_drv_do_init_reg (os_driver_reg_t *handle)
static int os_drv_do_reg (os_driver_reg_t *handle, unsigned major, char *driver_name)
static int os_drv_rmv_reg (os_driver_reg_t *handle)
static os_lock_t os_lock_alloc_init (void)
os_error_code os_register_interrupt (char *driver_name, os_interrupt_id_t interrupt_id, os_interrupt_handler_t function)
os_error_code os_deregister_interrupt (os_interrupt_id_t interrupt_id)
os_error_code os_driver_init_registration (os_driver_reg_t handle)
void os_driver_add_registration (os_driver_reg_t handle, os_driver_fn_t name, void *function)
os_error_code os_driver_complete_registration (os_driver_reg_t handle, int major, char *driver_name)
uint32_t os_driver_get_major (os_driver_reg_t handle)
os_error_code os_driver_remove_registration (int major, char *driver_name)
void os_printk (char *msg,...)
void * os_alloc_memory (unsigned amount, int flags)
void os_free_memory (void *location)
void * os_alloc_coherent (unsigned amount, uint32_t *dma_addrp, int flags)
void os_free_coherent (unsigned size, void *virt_addr, uint32_t dma_addr)
void * os_map_device (uint32_t start, unsigned range_bytes)
void os_unmap_device (void *start, unsigned range_bytes)
os_error_code os_copy_to_user (void *to, void *from, unsigned size)
os_error_code os_copy_from_user (void *to, void *from, unsigned size)
uint8_t os_read8 (uint8_t *register_address)
void os_write8 (uint8_t *register_address, uint8_t value)
uint16_t os_read16 (uint16_t *register_address)
void os_write16 (uint16_t *register_address, uint16_t value)
uint32_t os_read32 (uint32_t *register_address)
void os_write32 (uint32_t *register_address, uint32_t value)
uint64_t os_read64 (uint64_t *register_address)
void os_write64 (uint64_t *register_address, uint64_t value)
os_error os_create_task (os_task_fn_t *task_fn)
void os_dev_schedule_task (os_task_fn_t *task_fn)
void os_stop_task (os_task_fn_t *task_fn)
void os_mdelay (unsigned long msecs)
void * os_va (uint32_t pa)
uint32_t os_pa (void *va)
void os_lock (os_lock_t lock_handle)
void os_unlock (os_lock_t lock_handle)
void os_lock_save_context (os_lock_t lock_handle, os_lock_context_t context)
void os_unlock_restore_context (os_lock_t lock_handle, os_lock_context_t context)
void os_lock_deallocate (os_lock_t lock_handle)
os_process_handle_t os_get_process_handle ()
void os_send_signal (os_process_handle_t proc, int sig)
void os_get_random_bytes (void *buf, unsigned count)
os_error_code os_sleep (os_sleep_object_t object, unsigned condition, unsigned atomic)
void os_wake_sleepers (os_sleep_object_t object)

Detailed Description

These are the operations which drivers should call to get the OS to perform services.


Define Documentation

#define os_alloc_coherent ( amount,
dma_addrp,
flags   )     (void*)dma_alloc_coherent(NULL, amount, dma_addrp, flags)

Allocate cache-coherent memory

Parameters:
amount Number of bytes to allocate
[out] dma_addrp Location to store physical address of allocated memory.
flags Some indication of purpose of memory (needs definition).
Returns:
(virtual space) pointer to allocated memory, or NULL if failed.

Referenced by sah_Block_Add_Page().

#define os_alloc_memory ( amount,
flags   )     (void*)kmalloc(amount, flags)

Allocate some kernel memory

Parameters:
amount Number of 8-bit bytes to allocate
flags Some indication of purpose of memory (needs definition)
Returns:
Pointer to allocated memory, or NULL if failed.

Referenced by add_entropy(), fsl_shw_add_entropy(), fsl_shw_get_random(), get_results(), OS_DEV_IOCTL(), OS_DEV_MMAP(), OS_DEV_OPEN(), rng_test_add_entropy(), rng_test_get_random(), sah_Block_Add_Page(), sah_get_results_pointers(), sah_HW_Reset(), and sah_Queue_Construct().

#define os_copy_from_user ( to,
from,
size   )     ((copy_from_user(to, from, size) == 0) ? 0 : OS_ERROR_BAD_ADDRESS_S)

Copy data from User space to Kernel space

Parameters:
to The target location in kernel memory
from The source location in user memory
size The number of bytes to be copied
Returns:
os_error_code

Referenced by add_entropy(), get_capabilities(), get_random(), get_results(), init_uco(), OS_DEV_IOCTL(), rng_test_add_entropy(), rng_test_get_random(), rng_test_read_register(), rng_test_write_register(), and sah_get_results_pointers().

#define os_copy_to_user ( to,
from,
size   )     ((copy_to_user(to, from, size) == 0) ? 0 : OS_ERROR_BAD_ADDRESS_S)

Copy data from Kernel space to User space

Parameters:
to The target location in user memory
from The source location in kernel memory
size The number of bytes to be copied
Returns:
os_error_code

Referenced by copy_fsl_code(), finish_random(), get_capabilities(), get_results(), handle_sah_ioctl_dar(), rng_test_add_entropy(), rng_test_get_random(), rng_test_read_register(), rng_test_write_register(), and sah_get_results_pointers().

#define os_create_task ( function_name   )     OS_ERROR_OK_S

Prepare a task to execute the given function. This should only be done once per function,, during the driver's initialization routine.

Parameters:
task_fn Name of the OS_DEV_TASK() function to be created.
Returns:
an OS ERROR code.

Referenced by OS_DEV_INIT().

#define os_deregister_interrupt ( interrupt_id   )     free_irq(interrupt_id, NULL)

Deregister an interrupt handler.

Parameters:
interrupt_id The interrupt line to stop monitoring
Returns:
os_error_code

Referenced by rng_cleanup(), and scc_cleanup().

#define os_dev_schedule_task ( function_name   )     tasklet_schedule(&(function_name ## let))

Schedule execution of a task.

Parameters:
function_name The function associated with the task.
Returns:
(void)

Referenced by RNG_ADD_WORK_ENTRY().

#define os_dev_stop_task ( function_name   ) 
Value:
do {                                                                          \
    tasklet_disable(&(function_name ## let));                                 \
    tasklet_kill(&(function_name ## let));                                    \
} while (0)

Make sure that task is no longer running and will no longer run.

This function will not return until both are true. This is useful when shutting down a driver.

Referenced by rng_cleanup().

#define os_driver_add_registration ( handle,
name,
function   )     do {handle.fops.name = (void*)(function); } while (0)

Add a function registration to driver registration.

Parameters:
handle A handle initialized by os_driver_init_registration().
name Which function is being supported.
function The result of a call to a _REF version of one of the driver function signature macros
Returns:
void

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

#define os_driver_complete_registration ( handle,
major,
driver_name   )     os_drv_do_reg(&handle, major, driver_name)

Finalize the driver registration with the kernel.

Upon return from this call, the driver may begin receiving calls at the defined entry points.

Parameters:
handle The handle used with os_driver_init_registration().
major The major device number to be associated with the driver. If this value is zero, a major number may be assigned. See os_driver_get_major() to determine final value. os_driver_remove_registration().
driver_name The driver name. Can be used as part of 'device node' name on platforms which support such a feature.
Returns:
An error code

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

#define os_driver_get_major ( handle   )     (handle.reg_complete ? MAJOR(handle.dev) : -1)

Get driver Major Number from handle after a successful registration.

Parameters:
handle A handle which has completed registration.
Returns:
The major number (if any) associated with the handle.

Referenced by rng_test_setup_user_driver_interaction(), and shw_setup_user_driver_interaction().

#define os_driver_init_registration ( handle   )     os_drv_do_init_reg(&handle)

Initialize driver registration.

If the driver handles open(), close(), ioctl(), read(), write(), or mmap() calls, then it needs to register their location with the kernel so that they get associated with the device.

Parameters:
handle The handle object to be used with this registration. The object must live (be in memory somewhere) at least until os_driver_remove_registration() is called.
Returns:
A handle for further driver registration, or NULL if failed.

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

#define os_driver_register_power_suspend ( handle,
function   )     handle.dd.suspend = function

Record 'power suspend' function for the device.

Parameters:
handle A handle initialized by os_driver_init_registration().
function Name of function to call on power suspend request

Status: Provisional

Returns:
void
#define os_driver_register_resume ( handle,
function   )     handle.dd.resume = function

Record 'power resume' function for the device.

Parameters:
handle A handle initialized by os_driver_init_registration().
function Name of function to call on power resume request

Status: Provisional

Returns:
void
#define os_driver_remove_registration ( handle   )     os_drv_rmv_reg(&handle)

Remove the driver's registration with the kernel.

Upon return from this call, the driver not receive any more calls at the defined entry points (other than ISR and shutdown).

Parameters:
handle A handle initialized by os_driver_init_registration().
Returns:
An error code.

Referenced by OS_DEV_SHUTDOWN(), and shw_cleanup().

#define os_free_coherent ( size,
virt_addr,
dma_addr   )     dma_free_coherent(NULL, size, virt_addr, dma_addr

Free cache-coherent memory

Parameters:
size Number of bytes which were allocated.
virt_addr Virtual(kernel) address of memory.to be freed, as returned by os_alloc_coherent().
dma_addr Physical address of memory.to be freed, as returned by os_alloc_coherent().
Returns:
void
#define os_free_memory ( location   )     kfree(location)

Free some kernel memory

Parameters:
location The beginning of the region to be freed.

Do some OSes have separate free() functions which should be distinguished by passing in flags here, too? Don't some also require the size of the buffer being freed?

Referenced by add_entropy(), finish_random(), fsl_shw_add_entropy(), fsl_shw_deregister_user(), fsl_shw_get_random(), fsl_shw_get_results(), get_results(), OS_DEV_CLOSE(), OS_DEV_IOCTL(), rng_test_add_entropy(), rng_test_get_random(), sah_get_results_pointers(), sah_HW_Reset(), and sah_Queue_Destroy().

 
#define os_get_process_handle (  )     current

Determine process handle

The process handle of the current user is returned.

Returns:
A handle on the current process.

Referenced by handle_sah_ioctl_dar(), and init_uco().

#define os_get_random_bytes ( buf,
count   )     get_random_bytes(buf, count)

Get some random bytes

Parameters:
buf The location to store the random data.
count The number of bytes to store.
Returns:
void
#define os_lock ( lock_handle   )     spin_lock(lock_handle)

Acquire a lock.

This function should only be called from an interrupt service routine.

Parameters:
lock_handle A handle to the lock to acquire.
Returns:
void
#define os_lock_deallocate ( lock_handle   )     kfree(lock_handle)

Deallocate a lock handle.

Parameters:
lock_handle An os_lock_t that has been allocated.
Returns:
void

Referenced by sah_Stop_Mem_Map(), and shw_cleanup().

#define os_lock_save_context ( lock_handle,
context   )     spin_lock_irqsave(lock_handle, context)
#define os_map_device ( start,
range_bytes   )     (void*)ioremap_nocache((start), range_bytes)

Map an I/O space into kernel memory space

Parameters:
start The starting address of the (physical / io space) region
range_bytes The number of bytes to map
Returns:
A pointer to the mapped area, or NULL on failure

Referenced by rng_map_RNG_memory().

#define os_mdelay   mdelay

Delay some number of microseconds

Note that this is a busy-loop, not a suspension of the task/process.

Parameters:
msecs The number of microseconds to delay
Returns:
void
#define os_pa   __pa

Calculate physical address from virtual address

Parameters:
va Virtual address
Returns:
physical address
Note:
this assumes that addresses are 32 bits wide

Referenced by sah_Block_Add_Page(), sah_HW_Reset(), and sah_Physicalise_Links().

#define os_printk ( ...   )     (void) printk(__VA_ARGS__)

Print a message to console / into log file. After the msg argument a number of printf-style arguments may be added. Types should be limited to printf string, char, octal, decimal, and hexadecimal types. (This excludes pointers, and floating point).

Parameters:
msg The main text of the message to be logged
s The printf-style arguments which go with msg, if any
Returns:
(void)

Referenced by OS_DEV_INIT(), OS_DEV_SHUTDOWN(), rng_drain_fifo(), rng_test_add_entropy(), rng_test_get_random(), rng_test_read_register(), rng_test_setup_user_driver_interaction(), rng_test_write_register(), sah_DePhysicalise_Links(), sah_HW_Reset(), sah_Init_Mem_Map(), sah_Physicalise_Descriptors(), sah_Physicalise_Links(), scc_init(), scc_update_state(), and setup_interrupt_handling().

#define os_read16 ( register_address   )     __raw_readw(register_address)

Read a 16-bit device register

Parameters:
register_address The (bus) address of the register to write to
Returns:
The value in the register
#define os_read32 ( register_address   )     __raw_readl((uint32_t*)(register_address))

Read a 32-bit device register

Parameters:
register_address The (bus) address of the register to write to
Returns:
The value in the register

Referenced by sah_HW_Read_CDAR(), sah_HW_Read_Config(), sah_HW_Read_Control(), sah_HW_Read_DAR(), sah_HW_Read_Error_Status(), sah_HW_Read_Fault_Address(), sah_HW_Read_IDAR(), sah_HW_Read_MM_Status(), sah_HW_Read_Op_Status(), sah_HW_Read_Status(), and sah_HW_Read_Version().

#define os_read64 ( register_address   )     ERROR_UNIMPLEMENTED

Read a 64-bit device register

Parameters:
register_address The (bus) address of the register to write to
Returns:
The value in the register
#define os_read8 ( register_address   )     __raw_readb(register_address)

Read a 8-bit device register

Parameters:
register_address The (bus) address of the register to write to
Returns:
The value in the register
#define os_register_a_device ( device_information   )     platform_device_register(device_information)

register a device to a driver

this routine registers a drivers devices to the Linux Device Model

Parameters:
device_information The platform_device structure information
Returns:
An error code.

Status: denigrated in favor of os_driver_complete_registration()

#define os_register_interrupt ( driver_name,
interrupt_id,
function   )     request_irq(interrupt_id, function, 0, driver_name, NULL)

Register an interrupt handler.

Parameters:
driver_name The name of the driver
interrupt_id The interrupt line to monitor (type os_interrupt_id_t)
function The function to be called to handle an interrupt
Returns:
os_error_code

Referenced by rng_setup_interrupt_handling(), and setup_interrupt_handling().

#define os_register_to_driver ( driver_information   )     driver_register(driver_information)

Register a driver with the Linux Device Model.

Parameters:
driver_information The device_driver structure information
Returns:
An error code.

Status: denigrated in favor of os_driver_complete_registration()

#define os_send_signal ( proc,
sig   )     send_sig(sig, proc, 0);

Send a signal to a process

Parameters:
proc A handle to the target process.
sig The POSIX signal to send to that process.

Referenced by shw_user_callback().

#define os_sleep ( object,
condition,
atomic   ) 
Value:
({                                                                      \
    DEFINE_WAIT(_waitentry_);                                           \
    os_error_code code = OS_ERROR_OK_S;                                 \
                                                                        \
    while (!(condition)) {                                              \
        prepare_to_wait(&(object##_qh), &_waitentry_,                   \
                        atomic ? 0 : TASK_INTERRUPTIBLE);               \
        if (!(condition)) {                                             \
            schedule();                                                 \
        }                                                               \
                                                                        \
        finish_wait(&(object##_qh), &_waitentry_);                      \
                                                                        \
        if (!atomic && signal_pending(current)) {                       \
            code = OS_ERROR_FAIL_S; /* NEED SOMETHING BETTER */         \
            break;                                                      \
        }                                                               \
    };                                                                  \
                                                                        \
    code;                                                               \
})

Go to sleep on an object.

Parameters:
object The object on which to sleep
condition An expression to check for sleep completion. Must be coded so that it can be referenced more than once inside macro, i.e., no ++ or other modifying expressions.
atomic Non-zero if sleep must not return until condition.
Returns:
error code -- OK or sleep interrupted??

Referenced by fsl_shw_get_random().

#define os_unlock ( lock_handle   )     spin_unlock(lock_handle)

Unlock a lock. Lock must have been acquired by os_lock().

Parameters:
lock_handle A handle to the lock to unlock.
Returns:
void
#define os_unlock_restore_context ( lock_handle,
context   )     spin_unlock_irqrestore(lock_handle, context)
#define os_unmap_device ( start,
range_bytes   )     iounmap((void*)(start))

Unmap an I/O space from kernel memory space

Parameters:
start The starting address of the (virtual) region
range_bytes The number of bytes to unmap
Returns:
None

Referenced by OS_DEV_SHUTDOWN().

#define os_unregister_a_device ( device_information   )     platform_device_unregister(device_information)

unregister a device from a driver

this routine unregisters a drivers devices from the Linux Device Model

Parameters:
device_information The platform_device structure information
Returns:
An error code.

Status: Denigrated. See os_register_a_device().

#define os_unregister_from_driver ( driver_information   )     driver_unregister(driver_information)

Unregister a driver from the Linux Device Model

this routine unregisters from the Linux Device Model

Parameters:
driver_information The device_driver structure information
Returns:
An error code.

Status: Denigrated. See os_register_to_driver().

#define os_va   __va

Calculate virtual address from physical address

Parameters:
pa Physical address
Returns:
virtual address
Note:
this assumes that addresses are 32 bits wide
#define os_wake_sleepers ( object   )     wake_up_interruptible(&(object##_qh));

Wake up whatever is sleeping on sleep object

Parameters:
object The object on which things might be sleeping
Returns:
none

Referenced by OS_DEV_TASK().

#define os_write16 ( register_address,
value   )     __raw_writew(value, (uint32_t*)(register_address))

Write a 16-bit device register

Parameters:
register_address The (bus) address of the register to write to
value The value to write into the register
#define os_write32 ( register_address,
value   )     __raw_writel(value, register_address)

Write a 32-bit device register

Parameters:
register_address The (bus) address of the register to write to
value The value to write into the register

Referenced by sah_HW_Write_Command(), sah_HW_Write_Config(), sah_HW_Write_Control(), and sah_HW_Write_DAR().

#define os_write64 ( register_address,
value   )     ERROR_UNIMPLEMENTED

Write a 64-bit device register

Parameters:
register_address The (bus) address of the register to write to
value The value to write into the register
#define os_write8 ( register_address,
value   )     __raw_writeb(value, register_address)

Write a 8-bit device register

Parameters:
register_address The (bus) address of the register to write to
value The value to write into the register

Function Documentation

void* os_alloc_coherent ( unsigned  amount,
uint32_t *  dma_addrp,
int  flags 
)

Allocate cache-coherent memory

Parameters:
amount Number of bytes to allocate
[out] dma_addrp Location to store physical address of allocated memory.
flags Some indication of purpose of memory (needs definition).
Returns:
(virtual space) pointer to allocated memory, or NULL if failed.
void* os_alloc_memory ( unsigned  amount,
int  flags 
)

Allocate some kernel memory

Parameters:
amount Number of 8-bit bytes to allocate
flags Some indication of purpose of memory (needs definition)
Returns:
Pointer to allocated memory, or NULL if failed.
os_error_code os_copy_from_user ( void *  to,
void *  from,
unsigned  size 
)

Copy data from User space to Kernel space

Parameters:
to The target location in kernel memory
from The source location in user memory
size The number of bytes to be copied
Returns:
os_error_code
os_error_code os_copy_to_user ( void *  to,
void *  from,
unsigned  size 
)

Copy data from Kernel space to User space

Parameters:
to The target location in user memory
from The source location in kernel memory
size The number of bytes to be copied
Returns:
os_error_code
os_error os_create_task ( os_task_fn_t task_fn  ) 

Prepare a task to execute the given function. This should only be done once per task, during the driver's initialization routine.

Parameters:
task_fn Name of the OS_DEV_TASK() function to be created.
Returns:
an OS ERROR code.
os_error_code os_deregister_interrupt ( os_interrupt_id_t  interrupt_id  ) 

Deregister an interrupt handler.

Parameters:
interrupt_id The interrupt line to stop monitoring
Returns:
os_error_code
void os_dev_schedule_task ( os_task_fn_t task_fn  ) 

Run the task associated with an OS_DEV_TASK() function

The task will begin execution sometime after or during this call.

Parameters:
task_fn Name of the OS_DEV_TASK() function to be scheduled.
Returns:
void
void os_driver_add_registration ( os_driver_reg_t  handle,
os_driver_fn_t  name,
void *  function 
)

Add a function registration to driver registration.

Parameters:
handle The handle used with os_driver_init_registration().
name Which function is being supported.
function The result of a call to a _REF version of one of the driver function signature macros driver function signature macros
Returns:
void
os_error_code os_driver_complete_registration ( os_driver_reg_t  handle,
int  major,
char *  driver_name 
)

Finalize the driver registration with the kernel.

Upon return from this call, the driver may begin receiving calls at the defined entry points.

Parameters:
handle The handle used with os_driver_init_registration().
major The major device number to be associated with the driver. If this value is zero, a major number may be assigned. See os_driver_get_major() to determine final value. os_driver_remove_registration().
driver_name The driver name. Can be used as part of 'device node' name on platforms which support such a feature.
Returns:
An error code
uint32_t os_driver_get_major ( os_driver_reg_t  handle  ) 

Get driver Major Number from handle after a successful registration.

Parameters:
handle A handle which has completed registration.
Returns:
The major number (if any) associated with the handle.
os_error_code os_driver_init_registration ( os_driver_reg_t  handle  ) 

Initialize driver registration.

If the driver handles open(), close(), ioctl(), read(), write(), or mmap() calls, then it needs to register their location with the kernel so that they get associated with the device.

Parameters:
handle The handle object to be used with this registration. The object must live (be in memory somewhere) at least until os_driver_remove_registration() is called.
Returns:
An os error code.
os_error_code os_driver_remove_registration ( int  major,
char *  driver_name 
)

Remove the driver's registration with the kernel.

Upon return from this call, the driver not receive any more calls at the defined entry points (other than ISR and shutdown).

Parameters:
major The major device number to be associated with the driver.
driver_name The driver name
Returns:
An error code.
static int os_drv_do_init_reg ( os_driver_reg_t handle  )  [inline, static]
static int os_drv_do_reg ( os_driver_reg_t handle,
unsigned  major,
char *  driver_name 
) [inline, static]

INTERNAL function of the Linux port of the OS API. Implements the os_driver_complete_registration() function.

Parameters:
handle The handle used with os_driver_init_registration().
major The major device number to be associated with the driver. If this value is zero, a major number may be assigned. See os_driver_get_major() to determine final value. os_driver_remove_registration().
driver_name The driver name. Can be used as part of 'device node' name on platforms which support such a feature.
Returns:
An error code

References os_driver_reg_t::cd, os_driver_reg_t::cs, os_driver_reg_t::dd, os_driver_reg_t::dev, os_driver_reg_t::fops, OS_ERROR_FAIL_S, OS_ERROR_NO_MEMORY_S, OS_ERROR_OK_S, os_driver_reg_t::pd, os_driver_reg_t::power_complete, and os_driver_reg_t::reg_complete.

static int os_drv_rmv_reg ( os_driver_reg_t handle  )  [inline, static]

INTERNAL implemention of os_driver_remove_registration.

Parameters:
handle A handle initialized by os_driver_init_registration().
Returns:
An error code.

References os_driver_reg_t::cd, os_driver_reg_t::cs, os_driver_reg_t::dd, os_driver_reg_t::dev, OS_ERROR_OK_S, os_driver_reg_t::pd, os_driver_reg_t::power_complete, and os_driver_reg_t::reg_complete.

void os_free_coherent ( unsigned  size,
void *  virt_addr,
uint32_t  dma_addr 
)

Free cache-coherent memory

Parameters:
size Number of bytes which were allocated.
[out] virt_addr Virtual(kernel) address of memory.to be freed, as returned by os_alloc_coherent().
[out] dma_addr Physical address of memory.to be freed, as returned by os_alloc_coherent().
Returns:
void
void os_free_memory ( void *  location  ) 

Free some kernel memory

Parameters:
location The beginning of the region to be freed.

Do some OSes have separate free() functions which should be distinguished by passing in flags here, too? Don't some also require the size of the buffer being freed? Perhaps separate routines for each alloc/free pair (DMAable, etc.)?

os_process_handle_t os_get_process_handle (  ) 

Determine process handle

The process handle of the current user is returned.

Returns:
A handle on the current process.
void os_get_random_bytes ( void *  buf,
unsigned  count 
)

Get some random bytes

Parameters:
buf The location to store the random data.
count The number of bytes to store.
Returns:
void
void os_lock ( os_lock_t  lock_handle  ) 

Acquire a lock.

This function should only be called from an interrupt service routine.

Parameters:
lock_handle A handle to the lock to acquire.
Returns:
void
os_lock_t os_lock_alloc_init ( void   )  [inline, static]

Allocate and initialize a lock, returning a lock handle.

The lock state will be initialized to 'unlocked'.

Returns:
A lock handle, or NULL if an error occurred.

Referenced by OS_DEV_INIT(), sah_Init_Mem_Map(), and sah_Queue_Manager_Init().

void os_lock_deallocate ( os_lock_t  lock_handle  ) 

Deallocate a lock handle.

Parameters:
lock_handle An os_lock_t that has been allocated.
Returns:
void
void os_lock_save_context ( os_lock_t  lock_handle,
os_lock_context_t  context 
)

Acquire a lock in non-ISR context

This function will spin until the lock is available.

Parameters:
lock_handle A handle of the lock to acquire.
context Place to save the before-lock context
Returns:
void
void* os_map_device ( uint32_t  start,
unsigned  range_bytes 
)

Map an I/O space into kernel memory space

Parameters:
start The starting address of the (physical / io space) region
range_bytes The number of bytes to map
Returns:
A pointer to the mapped area, or NULL on failure
void os_mdelay ( unsigned long  msecs  ) 

Delay some number of microseconds

Note that this is a busy-loop, not a suspension of the task/process.

Parameters:
msecs The number of microseconds to delay
Returns:
void
uint32_t os_pa ( void *  va  ) 

Calculate physical address from virtual address

Parameters:
va Virtual address
Returns:
physical address
Note:
this assumes that addresses are 32 bits wide
void os_printk ( char *  msg,
  ... 
)

Print a message to console / into log file. After the msg argument a number of printf-style arguments may be added. Types should be limited to printf string, char, octal, decimal, and hexadecimal types. (This excludes pointers, and floating point).

Parameters:
msg The message to print to console / system log
Returns:
(void)
uint16_t os_read16 ( uint16_t *  register_address  ) 

Read a 16-bit device register

Parameters:
register_address The (bus) address of the register to write to
Returns:
The value in the register
uint32_t os_read32 ( uint32_t *  register_address  ) 

Read a 32-bit device register

Parameters:
register_address The (bus) address of the register to write to
Returns:
The value in the register
uint64_t os_read64 ( uint64_t *  register_address  ) 

Read a 64-bit device register

Parameters:
register_address The (bus) address of the register to write to
Returns:
The value in the register
uint8_t os_read8 ( uint8_t *  register_address  ) 

Read an 8-bit device register

Parameters:
register_address The (bus) address of the register to write to
Returns:
The value in the register
os_error_code os_register_interrupt ( char *  driver_name,
os_interrupt_id_t  interrupt_id,
os_interrupt_handler_t  function 
)

Register an interrupt handler.

Parameters:
driver_name The name of the driver
interrupt_id The interrupt line to monitor (type os_interrupt_id_t)
function The function to be called to handle an interrupt
Returns:
os_error_code
void os_send_signal ( os_process_handle_t  proc,
int  sig 
)

Send a signal to a process

Parameters:
proc A handle to the target process.
sig The POSIX signal to send to that process.
os_error_code os_sleep ( os_sleep_object_t  object,
unsigned  condition,
unsigned  atomic 
)

Go to sleep on an object.

Example: code = os_sleep(my_queue, available_count == 0, 0);

Parameters:
object The object on which to sleep
condition An expression to check for sleep completion. Must be coded so that it can be referenced more than once inside macro, i.e., no ++ or other modifying expressions.
atomic Non-zero if sleep must not return until condition.
Returns:
error code -- OK or sleep interrupted??
void os_stop_task ( os_task_fn_t task_fn  ) 

Make sure that task is no longer running and will no longer run.

This function will not return until both are true. This is useful when shutting down a driver.

Parameters:
task_fn Name of the OS_DEV_TASK() funciton to be stopped.
void os_unlock ( os_lock_t  lock_handle  ) 

Unlock a lock. Lock must have been acquired by os_lock().

Parameters:
lock_handle A handle to the lock to unlock.
Returns:
void
void os_unlock_restore_context ( os_lock_t  lock_handle,
os_lock_context_t  context 
)

Release a lock in non-ISR context

Parameters:
lock_handle A handle of the lock to release.
context Place where before-lock context was saved.
Returns:
void
void os_unmap_device ( void *  start,
unsigned  range_bytes 
)

Unmap an I/O space from kernel memory space

Parameters:
start The starting address of the (virtual) region
range_bytes The number of bytes to unmap
Returns:
None
void* os_va ( uint32_t  pa  ) 

Calculate virtual address from physical address

Parameters:
pa Physical address
Returns:
virtual address
Note:
this assumes that addresses are 32 bits wide
void os_wake_sleepers ( os_sleep_object_t  object  ) 

Wake up whatever is sleeping on sleep object

Parameters:
object The object on which things might be sleeping
Returns:
none
void os_write16 ( uint16_t *  register_address,
uint16_t  value 
)

Write a 16-bit device register

Parameters:
register_address The (bus) address of the register to write to
value The value to write into the register
void os_write32 ( uint32_t *  register_address,
uint32_t  value 
)

Write a 32-bit device register

Parameters:
register_address The (bus) address of the register to write to
value The value to write into the register
void os_write64 ( uint64_t *  register_address,
uint64_t  value 
)

Write a 64-bit device register

Parameters:
register_address The (bus) address of the register to write to
value The value to write into the register
void os_write8 ( uint8_t *  register_address,
uint8_t  value 
)

Write an 8-bit device register

Parameters:
register_address The (bus) address of the register to write to
value The value to write into the register
footer
©  Freescale Semiconductor, Inc., 2007.  All rights reserved.
Freescale Confidential Proprietary
NDA Required
doxygen