Chapter 2. API Reference
details.
TLSP Deletion Callbacks
Vanilla FreeRTOS provides a Thread Local Storage Pointers (TLSP) feature. These are pointers stored directly in
the Task Control Block (TCB) of a particular task. TLSPs allow each task to have its own unique set of pointers to
data structures. Vanilla FreeRTOS expects users to…
• set a task’s TLSPs by calling vTaskSetThreadLocalStoragePointer() after the task has been
created.
• get a task’s TLSPs by calling pvTaskGetThreadLocalStoragePointer() during the task’s life-
time.
• free the memory pointed to by the TLSPs before the task is deleted.
However, there can be instances where users may want the freeing of TLSP memory to be automatic. Therefore, ESP-
IDF FreeRTOS provides the additional feature of TLSP deletion callbacks. These user provided deletion callbacks
are called automatically when a task is deleted, thus allows the TLSP memory to be cleaned up without needing to
add the cleanup logic explicitly to the code of every task.
The TLSP deletion callbacks are set in a similar fashion to the TLSPs themselves.
• vTaskSetThreadLocalStoragePointerAndDelCallback() sets both a particular TLSP and its
associated callback.
• Calling the Vanilla FreeRTOS function vTaskSetThreadLocalStoragePointer() will simply set
the TLSP’s associated Deletion Callback to NULL meaning that no callback will be called for that TLSP
during task deletion.
When implementing TLSP callbacks, users should note the following:
• The callback must never attempt to block or yield and critical sections should be kept as short as possible
• The callback is called shortly before a deleted task’s memory is freed. Thus, the callback can either be called
from vTaskDelete() itself, or from the idle task.
Component Specific Properties
Besides standard component variables that are available with basic cmake build properties, FreeRTOS component
also provides arguments (only one so far) for simpler integration with other modules:
• ORIG_INCLUDE_PATH - contains an absolute path to freertos root include folder. Thus instead of #include
“freertos/FreeRTOS.h” you can refer to headers directly: #include “FreeRTOS.h”.
API Reference
Ring Buffer API
Header File
• components/esp_ringbuf/include/freertos/ringbuf.h
Functions
RingbufHandle_t xRingbufferCreate(size_t xBufferSize, RingbufferType_t xBufferType)
Create a ring buffer.
Note xBufferSize of no-split/allow-split buffers will be rounded up to the nearest 32-bit aligned size.
Return A handle to the created ring buffer, or NULL in case of error.
Parameters
• [in] xBufferSize: Size of the buffer in bytes. Note that items require space for overhead in
no-split/allow-split buffers
Espressif Systems 964
Submit Document Feedback
Release v4.4