OVMS3-idf/docs/en/api-reference/system/freertos_additions.rst

FreeRTOS Additions
==================

Overview
--------

ESP-IDF FreeRTOS is based on the Xtensa port of FreeRTOS v8.2.0 with significant modifications
for SMP compatibility (see :doc:`ESP-IDF FreeRTOS SMP Changes<../../api-guides/freertos-smp>`).
However various features specific to ESP-IDF FreeRTOS have been added. The features are as follows:

:ref:`ring-buffers`: Ring buffers were added to provide a form of buffer that could accept
entries of arbitrary lengths.

:ref:`hooks`: ESP-IDF FreeRTOS hooks provides support for registering extra Idle and
Tick hooks at run time. Moreover, the hooks can be asymmetric amongst both CPUs.


.. _ring-buffers:

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. Items are sent to 
ring buffers by copy, however for efficiency reasons **items are retrieved by reference**. As a
result, all retrieved items **must also be returned** 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. 

**Allow-Split** buffers will allow an item to be split when wrapping around if doing so will allow
the item to be stored. 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 and 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/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.

.. note::
    Each item stored in no-split/allow-split buffers will **require an additional 8 bytes for a header**.
    Item sizes will also be rounded up to a 32-bit aligned size (multiple of 4 bytes), however the true
    item size is recorded within the header. The sizes of no-split/allow-split buffers will also
    be rounded up when created.

Usage
^^^^^

The following example demonstrates the usage of :cpp:func:`xRingbufferCreate`
and :cpp:func:`xRingbufferSend` to create a ring buffer then send an item to it.

.. code-block:: c

    #include "freertos/ringbuf.h"
    static char tx_item[] = "test_item";

    ...

        //Create ring buffer
        RingbufHandle_t buf_handle;
        buf_handle = xRingbufferCreate(1028, RINGBUF_TYPE_NOSPLIT);
        if (buf_handle == NULL) {
            printf("Failed to create ring buffer\n");
        }

        //Send an item
        UBaseType_t res =  xRingbufferSend(buf_handle, tx_item, sizeof(tx_item), pdMS_TO_TICKS(1000));
        if (res != pdTRUE) {
            printf("Failed to send item\n");
        }


The following example demonstrates retrieving and returning an item from a **no-split ring buffer**
using :cpp:func:`xRingbufferReceive` and :cpp:func:`vRingbufferReturnItem`

.. code-block:: c

    ...
        
        //Receive an item from no-split ring buffer
        size_t item_size;
        char *item = (char *)xRingbufferReceive(buf_handle, &item_size, pdMS_TO_TICKS(1000));

        //Check received item
        if (item != NULL) {
            //Print item
            for (int i = 0; i < item_size; i++) {
                printf("%c", item[i]);
            }
            printf("\n");
            //Return Item
            vRingbufferReturnItem(buf_handle, (void *)item);
        } else {
            //Failed to receive item
            printf("Failed to receive item\n");
        }


The following example demonstrates retrieving and returning an item from an **allow-split ring buffer**
using :cpp:func:`xRingbufferReceiveSplit` and :cpp:func:`vRingbufferReturnItem`

.. code-block:: c

    ...

        //Receive an item from allow-split ring buffer
        size_t item_size1, item_size2;
        char *item1, *item2;
        BaseType_t ret = xRingbufferReceiveSplit(buf_handle, (void **)&item1, (void **)&item2, &item_size1, &item_size2, pdMS_TO_TICKS(1000));

        //Check received item
        if (ret == pdTRUE && item1 != NULL) {
            for (int i = 0; i < item_size1; i++) {
                printf("%c", item1[i]);
            }
            vRingbufferReturnItem(buf_handle, (void *)item1);
            //Check if item was split
            if (item2 != NULL) {
                for (int i = 0; i < item_size2; i++) {
                    printf("%c", item2[i]);
                }
                vRingbufferReturnItem(buf_handle, (void *)item2);
            }
            printf("\n");
        } else {
            //Failed to receive item
            printf("Failed to receive item\n");
        }


The following example demonstrates retrieving and returning an item from a **byte buffer**
using :cpp:func:`xRingbufferReceiveUpTo` and :cpp:func:`vRingbufferReturnItem`

