Synchronization

Synchronization resource. More...

Collaboration diagram for Synchronization:

Data Structures
struct	semaphore_t

Typedefs
typedef volatile int32_t	sync_object_t
	Type for an interrupt synchronization object.
typedef volatile uint32_t	lock_object_t
	Type for an interrupt lock object.

Enumerations
enum	osa_status_t {   kStatus_OSA_Success = 0U,   kStatus_OSA_Error = 1U,   kStatus_OSA_Timeout = 2U,   kStatus_OSA_Idle = 3U }
enum	sync_timeouts { kSyncWaitForever = 0xffffffffU }

Counting Semaphore
osa_status_t	OSA_SemaCreate (semaphore_t *pSem, uint8_t initValue)
	Creates a semaphore with a given value. More...
osa_status_t	OSA_SemaWait (semaphore_t *pSem, uint32_t timeout)
	Pending a semaphore with timeout. More...
osa_status_t	OSA_SemaPost (semaphore_t *pSem)
	Signals for someone waiting on the semaphore to wake up. More...
osa_status_t	OSA_SemaDestroy (semaphore_t *pSem)
	Destroys a previously created semaphore. More...
void	OSA_TimeDelay (uint32_t delay)
	Delays execution for a number of milliseconds. More...

Usage Information

Synchronization resource.

---

Data Structure Documentation

struct semaphore_t

Data Fields
volatile bool	isWaiting	Is any task waiting for a timeout on this object
volatile uint8_t	semCount	The count value of the object
uint64_t	tickStart	The ticks to start timeout
uint32_t	timeout	Timeout to wait in milliseconds

Enumeration Type Documentation

enum osa_status_t

Enumerator
kStatus_OSA_Success	Success
kStatus_OSA_Error	Failed
kStatus_OSA_Timeout	Timeout occurs while waiting
kStatus_OSA_Idle	Used for bare metal only, the wait object is not ready and timeout still not occur

enum sync_timeouts

Enumerator
kSyncWaitForever	Constant to pass for the sync_wait() timeout in order to wait indefinitely.

Function Documentation

osa_status_t OSA_SemaCreate	(	semaphore_t *	pSem,
		uint8_t	initValue
	)

Creates a semaphore with a given value.

This function creates a semaphore and sets the value to the parameter initValue.

Parameters

pSem	Pointer to the semaphore.
initValue	Initial value the semaphore will be set to.

Return values

kStatus_OSA_Success	The semaphore is created successfully.
kStatus_OSA_Error	The semaphore can not be created.

Example:

semaphore_t mySem;
OSA_SemaCreate(&mySem, 0);

osa_status_t OSA_SemaDestroy

(

semaphore_t *

pSem

)

Destroys a previously created semaphore.

Parameters

pSem	Pointer to the semaphore to destroy.

Return values

kStatus_OSA_Success	The semaphore is successfully destroyed.
kStatus_OSA_Error	The semaphore can not be destroyed.

Example:

osa_status_t status;
status = OSA_SemaDestroy(&mySem);
switch(status)
{
    //...
}

osa_status_t OSA_SemaPost

(

semaphore_t *

pSem

)

Signals for someone waiting on the semaphore to wake up.

Wakes up one task that is waiting on the semaphore. If no task is waiting, increases the semaphore's counting value.

Parameters

pSem	Pointer to the semaphore to signal.

Return values

kStatus_OSA_Success	The semaphore is successfully signaled.
kStatus_OSA_Error	The object can not be signaled or invalid parameter.

Example:

osa_status_t status;
status = OSA_SemaPost(&mySem);
switch(status)
{
    //...
}

osa_status_t OSA_SemaWait	(	semaphore_t *	pSem,
		uint32_t	timeout
	)

Pending a semaphore with timeout.

This function checks the semaphore's counting value. If it is positive, decreases it and returns kStatus_OSA_Success. Otherwise, a timeout is used to wait.

Parameters

pSem	Pointer to the semaphore.
timeout	The maximum number of milliseconds to wait if semaphore is not positive. Pass OSA_WAIT_FOREVER to wait indefinitely, pass 0 will return kStatus_OSA_Timeout immediately.

Return values

kStatus_OSA_Success	The semaphore is received.
kStatus_OSA_Timeout	The semaphore is not received within the specified 'timeout'.
kStatus_OSA_Error	An incorrect parameter was passed.
kStatus_OSA_Idle	The semaphore is not available and 'timeout' is not exhausted, This is only for bare metal.

Note

With bare metal, a semaphore can not be waited by more than one task at the same time.

Example:

osa_status_t status;
status = OSA_SemaWait(&mySem, 100);
switch(status)
{
    //...
}

void OSA_TimeDelay

(

uint32_t

delay

)

Delays execution for a number of milliseconds.

Parameters

delay

The time in milliseconds to wait.