Espressif ESP32-S2 Programming Manual page 974

Chapter 2. API Reference
(continued from previous page)
//Create a ring buffer with manually allocated memory
RingbufHandle_t handle = xRingbufferCreateStatic(BUFFER_SIZE, BUFFER_TYPE, buffer_
storage, buffer_struct);
→
...
//Delete the ring buffer after used
vRingbufferDelete(handle);
//Manually free all blocks of memory
free(buffer_struct);
free(buffer_storage);
Priority Inversion Ideally, ring buffers can be used with multiple tasks in an SMP fashion where the highest
priority task will always be serviced first. However due to the usage of binary semaphores in the ring buffer's
underlying implementation, priority inversion may occur under very specific circumstances.
The ring buffer governs sending by a binary semaphore which is given whenever space is freed on the ring buffer. The
highest priority task waiting to send will repeatedly take the semaphore until sufficient free space becomes available
or until it times out. Ideally this should prevent any lower priority tasks from being serviced as the semaphore should
always be given to the highest priority task.
However, in between iterations of acquiring the semaphore, there is a gap in the critical section which may permit
another task (on the other core or with an even higher priority) to free some space on the ring buffer and as a result give
the semaphore. Therefore, the semaphore will be given before the highest priority task can re-acquire the semaphore.
This will result in the semaphore being acquired by the second-highest priority task waiting to send, hence
causing priority inversion.
This side effect will not affect ring buffer performance drastically given if the number of tasks using the ring buffer
simultaneously is low, and the ring buffer is not operating near maximum capacity.
Hooks
FreeRTOS consists of Idle Hooks and Tick Hooks which allow for application specific functionality to be added to the
Idle Task and Tick Interrupt. ESP-IDF provides its own Idle and Tick Hook API in addition to the hooks provided
by vanilla FreeRTOS. ESP-IDF hooks have the added benefit of being run time configurable and asymmetrical.
Vanilla FreeRTOS Hooks Idle and Tick Hooks in vanilla FreeRTOS are implemented by the user defining the
functions vApplicationIdleHook() and vApplicationTickHook() respectively somewhere in the ap-
plication. Vanilla FreeRTOS will run the user defined Idle Hook and Tick Hook on every iteration of the Idle Task
and Tick Interrupt respectively.
Vanilla FreeRTOS hooks are referred to as Legacy Hooks in ESP-IDF FreeRTOS. To enable legacy hooks, CON-
FIG_FREERTOS_LEGACY_HOOKS should be enabled in project configuration menu.
ESP-IDF Idle and Tick Hooks For some use-cases it may be necessary for the Idle Tasks or Tick Interrupts to
execute multiple hooks that are configurable at run time.
Therefore, ESP-IDF provides its own hooks API in addition to the legacy hooks provided by vanilla FreeRTOS.
The ESP-IDF tick and idle hooks are registered at run time. Each tick hook and idle hook must be registered to a
specific CPU. When the idle task runs or a tick interrupt occurs on a particular CPU, the CPU will run each of its
registered idle hook and tick hook in turn.
Note: Tick interrupt stays active whilst cache is disabled and hence vApplicationTickHook() (legacy case)
or ESP-IDF tick hooks must be placed in internal RAM. Please refer to the SPI flash API documentation for more
Espressif Systems 963 Release v4.4
Submit Document Feedback