Defines, Structures, Typedefs, Functions. More...

Files
file	clOsalApi.h
	Operating System Abstraction Layer API.
file	clOsalErrors.h
	Header file of Error codes returned by Clovis OS Abstraction Layer.

Macros
#define	CL_OSAL_ERR_CONDITION_BROADCAST 0x10e
	Error returned when unable to restart all threads waiting on a condition variable.
#define	CL_OSAL_ERR_CONDITION_CREATE 0x10b
	Error returned when initializing condition variable fails.
#define	CL_OSAL_ERR_CONDITION_DELETE 0x10c
	Error returned when destroying condition variable fails.
#define	CL_OSAL_ERR_CONDITION_SIGNAL 0x10f
	Error returned when unable to restart a thread waiting on a condition variable.
#define	CL_OSAL_ERR_CONDITION_TIMEDOUT 0x132
	Error returned when the thread is not signalled within a time period specified.
#define	CL_OSAL_ERR_CONDITION_WAIT 0x10d
	Error returned when waiting on a condition variable fails.
#define	CL_OSAL_ERR_COS_CLEANUP 0x111
	Error returned when finalization of osal library fails.
#define	CL_OSAL_ERR_COS_INIT 0x127
	Error returned when initialization of osal library failed.
#define	CL_OSAL_ERR_CREATE_MUTEX 0x101
	Error returned when creation of mutex fails.
#define	CL_OSAL_ERR_MEM_POOL_CREATE 0x128
	Error returned when creation of memory pool fails.
#define	CL_OSAL_ERR_MEM_POOL_DELETE 0x130
	Error returned when deleting of memory pool fails.
#define	CL_OSAL_ERR_MEM_POOL_DETACH 0x129
	Error returned when detaching of memory pool fails.
#define	CL_OSAL_ERR_MUTEX_CREATE 0x107
	Error returned when creation of mutex fails.
#define	CL_OSAL_ERR_MUTEX_DELETE 0x10a
	Error returned when deletion of mutex fails.
#define	CL_OSAL_ERR_MUTEX_LOCK 0x108
	Error returned when locking of mutex fails.
#define	CL_OSAL_ERR_MUTEX_UNLOCK 0x109
	Error returned when unlocking of mutex fails.
#define	CL_OSAL_ERR_NAME_TOO_LONG 0x131
	Error returned when the name given in semaphore creation is greater than 20.
#define	CL_OSAL_ERR_NO_TASK_EXIST 0x113
	Error returned when the task referred to does not exist.
#define	CL_OSAL_ERR_OS_ERROR 0x100
	Error returned when the osal library is not initialized.
#define	CL_OSAL_ERR_PROCESS_CREATE 0x11c
	Error returned when process creation fails.
#define	CL_OSAL_ERR_PROCESS_DELETE 0x11d
	Error returned when deletion fails.
#define	CL_OSAL_ERR_PROCESS_WAIT 0x11e
	Error returned when waiting on a child process fails.
#define	CL_OSAL_ERR_SCHEDULE_POLICY 0x110
	Not used.
#define	CL_OSAL_ERR_SEM_CREATE 0x116
	Error returned when creation of semaphore fails.
#define	CL_OSAL_ERR_SEM_DELETE 0x11b
	Error returned when deletion of a semaphore fails.
#define	CL_OSAL_ERR_SEM_GET_VALUE 0x11a
	Error returned when the value of semaphore cannot be obtained.
#define	CL_OSAL_ERR_SEM_ID_GET 0x117
	Error returned when the semaphore ID cannot be retrieved.
#define	CL_OSAL_ERR_SEM_LOCK 0x118
	Error returned when locking of a semaphore fails.
#define	CL_OSAL_ERR_SEM_UNLOCK 0x119
	Error returned when unlocking of a semaphore fails.
#define	CL_OSAL_ERR_SHM_ATTACH 0x122
	On failure in attaching a shared memory.
#define	CL_OSAL_ERR_SHM_CREATE 0x11f
	Error returned when creation of shared memory fails.
#define	CL_OSAL_ERR_SHM_DELETE 0x121
	Error returned when deletion of shared memory fails.
#define	CL_OSAL_ERR_SHM_DETACH 0x123
	On failure in detaching a shared memory.
#define	CL_OSAL_ERR_SHM_ID_GET 0x120
	Error returned when the ID of the shared memory cannot be retrieved.
#define	CL_OSAL_ERR_SHM_MODE_GET 0x125
	On failure in retrieving permissions of a shared memory.
#define	CL_OSAL_ERR_SHM_MODE_SET 0x124
	On failure in setting permissions to a shared memory.
#define	CL_OSAL_ERR_SHM_SIZE 0x126
	On failure in retrieving size of a shared memory.
#define	CL_OSAL_ERR_TASK_ATTRIBUTE_GET 0x112
	Error returned when task attribute cannot be retrieved.
#define	CL_OSAL_ERR_TASK_ATTRIBUTE_INIT 0x102
	Error returned when initialization of task attribute fails.
#define	CL_OSAL_ERR_TASK_ATTRIBUTE_SET 0x105
	Error returned when task attribute cannot be set.
#define	CL_OSAL_ERR_TASK_CREATE 0x103
	Error returned when creation of task fails.
#define	CL_OSAL_ERR_TASK_DELAY 0x106
	Error returned when delaying a task fails.
#define	CL_OSAL_ERR_TASK_DELETE 0x104
	Error returned when deletion of task fails.
#define	CL_OSAL_ERR_TASK_STACK_SIZE 0x114
	Error returned when stack size of thread creation attribute cannot be set.
#define	CL_OSAL_ERR_TIME_OF_DAY 0x115
	Error returned when time of day cannot be obtained.
#define	CL_OSAL_MIN_STACK_SIZE 196608
	This is required while Thread or Task creation.
#define	CL_OSAL_NAME_MAX 32
	The maximum length of thread/task names.
#define	CL_OSAL_SHM_EXCEPTION_LENGTH 2048
	Shared memory area definition.

Typedefs
typedef ClOsalCondT *	ClOsalCondIdT
	The type of an identifier to the OSAL condition ID.
typedef pthread_cond_t	ClOsalCondT
	The thread condition type wrapped.
typedef ClOsalMutexT *	ClOsalMutexIdT
	The type of an identifier to the OSAL Mutex ID.
typedef ClUint32T	ClOsalPidT
	The type of an identifier to the OSAL Process ID.
typedef void(*	ClOsalProcessFuncT )(void *)
	CAllback type of callback function invoked when a process is created.
typedef ClHandleT	ClOsalSemIdT
	The type of an identifier to the OSAL Semaphore ID.
typedef enum ClOsalSharedMutexFlags	ClOsalSharedMutexFlagsT
	The mutex type to be initialized.
typedef ClUint32T	ClOsalShmIdT
	The type of an identifier to the OSAL Shared Memory ID.
typedef ClPtrT	ClOsalTaskDataT
	The type of an identifier to the OSAL Task Data type.
typedef ClUint64T	ClOsalTaskIdT
	The type of an identifier to the OSAL Task ID.
typedef void(*	ClOsalTaskKeyDeleteCallBackT )(void *)
	CAllback type of callback function invoked when the task specific private key is destruyed.

Enumerations
enum	ClOsalProcessFlagT { CL_OSAL_PROCESS_WITH_NEW_SESSION = CL_BIT(0), CL_OSAL_PROCESS_WITH_NEW_GROUP = CL_BIT(1) }
	Process creation flags. More...