.. code-block:: c

    ...

        //Receive data from byte buffer
        size_t item_size;
        char *item = (char *)xRingbufferReceiveUpTo(buf_handle, &item_size, pdMS_TO_TICKS(1000), sizeof(tx_item));

        //Check received data
        if (item != NULL) {
            //Print item
            for (int i = 0; i < item_size; i++) {
                printf("%c", item[i]);
            }
            printf("\n");
            //Return Item
            vRingbufferReturnItem(buf_handle, (void *)item);
        } else {
            //Failed to receive item
            printf("Failed to receive item\n");
        }


For ISR safe versions of the functions used above, call :cpp:func:`xRingbufferSendFromISR`, :cpp:func:`xRingbufferReceiveFromISR`,
:cpp:func:`xRingbufferReceiveSplitFromISR`, :cpp:func:`xRingbufferReceiveUpToFromISR`, and :cpp:func:`vRingbufferReturnItemFromISR` 


Sending to Ring Buffer
^^^^^^^^^^^^^^^^^^^^^^

The following diagrams illustrate the differences between no-split/allow-split buffers 
and byte buffers with regards to sending items/data. The diagrams assume that three 
items of sizes **18, 3, and 27 bytes** are sent respectively to a **buffer of 128 bytes**.

.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_send_non_byte_buf.diag
    :caption: Sending items to no-split/allow-split ring buffers
    :align: center

For no-split/allow-split buffers, a header of 8 bytes precedes every data item. Furthermore, the space 
occupied by each item is **rounded up to the nearest 32-bit aligned size** in order to maintain overall
32-bit alignment. However the true size of the item is recorded inside the header which will be 
returned when the item is retrieved.

Referring to the diagram above, the 18, 3, and 27 byte items are **rounded up to 20, 4, and 28 bytes**
respectively. An 8 byte header is then added in front of each item.

.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_send_byte_buf.diag
    :caption: Sending items to byte buffers
    :align: center

Byte buffers treat data as a sequence of bytes and does not incur any overhead 
(no headers). As a result, all data sent to a byte buffer is merged into a single item.

Referring to the diagram above, the 18, 3, and 27 byte items are sequentially written to the
byte buffer and **merged into a single item of 48 bytes**.

Wrap around
^^^^^^^^^^^

The following diagrams illustrate the differences between no-split, allow-split, and byte
buffers when a sent item requires a wrap around. The diagrams assumes a buffer of **128 bytes**
with **56 bytes of free space that wraps around** and a sent item of **28 bytes**.

.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_wrap_no_split.diag
    :caption: Wrap around in no-split buffers
    :align: center

No-split buffers will **only store an item in continuous free space and will not split
an item under any circumstances**. When the free space at the tail of the buffer is insufficient
to completely store the item and its header, the free space at the tail will be **marked as dummy data**. 
The buffer will then wrap around and store the item in the free space at the head of the buffer.

Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is 
insufficient to store the 28 byte item. Therefore the 16 bytes is marked as dummy data and
the item is written to the free space at the head of the buffer instead.

.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_wrap_allow_split.diag
    :caption: Wrap around in allow-split buffers 
    :align: center

Allow-split buffers will attempt to **split the item into two parts** when the free space at the tail
of the buffer is insufficient to store the item data and its header. Both parts of the
split item will have their own headers (therefore incurring an extra 8 bytes of overhead).

Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is insufficient
to store the 28 byte item. Therefore the item is split into two parts (8 and 20 bytes) and written
as two parts to the buffer.

.. note::
    Allow-split buffers treats the both parts of the split item as two separate items, therefore call
    :cpp:func:`xRingbufferReceiveSplit` instead of :cpp:func:`xRingbufferReceive` to receive both
    parts of a split item in a thread safe manner.

.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_wrap_byte_buf.diag
    :caption: Wrap around in byte buffers 
    :align: center

Byte buffers will **store as much data as possible into the free space at the tail of buffer**. The remaining 
data will then be stored in the free space at the head of the buffer. No overhead is incurred when wrapping
around in byte buffers.

Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is insufficient to
completely store the 28 bytes of data. Therefore the 16 bytes of free space is filled with data, and the
remaining 12 bytes are written to the free space at the head of the buffer. The buffer now contains
data in two separate continuous parts, and each part continuous will be treated as a separate item by the 
byte buffer.

Retrieving/Returning
^^^^^^^^^^^^^^^^^^^^

The following diagrams illustrates the differences between no-split/allow-split and
byte buffers in retrieving and returning data.

.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_read_ret_non_byte_buf.diag
    :caption: Retrieving/Returning items in no-split/allow-split ring buffers
    :align: center

