linux/drivers/mxc/security/sahara2/include/portable_os.h File Reference

Defines

#define LINUX
#define PORTABLE_OS_VERSION   101
#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)
#define OS_DEV_INIT_DCL(function_name)
#define OS_DEV_SHUTDOWN_DCL(function_name)
#define OS_DEV_OPEN_DCL(function_name)
#define OS_DEV_IOCTL_DCL(function_name)
#define OS_DEV_READ_DCL(function_name)
#define OS_DEV_WRITE_DCL(function_name)
#define OS_DEV_MMAP_DCL(function_name)
#define OS_DEV_CLOSE_DCL(function_name)
#define OS_DEV_ISR_DCL(function_name)
#define OS_DEV_TASK_DCL(function_name)

Typedefs

typedef int os_interrupt_id_t
typedef int os_process_handle_t
typedef int * os_lock_t
typedef int os_lock_context_t
typedef int os_sleep_object_t
typedef void * os_driver_reg_t
typedef void(* os_init_function_t )(void)
typedef void(* os_shutdown_function_t )(void)
typedef void(* os_user_function_t )(void)
typedef void(* os_interrupt_handler_t )(void)
typedef void(* os_task_fn_t )(void)

Enumerations

enum  os_error_code {
  OS_ERROR_OK_S = 0,
  OS_ERROR_FAIL_S = -EIO,
  OS_ERROR_NO_MEMORY_S = -ENOMEM,
  OS_ERROR_BAD_ADDRESS_S = -EFAULT,
  OS_ERROR_BAD_ARG_S = -EINVAL,
  OS_ERROR_OK_S = 0,
  OS_ERROR_FAIL_S,
  OS_ERROR_NO_MEMORY_S,
  OS_ERROR_BAD_ADDRESS_S,
  OS_ERROR_BAD_ARG_S
}
enum  os_driver_fn_t {
  OS_FN_OPEN,
  OS_FN_CLOSE,
  OS_FN_READ,
  OS_FN_WRITE,
  OS_FN_IOCTL,
  OS_FN_MMAP
}

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)
static 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)
void os_dev_init_return (os_error_code code)
void os_dev_shutdown_return (os_error_code code)
void os_dev_isr_return (int code)
void os_dev_open_return (os_error_code code)
void os_dev_ioctl_return (os_error_code code)
void os_dev_read_return (os_error_code code)
void os_dev_write_return (os_error_code code)
void os_dev_mmap_return (os_error_code code)
void os_dev_close_return (os_error_code code)
void os_dev_task_begin (void)
void os_dev_task_return (os_error_code code)
int os_dev_is_flag_read (void)
int os_dev_is_flag_write (void)
int os_dev_is_flag_nonblock (void)
int os_dev_get_major (void)
int os_dev_get_minor (void)
unsigned os_dev_get_ioctl_op (void)
os_dev_ioctl_arg_t os_dev_get_ioctl_arg (void)
unsigned os_dev_get_count (void)
void * os_dev_get_user_buffer (void)
unsigned os_dev_get_file_flags (void)
void os_dev_set_user_private (void *struct_p)
void * os_dev_get_user_private (void)
int os_dev_get_irq (void)
os_init_function_t OS_DEV_INIT_REF (symbol function_name)
os_shutdown_function_t OS_DEV_SHUTDOWN_REF (symbol function_name)
os_user_function_t OS_DEV_OPEN_REF (symbol function_name)
os_user_function_t OS_DEV_CLOSE_REF (symbol function_name)
os_user_function_t OS_DEV_READ_REF (symbol function_name)
os_user_function_t OS_DEV_WRITE_REF (symbol function_name)
os_user_function_t OS_DEV_IOCTL_REF (symbol function_name)
os_user_function_t OS_DEV_MMAP_REF (symbol function_name)
os_interrupt_handler_t OS_DEV_ISR_REF (symbol function_name)
void os_flush_cache_all (void)
void os_cache_flush_range (void *start, uint32_t len)
void os_cache_inv_range (void *start, uint32_t len)
void os_cache_clean_range (void *start, uint32_t len)

Detailed Description

This file should be included by portable driver code in order to gain access to the OS-specific header files. It is the only OS-related header file that the writer of a portable driver should need.

This file also contains the documentation for the common API.

Begin reading the documentation for this file at the main page.


Define Documentation

#define LINUX

Introduction

This defines the API / kernel programming environment for portable drivers.

This API is broken up into several functional areas. It greatly limits the choices of a device-driver author, but at the same time should allow for greater portability of the resulting code.

Each kernel-to-driver function (initialization function, interrupt service routine, etc.) has a 'portable signature' which must be used, and a specific function which must be called to generate the return statement. There is one exception, a background task or "bottom half" routine, which instead has a specific structure which must be followed. These signatures and function definitions are found in Driver Signatures.

None of these kernel-to-driver functions seem to get any arguments passed to them. Instead, there are Functions for Getting Arguments in Signature functions which allow one of these functions to get at fairly generic parts of its calling arguments, if there are any.

Almost every driver will have some need to call the operating system Driver-to-Kernel Operations is the list of services which are available to the driver.

Warning

The specifics of the types, values of the various enumerations (unless specifically stated, like = 0), etc., are only here for illustrative purposes. No attempts should be made to make use of any specific knowledge gleaned from this documentation. These types are only meant to be passed in and out of the API, and their contents are to be handled only by the provided OS-specific functions.

Also, note that the function may be provided as macros in some implementations, or vice versa.

Writing a Portable Driver

First off, writing a portable driver means calling no function in an OS except what is available through this header file.

