AM263x MCU+ SDK  08.02.01
Semaphore

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,

Example usage to define a semaphore

/* semaphore objects, typically these are global's */
SemaphoreP_Object gBinarySem;
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

/* wait forever for the mutex to be available, lock or enter the critical section */
/* 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 */
/* access the resource */
/* release resoource */
resourceId = (resourceId+1)%NUM_RESOURCES;
SemaphoreP_post(&gCountingSem);

API

APIs for Semaphore

SystemP_WAIT_FOREVER
#define SystemP_WAIT_FOREVER
Value to use when needing a timeout of infinity or wait forver until resource is available.
Definition: SystemP.h:83
SemaphoreP.h
SemaphoreP_constructCounting
int32_t SemaphoreP_constructCounting(SemaphoreP_Object *obj, uint32_t initValue, uint32_t maxValue)
Create a counting semaphore object.
ClockP.h
SemaphoreP_constructMutex
int32_t SemaphoreP_constructMutex(SemaphoreP_Object *obj)
Create a mutex semaphore object.
SystemP_TIMEOUT
#define SystemP_TIMEOUT
Return status when the API execution was not successful due to a time out.
Definition: SystemP.h:66
SystemP_SUCCESS
#define SystemP_SUCCESS
Return status when the API execution was successful.
Definition: SystemP.h:56
SemaphoreP_post
void SemaphoreP_post(SemaphoreP_Object *obj)
Post a semaphore object or unlock a mutex.
SemaphoreP_Object
Opaque semaphore object used with the semaphore APIs.
Definition: SemaphoreP.h:59
SemaphoreP_constructBinary
int32_t SemaphoreP_constructBinary(SemaphoreP_Object *obj, uint32_t initValue)
Create a binary semaphore object.
ClockP_usecToTicks
uint32_t ClockP_usecToTicks(uint64_t usecs)
Convert usecs to clock ticks.
SemaphoreP_pend
int32_t SemaphoreP_pend(SemaphoreP_Object *obj, uint32_t timeToWaitInTicks)
Pend on a semaphore object or lock a mutex.