Items in no-split/allow-split buffers are **retrieved in strict FIFO order** and **must be returned** 
for the occupied space to be freed. Multiple items can be retrieved before returning, and the items 
do not necessarily need to be returned in the order they were retrieved. However the freeing of space
must occur in FIFO order, therefore not returning the earliest retrieved item will prevent the space 
of subsequent items from being freed.

Referring to the diagram above, the **16, 20, and 8 byte items are retrieved in FIFO order**. However the items
are not returned in they were retrieved (20, 8, 16). As such, the space is not freed until the first item
(16 byte) is returned.

.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_read_ret_byte_buf.diag
    :caption: Retrieving/Returning data in byte buffers
    :align: center

Byte buffers **do not allow multiple retrievals before returning** (every retrieval must be followed by a return
before another retrieval is permitted). When using :cpp:func:`xRingbufferReceive` or 
:cpp:func:`xRingbufferReceiveFromISR`, all continuous stored data will be retrieved. :cpp:func:`xRingbufferReceiveUpTo`
or :cpp:func:`xRingbufferReceiveUpToFromISR` can be used to restrict the maximum number of bytes retrieved. Since
every retrieval must be followed by a return, the space will be freed as soon as the data is returned.

Referring to the diagram above, the 38 bytes of continuous stored data at the tail of the buffer is retrieved, 
returned, and freed. The next call to :cpp:func:`xRingbufferReceive` or :cpp:func:`xRingbufferReceiveFromISR` 
then wraps around and does the same to the 30 bytes of continuous stored data at the head of the buffer.

Ring Buffers with Queue Sets
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Ring buffers can be added to FreeRTOS queue sets using :cpp:func:`xRingbufferAddToQueueSetRead` such that every
time a ring buffer receives an item or data, the queue set is notified. Once added to a queue set, every
attempt to retrieve an item from a ring buffer should be preceded by a call to :cpp:func:`xQueueSelectFromSet`.
To check whether the selected queue set member is the ring buffer, call :cpp:func:`xRingbufferCanRead`.

The following example demonstrates queue set usage with ring buffers.

.. code-block:: c

    #include "freertos/queue.h"
    #include "freertos/ringbuf.h"

    ...

        //Create ring buffer and queue set
        RingbufHandle_t buf_handle = xRingbufferCreate(1028, RINGBUF_TYPE_NOSPLIT);
        QueueSetHandle_t queue_set = xQueueCreateSet(3);

        //Add ring buffer to queue set
        if (xRingbufferAddToQueueSetRead(buf_handle, queue_set) != pdTRUE) {
            printf("Failed to add to queue set\n");
        }

    ...

        //Block on queue set
        xQueueSetMemberHandle member = xQueueSelectFromSet(queue_set, pdMS_TO_TICKS(1000));

        //Check if member is ring buffer
        if (member != NULL && xRingbufferCanRead(buf_handle, member) == pdTRUE) {
            //Member is ring buffer, receive item from ring buffer
            size_t item_size;
            char *item = (char *)xRingbufferReceive(buf_handle, &item_size, 0);

            //Handle item
            ...

        } else {
            ...
        }


Ring Buffer API Reference
-------------------------

.. note::
    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.

.. include:: /_build/inc/ringbuf.inc


.. _hooks:

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 application. 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, :ref:`CONFIG_FREERTOS_LEGACY_HOOKS`, 
:ref:`CONFIG_FREERTOS_LEGACY_IDLE_HOOK`, and :ref:`CONFIG_FREERTOS_LEGACY_TICK_HOOK` 
should all be enabled in ``make menuconfig``.

Due to vanilla FreeRTOS being designed for single core, ``vApplicationIdleHook()``
and ``vApplicationTickHook()`` can only be defined once. However, the ESP32 is dual core
in nature, therefore same Idle Hook and Tick Hook are used for both cores (in other words,
the hooks are symmetrical for both cores).

ESP-IDF Idle and Tick Hooks
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Due to the the dual core nature of the ESP32, it may be necessary for some
applications to have separate hooks for each core. Furthermore, it may
be necessary for the Idle Tasks or Tick Interrupts to execute multiple hooks
that are configurable at run time. Therefore the ESP-IDF provides it's own hooks
API in addition to the legacy hooks provided by Vanilla FreeRTOS. 

The ESP-IDF tick/idle hooks are registered at run time, and each tick/idle hook 
must be registered to a specific CPU. When the idle task runs/tick Interrupt
occurs on a particular CPU, the CPU will run each of its registered idle/tick hooks
in turn.


Hooks API Reference
-------------------

.. include:: /_build/inc/esp_freertos_hooks.inc