Secondly, all OS-called functions in your driver must be invoked and referenced through the signature routines.

Thirdly, there might be some rules which you can get away with ignoring or violating on one OS, yet will cause your code not to be portable to a different OS.

Limitations

This API is not expected to handle every type of driver which may be found in an operating system. For example, it will not be able to handle the usual design for something like a UART driver, where there are multiple logical devices to access, because the design usually calls for some sort of indication to the OS_DEV_TASK() function or OS_DEV_ISR() to indicate which channel is to be serviced by that instance of the task/function. This sort of argument is missing in this API for functions like os_dev_schedule_task() and os_register_interrupt().

Porting Guidelines

This section is intended for a developer who needs to port the header file to an operating system which is not yet supported.

This interface allows for a lot of flexibility when it comes to porting to an operating systems device driver interface. There are three main areas to examine: The use of Driver Routine Signatures, the use of Driver Argument Access functions, the Calls to Kernel Functions, and Data Types.

Porting Driver Routine Signatures

The three macros for each function (e.g. OS_DEV_INIT(), OS_DEV_INIT_DCL(), and OS_DEV_INIT_REF()) allow the flexibility of having a 'wrapper' function with the OS-required signature, which would then call the user's function with some different signature.

The first form would lay down the wrapper function, followed by the signature for the user function. The second form would lay down just the signatures for both functions, and the last function would reference the wrapper function, since that is the interface function called by the OS.

Note that the driver author has no visibility at all to the signature of the routines. The author can access arguments only through a limited set of functions, and must return via another function.

The Return Functions allow a lot of flexibility in converting the return value, or not returning a value at all. These will likely be implemented as macros.

Porting Driver Argument Access Functions

The signatures defined by the guide will usually be replaced with macro definitions.

Porting Calls to Kernel Functions

The signatures defined by the guide may be replaced with macro definitions, if that makes more sense.

Implementors are free to ignore arguments which are not applicable to their OS.

Porting Data Types

#define this flag to build your driver as a Linux driver

#define PORTABLE_OS_VERSION   101

Symbol to give version number of the implementation file. Earliest definition is in version 1.1, with value 101 (to mean version 1.1)


Typedef Documentation

typedef void* os_driver_reg_t

Driver registration handle

typedef void(* os_init_function_t)(void)

Function signature for an OS_DEV_INIT() function.

Returns:
A call to os_dev_init_return() function.
typedef void(* os_interrupt_handler_t)(void)

Function signature for the portable interrupt handler

While it would be nice to know which interrupt is being serviced, the Least Common Denominator rule says that no arguments get passed in.

Returns:
A call to os_dev_isr_return()
typedef int os_interrupt_id_t

Type used for registering and deregistering interrupts.

This is typically an interrupt channel number.

typedef int os_lock_context_t

Context while locking.

typedef int* os_lock_t

Handle to a lock.

typedef int os_process_handle_t

Type used as handle for a process

See os_get_process_handle() and os_send_signal().

typedef void(* os_shutdown_function_t)(void)

Function signature for an OS_DEV_SHUTDOWN() function.

Returns:
A call to os_dev_shutdown_return() function.
typedef int os_sleep_object_t

An object which can be slept on and later used to wake any/all sleepers.

typedef void(* os_task_fn_t)(void)

Function signature for a task function

Many task function definitions get some sort of generic argument so that the same function can run across many (queues, channels, ...) as separate task instances. This has been left out of this API.

This function must be structured as documented by OS_DEV_TASK().

typedef void(* os_user_function_t)(void)

Function signature for a user-driver function.

Returns:
A call to the appropriate os_dev_xxx_return() function.

Enumeration Type Documentation

Function types which can be associated with driver entry points. These are used in os_driver_add_registration().

Note that init and shutdown are absent.

Enumerator:
OS_FN_OPEN 

open() operation handler.

OS_FN_CLOSE 

close() operation handler.

OS_FN_READ 

read() operation handler.

OS_FN_WRITE 

write() operation handler.

OS_FN_IOCTL 

ioctl() operation handler.

OS_FN_MMAP 

mmap() operation handler.

Generic return code for functions which need such a thing.

No knowledge should be assumed of the value of any of these symbols except that OS_ERROR_OK_S is guaranteed to be zero.

Enumerator:
OS_ERROR_OK_S 

Success

OS_ERROR_FAIL_S 

Generic driver failure

OS_ERROR_NO_MEMORY_S 

Failure to acquire/use memory

OS_ERROR_BAD_ADDRESS_S 

Bad address

OS_ERROR_BAD_ARG_S 

Bad input argument

OS_ERROR_OK_S 

Success

OS_ERROR_FAIL_S 

Generic driver failure

OS_ERROR_NO_MEMORY_S 

Failure to acquire/use memory

OS_ERROR_BAD_ADDRESS_S 

Bad address

OS_ERROR_BAD_ARG_S 

Bad input argument


Function Documentation

void os_cache_clean_range ( void *  start,
uint32_t  len 
)

Clean a range of addresses from the cache

Parameters:
start Starting virtual address
len Number of bytes to flush
void os_cache_flush_range ( void *  start,
uint32_t  len 
)

Flush a range of addresses from the cache

Parameters:
start Starting virtual address
len Number of bytes to flush
void os_cache_inv_range ( void *  start,
uint32_t  len 
)

Invalidate a range of addresses in the cache

Parameters:
start Starting virtual address
len Number of bytes to flush
void os_flush_cache_all ( void   ) 

Flush and invalidate all cache lines.

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