RTOS Semaphore Services

http://www.beck-ipc.com/files/api/scxxx/rtxover.htm

Semaphores are used to guarantee a task mutually exclusive access to a critical resource.
Semaphores synchronize asynchronous occurring activities.
They are an essential part of a multitasking system.
A good description of multitasking systems and semaphores is available
in the book "Operating systems" from Andrew Tanenbaum.

The @CHIP-RTOS API provides two types of semaphores:

A counting semaphore is a semaphore with an associated counter,
which can be incremented (signal) and decremented (wait).
The resource controlled by the semaphore is free (available)
when the counter is greater than 0.

A resource semaphore is a counting semaphore with a maximum count of one.
It can be used to provide mutually exclusive access to a single resource.
A resource semaphore is also called a binary semaphore.
It differs from a counting semaphore in one significant feature:
The resource ownership is tied to a specific task.
No other task except the task owning the resource is allowed
to signal the associated semaphore to release the resource.

The counting and resource semaphores provide automatic timeout.
Tasks can specify the maximum time for waiting on a semaphore.
The tasks wait in FIFO order for a resource.

A semaphore is created with the RTX_Create_Sem() API.
The @CHIP-RTOS needs a unique four byte semaphore name and
on success returns a new semaphore ID (or handle) to the caller.
This handle is needed for the other semaphore services.

Using a counting semaphore:

A counting semaphore is created by specifying an initial count
greater or equal to zero in the call to RTX_Create_Sem().

If a semaphore is initialized with a value n,
it can be used to control access to n resources,

e.g. a counting semaphore with the initial value three assures that
no more than three tasks can own a resource at any one time.

Access to a resource controlled by a counting semaphore is acquired
with a call to RTX_Wait_Sem() or RTX_Get_Sem().

If the resource is available the @CHIP-RTOS gives it to the task immediately.
When the task is finished using the resource,
it signals its release by calling RTX_Signal_Sem().

Using a resource semaphore:

A resource semaphore is created by specifying
an initial count of -1 in the call of RTX_Create_Sem().

The @CHIP-RTOS creates a resource semaphore and automatically
gives it an initial value of one indicating that the resource is free.

A resource is reserved by calling RTX_Reserve_Sem() with the semaphore ID
returned by RTX_Create_Sem().
The resource is released with a call to RTX_Release_Sem().

Semaphore Services:

RTX_Create_Sem() Create a semaphore
RTX_Delete_Sem() Delete a semaphore
RTX_Get_Sem() Get access to semaphore (no wait)
RTX_Wait_Sem() Wait on a semaphore (optional timeout)

--- Resource Semaphore API ----
RTX_Free_Sem() Free a resource semaphore
RTX_Release_Sem() Release a resource semaphore
RTX_Reserve_Sem() Get a resource semaphore

--- Counting Semaphore API ----
RTX_Signal_Sem() Signal a counting semaphore

http://www.keil.com/pack/doc/arm/cmsis/cmsis/documentation/rtos/html/group___c_m_s_i_s___r_t_o_s___semaphore_mgmt.html#details

The Semaphore Management function group is used to manage and protect access to shared resources.
For example, with a Semaphore the access to a group of identical peripherals can be managed.
The number of available resources is specified as parameter of the osSemaphoreCreate function.

Each time a Semaphore token is obtained with osSemaphoreWait the semaphore count is decremented.
When the semaphore count is 0, no Semaphore token can be obtained.
Semaphores are released with osSemaphoreRelease; this function increments the semaphore count.