Driver-to-Kernel Operations


Functions

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)
os_lock_t os_lock_alloc_init (void)
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.

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.

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_HW_Reset(), and sah_Queue_Construct().

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

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

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

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

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.

Referenced by OS_DEV_INIT().

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

Referenced by rng_cleanup().

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

Referenced by RNG_ADD_WORK_ENTRY().

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

Referenced by rng_test_setup_user_driver_interaction(), and shw_setup_user_driver_interaction().

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

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

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.

Referenced by rng_test_setup_user_driver_interaction(), and shw_setup_user_driver_interaction().

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.

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

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.

Referenced by OS_DEV_SHUTDOWN(), and shw_cleanup().

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.)?

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_HW_Reset(), and sah_Queue_Destroy().

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.

Referenced by init_uco().

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   ) 

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(), 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

Referenced by shw_cleanup().

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

Referenced by fsl_shw_deregister_user(), fsl_shw_get_results(), OS_DEV_TASK(), sah_Handle_Interrupt(), sah_postprocess_queue(), sah_process_finished_request(), sah_Queue_Manager_Append_Entry(), sah_reset_sahara_request(), SHW_ADD_USER(), and SHW_REMOVE_USER().

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

Referenced by rng_map_RNG_memory().

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

Referenced by sah_HW_Reset().

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)

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(), and sah_HW_Reset().

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

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

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

Referenced by rng_setup_interrupt_handling().

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.

Referenced by shw_user_callback().

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??

Referenced by fsl_shw_get_random().

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

Referenced by fsl_shw_deregister_user(), fsl_shw_get_results(), OS_DEV_TASK(), sah_Handle_Interrupt(), sah_postprocess_queue(), sah_process_finished_request(), sah_Queue_Manager_Append_Entry(), sah_reset_sahara_request(), SHW_ADD_USER(), and SHW_REMOVE_USER().

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

Referenced by OS_DEV_SHUTDOWN().

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

Referenced by OS_DEV_TASK().

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

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

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