Main Page Modules Alphabetical List Data Structures File List Data Fields Globals
IXP425 Operating System Services Library (IxOSSL) APIThis service provides a layer of OS dependency services.
More...
|
Data Structures |
struct | ix_ossl_thread_main_info_t |
| This type defines thread main info. More...
|
struct | ix_ossl_time_t |
| This type defines OSSL time. More...
|
Defines |
#define | IX_OSSL_ERROR_SUCCESS |
| This symbol defines an error token that indicates the successful completion of the OSSL calls.
|
#define | IX_OSSL_ERROR_FAILURE |
| This symbol defines an error token that indicates the failed completion of the OSSL calls.
|
#define | IX_OSSL_WAIT_FOREVER |
| This symbol is useful for specifying an 'indefinite wait' timeout value in ix_ossl_sem_take and ix_ossl_mutex_lock function calls.
|
#define | IX_OSSL_WAIT_NONE |
| This symbol is useful for specifying a 'no wait' timeout value in ix_ossl_sem_take and ix_ossl_mutex_lock function calls.
|
#define | BILLION |
| Define a constant for the value 1 billion, used by OSSL TIME macros. Equivalent to (1000 million nanoseconds / second).
|
#define | TICKS_PER_NSEC |
| The number of OS Ticks per nano-second on Linux.
|
#define | IX_OSSL_TIME_EQ(a, b) |
| Compares a operand with b operand. Returns true if they are equal and false otherwise.
|
#define | IX_OSSL_TIME_GT(a, b) |
| Compares a operand with b operand. Returns true if a > b, and false otherwise.
|
#define | IX_OSSL_TIME_LT(a, b) |
| Compares a operand with b operand. Returns true if a < b, and false otherwise.
|
#define | IX_OSSL_TIME_ISZERO(a) |
| This macro checks if the operand a is zero. Returns true if a is zero (both sec and nsec fields must be zero) and false otherwise.
|
#define | IX_OSSL_TIME_SET(a, b) |
| This macro sets operand a to the value of operand b.
|
#define | IX_OSSL_TIME_ADD(a, b) |
| This macro performs a += b operation.
|
#define | IX_OSSL_TIME_SUB(a, b) |
| This macro performs a -= b operation.
|
#define | IX_OSSL_TIME_NORMALIZE(a) |
| This macro normalizes the value of a. If 'a.nsec' > 10^9, it is decremented by 10^9 and 'a.sec' is incremented by 1.
|
#define | IX_OSSL_TIME_VALID(a) |
| This macro checks whether a is a valid ix_ossl_time_t i.e. 0 =< a.nsec < 10^9. Returns true if a is valid and false otherwise.
|
#define | IX_OSSL_TIME_ZERO(a) |
| This macro sets the value of a to zero.
|
#define | IX_OSSL_TIME_CONVERT_TO_TICK(a, b) |
| This macro converts b value in ix_ossl_time_t to a value in os ticks.
|
Typedefs |
typedef os_thread_t | ix_ossl_thread_t |
| This type defines OSSL thread type.
|
typedef os_sem_t | ix_ossl_sem_t |
| This type defines OSSL semaphore type.
|
typedef os_mutex_t | ix_ossl_mutex_t |
| This type defines OSSL mutex type.
|
typedef ix_error(* | ix_ossl_thread_entry_point_t )(void *arg, void **ptrRetObj) |
| This function type defines OSSL thread entry point function. .
|
typedef unsigned int | ix_ossl_size_t |
| This type describes a generic size type.
|
Enumerations |
enum | ix_ossl_error_code {
IX_OSSL_ERROR_SUCCESS,
IX_OSSL_ERROR_INVALID_ARGUMENTS,
IX_OSSL_ERROR_INVALID_OPERATION,
IX_OSSL_ERROR_THREAD_CALL_FAILURE,
IX_OSSL_ERROR_INVALID_PID,
IX_OSSL_ERROR_INVALID_TID,
IX_OSSL_ERROR_OS_CALL_FAILURE,
IX_OSSL_ERROR_TIMEOUT,
IX_OSSL_ERROR_NOMEM,
IX_OSSL_ERROR_NOSYS
} |
| This type defines error codes returned by OSSL calls. More...
|
enum | ix_ossl_sem_state {
IX_OSSL_SEM_UNAVAILABLE,
IX_OSSL_SEM_AVAILABLE
} |
| This type defines OSSL binary semaphore states. More...
|
enum | ix_ossl_mutex_state {
IX_OSSL_MUTEX_UNLOCK,
IX_OSSL_MUTEX_LOCK
} |
| This type defines OSSL mutex states. More...
|
enum | ix_ossl_thread_priority {
IX_OSSL_THREAD_PRI_HIGH,
IX_OSSL_THREAD_PRI_MEDIUM,
IX_OSSL_THREAD_PRI_LOW
} |
| This type define OSSL thread priority levels. More...
|
Functions |
IX_EXPORT_FUNCTION ix_error | ix_ossl_thread_create (ix_ossl_thread_entry_point_t entryPoint, void *arg, ix_ossl_thread_t *ptrTid) |
| create a thread
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_thread_get_id (ix_ossl_thread_t *ptrTid) |
| get id of calling thread
|
IX_EXPORT_FUNCTION void * | ix_ossl_thread_main_wrapper (void *ptrThreadInfo) |
| wrapper for user-provided thread function
|
IX_EXPORT_FUNCTION void | ix_ossl_thread_exit (ix_error retError, void *retObj) |
| Causes the calling thread to exit.
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_thread_kill (ix_ossl_thread_t tid) |
| kills the specified thread
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_thread_set_priority (ix_ossl_thread_t tid, ix_ossl_thread_priority priority) |
| sets the priority of the specified thread
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_thread_delay (int ticks) |
| delay the current task for specified number of OS ticks
|
IX_EXPORT_FUNCTION int | os_thread_create (void *(*start_routine)(void *), ix_ossl_thread_main_info_t *ptrThreadInfo, ix_ossl_thread_t *ptrTid, os_error *osError) |
| creates a thread (use ix_ossl_thread_create instead)
|
IX_EXPORT_FUNCTION int | os_thread_get_id (ix_ossl_thread_t *ptrTid) |
| get thread id (use ix_ossl_thread_get_id instead)
|
IX_EXPORT_FUNCTION int | os_thread_exit (void *ptrRetObj) |
| exits the calling thread (use ix_ossl_thread_exit instead)
|
IX_EXPORT_FUNCTION int | os_thread_kill (ix_ossl_thread_t tid, os_error *osError) |
| kill the specified thread (use ix_ossl_thread_kill instead)
|
IX_EXPORT_FUNCTION ix_error | os_thread_set_priority (ix_ossl_thread_t *tid, ix_ossl_thread_priority priority, os_error *osError) |
| sets priority of a thread (use ix_ossl_thread_set_priority instead)
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_tick_get (int *pticks) |
| gets number of OS ticks per second
|
IX_EXPORT_FUNCTION int | os_sleep (ix_uint32 sleeptime_ms, os_error *osError) |
| causes the calling thread to sleep for specified time (milliseconds)
|
IX_EXPORT_FUNCTION int | os_sleep_tick (ix_uint32 sleeptime_ticks, os_error *osError) |
| causes the calling thread to sleep for specified time (os ticks)
|
IX_EXPORT_FUNCTION int | os_time_get (ix_ossl_time_t *ptime, os_error *osError) |
| returns the system time with nano-second resolution
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_sem_init (int start_value, ix_ossl_sem_t *sid) |
| initialises a new semaphore
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_sem_take (ix_ossl_sem_t sid, ix_uint32 timeout) |
| take a semaphore, and block if semaphore not available
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_sem_give (ix_ossl_sem_t sid) |
| give back a semaphore
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_sem_flush (ix_ossl_sem_t sid, int *result) |
| unblocks all threads pending on the semaphore
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_sem_fini (ix_ossl_sem_t sid) |
| terminate the semaphore (free semaphore resources)
|
IX_EXPORT_FUNCTION int | os_thread_sema_create (int value, ix_ossl_sem_t *sid, os_error *osError) |
| create a thread semaphore
|
IX_EXPORT_FUNCTION int | os_thread_sema_P (ix_ossl_sem_t *sid, ix_uint32 timeout, os_error *osError) |
| pend on a semaphore (with timeout)
|
IX_EXPORT_FUNCTION int | os_thread_sema_V (ix_ossl_sem_t *sid, os_error *osError) |
| release a semaphore
|
IX_EXPORT_FUNCTION int | os_thread_sema_destroy (ix_ossl_sem_t *sid, os_error *osError) |
| destroy semaphore object
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_mutex_init (ix_ossl_mutex_state start_state, ix_ossl_mutex_t *mid) |
| initialises a new mutex object
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_mutex_lock (ix_ossl_mutex_t mid, ix_uint32 timeout) |
| lock a mutex
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_mutex_unlock (ix_ossl_mutex_t mid) |
| unlocks a mutex
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_mutex_fini (ix_ossl_mutex_t mid) |
| free a mutex
|
IX_EXPORT_FUNCTION int | os_thread_mutex_create (ix_ossl_mutex_state start_state, ix_ossl_mutex_t *mid, os_error *osError) |
| creates a thread mutex object
|
IX_EXPORT_FUNCTION int | os_thread_mutex_lock (ix_ossl_mutex_t *mutex, ix_uint32 timeout, os_error *osError) |
| lock a mutex
|
IX_EXPORT_FUNCTION int | os_thread_mutex_unlock (ix_ossl_mutex_t *mutex, os_error *osError) |
| unlock a mutex
|
IX_EXPORT_FUNCTION int | os_thread_mutex_destroy (ix_ossl_mutex_t *mutex, os_error *osError) |
| destroy a mutex object
|
ix_error | ix_ossl_sleep (ix_uint32 sleeptime_ms) |
| causes calling thread to sleep for specified time (milliseconds)
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_sleep_tick (ix_uint32 sleeptime_ticks) |
| causes calling thread to sleep for specified time (os ticks)
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_time_get (ix_ossl_time_t *ptime) |
| gets current system time with nano-second resolution
|
IX_EXPORT_FUNCTION void * | ix_ossl_malloc (ix_ossl_size_t arg_Size) |
| allocate a block of memory
|
IX_EXPORT_FUNCTION void | ix_ossl_free (void *arg_pMemory) |
| free a block of memory
|
IX_EXPORT_FUNCTION void * | ix_ossl_memcpy (void *arg_pDest, const void *arg_pSrc, ix_ossl_size_t arg_Count) |
| copy number of bytes from one memory location to another
|
IX_EXPORT_FUNCTION void * | ix_ossl_memset (void *arg_pDest, int arg_pChar, ix_ossl_size_t arg_Count) |
| fill a region of memory with a specified byte value
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_message_log_init (void) |
| initialise the error message logging facility
|
IX_EXPORT_FUNCTION ix_error | ix_ossl_message_log (char *arg_pFmtString,...) |
| log a printf-style message
|
Detailed Description
This service provides a layer of OS dependency services.
This file contains the prototypes of OS-independent wrapper functions which allow the programmer not to be tied to a specific operating system. The OSSL functions can be divided into three classes:
1) synchronization-related wrapper functions around thread system calls 2) thread-related wrapper functions around thread calls 3) transactor/workbench osapi calls -- defined in osApi.h
Both 1 and 2 classes of functions provide Thread Management, Thread Synchronization, Mutual Exclusion and Timer primitives. Namely, creation and deletion functions as well as the standard "wait" and "exit". Additionally, a couple of utility functions which enable to pause the execution of a thread are also provided.
The 3rd class provides a slew of other OSAPI functions to handle Transactor/WorkBench OS calls.
- Note:
- WHEREVER POSSIBLE, PLEASE USE THE EQUIVALENT API FUNCTION FROM THE IXP425 OS Services (IxOsServices) API COMPONENT INSTEAD IF ONE EXISTS.
Define Documentation
|
Define a constant for the value 1 billion, used by OSSL TIME macros. Equivalent to (1000 million nanoseconds / second).
Definition at line 394 of file ix_ossl.h. |
#define IX_OSSL_ERROR_FAILURE
|
|
|
This symbol defines an error token that indicates the failed completion of the OSSL calls.
Definition at line 351 of file ix_ossl.h. |
#define IX_OSSL_ERROR_SUCCESS
|
|
|
This symbol defines an error token that indicates the successful completion of the OSSL calls.
Definition at line 342 of file ix_ossl.h. |
#define IX_OSSL_TIME_ADD |
( |
a, |
|
|
b |
|
) |
|
|
|
This macro performs a += b operation.
- Parameters:
-
Definition at line 485 of file ix_ossl.h. |
#define IX_OSSL_TIME_CONVERT_TO_TICK |
( |
a, |
|
|
b |
|
) |
|
|
#define IX_OSSL_TIME_EQ |
( |
a, |
|
|
b |
|
) |
|
|
|
Compares a operand with b operand. Returns true if they are equal and false otherwise.
- Parameters:
-
- Returns:
- true if a == b and false otherwise.
Definition at line 416 of file ix_ossl.h. |
#define IX_OSSL_TIME_GT |
( |
a, |
|
|
b |
|
) |
|
|
|
Compares a operand with b operand. Returns true if a > b, and false otherwise.
- Parameters:
-
- Returns:
- true if a > b and false otherwise.
Definition at line 431 of file ix_ossl.h. |
#define IX_OSSL_TIME_ISZERO |
( |
a |
|
) |
|
|
|
This macro checks if the operand a is zero. Returns true if a is zero (both sec and nsec fields must be zero) and false otherwise.
- Parameters:
-
- Returns:
- true if a is zero and false otherwise.
Definition at line 461 of file ix_ossl.h. |
#define IX_OSSL_TIME_LT |
( |
a, |
|
|
b |
|
) |
|
|
|
Compares a operand with b operand. Returns true if a < b, and false otherwise.
- Parameters:
-
- Returns:
- true if a < b and false otherwise.
Definition at line 446 of file ix_ossl.h. |
#define IX_OSSL_TIME_NORMALIZE |
( |
a |
|
) |
|
|
|
This macro normalizes the value of a. If 'a.nsec' > 10^9, it is decremented by 10^9 and 'a.sec' is incremented by 1.
- Parameters:
-
Definition at line 523 of file ix_ossl.h. |
#define IX_OSSL_TIME_SET |
( |
a, |
|
|
b |
|
) |
|
|
|
This macro sets operand a to the value of operand b.
- Parameters:
-
Definition at line 473 of file ix_ossl.h. |
#define IX_OSSL_TIME_SUB |
( |
a, |
|
|
b |
|
) |
|
|
|
This macro performs a -= b operation.
- Parameters:
-
Definition at line 502 of file ix_ossl.h. |
#define IX_OSSL_TIME_VALID |
( |
a |
|
) |
|
|
|
This macro checks whether a is a valid ix_ossl_time_t i.e. 0 =< a.nsec < 10^9. Returns true if a is valid and false otherwise.
- Parameters:
-
- Returns:
- true if a is valid ix_ossl_time_t and false otherwise
Definition at line 541 of file ix_ossl.h. |
#define IX_OSSL_TIME_ZERO |
( |
a |
|
) |
|
|
|
This macro sets the value of a to zero.
- Parameters:
-
Definition at line 553 of file ix_ossl.h. |
#define IX_OSSL_WAIT_FOREVER
|
|
|
This symbol is useful for specifying an 'indefinite wait' timeout value in ix_ossl_sem_take and ix_ossl_mutex_lock function calls.
Definition at line 361 of file ix_ossl.h. |
#define IX_OSSL_WAIT_NONE
|
|
|
This symbol is useful for specifying a 'no wait' timeout value in ix_ossl_sem_take and ix_ossl_mutex_lock function calls.
Definition at line 370 of file ix_ossl.h. |
|
The number of OS Ticks per nano-second on Linux.
Definition at line 402 of file ix_ossl.h. |
Typedef Documentation
|
This type defines OSSL mutex type.
Definition at line 215 of file ix_ossl.h. |
|
This type defines OSSL semaphore type.
Definition at line 207 of file ix_ossl.h. |
|
This type describes a generic size type.
Definition at line 1255 of file ix_ossl.h. |
ix_ossl_thread_entry_point_t
|
|
|
This function type defines OSSL thread entry point function. .
- Parameters:
-
void | * arg (in) - pointer to a custom thread argument |
void | ** ptrRetObj (out) - address where a pointer to a custom data structure or object will be returned by the thread on exit. |
Definition at line 247 of file ix_ossl.h. |
|
This type defines OSSL thread type.
Definition at line 199 of file ix_ossl.h. |
Enumeration Type Documentation
|
This type defines error codes returned by OSSL calls.
- Enumeration values:
-
IX_OSSL_ERROR_SUCCESS |
success |
IX_OSSL_ERROR_INVALID_ARGUMENTS |
invalid arguments |
IX_OSSL_ERROR_INVALID_OPERATION |
invalid operation |
IX_OSSL_ERROR_THREAD_CALL_FAILURE |
thread operation failed |
IX_OSSL_ERROR_INVALID_PID |
invalid process id |
IX_OSSL_ERROR_INVALID_TID |
invalid thread id |
IX_OSSL_ERROR_OS_CALL_FAILURE |
invalid arguments |
IX_OSSL_ERROR_TIMEOUT |
OS operation failed. |
IX_OSSL_ERROR_NOMEM |
memory unavailable |
IX_OSSL_ERROR_NOSYS |
system resource unavailable |
Definition at line 277 of file ix_ossl.h. |
|
This type defines OSSL mutex states.
- Enumeration values:
-
IX_OSSL_MUTEX_UNLOCK |
Mutex unlocked. |
IX_OSSL_MUTEX_LOCK |
Mutex locked. |
Definition at line 312 of file ix_ossl.h. |
|
This type defines OSSL binary semaphore states.
- Enumeration values:
-
IX_OSSL_SEM_UNAVAILABLE |
Semaphore unavailable. |
IX_OSSL_SEM_AVAILABLE |
Semaphore available. |
Definition at line 298 of file ix_ossl.h. |
enum ix_ossl_thread_priority
|
|
|
This type define OSSL thread priority levels.
- Enumeration values:
-
IX_OSSL_THREAD_PRI_HIGH |
High priority thread. |
IX_OSSL_THREAD_PRI_MEDIUM |
Medium priority thread. |
IX_OSSL_THREAD_PRI_LOW |
Low priority thread. |
Definition at line 325 of file ix_ossl.h. |
Function Documentation
IX_EXPORT_FUNCTION void ix_ossl_free |
( |
void * |
arg_pMemory |
) |
|
|
|
free a block of memory
This function will free a memory block specified by the passed address. The ix_ossl_free function deallocates a memory block (arg_pMemory) that was previously allocated by a call to ix_ossl_malloc.If arg_pMemory is NULL, the pointer is ignored and ix_ossl_free immediately returns. Attempting to free an invalid pointer (a pointer to a memory block that was not allocated by ix_ossl_malloc) may affect subsequent allocation requests and cause errors.
See ixOsServCacheDmaFree for an alternative.
- Parameters:
-
arg_pMemory | void* (in) - address of the memory block to be deallocated. |
|
|
allocate a block of memory
This function will allocate a memory block. the function returns a void pointer to the allocated space, or NULL if there is insufficient memory available. To return a pointer to a type other than void, use a type cast on the return value. The storage space pointed to by the return value is guaranteed to be suitably aligned for storage of any type of object. If size is 0, ix_ossl_malloc allocates a zero-length item in the heap and returns a valid pointer to that item. Always check the return from ix_ossl_malloc, even if the amount of memory requested is small.
See ixOsServCacheDmaAlloc for an alternative.
- Parameters:
-
arg_Size | ix_ossl_size_t (in) - the size of the memory block requested. |
- Returns:
- Returns a valid address if successful or a NULL for failure.
|
IX_EXPORT_FUNCTION void* ix_ossl_memcpy |
( |
void * |
arg_pDest, |
|
|
const void * |
arg_pSrc, |
|
|
ix_ossl_size_t |
arg_Count |
|
) |
|
|
|
copy number of bytes from one memory location to another
This function will copy memory bytes between buffers. The ix_ossl_memcpy function copies count bytes of arg_pSrc to arg_pDest. If the source and destination overlap, this function does not ensure that the original source bytes in the overlapping region are copied before being overwritten.
- Parameters:
-
arg_pDest | void* (in|out) - destination buffer address |
arg_pSrc | const void* (in) - source buffer address |
arg_Count | ix_ossl_size_t - number of bytes to copy |
- Returns:
- Returns the address of the destination buffer.
|
IX_EXPORT_FUNCTION void* ix_ossl_memset |
( |
void * |
arg_pDest, |
|
|
int |
arg_pChar, |
|
|
ix_ossl_size_t |
arg_Count |
|
) |
|
|
|
fill a region of memory with a specified byte value
This function sets buffers to a specified character. The ix_ossl_memset function sets the first arg_Count bytes of arg_pDest to the character arg_Char.
- Parameters:
-
arg_pDest | void* (in|out) - destination buffer address |
arg_pChar | int (in) - character to set |
arg_Count | ix_ossl_size_t (in) - number of characters to set |
- Returns:
- Returns the address of the destination buffer.
|
IX_EXPORT_FUNCTION ix_error ix_ossl_message_log |
( |
char * |
arg_pFmtString, |
|
|
... |
|
|
) |
|
|
|
log a printf-style message
This routine is used to log a specified message. This routine's syntax is similar to printf() - a format string is followed by a variable number of arguments which will be interpreted and formated according to the fmt_string passed as the first argument. Further details will be provided on where the messages will be logged!
See ixOsServLog for an alternative.
- Parameters:
-
arg_pFmtString | char* (in) - format string for the log message |
- Returns:
- IX_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
IX_EXPORT_FUNCTION ix_error ix_ossl_message_log_init |
( |
void |
|
) |
|
|
|
initialise the error message logging facility
This function is used to initialize the error message logging. For each OS the messages will be logged into an implementation dependent stream. Further details will be provided on where the messages will be logged! This function should be called before any call to ix_ossl_message_log().
See ixOsServLogLevelSet for an alternative.
- Returns:
- IX_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
|
free a mutex
This function frees a mutex.'mid' is the id mutex id. The mutex is deleted, all resources are freed. Any threads pending on this mutex will be unblocked and return an error.
- Parameters:
-
mid | ix_ossl_mutex_t (in) - mutex id |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
|
initialises a new mutex object
This function initializes a new mutex. 'mid' is a pointer to an ix_ossl_mutex_t. Upon success, '*mid' will contain the mutex id. 'start_state' is the initial locking state.
- Note:
- Parameters:
-
start_state | ix_ossl_mutex_state (in) - 'start_state' is initial locking state. Valid values are :- 'OSSL_MUTEX_LOCK': Lock the mutex 'OSSL_MUTEX_UNLOCK': Leave the mutex unlocked |
mid | ix_ossl_mutex_t* (out) - pointer to id of the mutex created |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
IX_EXPORT_FUNCTION ix_error ix_ossl_mutex_lock |
( |
ix_ossl_mutex_t |
mid, |
|
|
ix_uint32 |
timeout |
|
) |
|
|
|
lock a mutex
This function locks the mutex. If the mutex is already locked, the thread will block. If the time indicated in 'timeout' is reached, the thread will unblock and return error indication. If the timeout is set to 'IX_OSSL_WAIT_NONE', the thread will never block (this is trylock). If the timeout is set to 'IX_OSSL_WAIT_FOREVER', the thread will block until the mutex is unlocked.
- Parameters:
-
mid | ix_ossl_mutex_t (in) - mutex id. |
timeout | ix_uint32 (in) - timeout value of type ix_uint32 expressed in miliseconds. |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
|
unlocks a mutex
This function unlocks the mutex. 'mid' is the mutex id. If there are threads pending on the mutex, the next one is given the lock. If there are no pending threads, then the mutex is unlocked.
- Parameters:
-
mid | ix_ossl_mutex_t (in) - mutex id |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
IX_EXPORT_FUNCTION ix_error ix_ossl_sem_fini |
( |
ix_ossl_sem_t |
sid |
) |
|
|
|
terminate the semaphore (free semaphore resources)
This function frees a semaphore.'sid' is semaphore id. The semaphore is terminated, all resources are freed. The threads pending on this semaphore will be released and return an error.
- Parameters:
-
sid | ix_ossl_sem_t (in) - semaphore id |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
IX_EXPORT_FUNCTION ix_error ix_ossl_sem_flush |
( |
ix_ossl_sem_t |
sid, |
|
|
int * |
result |
|
) |
|
|
|
unblocks all threads pending on the semaphore
This function unblocks all pending threads without altering the semaphore count. 'sid' is the id for the semaphore. '*result' will be non-zero if a thread was unblocked during this call.
- Parameters:
-
sid | ix_ossl_sem_t (in) - semaphore id |
result | int* (out) - the value referred will be non-zero if a thread was unblocked during this call |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
IX_EXPORT_FUNCTION ix_error ix_ossl_sem_give |
( |
ix_ossl_sem_t |
sid |
) |
|
|
|
give back a semaphore
This function causes the next available thread in the pend queue to be unblocked. If no thread is pending on this semaphore, the semaphore becomes 'full'.
- Parameters:
-
sid | ix_ossl_sem_t (in) - semaphore id. |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
IX_EXPORT_FUNCTION ix_error ix_ossl_sem_init |
( |
int |
start_value, |
|
|
ix_ossl_sem_t * |
sid |
|
) |
|
|
|
initialises a new semaphore
This function initializes a new semaphore. 'sid' is a pointer to an ix_ossl_sem_t. Upon success, '*sid' will be the semaphore id used in all other ix_ossl_sem functions. The newly created semaphore will be initialized the value of 'start_value'.
- Parameters:
-
start_value | int (in) - initial value of the semaphore |
sid | ix_ossl_sem_t* (out) - Address where the newly created semaphore id will returned. |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
IX_EXPORT_FUNCTION ix_error ix_ossl_sem_take |
( |
ix_ossl_sem_t |
sid, |
|
|
ix_uint32 |
timeout |
|
) |
|
|
|
take a semaphore, and block if semaphore not available
If the semaphore is 'empty', the calling thread is blocked. If the semaphore is 'full', it is taken and control is returned to the caller. If the time indicated in 'timeout' is reached, the thread will unblock and return an error indication. If the timeout is set to 'IX_OSSL_WAIT_NONE', the thread will never block; if it is set to 'IX_OSSL_WAIT_FOREVER', the thread will block until the semaphore is available.
- Parameters:
-
sid | ix_ossl_sem_t (in) - semaphore id. |
timeout | ix_uint32 (in) - timeout value of type ix_uint32 expressed in miliseconds |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
ix_error ix_ossl_sleep |
( |
ix_uint32 |
sleeptime_ms |
) |
|
|
|
causes calling thread to sleep for specified time (milliseconds)
This function causes the calling thread to sleep for the specified time.
- Parameters:
-
sleeptime_ms | ix_uint32 (in) - sleep time specified in milliseconds. |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
: In VxWorks this function has a resolution dictated by sysClkRateGet(). Very small delays could be truncated to 0 i.e. no delay at all. See ixOsServTaskSleep() for an alternative. |
IX_EXPORT_FUNCTION ix_error ix_ossl_sleep_tick |
( |
ix_uint32 |
sleeptime_ticks |
) |
|
|
|
causes calling thread to sleep for specified time (os ticks)
This function causes the calling thread to sleep for the time specified in OS ticks.
- Parameters:
-
sleeptime_ticks | ix_uint32 (in) - sleep time specified in os ticks. |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
|
create a thread
This function creates a cancellable thread that will execute the user-provided entry point function. Custom arguments can be passed to this function using the "arg" argument.
- Parameters:
-
entryPoint | ix_ossl_thread_entry_point_t (in) - thread's entry point function. |
arg | void* (in) - pointer to custom arguments that will be passed to entry point function as the first argument. |
ptrTid | ix_ossl_thread_t* (out) - address at which the thread id of the newly created thread will be returned |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
IX_EXPORT_FUNCTION ix_error ix_ossl_thread_delay |
( |
int |
ticks |
) |
|
|
|
delay the current task for specified number of OS ticks
This function causes the current task to delay for the specified number of OS ticks. Control of the CPU is relinquished during this time allowing other system tasks a chance to execute.
- Parameters:
-
ticks | int (in) - number of OS ticks to delay task. |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or IX_OSSL_ERROR_FAILURE for failure.
|
IX_EXPORT_FUNCTION void ix_ossl_thread_exit |
( |
ix_error |
retError, |
|
|
void * |
retObj |
|
) |
|
|
|
Causes the calling thread to exit.
This function causes the calling thread to exit. It gives the opportunity to the caller to pass back to a waiting parent a pointer to a custom data structure and an ix_error token.
- Parameters:
-
retError | ix_error (in) - ix_error token to be returned to the waiting parent (0 if no error is returned) |
retObj | void* (in) - pointer to custom data structure returned to the waiting parent on thread exit.It is used for post-mortem debugging.(null if no data structure is returned) |
- Returns:
- none
|
|
get id of calling thread
This function returns id of the calling thread.
- Parameters:
-
ptrTid | ix_ossl_thread_t* (out) - address at which the id of the calling thread will be returned |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
|
kills the specified thread
Kills the running thread specified by its thread id. Because the thread will be killed instantly, the caller must be extremely careful when using this function as the thread will not have time to release any of the resources it is currently owning. ix_ossl_thread_exit should be used to delete a thread and its resources instead!.
- Parameters:
-
tid | ix_ossl_thread_t (in) - id of the thread to be killed |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
- Warning:
- This function does not kill linux kernel threads. It only sends the SIG_TERM signal and it is the resposibility of the thread to check for this signal (see signal_pending) and terminate itself.
|
IX_EXPORT_FUNCTION void* ix_ossl_thread_main_wrapper |
( |
void * |
ptrThreadInfo |
) |
|
|
|
wrapper for user-provided thread function
This function provides the needed pthread-compliant entry point function. It basically acts as a wrapper around the user-provided function. It still does one important thing which is to set the cancellation type of the thread to ASYNCHRONOUS (which translates into instantaneous")
- Parameters:
-
ptrThreadInfo | void* (in) - pointer to our temporary structure containing pointers to the thread's entry point function and its argument structure |
- Returns:
- void *
|
|
sets the priority of the specified thread
This function sets the priority of the indicated thread. Possible values for 'priority' are IX_OSSL_THREAD_PRI_HIGH, IX_OSSL_THREAD_PRI_MED, and IX_OSSL_THREAD_PRI_LOW.
- Parameters:
-
tid | ix_ossl_thread_t (in) - id of the thread |
priority | ix_ossl_thread_priority (in) - valid priority values are: IX_OSSL_THREAD_PRI_HIGH, IX_OSSL_THREAD_PRI_MED, and IX_OSSL_THREAD_PRI_LOW. |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
IX_EXPORT_FUNCTION ix_error ix_ossl_tick_get |
( |
int * |
pticks |
) |
|
|
|
gets number of OS ticks per second
This function returns the number of os ticks per second.
- Parameters:
-
pticks | int* (out) - pointer to location where data will be returned. |
- Returns:
- IX_OSSL_ERROR_SUCCESS.
|
IX_EXPORT_FUNCTION ix_error ix_ossl_time_get |
( |
ix_ossl_time_t * |
ptime |
) |
|
|
|
gets current system time with nano-second resolution
This function places the current value of a timer, in seconds and nano-seconds, into an ix_ossl_time_t structure pointed by 'ptime'. This function does not provide a time-of-day. The intention is to provide a nano-second resolution time.
- Parameters:
-
ptime | ix_ossl_time_t* (out) - pointer to 'ix_ossl_time_t' structure where data will be returned. |
- Returns:
- IX_OSSL_ERROR_SUCCESS if successful or a valid ix_error token for failure.
|
IX_EXPORT_FUNCTION int os_sleep |
( |
ix_uint32 |
sleeptime_ms, |
|
|
os_error * |
osError |
|
) |
|
|
|
causes the calling thread to sleep for specified time (milliseconds)
This function causes the calling thread to sleep for the specified time.
- Parameters:
-
sleeptime_ms | ix_uint32 (in) - sleep time specified in milliseconds. |
osError | os_error* (out) - pointer to the datastructure where the error conditions are returned. |
|
IX_EXPORT_FUNCTION int os_sleep_tick |
( |
ix_uint32 |
sleeptime_ticks, |
|
|
os_error * |
osError |
|
) |
|
|
|
causes the calling thread to sleep for specified time (os ticks)
This function causes the calling thread to sleep for the time specified in OS ticks.
- Parameters:
-
sleeptime_ticks | ix_uint32 (in) - sleep time specified in OS ticks. |
osError | os_error* (out) - pointer to the datastructure where the error conditions are returned. |
|
|
creates a thread (use ix_ossl_thread_create instead)
Create a cancellable thread that will execute the user-provided entry point function. Custom arguments can be passed to this function using the "arg" argument.
- Parameters:
-
start_routine | void * (*)(void *) (in ) - pointer to thread's entry point function |
ptrThreadInfo | ix_ossl_thread_main_info_t* (in) - pointer to custom argument structure that will be passed to entry point function |
ptrTid | ix_ossl_thread_t* (out) - address at which the thread id of the newly created thread will be returned |
osError | os_error* (out) - pointer to the datastructure where OS error codes are returned. |
|
IX_EXPORT_FUNCTION int os_thread_exit |
( |
void * |
ptrRetObj |
) |
|
|
|
exits the calling thread (use ix_ossl_thread_exit instead)
This function causes the calling thread to exit. It gives the opportunity (this is not a requirement!) to the caller to pass back to a waiting parent a pointer to a custom data structure and an ix_error token.
- Parameters:
-
ptrRetObj | void* (out) - pointer to custom data structure (null if no data structure is returned) |
|
|
get thread id (use ix_ossl_thread_get_id instead)
Returns the thread id of the calling thread
- Parameters:
-
ptrTid | ix_ossl_thread_t* (out) - address at which the thread id of the inquiring thread will be returned |
|
IX_EXPORT_FUNCTION int os_thread_kill |
( |
ix_ossl_thread_t |
tid, |
|
|
os_error * |
osError |
|
) |
|
|
|
kill the specified thread (use ix_ossl_thread_kill instead)
Kills the running thread specified by its thread id.
- Parameters:
-
tid | ix_ossl_thread_t (in) - id of the thread to be killed |
osError | os_error* (out) - pointer to the datastructure where OS error conditions are returned. |
|
|
creates a thread mutex object
Create a thread mutex object.
See ixOsServMutexInit for an alternative.
- Parameters:
-
start_state | ix_ossl_mutex_state (in) - the value that the mutex state should be initialized to. |
mid | ix_ossl_mutex_t* (out) - id of the thread mutex created. |
osError | os_error* (out) - pointer to the datastructure where the error conditions are returned. |
|
IX_EXPORT_FUNCTION int os_thread_mutex_destroy |
( |
ix_ossl_mutex_t * |
mutex, |
|
|
os_error * |
osError |
|
) |
|
|
|
destroy a mutex object
Destroy the thread mutex object.
see ixOsServMutexDestroy for an alternative
- Parameters:
-
mutex | ix_ossl_mutex_t* (in) - pointer to the thread mutex object. |
osError | os_error* (out) - pointer to the datastructure where the error conditions are returned. |
|
IX_EXPORT_FUNCTION int os_thread_mutex_lock |
( |
ix_ossl_mutex_t * |
mutex, |
|
|
ix_uint32 |
timeout, |
|
|
os_error * |
osError |
|
) |
|
|
|
lock a mutex
This function locks the mutex. If the mutex is already locked, the task will block. If the time indicated in 'timeout' is reached, the task will unblock and retun error indication. If timeout is set to '0', the task will never block.
See ixOsServMutexLock for an alternative.
- Parameters:
-
mutex | ix_ossl_mutex_t* (in) - pointer to the thread mutex object. |
timeout | ix_uint32 (in) - 'timeout' value |
osError | os_error* (out) - pointer to the datastructure where the error conditions are returned. |
|
IX_EXPORT_FUNCTION int os_thread_mutex_unlock |
( |
ix_ossl_mutex_t * |
mutex, |
|
|
os_error * |
osError |
|
) |
|
|
|
unlock a mutex
This function unlocks the mutex. If there are tasks pending on the mutex, the next one is given the lock. If there are no pending tasks, then the mutex is unlocked.
See ixOsServMutexUnlock for an alternative.
- Parameters:
-
mutex | ix_ossl_mutex_t* (in) - pointer to the thread mutex object. |
osError | os_error* (out) - pointer to the datastructure where the error conditions are returned. |
|
IX_EXPORT_FUNCTION int os_thread_sema_create |
( |
int |
value, |
|
|
ix_ossl_sem_t * |
sid, |
|
|
os_error * |
osError |
|
) |
|
|
|
create a thread semaphore
Create a thread semaphore object.
- Parameters:
-
value | int (in) - value that the semaphore should be initialize to. |
sid | ix_ossl_sem_t* (out) - id of the thread semaphore created. |
osError | os_error* (out) - pointer to the datastructure where the error conditions are returned. |
|
IX_EXPORT_FUNCTION int os_thread_sema_destroy |
( |
ix_ossl_sem_t * |
sid, |
|
|
os_error * |
osError |
|
) |
|
|
|
destroy semaphore object
Destroy the thread semaphore object.
- Parameters:
-
sid | ix_ossl_sem_t* (in) - pointer to the thread semaphore object. |
osError | os_error* (out) - pointer to the datastructure where the error conditions are returned. |
|
IX_EXPORT_FUNCTION int os_thread_sema_P |
( |
ix_ossl_sem_t * |
sid, |
|
|
ix_uint32 |
timeout, |
|
|
os_error * |
osError |
|
) |
|
|
|
pend on a semaphore (with timeout)
Waits on the specified semaphore until the units are available or timeout occurs.
- Parameters:
-
sid | ix_ossl_sem_t* (in) - pointer to the semaphore object. |
timeout | ix_uint32 (in) - timeout value. |
osError | os_error* (out) - pointer to the datastructure where the error conditions are returned. |
|
IX_EXPORT_FUNCTION int os_thread_sema_V |
( |
ix_ossl_sem_t * |
sid, |
|
|
os_error * |
osError |
|
) |
|
|
|
release a semaphore
This function releases the specified semaphore and the semaphore state becomes available after this function call.
- Parameters:
-
sid | ix_ossl_sem_t* (in) - pointer to the thread semaphore object. |
osError | os_error* (out) - pointer to the datastructure where the error conditions are returned. |
|
|
sets priority of a thread (use ix_ossl_thread_set_priority instead)
This function sets the priority of the indicated thread. possible values for 'priority' are IX_OSSL_PRI_HIGH, IX_OSSL_PRI_MED, and IX_OSSL_PRI_LOW. The effect of priority is OS dependant.
- Parameters:
-
tid | ix_ossl_thread_t* (in) - pointer to the thread object |
priority | ix_ossl_thread_priority (in) - priority priority level. |
osError | os_error* (out) - pointer to the datastructure where OS error conditions are returned. |
|
IX_EXPORT_FUNCTION int os_time_get |
( |
ix_ossl_time_t * |
ptime, |
|
|
os_error * |
osError |
|
) |
|
|
|
returns the system time with nano-second resolution
This function places the current value of time, in (seconds, nanoseconds), into the '*ptime' structure. This function does not provide a time-of-day. The purpose is to provide a nano-second resolution time.
- Parameters:
-
ptime | ix_ossl_time_t* (out) - address to the time structure. |
osError | os_error* (out) - pointer to the datastructure where the error conditions are returned. |
|
|