AM263Px MCU+ SDK: Semaphore

| AM263Px MCU+ SDK 26.00.00 |

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,

#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

args
void * args
Definition: hsmclient_msg.h:4
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_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.