Coldwave Documentation

Appearance

Semaphores ​

A semaphore is used as a signaling mechanism between threads or interrupt routines.

When a semaphore is acquired or taken (by calling osSemaphoreAcquire()), the associated count is decreased. When a semaphore is released or given (by calling osSemaphoreRelease()), the count is increased.

If a thread tries to acquire a semaphore, but the semaphore's count is zero, the thread will be put into a Blocked state, waiting until another task releases that semaphore.

If the count is greater than zero, the thread will acquire the semaphore and continue its execution.

Semaphores are created using osSemaphoreNew() and deleted using osSemaphoreDelete(). Each semaphore has an associated osSemaphoreId_t identifier.

Semaphores are thread-safe, meaning that multiple threads can safely attempt to acquire or release the semaphore concurrently without corrupting its state.

Example usage ​

cpp
 #include <kernel.h>

 osSemaphoreId_t sem_id;  // Declare a semaphore id

 void workerThread(void *argument)
 {
    // Your specific handling code
    // ...

   // Then, wait for a semaphore using its ID
    osStatus_t status = osSemaphoreAcquire(sem_id, osWaitForever);

    if (status == osOK) {
        // Acquired the semaphore successfully. Proceed to protected region of code.
        // Enter protected code

        // ...

        // Done with protected code. Release semaphore
        osSemaphoreRelease(sem_id);
    }
 }

 int main() {
    // Your OS initialization code
    // ...

    osThreadId_t tid_workerThread;

    // Create a semaphore
    sem_id = osSemaphoreNew(1, 1, NULL);

    if(sem_id == NULL){
        //handle case when semaphore could not be created
    }

    // Create a workerThread
    tid_workerThread = osThreadNew(workerThread, NULL, NULL);

    // Your specific code
    // ...

    // When it's time to allow the workerThread to proceed
    osSemaphoreRelease(sem_id);

    return 0;
}

Types ​

Name
structosSemaphoreAttr_t

Functions Overview ​

Name
osSemaphoreId_tosSemaphoreNew(uint32_t max_count, uint32_t initial_count, const osSemaphoreAttr_t * attr)
Create and Initialize a Semaphore object.
const char *osSemaphoreGetName(osSemaphoreId_t semaphore_id)
Get name of a Semaphore object.
osStatus_tosSemaphoreAcquire(osSemaphoreId_t semaphore_id, uint32_t timeout)
Acquire a Semaphore token or timeout if no tokens are available.
osStatus_tosSemaphoreRelease(osSemaphoreId_t semaphore_id)
Release a Semaphore token up to the initial maximum count.
uint32_tosSemaphoreGetCount(osSemaphoreId_t semaphore_id)
Get current Semaphore token count.
osStatus_tosSemaphoreDelete(osSemaphoreId_t semaphore_id)
Delete a Semaphore object.
uint32_tosSemaphoreReset(osSemaphoreId_t semaphore_id)
Rese a Semaphore to its initial state.

Function Details ​

function osSemaphoreNew ​

cpp
osSemaphoreId_t osSemaphoreNew(
    uint32_t max_count,
    uint32_t initial_count,
    const osSemaphoreAttr_t * attr
)

Create and Initialize a Semaphore object.

Parameters:

  • max_count maximum number of available tokens.
  • initial_count initial number of available tokens.
  • attr semaphore attributes; NULL: default values.

Return: semaphore ID for reference by other functions or NULL in case of error.

function osSemaphoreGetName ​

cpp
const char * osSemaphoreGetName(
    osSemaphoreId_t semaphore_id
)

Get name of a Semaphore object.

Parameters:

Return: name as null-terminated string.

function osSemaphoreAcquire ​

cpp
osStatus_t osSemaphoreAcquire(
    osSemaphoreId_t semaphore_id,
    uint32_t timeout
)

Acquire a Semaphore token or timeout if no tokens are available.

Parameters:

  • semaphore_id semaphore ID obtained by osSemaphoreNew.
  • timeout CMSIS_RTOS_TimeOutValue or 0 in case of no time-out.

Return: status code that indicates the execution status of the function.

function osSemaphoreRelease ​

cpp
osStatus_t osSemaphoreRelease(
    osSemaphoreId_t semaphore_id
)

Release a Semaphore token up to the initial maximum count.

Parameters:

Return: status code that indicates the execution status of the function.

function osSemaphoreGetCount ​

cpp
uint32_t osSemaphoreGetCount(
    osSemaphoreId_t semaphore_id
)

Get current Semaphore token count.

Parameters:

Return: number of tokens available.

function osSemaphoreDelete ​

cpp
osStatus_t osSemaphoreDelete(
    osSemaphoreId_t semaphore_id
)

Delete a Semaphore object.

Parameters:

Return: status code that indicates the execution status of the function.

function osSemaphoreReset ​

cpp
uint32_t osSemaphoreReset(
    osSemaphoreId_t semaphore_id
)

Rese a Semaphore to its initial state.

Parameters:

Return: status code that indicates the execution status of the function.