enum	ClOsalSchedulePolicyT { CL_OSAL_SCHED_OTHER = SCHED_OTHER, CL_OSAL_SCHED_FIFO = SCHED_FIFO, CL_OSAL_SCHED_RR = SCHED_RR }
	The following enumeration type contains schedule policy of the tasks that will be created. More...
enum	ClOsalSharedMutexFlags
	The mutex type to be initialized.
enum	ClOsalShmSecurityModeFlagT { CL_OSAL_SHM_MODE_READ_USER = 0x0100, CL_OSAL_SHM_MODE_READ_GROUP = 0x0020, CL_OSAL_SHM_MODE_READ_OTHERS = 0x0004, CL_OSAL_SHM_MODE_WRITE_USER = 0x0080, CL_OSAL_SHM_MODE_WRITE_GROUP = 0x0010, CL_OSAL_SHM_MODE_WRITE_OTHERS = 0x0002 }
	Shared memory security options. More...
enum	ClOsalThreadPriorityT { CL_OSAL_THREAD_PRI_NOT_APPLICABLE = 0, CL_OSAL_THREAD_PRI_HIGH = 160, CL_OSAL_THREAD_PRI_MEDIUM = 80, CL_OSAL_THREAD_PRI_LOW = 1 }
	The following enumeration type contains the various thread priorities. More...

Functions
ClRcT	clOsalCondBroadcast (ClOsalCondIdT conditionId)
	Broadcasts a condition.
ClRcT	clOsalCondCreate (ClOsalCondIdT *pConditionId)
	Creates a condition variable.
ClRcT	clOsalCondDelete (ClOsalCondIdT conditionId)
	Deletes a condition variable.
ClRcT	clOsalCondDestroy (ClOsalCondT *pCond)
	Destroys a condition variable.
ClRcT	clOsalCondInit (ClOsalCondT *pCond)
	Initializes a condition variable.
ClRcT	clOsalCondSignal (ClOsalCondIdT conditionId)
	Signals a condition.
ClRcT	clOsalCondWait (ClOsalCondIdT conditionId, ClOsalMutexIdT mutexId, ClTimerTimeOutT time)
	Waits for a condition.
ClRcT	clOsalFinalize (void)
ClRcT	clOsalInitialize (const ClPtrT pConfig)
	Initializes the Operating System Abstraction Layer (OSAL).
ClRcT	clOsalMutexCreate (ClOsalMutexIdT *pMutexId)
	Creates a mutex.
ClRcT	clOsalMutexCreateAndLock (ClOsalMutexIdT *pMutexId)
	Creates a mutex in locked state.
ClRcT	clOsalMutexDelete (ClOsalMutexIdT mutexId)
	Deletes a mutex.
ClRcT	clOsalMutexDestroy (ClOsalMutexT *pMutex)
	Destroys a mutex.
ClRcT	clOsalMutexInit (ClOsalMutexT *pMutex)
	Initializes a mutex.
ClRcT	clOsalMutexLock (ClOsalMutexIdT mutexId)
	Locks a mutex.
ClRcT	clOsalMutexUnlock (ClOsalMutexIdT mutexId)
	Unlocks a mutex.
ClRcT	clOsalNanoTimeGet (ClNanoTimeT *pTime)
	Returns the time since Epoch, with a best resolution of 1 nanosecond.
ClRcT	clOsalPageSizeGet (ClInt32T *pSize)
ClRcT	clOsalPrintf (const ClCharT *fmt,...)
	Prints to the standard output.
ClRcT	clOsalProcessCreate (ClOsalProcessFuncT fpFunction, void functionArg, ClOsalProcessFlagT creationFlags, ClOsalPidT pProcessId)
	Creates a process.
ClRcT	clOsalProcessDelete (ClOsalPidT processId)
	Deletes a process.
ClRcT	clOsalProcessSelfIdGet (ClOsalPidT *pProcessId)
	Retrieves the processId.
ClRcT	clOsalProcessSharedCondInit (ClOsalCondT *pCond)
	Initializes a condition variable that can be used in multiple processes.
ClRcT	clOsalProcessSharedMutexInit (ClOsalMutexT pMutex, ClOsalSharedMutexFlagsT flags, ClUint8T pKey, ClUint32T keyLen, ClInt32T value)
	Initializes a process-shared mutex.
ClRcT	clOsalProcessWait (ClOsalPidT processId)
	Waits for a process to exit.
ClRcT	clOsalRecursiveMutexInit (ClOsalMutexT *pMutex)
	Initializes a mutex.
ClRcT	clOsalSelfTaskIdGet (ClOsalTaskIdT *pTaskId)
	Retrieves task id.
ClRcT	clOsalSemCreate (ClUint8T pName, ClUint32T value, ClOsalSemIdT pSemId)
	Creates a semaphore.
ClRcT	clOsalSemDelete (ClOsalSemIdT semId)
	Deletes a semaphore.
ClRcT	clOsalSemIdGet (ClUint8T pName, ClOsalSemIdT pSemId)
	Retrieves the semaphore id.
ClRcT	clOsalSemLock (ClOsalSemIdT semId)
	Locks a semaphore.
ClRcT	clOsalSemTryLock (ClOsalSemIdT semId)
	Locks a semaphore if it is available.
ClRcT	clOsalSemUnlock (ClOsalSemIdT semId)
	Unlocks a semaphore.
ClRcT	clOsalSemValueGet (ClOsalSemIdT semId, ClUint32T *pSemValue)
	Retrieves the value of a semaphore.
ClRcT	clOsalShmAttach (ClOsalShmIdT shmId, void pInMem, void *ppOutMem)
	Attaches a shared memory.
ClRcT	clOsalShmCreate (ClUint8T pName, ClUint32T size, ClOsalShmIdT pShmId)
	Creates a shared memory.
ClRcT	clOsalShmDelete (ClOsalShmIdT shmId)
	Deletes a shared memory.
ClRcT	clOsalShmDetach (void *pMem)
	Detaches a shared memory.
ClRcT	clOsalShmIdGet (ClUint8T pName, ClOsalShmIdT pShmId)
	Retrieves a shared memory Id.
ClRcT	clOsalShmSecurityModeGet (ClOsalShmIdT shmId, ClUint32T *pMode)
	Retrieves permissions of shared memory.
ClRcT	clOsalShmSecurityModeSet (ClOsalShmIdT shmId, ClUint32T mode)
	Sets permissions to shared memory.
ClRcT	clOsalShmSizeGet (ClOsalShmIdT shmId, ClUint32T *pSize)
	Retrieves the size of shared memory.
void	clOsalSigHandlerInitialize (void)
	Installs and initializes the signal handler.
ClTimeT	clOsalStopWatchTimeGet (void)
	Retrieves the time since the machine is up.
ClRcT	clOsalTaskCreateAttached (const ClCharT taskName, ClOsalSchedulePolicyT schedulePolicy, ClUint32T priority, ClUint32T stackSize, void (fpTaskFunction)(void ), void pTaskFuncArgument, ClOsalTaskIdT pTaskId)
	Creates a task.
ClRcT	clOsalTaskCreateDetached (const ClCharT taskName, ClOsalSchedulePolicyT schedulePolicy, ClUint32T priority, ClUint32T stackSize, void (fpTaskFunction)(void ), void *pTaskFuncArgument)
	Creates a task.
ClRcT	clOsalTaskDataGet (ClUint32T key, ClOsalTaskDataT *pThreadData)
	Retrieves the thread-specific data.
