Chapter 2. API Reference
‘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;
void vATask( void * pvParameters )
{
// Semaphore cannot be used before a call to xSemaphoreCreateMutex().
// This is a macro so pass the variable in directly.
xSemaphore = xSemaphoreCreateMutex();
if( xSemaphore != NULL )
{
// The semaphore was created successfully.
// The semaphore can now be used.
}
}
Return If the mutex was successfully created then a handle to the created semaphore is returned. If there was
not enough heap to allocate the mutex data structures then NULL is returned.
xSemaphoreCreateMutexStatic(pxMutexBuffer)
Creates a new mutex type semaphore instance, and returns a handle by which the new mutex can be referenced.
Internally, within the FreeRTOS implementation, mutex semaphores use a block of memory, in which
the mutex structure is stored. If a mutex is created using xSemaphoreCreateMutex() then the required
memory is automatically dynamically allocated inside the xSemaphoreCreateMutex() function. (see https:
//www.FreeRTOS.org/a00111.html). If a mutex is created using xSemaphoreCreateMutexStatic() then the
application writer must provided the memory. xSemaphoreCreateMutexStatic() therefore allows a mutex to
be created without using any dynamic memory allocation.
Mutexes created using this function can be accessed using the xSemaphoreTake() and xSemaphoreGive()
macros. The xSemaphoreTakeRecursive() and xSemaphoreGiveRecursive() macros must not be used.
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 * pvParameters )
{
// A mutex cannot be used before it has been created. xMutexBuffer is
// into xSemaphoreCreateMutexStatic() so no dynamic memory allocation is
// attempted.
xSemaphore = xSemaphoreCreateMutexStatic( &xMutexBuffer );
// As no dynamic memory allocation was performed, xSemaphore cannot be NULL,
// so there is no need to check it.
}
Espressif Systems 909
Submit Document Feedback
Release v4.4
To Next Page
Loading...