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) |
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 LINUX |
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.
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.
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.
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().
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.
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.
The signatures defined by the guide will usually be replaced with macro definitions.
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.
#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 void* os_driver_reg_t |
Driver registration handle
typedef void(* os_init_function_t)(void) |
Function signature for an OS_DEV_INIT() 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.
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.
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.
enum os_driver_fn_t |
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.
enum os_error_code |
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.
void os_cache_clean_range | ( | void * | start, | |
uint32_t | len | |||
) |
Clean a range of addresses from the cache
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
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
start | Starting virtual address | |
len | Number of bytes to flush |
void os_flush_cache_all | ( | void | ) |
Flush and invalidate all cache lines.
© Freescale Semiconductor, Inc., 2007.
All rights reserved. Freescale Confidential Proprietary NDA Required |
![]() |