ClRcT	clOsalTaskDataSet (ClUint32T key, ClOsalTaskDataT threadData)
	Sets the thread-specific data.
ClRcT	clOsalTaskDelay (ClTimerTimeOutT timeOut)
	Delays a task.
ClRcT	clOsalTaskDelete (ClOsalTaskIdT taskId)
	Deletes a task.
ClRcT	clOsalTaskDetach (ClOsalTaskIdT taskId)
	No longer interested in the task's alive/dead state.
ClRcT	clOsalTaskJoin (ClOsalTaskIdT taskId)
	Joins a task.
ClRcT	clOsalTaskKeyCreate (ClUint32T *pKey, ClOsalTaskKeyDeleteCallBackT pCallbackFunc)
	Creates a key for thread-specific data.
ClRcT	clOsalTaskKeyDelete (ClUint32T key)
	Deletes the key for thread-specific data.
ClRcT	clOsalTaskKill (ClOsalTaskIdT taskId, ClInt32T sig)
	Kills a task by sending a signal.
ClRcT	clOsalTaskNameGet (ClOsalTaskIdT taskId, ClCharT **ppTaskName)
	Retrieves task name.
ClRcT	clOsalTaskPriorityGet (ClOsalTaskIdT taskId, ClUint32T *pTaskPriority)
	Retrieves the priority of the task.
ClRcT	clOsalTaskPrioritySet (ClOsalTaskIdT taskId, ClUint32T taskPriority)
	Sets the priority of the task.
ClRcT	clOsalTimeOfDayGet (ClTimerTimeOutT *pTime)
	Retrieves the current time.

Variables
ClOsalShmIdT	gClCompUniqueShmId
	Shared memory ID associated with the component.
ClOsalShmAreaDefT *	gpClShmArea
	Shared memory associated with the component.

Detailed Description

Defines, Structures, Typedefs, Functions.

Enumeration Type Documentation

enum ClOsalProcessFlagT

Process creation flags.

The values of the ClOsalProcessFlagT enumeration type have the following interpretation:

Enumerator:

CL_OSAL_PROCESS_WITH_NEW_SESSION	This will create a process with new session.
CL_OSAL_PROCESS_WITH_NEW_GROUP	This would create a new process group.

enum ClOsalSchedulePolicyT

The following enumeration type contains schedule policy of the tasks that will be created.

The values of the ClOsalSchedulePolicyT enumeration type have the following interpretation: other is the default scheduling policy fifo & rr are used for real time threads (you must be running with superuser priviledges).

Enumerator:

CL_OSAL_SCHED_OTHER	Default scheduling mechanism.
CL_OSAL_SCHED_FIFO	First-in-first-out.
CL_OSAL_SCHED_RR	Roundrobin.

enum ClOsalShmSecurityModeFlagT

Shared memory security options.

Enumerator:

CL_OSAL_SHM_MODE_READ_USER	read-only by this user
CL_OSAL_SHM_MODE_READ_GROUP	read-only by the group
CL_OSAL_SHM_MODE_READ_OTHERS	read-only by everyone
CL_OSAL_SHM_MODE_WRITE_USER	read/write by this user
CL_OSAL_SHM_MODE_WRITE_GROUP	read/write by the group
CL_OSAL_SHM_MODE_WRITE_OTHERS	read/write by everyone

enum ClOsalThreadPriorityT

The following enumeration type contains the various thread priorities.

The values of the ClOsalProcessFlagT enumeration type have the following interpretation:

Enumerator:

CL_OSAL_THREAD_PRI_NOT_APPLICABLE	When the scheduling is CL_OSAL_SCHED_OTHER, priority is not used.
CL_OSAL_THREAD_PRI_HIGH	Highest thread priority.
CL_OSAL_THREAD_PRI_MEDIUM	Medium thread priority.
CL_OSAL_THREAD_PRI_LOW	Lowest thread priority.

Function Documentation

ClRcT clOsalCondBroadcast ( ClOsalCondIdT conditionId )

Broadcasts a condition.

Parameters

conditionId Identifier of the condition variable. This must be the same as one returned when the condition variable was created. Any other value will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_CONDITION_BROADCAST	On failure to broadcast the condition.

Description: This API is used to resume all the tasks that are waiting on the condition variable. If no tasks are waiting on that condition then nothing happens.

See Also: clOsalCondCreate(), clOsalCondDelete(), clOsalCondWait(), clOsalCondSignal()

ClRcT clOsalCondCreate ( ClOsalCondIdT * pConditionId )

Creates a condition variable.

Parameters

pConditionId (out) Identifier of the condition variable created is stored here. This must be a valid pointer and cannot be NULL.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_NO_MEM	On memory allocation failure.
CL_ERR_CONDITION_CREATE	On failure in creating a condition variable.

Description: This API is used to create a condition variable. The condition variable is allocated on the heap. Use clOsalCondDelete() to destroy it.

See Also: clOsalCondDelete(), clOsalCondWait(), clOsalCondBroadcast(), clOsalCondSignal()

ClRcT clOsalCondDelete ( ClOsalCondIdT conditionId )

Deletes a condition variable.

Parameters

conditionId Identifier of the condition variable to be deleted. No task must be waiting on this condition variable when delete is invoked. This must be the same as one returned when the condition variable was created. Any other value will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_CONDITION_TIMEDOUT	On condition timedout
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_CONDITION_DELETE	On failure in deleting the condition variable.

Description: This API is used to delete a condition variable, and free associated memory. It is paired with clOsalCondCreate()

See Also: clOsalCondCreate(), clOsalCondWait(), clOsalCondBroadcast(), clOsalCondSignal()

ClRcT clOsalCondDestroy ( ClOsalCondT * pCond )

Destroys a condition variable.

Parameters

conditionId Identifier of the condition variable to be destroyed. No task must be waiting on this condition variable when destroy is invoked. This must be the same as one returned when the condition variable was initialized. Any other value will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_CONDITION_TIMEDOUT	On condition timedout
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_CONDITION_DELETE	On failure in deleting the condition variable.

Description: This API is used to delete a condition variable. It is paired with clOsalCondInit(), NOT clOsalCondCreate().

See Also: clOsalCondInit(), clOsalCondWait(), clOsalCondBroadcast(), clOsalCondSignal()

ClRcT clOsalCondInit ( ClOsalCondT * pCond )

Initializes a condition variable.

Parameters

pCond (out) Identifier of the condition variable initialized is stored here. This must be a valid pointer and cannot be NULL.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_CONDITION_INIT	On failure in creating a condition variable.

Description: This API is used to initialize a condition variable. Use clOsalCondDelete() to delete it, NOT clOsalCondDestroy()

See Also: clOsalCondDelete(), clOsalCondWait(), clOsalCondBroadcast(), clOsalCondSignal()

ClRcT clOsalCondSignal ( ClOsalCondIdT conditionId )

Signals a condition.

Parameters

conditionId Identifier of the condition variable. This must be the same as one returned when the condition variable was created. Any other value will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_CONDITION_SIGNAL	On failure to signal a condition.

Description: This API is used to resume one of the tasks that are waiting on the condition variable. If no tasks are waiting on that condition then nothing happens. If there are several threads waiting on the condition then exactly one task is resumed.

See Also: clOsalCondCreate(), clOsalCondDelete(), clOsalCondWait(), clOsalCondBroadcast()

