Semaphore

Table of Contents

• Features Supported
• Features NOT Supported
• Important Usage Guidelines
• Example Usage
• API

Features Supported

• APIs to create binary and counting semaphore's
• APIs to create mutual exclusion semaphore
• Nesting of mutual exclusion semaphores
• Priority inheritance when supported by the underlying OS

Features NOT Supported

NA

Important Usage Guidelines

• SemaphoreP_post can be called from ISR as well as task context
• SemaphoreP_pend should not be called within ISR context. It can be called from task context.
• SemaphoreP_pend will block until the user specific timeout ticks have expired or semaphore is acquired.
  • In baremetal case, there is only a single main task and that will block or spin until the ticks have elasped or semaphore acquire is successful
  • In RTOS case, the current executing task will 'pend' and schedular will switch to another ready task until the ticks have elasped or semaphore acquire is successful
  • In both cases ISR's are still active
• There is nothing like priority inheritance in no-RTOS mode

Example Usage

Include the below file to access the APIs,

#include <kernel/dpl/SemaphoreP.h>
#include <kernel/dpl/ClockP.h>

Example usage to define a semaphore

/* semaphore objects, typically these are global's */
SemaphoreP_Object gBinarySem;
SemaphoreP_Object gMutexSem;
SemaphoreP_Object gCountingSem;
 
/* resource to protect with counting semaphore */
#define NUM_RESOURCES   (10u)
uint32_t gResource[NUM_RESOURCES];
 

Example usage to post a binary semaphore from a ISR

/* peripheral ISR which post's the binary semaphore */
void myISR(void *args)
{
    SemaphoreP_post(&gBinarySem);
}

Example usage to create and use a mutex

    SemaphoreP_constructMutex(&gMutexSem);
 
    /* wait forever for the mutex to be available, lock or enter the critical section */
    SemaphoreP_pend(&gMutexSem, SystemP_WAIT_FOREVER);
 
    /* mutual exclusion, critical section */
 
    /* unlock the mutex, exit critical section */
    SemaphoreP_post(&gMutexSem);

Example usage to create and use a binary semaphore with timeout

    int32_t status;
 
    SemaphoreP_constructBinary(&gBinarySem, 0);
 
    // initialize peripheral
    // register myISR
    // enable peripheral
 
    /* wait for 10ms for the semaphore to be post by the peripheral */
    status = SemaphoreP_pend(&gBinarySem, ClockP_usecToTicks(10*1000));
    if(status==SystemP_SUCCESS)
    {
        /* success */
    }
    else
    if(status==SystemP_TIMEOUT)
    {
        /* failed due to timeout */
    }
    else
    {
        /* other failure */
    }
 

Example usage to create and use a counting semaphore

    uint32_t resourceId = 0;
 
    SemaphoreP_constructCounting(&gCountingSem, NUM_RESOURCES, NUM_RESOURCES);
 
    /* wait for a resource to be available */
    SemaphoreP_pend(&gCountingSem, SystemP_WAIT_FOREVER);
 
    /* access the resource */
 
    /* release resoource */
    resourceId = (resourceId+1)%NUM_RESOURCES;
    SemaphoreP_post(&gCountingSem);
 

API

APIs for Semaphore