Synchronization
Utilities

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.