ClRcT clOsalCondWait	(	ClOsalCondIdT	conditionId,
		ClOsalMutexIdT	mutexId,
		ClTimerTimeOutT	time
	)

Waits for a condition.

Parameters

conditionId	Identifier of the condition variable. This must be the same as one returned when the condition variable was created. Any other value can will be invalid.
mutexId	Identifier of the mutex. This must be the same as one returned when the mutex was created. Any other value will be invalid.
time	Duration for which the task waits for a condition. The time structure must be filled in with valid values. If the time out is zero then the task waits indefinitely for the signal.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_CONDITION_WAIT	On failure to wait for a condition.

Description

This API is used to unlock a mutex and wait on a condition variable to be signalled as the task execution is suspended. The mutex must be locked before entering into wait.

If the time out value is specified then the task would wait for the specified time.
If the condition is not signalled within the specified time then an error is returned.
If the timeout specified is zero then the task waits indefinitely until it receives a signal.

See Also: clOsalCondCreate(), clOsalCondDelete(), clOsalCondBroadcast(), clOsalCondSignal()

ClRcT clOsalFinalize ( void )

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_CL_OSAL_CLEANUP	On failure to clean up OSAL.
CL_ERR_MUTEX_DELETE	On failure in deleting mutex.

Description: This API is used to clean-up OSAL. This is last OSAL API that is invoked, typically this must be called during system shutdown.

See Also: clOsalInitialize()

ClRcT clOsalInitialize ( const ClPtrT pConfig )

Initializes the Operating System Abstraction Layer (OSAL).

Header File:: clOsalApi.h

Library File:: libClOsal

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NO_MEM	On memory allocation failure.
CL_ERR_MUTEX_CREATE	On failure in creating a mutex.

Description:: This API is used to initialize the OSAL. This should be the first API to be called before any of the other OSAL APIs are invoked.

See Also: clOsalFinalize()

ClRcT clOsalMutexCreate ( ClOsalMutexIdT * pMutexId )

Creates a mutex.

Parameters

pMutexId (out) Identifier of the mutex created is stored here. This must be a valid pointer (cannot be NULL).

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_NO_MEM	On memory allocation failure.
CL_ERR_MUTEX_CREATE	On failure in creating a Mutex.

Description: This API is used to create and initialize a mutual exclusion semaphore.

See Also: clOsalMutexCreateAndLock(), clOsalMutexDelete()

ClRcT clOsalMutexCreateAndLock ( ClOsalMutexIdT * pMutexId )

Creates a mutex in locked state.

Parameters

pMutexId (out) Identifier of the mutex created is stored here. This must be a valid pointer and cannot be NULL.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_NO_MEM	On memory allocation failure.
CL_ERR_MUTEX_CREATE	On failure in creating a mutex.
CL_ERR_MUTEX_LOCK	On failure in locking a mutex.

Description: This API is used to create and initialize a mutual exclusion semaphore in locked state.

See Also: clOsalMutexCreate(), clOsalMutexDelete()

ClRcT clOsalMutexDelete ( ClOsalMutexIdT mutexId )

Deletes a mutex.

Parameters

mutexId Identifier of the mutex to be deleted. The mutex id must be same as one returned when the mutex was created. All other values will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_MUTEX_DELETE	On failure in deleting a mutex.

Description: This API is used to delete a mutex.

See Also: clOsalMutexCreateAndLock(), clOsalMutexCreate()

ClRcT clOsalMutexDestroy ( ClOsalMutexT * pMutex )

Destroys a mutex.

Parameters

mutexId Mutex to be destroyed. The mutex must be same as one returned when the mutex was initialized. All other values will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_MUTEX_DELETE	On failure in destroying the mutex.

Description: This API is used to destroy a mutex.

See Also: clOsalMutexInit(), clOsalMutexCreateAndLock(), clOsalMutexCreate()

ClRcT clOsalMutexInit ( ClOsalMutexT * pMutex )

Initializes a mutex.

Parameters

pMutex (out) Mutex initialization data is stored here. This must be a valid pointer.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_MUTEX_CREATE	On failure in initializing a Mutex.

Description: This API is used to initialize a mutual exclusion semaphore. It differs from clOsalMutexCreate in that "Create" allocates memory while this function uses the ClOsalMutexT object's memory. To clean up use clOsalMutexDestroy() NOT clOsalMutexDelete()

See Also: clOsalMutexCreate(), clOsalRecursiveMutexInit(), clOsalMutexCreateAndLock(), clOsalMutexDestroy()

ClRcT clOsalMutexLock ( ClOsalMutexIdT mutexId )

Locks a mutex.

Parameters

mutexId Identifier of the mutex to be locked. The mutex id must be same as one returned when the mutex was created. All other values will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_MUTEX_LOCK	On failure in locking a mutex.

Description: This API is used to lock a mutex.

See Also: clOsalMutexUnlock

ClRcT clOsalMutexUnlock ( ClOsalMutexIdT mutexId )

Unlocks a mutex.

Parameters

mutexId Identifier of the mutex to be unlocked. The mutex ID must be same as one returned when the mutex was created. All other values will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_MUTEX_UNLOCK	On failure in unlocking a mutex.

Description: This API is used to unlock a mutex.

See Also: clOsalMutexLock()

ClRcT clOsalNanoTimeGet ( ClNanoTimeT * pTime )

Returns the time since Epoch, with a best resolution of 1 nanosecond.

Actual resolution is hardware dependent.

Parameters

pTime Current time

Return values

CL_OK	This API executed successfully.
CL_OSAL_ERR_OS_ERROR	The OS abstraction layer has not been initialized. In other words, clOsalInitialize() has not been called.
CL_ERR_NULL_PTR	'pTime' is NULL
CL_ERR_UNSPECIFIED	An unknown error has occured in fetching the current time. This will not be returned under normal circumstances.

See Also: clOsalTimeOfDayGet()

ClRcT clOsalPageSizeGet ( ClInt32T * pSize )

Synopsis:: Returns the size of a page in bytes

Header File:: clOsalApi.h clOsalErrors.h

Library File:: libClOsal.a libClOsal.so

Parameters

pSize The returned length

Return values

CL_OK	This API executed successfully.
CL_OSAL_ERR_OS_ERROR	The OS abstraction layer has not been initialized. In other words, clOsalInitialize() has not been called.
CL_ERR_NULL_PTR	'pSize' is NULL
CL_ERR_NOT_SUPPORTED	This limit cannot be queried at run-time.
CL_ERR_UNSPECIFIED	An unknown error was returned by sysconf()

Description:: None

Related APIs:: None

ClRcT clOsalPrintf	(	const ClCharT *	fmt,
			...
	)

Prints to the standard output.

Parameters

fmt	Format string to be printed.

Return values

CL_RC_OK	This API executed successfully.
CL_OS_ERROR	On failure to print to standard output.

Description: This API is used to print to the standard output.

ClRcT clOsalProcessCreate	(	ClOsalProcessFuncT	fpFunction,
		void *	functionArg,
		ClOsalProcessFlagT	creationFlags,
		ClOsalPidT *	pProcessId
	)

Creates a process.

Parameters

fpFunction	Function to be invoked when the process is created. This must be a valid pointer and cannot be NULL.
functionArg	Argument passed to the fpFunction that is created along with the cretionof the the process. This can be a valid pointer or NULL.
creationFlags	Flags that control certain properties including creation of new session, process group and creating the process in a suspended state.
pProcessId	(out) Id of the process created is stored in this location. This must be a valid pointer cand cannot be NULL.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_PROCESS_CREATE	On failure to create a process.

