Espressif ESP32-S2 Programming Manual page 923

Chapter 2. API Reference
(decrementing the semaphore count value). The count value is therefore the difference between the number of
events that have occurred and the number that have been processed. In this case it is desirable for the initial
count value to be zero.
2) Resource management.
In this usage scenario the count value indicates the number of resources available. To obtain control of a
resource a task must first obtain a semaphore - decrementing the semaphore count value. When the count value
reaches zero there are no free resources. When a task finishes with the resource it'gives' the semaphore back
- incrementing the semaphore count value. In this case it is desirable for the initial count value to be equal to
the maximum count value, indicating that all resources are free.
Example usage:
SemaphoreHandle_t xSemaphore;
void vATask( void
{
SemaphoreHandle_t xSemaphore
// Semaphore cannot be used before a call to
// The max value to which the semaphore can count should be 10,
// initial value assigned to the count should be
xSemaphore = xSemaphoreCreateCounting( 10,
if( xSemaphore
{
// The semaphore was created
// The semaphore can now be
}
}
Return Handle to the created semaphore. Null if the semaphore could not be created.
Parameters
• uxMaxCount: The maximum count value that can be reached. When the semaphore reaches this
value it can no longer be 'given'.
• uxInitialCount: The count value assigned to the semaphore when it is created.
xSemaphoreCreateCountingStatic(uxMaxCount, uxInitialCount, pxSemaphoreBuffer)
Creates a new counting semaphore instance, and returns a handle by which the new counting semaphore can
be referenced.
In many usage scenarios it is faster and more memory efficient to use a direct to task notification in place of a
counting semaphore!
Internally, within the FreeRTOS implementation, counting semaphores use a block of memory, in which the
counting semaphore structure is stored. If a counting semaphore is created using xSemaphoreCreateCount-
ing() then the required memory is automatically dynamically allocated inside the xSemaphoreCreateCount-
ing() function. (see https://www.FreeRTOS.org/a00111.html). If a counting semaphore is created using
xSemaphoreCreateCountingStatic() then the application writer must provide the memory. xSemaphoreCre-
ateCountingStatic() therefore allows a counting semaphore to be created without using any dynamic memory
allocation.
Counting semaphores are typically used for two things:
1) Counting events.
In this usage scenario an event handler will 'give'a semaphore each time an event occurs (incrementing
the semaphore count value), and a handler task will 'take'a semaphore each time it processes an event
(decrementing the semaphore count value). The count value is therefore the difference between the number of
events that have occurred and the number that have been processed. In this case it is desirable for the initial
count value to be zero.
2) Resource management.
Espressif Systems
* pvParameters )
= NULL;
!= NULL )
successfully.
used.
https://www.FreeRTOS.org/RTOS-task-notifications.html
Submit Document Feedback
xSemaphoreCreateCounting().
0.
0 );
912
and the
Release v4.4