Espressif ESP32-S2 Programming Manual page 922

Chapter 2. API Reference
xSemaphoreCreateRecursiveMutexStatic() therefore allows a recursive mutex to be created without using any
dynamic memory allocation.
Mutexes created using this macro can be accessed using the xSemaphoreTakeRecursive() and xSemaphore-
GiveRecursive() macros. The xSemaphoreTake() and xSemaphoreGive() macros must not be used.
A mutex used recursively can be 'taken'repeatedly by the owner. The mutex doesn't become available
again until the owner has called xSemaphoreGiveRecursive() for each successful'take' request. For example,
if a task successfully 'takes'the same mutex 5 times then the mutex will not be available to any other task
until it has also 'given'the mutex back exactly five times.
This type of semaphore uses a priority inheritance mechanism so a task 'taking' a semaphore MUST ALWAYS
'give'the semaphore back once the semaphore it is no longer required.
Mutex type semaphores cannot be used from within interrupt service routines.
See xSemaphoreCreateBinary() for an alternative implementation that can be used for pure synchronisation
(where one task or interrupt always 'gives'the semaphore and another always 'takes'the semaphore) and
from within interrupt service routines.
Example usage:
SemaphoreHandle_t xSemaphore;
StaticSemaphore_t xMutexBuffer;
void vATask( void
{
// A recursive semaphore cannot be used before it
// recursive mutex
// The address of xMutexBuffer
// the mutexes data structures
// attempted.
xSemaphore =
// As no dynamic memory allocation was performed, xSemaphore cannot be NULL,
// so there
}
Return If the recursive mutex was successfully created then a handle to the created recursive mutex is returned.
If pxMutexBuffer was NULL then NULL is returned.
Parameters
• pxStaticSemaphore: Must point to a variable of type StaticSemaphore_t, which will then be
used to hold the recursive mutex' s data structure, removing the need for the memory to be allocated
dynamically.
xSemaphoreCreateCounting(uxMaxCount, uxInitialCount)
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 xSemaphoreCreate-
Counting() then the required memory is automatically dynamically allocated inside the xSemaphoreCreate-
Counting() function. (see https://www.FreeRTOS.org/a00111.html). If a counting semaphore is created us-
ing xSemaphoreCreateCountingStatic() then the application writer can instead optionally provide the memory
that will get used by the counting semaphore. xSemaphoreCreateCountingStatic() 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
Espressif Systems
* pvParameters )
is created using
is
-
xSemaphoreCreateRecursiveMutexStatic( &xMutexBuffer );
is no need to check
https://www.FreeRTOS.org/RTOS-task-notifications.html
Submit Document Feedback
is
xSemaphoreCreateRecursiveMutexStatic().
passed into the function,
so no dynamic memory allocation will be
it.
911
created. Here a
and will hold
Release v4.4