Description: This API is used to create a process.

See Also: clOsalProcessDelete(), clOsalProcessWait(), clOsalProcessSelfIdGet()

ClRcT clOsalProcessDelete ( ClOsalPidT processId )

Deletes a process.

Parameters

processId Id of the process to be deleted. This must be the same as one returned when the process was created.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_PROCESS_DELETE	On failure in deleting a process.

Description: This API is used to delete a process.

See Also: clOsalProcessCreate(), clOsalProcessWait(), clOsalProcessSelfIdGet()

ClRcT clOsalProcessSelfIdGet ( ClOsalPidT * pProcessId )

Retrieves the processId.

Parameters

pProcessId (out) ProcessId of the caller is stored in this location.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.

Description: This API is used to obtain the processId of the caller.

See Also: clOsalProcessCreate(), clOsalProcessDelete(), clOsalProcessWait(),

ClRcT clOsalProcessSharedCondInit ( ClOsalCondT * pCond )

Initializes a condition variable that can be used in multiple processes.

Parameters

pCond (out) Identifier of the condition variable initialized is stored here. This must be a valid pointer to shared memory.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_CONDITION_INIT	On failure in creating a condition variable.

Description: This API is used to initialize a condition variable. Use clOsalCondDestroy() to delete it, NOT clOsalCondDelete()

See Also: clOsalCondDestroy(), clOsalCondWait(), clOsalCondBroadcast(), clOsalCondSignal()

ClRcT clOsalProcessSharedMutexInit	(	ClOsalMutexT *	pMutex,
		ClOsalSharedMutexFlagsT	flags,
		ClUint8T *	pKey,
		ClUint32T	keyLen,
		ClInt32T	value
	)

Initializes a process-shared mutex.

Parameters

pMutex (out) Mutex initialization data is stored here. This must be a valid pointer to shared memory.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_MUTEX_CREATE	On failure in initializing a Mutex.

Description: This API is used to initialize a mutual exclusion semaphore that can be used to synchronize threads running in different processes

See Also: clOsalMutexInit(), clOsalRecursiveMutexInit(), clOsalMutexDelete()

ClRcT clOsalProcessWait ( ClOsalPidT processId )

Waits for a process to exit.

Parameters

processId Id of the process for which the calling process needs to wait. This must be the same as one returned when the process was created. If zero is passed then the calling process waits for all the processes, that it created, to exit.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_PROCESS_WAIT	On failure to wait for a process to exit.

Description: This API is used to suspend the execution of a process until the the processes created from with in the process has exited.

See Also: clOsalProcessCreate(), clOsalProcessDelete(), clOsalProcessSelfIdGet()

ClRcT clOsalRecursiveMutexInit ( ClOsalMutexT * pMutex )

Initializes a mutex.

Parameters

pMutex (out) Mutex initialization data is stored here. This must be a valid pointer and cannot be NULL.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_MUTEX_CREATE	On failure in initializing a Mutex.

Description: This API is used to initialize a mutual exclusion semaphore. The mutex is recursive – i.e. same thread can 'lock' it multiple times, so long as it 'unlocks' it the same # of times.

See Also: clOsalMutexCreate(), clOsalRecursiveMutexInit(), clOsalMutexCreateAndLock(), clOsalMutexDelete()

ClRcT clOsalSelfTaskIdGet ( ClOsalTaskIdT * pTaskId )

Retrieves task id.

Parameters

pTaskId (out) Task ID of the calling task is stored here. This must be a valid pointer and cannot be NULL.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.

Description: This API is used to obtain the task Id of the calling task.

See Also: clOsalTaskCreate(), clOsalTaskDelete(), clOsalTaskNameGet(), clOsalTaskPriorityGet(), clOsalTaskPrioritySet(), clOsalTaskDelay()

ClRcT clOsalSemCreate	(	ClUint8T *	pName,
		ClUint32T	value,
		ClOsalSemIdT *	pSemId
	)

Creates a semaphore.

Parameters

pName	Name of the semaphore to be created. If the same name is specified then the same semaphore ID is returned. Name must not be more than 20 characters and cannot be NULL.
value	Value of the semaphore. This is required to set the semaphore before it is used first time. This must be a positive integer and must be less than `CL_SEM_MAX_VALUE`. Zero will be invalid.
pSemId	(out) Identifier of the semaphore created is stored in this location. This must be a valid pointer and cannot be NULL.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_SEM_CREATE	On failure in creating a semaphore.
CL_ERR_NAME_TOO_LONG	If semaphore name is too long.
CL_ERR_NULL_PTR	On passing a NULL pointer.

Description: This API is used to create an counting semaphore. If the semaphore with the same name exists then the exisiting semaphore is obtained else a new semaphore is created.

See Also: clOsalSemIdGet(), clOsalSemLock(), clOsalSemTryLock(), clOsalSemUnlock(), clOsalSemValueGet(), clOsalSemDelete()

ClRcT clOsalSemDelete ( ClOsalSemIdT semId )

Deletes a semaphore.

Parameters

semId Identifier of the semaphore to be locked. This must be the same as one returned when the semaphore was created. Any other value will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_SEM_DELETE	On failure in deleting a semaphore.

Description: This API is used to destroy a semaphore. No process must be waiting for the semaphore while the semaphore is being destroyed. If one or more processes are waiting on the semaphore then the semaphore does not get destroyed.

See Also: clOsalSemCreate(), clOsalSemIdGet(), clOsalSemLock(), clOsalSemTryLock(), clOsalSemUnlock(), clOsalSemValueGet(),

ClRcT clOsalSemIdGet	(	ClUint8T *	pName,
		ClOsalSemIdT *	pSemId
	)

Retrieves the semaphore id.

Parameters

pName	Name of the semaphore for the which the ID is required.NULL is not valid.
pSemId	(out) A memory location to store the ID.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_SEM_ID_GET	On failure in retrieving the semaphore ID.

Description: This API is used to obtain the ID of the semaphore if the name is specified.

See Also: clOsalSemCreate(),clOsalSemLock(), clOsalSemTryLock(), clOsalSemUnlock(), clOsalSemValueGet(), clOsalSemDelete()

ClRcT clOsalSemLock ( ClOsalSemIdT semId )

Locks a semaphore.

Parameters

semId Identifier of the semaphore to be locked. This must be the same as what was returned when the semaphore was created. Any other value will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_SEM_LOCK	On failure in locking a semaphore.

Description: This API is used to lock a semaphore. If the semaphore is already locked (unavailable) then trying to lock the same semaphore suspends the execution of the process until the semaphore is available. The value of the semaphore is decremented.

See Also: clOsalSemCreate(), clOsalSemIdGet(), clOsalSemTryLock(), clOsalSemUnlock(), clOsalSemValueGet(), clOsalSemDelete()

ClRcT clOsalSemTryLock ( ClOsalSemIdT semId )

Locks a semaphore if it is available.

Parameters

semId Identifier of the semaphore to be locked. This must be the same as one returned when the semaphore was created. Any other value will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_SEM_LOCK	On failure in try-locking a semaphore.

Description: This API is used to lock a semaphore if the semaphore is available. If the semaphore is unavailable then the call just returns without blocking. The call returns immediately (non-blocking) on both the cases. If the semaphore is available,then semaphore is locked and will remain locked until it is unlocked explicitly. The value of the semaphore is decremented.

