Main Page   Modules   Alphabetical List   Data Structures   File List   Data Fields   Globals  

IXP425 Operating System Services Library (IxOSSL) API

This 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 BILLION
 

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

This macro performs a += b operation.

Parameters:
a ix_ossl_time_t (in|out) - operand a
b ix_ossl_time_t (in) - operand b

Definition at line 485 of file ix_ossl.h.

#define IX_OSSL_TIME_CONVERT_TO_TICK a,
 ) 
 

This macro converts b value in ix_ossl_time_t to a value in os ticks.

Parameters:
a unsigned int (out) - operand a
b ix_ossl_time_t (in) - operand b

Definition at line 570 of file ix_ossl.h.

#define IX_OSSL_TIME_EQ a,
 ) 
 

Compares a operand with b operand. Returns true if they are equal and false otherwise.

Parameters:
a ix_ossl_time_t (in) - operand a
b ix_ossl_time_t (in) - operand b
Returns:
true if a == b and false otherwise.

Definition at line 416 of file ix_ossl.h.

#define IX_OSSL_TIME_GT a,
 ) 
 

Compares a operand with b operand. Returns true if a > b, and false otherwise.

Parameters:
a ix_ossl_time_t (in) - operand a
b ix_ossl_time_t (in) - operand b
Returns:
true if a > b and false otherwise.

Definition at line 431 of file ix_ossl.h.

#define IX_OSSL_TIME_ISZERO  ) 
 

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:
a ix_ossl_time_t (in) - operand a
Returns:
true if a is zero and false otherwise.

Definition at line 461 of file ix_ossl.h.

#define IX_OSSL_TIME_LT a,
 ) 
 

Compares a operand with b operand. Returns true if a < b, and false otherwise.

Parameters:
a ix_ossl_time_t (in) - operand a
b ix_ossl_time_t (in) - operand b
Returns:
true if a < b and false otherwise.

Definition at line 446 of file ix_ossl.h.

#define IX_OSSL_TIME_NORMALIZE  ) 
 

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:
a ix_ossl_time_t (in|out) - operand a

Definition at line 523 of file ix_ossl.h.

#define IX_OSSL_TIME_SET a,
 ) 
 

This macro sets operand a to the value of operand b.

Parameters:
a ix_ossl_time_t (out) - operand a
b ix_ossl_time_t (in) - operand b

Definition at line 473 of file ix_ossl.h.

#define IX_OSSL_TIME_SUB a,
 ) 
 

This macro performs a -= b operation.

Parameters:
a ix_ossl_time_t (in|out) - operand a
b ix_ossl_time_t (in) - operand b

Definition at line 502 of file ix_ossl.h.

#define IX_OSSL_TIME_VALID  ) 
 

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:
a ix_ossl_time_t (in) - operand a
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  ) 
 

This macro sets the value of a to zero.

Parameters:
a ix_ossl_time_t (in|out) - operand a

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.

#define TICKS_PER_NSEC
 

The number of OS Ticks per nano-second on Linux.

Definition at line 402 of file ix_ossl.h.


Typedef Documentation

ix_ossl_mutex_t
 

This type defines OSSL mutex type.

Definition at line 215 of file ix_ossl.h.

ix_ossl_sem_t
 

This type defines OSSL semaphore type.

Definition at line 207 of file ix_ossl.h.

ix_ossl_size_t
 

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.

ix_ossl_thread_t
 

This type defines OSSL thread type.

Definition at line 199 of file ix_ossl.h.


Enumeration Type Documentation

enum ix_ossl_error_code
 

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.

enum ix_ossl_mutex_state
 

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.

enum ix_ossl_sem_state
 

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.

IX_EXPORT_FUNCTION void* ix_ossl_malloc ix_ossl_size_t  arg_Size  ) 
 

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.

IX_EXPORT_FUNCTION ix_error ix_ossl_mutex_fini ix_ossl_mutex_t  mid  ) 
 

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.

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

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.

IX_EXPORT_FUNCTION ix_error ix_ossl_mutex_unlock ix_ossl_mutex_t  mid  ) 
 

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.

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

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

IX_EXPORT_FUNCTION ix_error ix_ossl_thread_get_id ix_ossl_thread_t ptrTid  ) 
 

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.

IX_EXPORT_FUNCTION ix_error ix_ossl_thread_kill ix_ossl_thread_t  tid  ) 
 

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 *

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

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.

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)

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)

IX_EXPORT_FUNCTION int os_thread_get_id ix_ossl_thread_t ptrTid  ) 
 

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.

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

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.

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)

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.

Automatically generated from sources. © Intel Corp. 2003