Chapter 2. API Reference
xSemaphoreCreateBinary() are created in a state such that the the semaphore must first be ‘given’before it
can be ‘taken’.
This type of semaphore can be used for pure synchronisation between tasks or between an interrupt and a
task. The semaphore need not be given back once obtained, so one task/interrupt can continuously‘give’the
semaphore while another continuously‘takes’the semaphore. For this reason this type of semaphore does not
use a priority inheritance mechanism. For an alternative that does use priority inheritance see xSemaphoreCre-
ateMutex().
Example usage:
SemaphoreHandle_t xSemaphore = NULL;
void vATask( void * pvParameters )
{
// Semaphore cannot be used before a call to vSemaphoreCreateBinary().
// This is a macro so pass the variable in directly.
xSemaphore = xSemaphoreCreateBinary();
if( xSemaphore != NULL )
{
// The semaphore was created successfully.
// The semaphore can now be used.
}
}
Return Handle to the created semaphore, or NULL if the memory required to hold the semaphore’s data
structures could not be allocated.
xSemaphoreCreateBinaryStatic(pxStaticSemaphore)
Creates a new binary semaphore instance, and returns a handle by which the new semaphore can be referenced.
NOTE: In many usage scenarios it is faster and more memory efficient to use a direct to task notification in
place of a binary semaphore! https://www.FreeRTOS.org/RTOS-task-notifications.html
Internally, within the FreeRTOS implementation, binary semaphores use a block of memory, in which the
semaphore structure is stored. If a binary semaphore is created using xSemaphoreCreateBinary() then the
required memory is automatically dynamically allocated inside the xSemaphoreCreateBinary() function. (see
https://www.FreeRTOS.org/a00111.html). If a binary semaphore is created using xSemaphoreCreateBina-
ryStatic() then the application writer must provide the memory. xSemaphoreCreateBinaryStatic() therefore
allows a binary semaphore to be created without using any dynamic memory allocation.
This type of semaphore can be used for pure synchronisation between tasks or between an interrupt and a
task. The semaphore need not be given back once obtained, so one task/interrupt can continuously‘give’the
semaphore while another continuously‘takes’the semaphore. For this reason this type of semaphore does not
use a priority inheritance mechanism. For an alternative that does use priority inheritance see xSemaphoreCre-
ateMutex().
Example usage:
SemaphoreHandle_t xSemaphore = NULL;
StaticSemaphore_t xSemaphoreBuffer;
void vATask( void * pvParameters )
{
// Semaphore cannot be used before a call to xSemaphoreCreateBinary() or
// xSemaphoreCreateBinaryStatic().
// The semaphore's data structures will be placed in the xSemaphoreBuffer
// variable, the address of which is passed into the function. The
// function's parameter is not NULL, so the function will not attempt any
// dynamic memory allocation, and therefore the function will not return
// return NULL.
xSemaphore = xSemaphoreCreateBinaryStatic( &xSemaphoreBuffer );
(continues on next page)
Espressif Systems 902
Submit Document Feedback
Release v4.4
To Next Page
Loading...