See Also: clOsalSemCreate(), clOsalSemIdGet(), clOsalSemLock(), clOsalSemUnlock(), clOsalSemValueGet(), clOsalSemDelete()

ClRcT clOsalSemUnlock ( ClOsalSemIdT semId )

Unlocks a semaphore.

Parameters

semId Identifier of the semaphore to be locked. This must be the same as one returned when the semaphore was created. Any other value will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_SEM_UNLOCK	On failure in unlocking a semaphore.

Description: This API is used to unlock a semaphore.Any process that is blocked on the semaphore resumes execution. If no process is blocked then the semaphore is made available for the others. The value of the semaphore is incremented.

See Also: clOsalSemCreate(), clOsalSemIdGet(), clOsalSemLock(), clOsalSemTryLock(), clOsalSemValueGet(), clOsalSemDelete()

ClRcT clOsalSemValueGet	(	ClOsalSemIdT	semId,
		ClUint32T *	pSemValue
	)

Retrieves the value of a semaphore.

Parameters

semId	Identifier of the semaphore to be locked. This must be the same as one returned when the semaphore was created. Any other value will be invalid.
pSemValue	(out) Value of the semaphore is stored in the location specified. This must be a valid pointer and cannot be NULL.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_SEM_GET_VALUE	On failure in retrieving the value of the semaphore.

Description: This API is used to return the value of a semaphore.

See Also: clOsalSemCreate(), clOsalSemIdGet(), clOsalSemLock(), clOsalSemTryLock(), clOsalSemUnlock(), clOsalSemDelete()

ClRcT clOsalShmAttach	(	ClOsalShmIdT	shmId,
		void *	pInMem,
		void **	ppOutMem
	)

Attaches a shared memory.

Parameters

shmId	Identifier of the shared memory region to be attached. This must be same as one returned the shared memory was created. All other values will be invalid.
pInMem	Pointer to the shared memory region to be attached. NULL address
ppOutMem	(out) Attached shared memory region is copied to this location. This must be a valid pointer and cannot be NULL.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_SHM_ATTACH	On failure in attaching the shared memory.

Description: This API is used to attach a shared memory region. The attach occurs at the address equal to the address specified by you rounded to the nearest multiple of the page size.

See Also: clOsalShmCreate(), clOsalShmIdGet(), clOsalShmDelete(),clOsalShmDetach(), clOsalShmSecurityModeSet(), clOsalShmSecurityModeGet(), clOsalShmSizeGet()

ClRcT clOsalShmCreate	(	ClUint8T *	pName,
		ClUint32T	size,
		ClOsalShmIdT *	pShmId
	)

Creates a shared memory.

Parameters

pName	Name for the shared memory region to be created. The same name must be specified if the same shared memory is to be used from some other process. This must be a valid pointer and cannot be NULL. Name must not be more than 20 characters.
size	Size of the shared memory to be created. This must be a positive integer.
pShmId	Identifier of the shared memory created is stored in this location. This must be a valid pointer and cannot be NULL.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_NAME_TOO_LONG	If the name specified is too long.
CL_ERR_SHM_ID_GET	On failure to retrieve the ID of the shared memory.
CL_ERR_SHM_CREATE	On failure to create a shared memory.

Description: This API is used to create a shared memory region. If the shared memory region with the same name exists then the existing shared memory is obtained, else a new shared memory region is created.

See Also: clOsalShmIdGet(), clOsalShmDelete(), clOsalShmAttach(), clOsalShmDetach(), clOsalShmSecurityModeSet(), clOsalShmSecurityModeGet(), clOsalShmSizeGet()

ClRcT clOsalShmDelete ( ClOsalShmIdT shmId )

Deletes a shared memory.

Parameters

shmId Id of the shared memory to be deleted. This must be the same as the one that was passed when the shared memory was created. Any other value will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_SHM_DELETE	On failure in deleting the shared memory.

Description: This API is used to delete a shared memory region. If more than one process has attached this shared memory then the destroy would just mark it for destroy. The shared memory is actually destroyed only after the last detach.

See Also: clOsalShmCreate(), clOsalShmIdGet(), clOsalShmAttach(), clOsalShmDetach(), clOsalShmSecurityModeSet(), clOsalShmSecurityModeGet(), clOsalShmSizeGet()

ClRcT clOsalShmDetach ( void * pMem )

Detaches a shared memory.

Parameters

pMem	Pointer to the shared memory region to be detached. The memory must have been attached to the process already. NULL will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_SHM_DETACH	On failure in detaching shared memory.

Description: This API is used to detach a shared memory region from the address space of the calling process. The memory segment to be detached must have been attached to the process.

See Also: clOsalShmCreate(), clOsalShmIdGet(), clOsalShmDelete(), clOsalShmAttach(), clOsalShmSecurityModeSet(), clOsalShmSecurityModeGet(), clOsalShmSizeGet()

ClRcT clOsalShmIdGet	(	ClUint8T *	pName,
		ClOsalShmIdT *	pShmId
	)

Retrieves a shared memory Id.

Parameters

pName	Name of the shared memory region for which the Id is to be obtained. This must be a valid pointer and cannot be NULL.
pShmId	Id of the shared memory is copied into this location. NULL will be invalid.

Return values

CL_RC_OK	The API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_SHM_ID_GET	On failure in obtaining the shared memory ID.

Description: This API is used to obtain the shared memory Id.

See Also: clOsalShmCreate(), clOsalShmDelete(), clOsalShmAttach(), clOsalShmDetach(), clOsalShmSecurityModeSet(), clOsalShmSecurityModeGet(), clOsalShmSizeGet()

ClRcT clOsalShmSecurityModeGet	(	ClOsalShmIdT	shmId,
		ClUint32T *	pMode
	)

Retrieves permissions of shared memory.

Parameters

shmId	Identifier of the shared memory region. This must be same as one returned when the shared memory was created. All other values will be invalid.
pMode	(out) Permission of the shared memory will be copied to this location. NULL will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_SHM_MODE_GET	On failure in retrieving permissions of the shared memory.

See Also: clOsalShmCreate(), clOsalShmIdGet(), clOsalShmDelete(), clOsalShmAttach(), clOsalShmDetach(), clOsalShmSecurityModeSet(), clOsalShmSizeGet()

ClRcT clOsalShmSecurityModeSet	(	ClOsalShmIdT	shmId,
		ClUint32T	mode
	)

Sets permissions to shared memory.

Parameters

shmId	Identifier of the shared memory region. This must be same as one returned when the shared memory was created. All other values will be invalid.
mode	Permission to be set. This can be any of the flags specified in ClOsalShmSecurityModeFlagT.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_SHM_MODE_SET	On failure in setting permissions to shared memory.

Description: This API is used to set permissions for a shared memory region.This allows only the access modes to be changed.

See Also: clOsalShmCreate(), clOsalShmIdGet(), clOsalShmDelete(), clOsalShmAttach(), clOsalShmDetach(), clOsalShmSecurityModeGet(), clOsalShmSizeGet()

ClRcT clOsalShmSizeGet	(	ClOsalShmIdT	shmId,
		ClUint32T *	pSize
	)

Retrieves the size of shared memory.

Parameters

shmId	Identifier of the shared memory region. This must be same as one returned when the shared memory was created. All other values will be invalid.
pSize	Size of the shared memory is copied into the specified location.

Return values

CL_RC_OK	This API executed successfully.:
CL_ERR_INVLD_PARAM	On passing an invalid parameter.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_SHM_SIZE	On failure in retrieving size of the shared memory.

