Freertos Additions - Espressif ESP32-S2 Programming Manual

Chapter 2. API Reference

2.6.11 FreeRTOS Additions

This document describes the additional features added to ESP-IDF FreeRTOS. This document is split into the fol-
lowing parts:
Contents
• FreeRTOS Additions
– Overview
– Ring Buffers
– Hooks
– TLSP Deletion Callbacks
– Component Specific Properties
– API Reference
Overview
ESP-IDF FreeRTOS is modified version of based on the Xtensa port of FreeRTOS v10.4.3 with significant modi-
fications for SMP compatibility (see
ESP-IDF FreeRTOS have been added. The features are as follows:
• Ring buffers: Ring buffers provide a FIFO buffer that can accept entries of arbitrary lengths.
• Hooks: ESP-IDF FreeRTOS hooks provides support for registering extra Idle and Tick hooks at run time.
Moreover, the hooks can be asymmetric among both CPUs.
• Thread Local Storage Pointer (TLSP) Deletion Callbacks: TLSP Deletion callbacks are run automatically
when a task is deleted, thus allowing users to clean up their TLSPs automatically.
• Component Specific Properties:
ORIG_INCLUDE_PATH.
Ring Buffers
The ESP-IDF FreeRTOS ring buffer is a strictly FIFO buffer that supports arbitrarily sized items. Ring buffers are a
more memory efficient alternative to FreeRTOS queues in situations where the size of items is variable. The capacity
of a ring buffer is not measured by the number of items it can store, but rather by the amount of memory used for
storing items. The ring buffer provides API to send an item, or to allocate space for an item in the ring buffer to be
filled manually by the user. For efficiency reasons, items are always retrieved from the ring buffer by reference.
As a result, all retrieved items must also be returned to the ring buffer by using
or vRingbufferReturnItemFromISR(), in order for them to be removed from the ring buffer completely.
The ring buffers are split into the three following types:
No-Split buffers will guarantee that an item is stored in contiguous memory and will not attempt to split an item
under any circumstances. Use No-Split buffers when items must occupy contiguous memory. Only this buffer type
allows you to get the data item address and write to the item by yourself. Refer the documentation of the functions
xRingbufferSendAcquire()
Allow-Split buffers will allow an item to be split in two parts when wrapping around the end of the buffer if there is
enough space at the tail and the head of the buffer combined to store the item. Allow-Split buffers are more memory
efficient than No-Split buffers but can return an item in two parts when retrieving.
Byte buffers do not store data as separate items. All data is stored as a sequence of bytes, and any number of bytes
can be sent or retrieved each time. Use byte buffers when separate items do not need to be maintained (e.g. a byte
stream).
Note: No-Split buffers and Allow-Split buffers will always store items at 32-bit aligned addresses. Therefore, when
retrieving an item, the item pointer is guaranteed to be 32-bit aligned. This is useful especially when you need to
send some data to the DMA.
Espressif Systems
ESP-IDF FreeRTOS SMP Changes). However, various new features specific to
Currently added only one component specific property
and xRingbufferSendComplete()
955
Submit Document Feedback
vRingbufferReturnItem()
for more details.
Release v4.4