Description: This API is used to obtain the size of the shared memory that was allocated.

See Also: clOsalShmCreate(), clOsalShmIdGet(), clOsalShmDelete(), clOsalShmAttach(), clOsalShmDetach(), clOsalShmSecurityModeSet(), clOsalShmSecurityModeGet(),

void clOsalSigHandlerInitialize ( void )

Installs and initializes the signal handler.

initialized. In other words, clOsalInitialize() has not been called.

Return values

CL_ERR_NULL_POINTER	'name' is NULL
CL_ERR_OP_NOT_PERMITTED	Permission denied to unlink the POSIX shared memory object.
CL_ERR_DOESNT_EXIST	A POSIX shared memory object by name 'name' does not exist
CL_ERR_UNSPECIFIED,:	An unknown error was returned by pathconf()

ClTimeT clOsalStopWatchTimeGet ( void )

Retrieves the time since the machine is up.

Parameters

pTime Pointer to variable of type ClTimerTimeOutT, in which the time is returned.

Return values

-1	if there is some system error.
on	success returns the time in microseconds.

Description: This API is used to return the current time, since the machine is up, in microseconds.

ClRcT clOsalTaskCreateAttached	(	const ClCharT *	taskName,
		ClOsalSchedulePolicyT	schedulePolicy,
		ClUint32T	priority,
		ClUint32T	stackSize,
		void ()(void *)	fpTaskFunction,
		void *	pTaskFuncArgument,
		ClOsalTaskIdT *	pTaskId
	)

Creates a task.

Parameters

taskName	Name of the task. This must be a valid string. NULL is regarded as invalid but the task creation does not fail.
schedulePolicy	Schedule policy can be set as one of the following: CL_OSAL_SCHED_RR For this, you must be logged in as super-user. It supports priority-based realtime round-robin scheduling. CL_OSAL_SCHED_FIFO For this, you must be logged in as super-user. It supports priority based pre-emptive scheduling. This parameter is ignored in case of VxWorks. CL_OSAL_SCHED_OTHER
priority	Priority at which the tasks is executed. The priority must be between 1 and 160 (1 - lowest priority 160 - highest priority). Any other value is regarded as wrong and task creation fails.
stackSize	Size (in bytes) of the user stack that must be created when the task is executed. The stack size must be a positive integer. If zero is mentioned, then the default stack size of 4096 bytes would be allocated. If the stack size mentioned is less than the default stack size then the default stack size is assigned.
fpTaskFunction	Entry point of the task. This function is executed when the task is executed. This is a function pointer and NULL argument would result in error.
pTaskFuncArgument	The argument to be passed to fpTaskFuncArgument when the function is executed. This must be a valid pointer and if there are no arguments to be passed then NULL can be passed. Any other value will be invalid.
pTaskId	(out)The identifier of the task started is stored here. This shall be any valid pointer, NULL will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_INVLD_PARAM	On passing invalid parameters.
CL_ERR_TASK_ATTRIBUTE_INIT	On failure in task attribute initialization.
CL_ERR_TASK_CREATE	On failure to create task.
CL_ERR_TASK_ATTRIBUTE_SET	On failure in setting task attributes.

Description: This API is used to spawn a new task that runs concurrently with the calling task. The new task invokes the user API fpTaskFunction with the argument pTaskFuncArgument to the function. The new task terminates explicitly by calling clOsalTaskDelete or implicitly, by returning from the fpTaskFunction. Since the task it "attached", it can be manipulated using the task handle returned in the pTaskId. parameter.

See Also: clOsalTaskDelete(), clOsalSelfTaskIdGet(), clOsalTaskNameGet(), clOsalTaskPriorityGet(), clOsalTaskPrioritySet(), clOsalTaskDelay()

ClRcT clOsalTaskCreateDetached	(	const ClCharT *	taskName,
		ClOsalSchedulePolicyT	schedulePolicy,
		ClUint32T	priority,
		ClUint32T	stackSize,
		void ()(void *)	fpTaskFunction,
		void *	pTaskFuncArgument
	)

Creates a task.

Parameters

taskName	Name of the task. This must be a valid string. NULL is regarded as invalid but the task creation does not fail.
schedulePolicy	Schedule policy can be set as one of the following: CL_OSAL_SCHED_RR For this, you must be logged in as super-user. It supports priority-based realtime round-robin scheduling. CL_OSAL_SCHED_FIFO For this, you must be logged in as super-user. It supports priority based pre-emptive scheduling. This parameter is ignored in case of VxWorks. CL_OSAL_SCHED_OTHER
priority	Priority at which the tasks is executed. The priority must be between 1 and 160 (1 - lowest priority 160 - highest priority). Any other value is regarded as wrong and task creation fails.
stackSize	Size (in bytes) of the user stack that must be created when the task is executed. The stack size must be a positive integer. If zero is mentioned, then the default stack size of 4096 bytes would be allocated. If the stack size mentioned is less than the default stack size then the default stack size is assigned.
fpTaskFunction	Entry point of the task. This function is executed when the task is executed. This is a function pointer and NULL argument would result in error.
pTaskFuncArgument	The argument to be passed to fpTaskFuncArgument when the function is executed. This must be a valid pointer and if there are no arguments to be passed then NULL can be passed. Any other value will be invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_INVLD_PARAM	On passing invalid parameters.
CL_ERR_TASK_ATTRIBUTE_INIT	On failure in task attribute initialization.
CL_ERR_TASK_CREATE	On failure to create task.
CL_ERR_TASK_ATTRIBUTE_SET	On failure in setting task attributes.

Description: This API is used to spawn a new task that runs concurrently with the calling task. The new task invokes the user API fpTaskFunction with the argument pTaskFuncArgument to the function. The new task terminates explicitly by calling clOsalTaskDelete or implicitly, by returning from the fpTaskFunction.

See Also: clOsalTaskDelete(), clOsalSelfTaskIdGet(), clOsalTaskNameGet(), clOsalTaskPriorityGet(), clOsalTaskPrioritySet(), clOsalTaskDelay()

ClRcT clOsalTaskDataGet	(	ClUint32T	key,
		ClOsalTaskDataT *	pThreadData
	)

Retrieves the thread-specific data.

Parameters

key	Key for the thread-specific data returned by clOsalTaskKeyCreate API.
pThreadData	(out) Pointer to ClUint32T in which the thread-specific data is returned on success.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_OS_ERROR	On failure in retrieving the thread-specific data.

Description: This API is used to return the thread-specific data of the calling task.

See Also: clOsalTaskKeyCreate(), clOsalTaskKeyDelete(), clOsalTaskDataSet()

ClRcT clOsalTaskDataSet	(	ClUint32T	key,
		ClOsalTaskDataT	threadData
	)

Sets the thread-specific data.

Parameters

key	Key for the thread-specific data returned by clOsalTaskKeyCreate API.
threadData	ThreadData to be assigned to the calling task.

Return values

CL_RC_OK	This API executed successfully.
CL_OS_ERROR	On failure to set thread-specific data.

Description: This API is used to set the thread-specific data for the calling task.

See Also: clOsalTaskKeyCreate(), clOsalTaskKeyDelete(), clOsalTaskDataGet()

ClRcT clOsalTaskDelay ( ClTimerTimeOutT timeOut )

Delays a task.

Parameters

time	Time duration for which the task is delayed. This value is in milliseconds. Any positive value will be valid.

Return values

CL_RC_OK	The API executed successfully.
CL_ERR_TASK_DELAY	On failure in delaying a task.

Description: This API causes the calling task to relinquish the CPU for the duration specified. For certain OSes like Linux the taks may not get scheduled back after the timedelay mentioned. It may be scheduled at a later time by the scheduler based on the scheduling time interval, also it can be interrupted by signals received by the process and could return before the delay time period.

See Also: clOsalTaskCreate(), clOsalTaskDelete(), clOsalSelfTaskIdGet(), clOsalTaskNameGet(), clOsalTaskPriorityGet(), clOsalTaskPrioritySet()

ClRcT clOsalTaskDelete ( ClOsalTaskIdT taskId )

Deletes a task.

Parameters

taskId Identifier of the task to be deleted. The taskId must be same as what was returned when the task was created. All other values will be invalid.

Return values

CL_RC_OK	This API executed successfully. (Not applicable for deleting the currently executing task)
CL_ERR_NO_TASK_EXIST	On deleting a task which does not exist.
CL_ERR_TASK_DELETE	On failure to delete a task.

Description: This API is used to delete a task.

See Also: clOsalTaskCreate(), clOsalSelfTaskIdGet(), clOsalTaskNameGet(), clOsalTaskPriorityGet(), clOsalTaskPrioritySet(), clOsalTaskDelay()

ClRcT clOsalTaskDetach ( ClOsalTaskIdT taskId )

No longer interested in the task's alive/dead state.

Parameters

taskId Identifier of the task to be detached. The taskId must be same as what was returned when the task was created. All other values will be invalid.

Return values

CL_RC_OK	This API executed successfully. (Not applicable for deleting the currently executing task)
CL_ERR_NO_TASK_EXIST	On deleting a task which does not exist.
CL_ERR_TASK_DELETE	On failure to delete a task.

Description: This API is used to tell the platform that this task should run independently of all other tasks. Its return code, or state will not be accessible by the program.

See Also: clOsalTaskCreate(), clOsalSelfTaskIdGet(), clOsalTaskNameGet(), clOsalTaskPriorityGet(), clOsalTaskPrioritySet(), clOsalTaskDelay()

ClRcT clOsalTaskJoin ( ClOsalTaskIdT taskId )

Joins a task.

Parameters

taskId Identifier of the task to be joined. The taskId must be same as what was returned when the task was created. All other values will be invalid.

Return values

CL_RC_OK	This API executed successfully. (Not applicable for deleting the currently executing task)
CL_ERR_NO_TASK_EXIST	On deleting a task which does not exist.
CL_ERR_TASK_DELETE	On failure to delete a task.

Description: This API is used to join a task. Joining a task means that the calling task will wait until the specified task is completed. Joining a task also cleans

See Also: clOsalTaskCreate(), clOsalSelfTaskIdGet(), clOsalTaskNameGet(), clOsalTaskPriorityGet(), clOsalTaskPrioritySet(), clOsalTaskDelay()

ClRcT clOsalTaskKeyCreate	(	ClUint32T *	pKey,
		ClOsalTaskKeyDeleteCallBackT	pCallbackFunc
	)

Creates a key for thread-specific data.

Parameters

pKey	(out) Pointer to ClUint32T, in which the created key is returned.
pCallbackFunc	Callback function, which is called when the key is deleted using clOsalTaskKeyDelete API.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_OS_ERROR	On failure to create a key for thread-specific data.

Description: This API is used to create a key for thread-specific data.

See Also: clOsalTaskKeyDelete(), clOsalTaskDataSet(), clOsalTaskDataGet()

ClRcT clOsalTaskKeyDelete ( ClUint32T key )

Deletes the key for thread-specific data.

Parameters

key	Key to be deleted.

Return values

CL_RC_OK	This API executed successfully.
CL_OS_ERROR	On failure in deleting the key for thread-specific data.

Description: This API is used to delete the key for thread-specific data, which is returned by clOsalTaskKeyCreate.

See Also: clOsalTaskKeyCreate(), clOsalTaskDataSet(), clOsalTaskDataGet()

ClRcT clOsalTaskKill	(	ClOsalTaskIdT	taskId,
		ClInt32T	sig
	)

Kills a task by sending a signal.

Parameters

taskId	Identifier of the task to be killed. The taskId must be same as what was returned when the task was created. All other values will be invalid.
sig	Signal to be sent to the task

Return values

CL_RC_OK	This API executed successfully. (Not applicable for killing the currently executing task)
CL_ERR_NO_TASK_EXIST	On killing a task which does not exist.
CL_ERR_TASK_DELETE	On failure to killing a task.

Description: This API is used to kill a task by sending a signal identified by the sig parameter.

See Also: clOsalTaskCreate(), ClOsalTaskDelete(), clOsalSelfTaskIdGet(),

ClRcT clOsalTaskNameGet	(	ClOsalTaskIdT	taskId,
		ClCharT **	ppTaskName
	)

Retrieves task name.

Parameters

taskId	Task ID of the task for the which the name is to be found. If the task ID is zero then the name of the current task is found.
ppTaskName	(out) Name of the task is stored here. This must be a valid pointer and cannot be NULL.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_NO_TASK_EXIST	On requesting for a task name which does not exist.

Description: This API is used to obtain the name of the task.

See Also: clOsalTaskCreate(), clOsalTaskDelete(), clOsalSelfTaskIdGet(), clOsalTaskPriorityGet(), clOsalTaskPrioritySet(), clOsalTaskDelay()

ClRcT clOsalTaskPriorityGet	(	ClOsalTaskIdT	taskId,
		ClUint32T *	pTaskPriority
	)

Retrieves the priority of the task.

Parameters

taskId	Task ID of the task for which the priority is to obtained. The task ID must be same as the one that was returned when the task was created. Any other value will be invalid.
pTaskPriority	(out) Priority of the task is stored here. This must be a valid pointer and cannot be NULL.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_TASK_ATTRIBUTE_GET	On failure in retrieving the priority of the task.

Description: This API is used to obtain the priority of a task.

See Also: clOsalTaskCreate(), clOsalTaskDelete(), clOsalSelfTaskIdGet(), clOsalTaskNameGet(), clOsalTaskPrioritySet(), clOsalTaskDelay()

ClRcT clOsalTaskPrioritySet	(	ClOsalTaskIdT	taskId,
		ClUint32T	taskPriority
	)

Sets the priority of the task.

Parameters

taskId	Task ID of the task for which the priority is to be set. The task ID must be same as the one that was returned when the task was created. Any other value will be invalid.
pTaskPriority	New priority of the task. This must be between 1 and 160. All other values are invalid.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_TASK_ATTRIBUTE_SET	On failure in setting the priority of the task.

Description: This API is used to set the priority of a task.

See Also: clOsalTaskCreate(), clOsalTaskDelete(), clOsalSelfTaskIdGet(), clOsalTaskNameGet(), clOsalTaskPriorityGet(), clOsalTaskDelay()

ClRcT clOsalTimeOfDayGet ( ClTimerTimeOutT * pTime )

Retrieves the current time.

Parameters

pTime Pointer to variable of type ClTimerTimeOutT, in which the time is returned.

Return values

CL_RC_OK	This API executed successfully.
CL_ERR_NULL_PTR	On passing a NULL pointer.
CL_ERR_TIME_OF_DAY	On failure in retrieving the time of day.

Description: This API is used to return the current time (number of seconds and milliseconds) since the Epoch.

Files

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

Function Documentation