esp-idf/docs/zh_CN/api-reference/system/freertos_additions.rst

FreeRTOS（附加功能）
================================

:link_to_translation:`en:[English]`

ESP-IDF 为 FreeRTOS 提供了多种附加功能。这些附加功能适用于 ESP-IDF 支持的所有 FreeRTOS 实现，即 ESP-IDF FreeRTOS 和 Amazon SMP FreeRTOS。本文档介绍了这些附加功能，内容包括以下几个部分：

.. contents:: 目录
    :depth: 2

.. ---------------------------------------------------- Overview -------------------------------------------------------

概述
--------

ESP-IDF 为 FreeRTOS 提供了以下附加功能：

- **环形 buffer**：FIFO 缓冲区，支持任意长度的数据项。
- **ESP-IDF tick 钩子和 idle 钩子**：ESP-IDF 提供了多个自定义的 tick 钩子和 idle 钩子，相较于 FreeRTOS，支持的钩子数量更多且更灵活。
- **线程本地存储指针 (TLSP) 删除回调**：当一个任务被删除时，TLSP 删除回调会自动运行，从而自动清理 TLSP。
- **IDF 附加 API**：专用于 ESP-IDF 的附加函数，用于增强 FreeRTOS 的功能。
- **组件专用功能**：目前只添加了一个专用于组件的功能，即 ``ORIG_INCLUDE_PATH``。

.. -------------------------------------------------- Ring buffers -----------------------------------------------------

环形 buffer
------------

FreeRTOS 提供了流 buffer 和消息 buffer，作为在任务和 ISR 之间发送任意大小数据的主要机制。然而，FreeRTOS 流 buffer 和消息 buffer 具有以下限制：

- 仅支持单一的发送者和单一的接收者
- 数据通过复制的方式进行传递
- 无法为延迟发送（即发送获取）预留 buffer 空间

为此，ESP-IDF 提供了一个单独的环形 buffer 来解决上述问题。

ESP-IDF 环形 buffer 是一个典型的 FIFO buffer，支持任意大小的数据项。在数据项大小可变的情况下，环形 buffer 比 FreeRTOS 队列更节约内存，可以替代 FreeRTOS 队列使用。环形 buffer 的容量不是由可以存储的数据项数量衡量的，而是由用于存储数据项的内存量来衡量的。

环形 buffer 提供了 API 来发送数据项，或为环形 buffer 中的数据项分配空间，以便进行手动填充。为提高效率， **数据项都通过引用的方式从环形 buffer 中检索出来**。因此，所有检索出的数据项也 **必须** 通过 :cpp:func:`vRingbufferReturnItem` 或 :cpp:func:`vRingbufferReturnItemFromISR` 返回到环形 buffer，以便将其从环形 buffer 中完全移除。

环形 buffer 分为以下三种类型：

**不可分割 buffer**：确保将一个数据项存储在连续的内存中，并且在任何情况下都不会尝试分割数据项。当数据项必须占用连续的内存时，请使用不可分割 buffer。 **仅不可分割 buffer 允许为延迟发送保留缓冲空间。** 更多信息请参考函数 :cpp:func:`xRingbufferSendAcquire` 和 :cpp:func:`xRingbufferSendComplete` 的文档。

**可分割 buffer**：当数据项在 buffer 末尾绕回时，如果 buffer 头部和尾部的总空间足够，则支持将一个数据项分成两部分进行存储。可分割 buffer 比不可分割 buffer 更节省内存，但在检索时可能会返回数据项的两个部分。

**字节 buffer**：不将数据存储为单独的数据项。所有数据都存储为字节序列，每次可以发送或检索任意大小的字节。当不需要单独维护数据项时，推荐使用字节 buffer，例如字节流。

.. note::

    不可分割 buffer 和可分割 buffer 在 32 位对齐地址上存储数据项。因此，在检索一个数据项时，数据项指针一定也是 32 位对齐的。这在向 DMA 发送数据时非常有用。

.. note::

    存储在不可分割或可分割 buffer 中的每个数据项 **需要额外的 8 字节用于标头**。数据项大小会向上取整为 32 位对齐大小，即 4 字节的倍数，实际的数据项大小则记录在标头中。不可分割和可分割 buffer 的大小在创建时也会向上取整。

使用方法
^^^^^^^^^^

以下示例演示了如何使用 :cpp:func:`xRingbufferCreate` 和 :cpp:func:`xRingbufferSend` 来创建环形 buffer，并向其发送数据项：

.. code-block:: c

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

    ...

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

        //发送一个数据项
        UBaseType_t res =  xRingbufferSend(buf_handle, tx_item, sizeof(tx_item), pdMS_TO_TICKS(1000));
        if (res != pdTRUE) {
            printf("Failed to send item\n");
        }

以下示例演示了如何使用 :cpp:func:`xRingbufferSendAcquire` 和 :cpp:func:`xRingbufferSendComplete` 代替 :cpp:func:`xRingbufferSend` 来获取环形 buffer（:cpp:enumerator:`RINGBUF_TYPE_NOSPLIT` 类型）上的内存，然后向其发送一个数据项。虽然增加了一个步骤，但可以实现获取要写入内存的地址，并自行写入内存。

.. code-block:: c

    #include "freertos/ringbuf.h"
    #include "soc/lldesc.h"

    typedef struct {
        lldesc_t dma_desc;
        uint8_t buf[1];
    } dma_item_t;

    #define DMA_ITEM_SIZE(N) (sizeof(lldesc_t)+(((N)+3)&(~3)))

    ...

        //为 DMA 描述符和相应的数据 buffer 检索空间
        //此步骤必须通过 SendAcquire 完成，否则，复制时地址可能会不同
        dma_item_t item;
        UBaseType_t res =  xRingbufferSendAcquire(buf_handle,
                            &item, DMA_ITEM_SIZE(buffer_size), pdMS_TO_TICKS(1000));
        if (res != pdTRUE) {
            printf("Failed to acquire memory for item\n");
        }
        item->dma_desc = (lldesc_t) {
            .size = buffer_size,
            .length = buffer_size,
            .eof = 0,
            .owner = 1,
            .buf = &item->buf,
        };
        //实际发送到环形 buffer 以供使用
        res = xRingbufferSendComplete(buf_handle, &item);
        if (res != pdTRUE) {
            printf("Failed to send item\n");
        }

以下示例演示了使用 :cpp:func:`xRingbufferReceive` 和 :cpp:func:`vRingbufferReturnItem` 从 **不可分割环形 buffer** 中检索和返回数据项：

.. code-block:: c

    ...

        //从不可分割环形 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");
            //返回数据项
            vRingbufferReturnItem(buf_handle, (void *)item);
        } else {
            //数据项检索失败
            printf("Failed to receive item\n");
        }


以下示例演示了使用 :cpp:func:`xRingbufferReceiveSplit` 和 :cpp:func:`vRingbufferReturnItem` 从 **可分割环形 buffer** 中检索和返回数据项：

.. code-block:: c

    ...

        //从可分割环形 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));

        //检查收到的数据项
        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 {
            //接收数据项失败
            printf("Failed to receive item\n");
        }


以下示例演示了使用 :cpp:func:`xRingbufferReceiveUpTo` 和 :cpp:func:`vRingbufferReturnItem` 从 **字节 buffer** 中检索和返回数据项：

.. code-block:: c

    ...

        //从字节 buffer 中接收数据
        size_t item_size;
        char *item = (char *)xRingbufferReceiveUpTo(buf_handle, &item_size, pdMS_TO_TICKS(1000), sizeof(tx_item));

        //检查接收到的数据
        if (item != NULL) {
            //Print item
            for (int i = 0; i < item_size; i++) {
                printf("%c", item[i]);
            }
            printf("\n");
            //返回数据项
            vRingbufferReturnItem(buf_handle, (void *)item);
        } else {
            //接收数据项失败
            printf("Failed to receive item\n");
        }


对于以上函数的 ISR 安全版本，请调用 :cpp:func:`xRingbufferSendFromISR`、 :cpp:func:`xRingbufferReceiveFromISR`、 :cpp:func:`xRingbufferReceiveSplitFromISR`、 :cpp:func:`xRingbufferReceiveUpToFromISR` 和 :cpp:func:`vRingbufferReturnItemFromISR`。

.. note::

    当字节在环形 buffer 的末端绕回时，需调用 ``RingbufferReceive[UpTo][FromISR]()`` 两次。

发送到环形 buffer
^^^^^^^^^^^^^^^^^^^^^^

以下图表将不可分割和可分割 buffer 与字节 buffer 进行对比，说明了三者在发送数据或数据项方面的差异。图表中，假设分别向 **128 字节的 buffer** 发送大小为 **18、3 和 27 字节** 的三个数据项：

.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_send_non_byte_buf.diag
    :caption: 向不可分割或可分割的环形 buffer 发送数据项
    :align: center

对于不可分割和可分割 buffer，每个数据项前都有 8 字节标头信息。此外，为了保持整体的 32 位对齐，每个数据项占用的空间都会 **向上取整到最接近的 32 位对齐大小**。数据项的实际大小会记录在标头中，并在检索数据项时返回。

参考上图，18、3 和 27 字节的数据项分别 **向上取整为 20、4 和 28 字节**，然后在每个数据项前面添加一个 8 字节的标头。

.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_send_byte_buf.diag
    :caption: 向字节 buffer 发送数据项
    :align: center

字节 buffer 将数据视为一个字节序列，不会产引入任何额外开销，不添加标头信息。因此，发送到字节 buffer 的所有数据都会合并成一个数据项。

参考上图，18、3 和 27 字节的数据项被顺序写入字节 buffer，并 **合并成一个 48 字节的数据项**。

使用 SendAcquire 和 SendComplete
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

不可分割 buffer 中的数据项严格按照 FIFO 顺序通过 ``SendAcquire`` 获取，并且必须通过 ``SendComplete`` 发送到 buffer 以便访问。也可以发送或获取多个数据项，且无需严格遵照获取顺序，但接收数据项却必须遵循 FIFO。所以，如果不为最早获取的数据项调用 ``SendComplete``，就无法接收后续数据项。

以下图表说明了当 ``SendAcquire`` 和 ``SendComplete`` 顺序不同时的情形。一开始，已经有一个 16 字节的数据项发送到环形 buffer。然后调用 ``SendAcquire`` 在环形 buffer 上获取 20、8、24 字节的空间。

.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_send_acquire_complete.diag
    :caption: 在不可分割环形 buffer 中 SendAcquire/SendComplete 数据项
    :align: center

然后填充 buffer，按照 8、24、20 字节的顺序通过 ``SendComplete`` 将数据项发送到环形 buffer。当 8 字节和 24 字节的数据发送后，仍只能获取 16 字节的数据项。因此，如果不为 20 字节数据项调用 ``SendComplete``，就无法获取该数据项，也无法获取 20 字节后的数据项。

当 20 字节数据项最终发送完成后，就可以在 buffer 中最初的 16 字节数据项之后，按照 20、8、24 字节的顺序接收所有的三个数据项。

由于 ``SendAcquire`` 及 ``SendComplete`` 要求所获取的 buffer 必须是完整的（未包装的），故可分割 buffer 和字节 buffer 不支持上述调用操作。


绕回
^^^^^^^^^^^

以下图表说明了发送数据项需要绕回时，不可分割、可分割和字节 buffer 之间的差异。图表假设有一个 **128 字节的 buffer**，其中有 **56 字节的空闲空间可以绕回使用**，并发送了一个 **28 字节** 的数据项。

.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_wrap_no_split.diag
    :caption: 在不可分割 buffer 中绕回
    :align: center

不可分割 buffer **只在连续的空闲空间中存储数据项，在任何情况下都不分割数据项**。当 buffer 尾部的空闲空间不足以完全存储数据项及其标头时，尾部的空闲空间将被 **标记为虚拟数据**。然后，数据项将绕回并存储在 buffer 头部的空闲空间中。

参考上图， buffer 尾部的 16 字节空闲空间不足以存储 28 字节的数据项，因此，这 16 字节被标记为虚拟数据，然后将数据项写入了 buffer 头部的空闲空间中。

.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_wrap_allow_split.diag
    :caption: 在可分割 buffer 中绕回
    :align: center

当 buffer 尾部的空闲空间不足以存储数据项及其标头时，可分割 buffer 会尝试 **将数据项分割成两部分**。分割的的两部分数据项都将有自己的标头，因此会产生额外的 8 字节开销。

参考上图， buffer 尾部的 16 字节空闲空间不足以存储 28 字节的数据项。因此将数据项分割成两部分（8 字节和 20 字节），并将两部分写入 buffer。

.. note::

    可分割 buffer 将其分割好的两部分数据视为两个独立的数据项，因此不应调用 :cpp:func:`xRingbufferReceive`。需调用 :cpp:func:`xRingbufferReceiveSplit` 以线程安全的方式接收分割的两部分数据项。

.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_wrap_byte_buf.diag
    :caption: 在字节 buffer 中绕回
    :align: center

字节 buffer **将尽可能多的数据存储到 buffer 尾部的空闲空间** 中。剩余的数据会存储在 buffer 头部的空闲空间。在字节 buffer 中绕回不会产生任何额外开销。

参考上图，buffer 尾部的 16 字节空闲空间不足以完全存储 28 字节的数据，因此，将数据填入这 16 字节空闲空间后，剩余的 12 字节会被写入 buffer 头部的空闲空间。此时，buffer 包含两个独立的连续数据，并且每个连续数据都被字节 buffer 视为一个独立数据项。

检索/返回
^^^^^^^^^^^^^^^^^^^^

以下图表说明了在检索和返回数据时，不可分割、可分割 buffer 和字节 buffer 之间的差异：

.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_read_ret_non_byte_buf.diag
    :caption: 在不可分割和可分割环形 buffer 中检索/返回数据项
    :align: center

不可分割 buffer 和可分割 buffer 中的数据项 **按严格的 FIFO 顺序检索** 并 **必须返回**，以释放占用的空间。在返回之前可以检索多个数据项，且不必按照检索的顺序返回数据项。但是，释放空间必须按 FIFO 顺序进行，因此如果不返回最早检索的数据项，就无法释放后续数据项占用的空间。

参考上图， **16、20 和 8 字节的数据项按 FIFO 顺序被检索出来**。但是，这些数据项并不是按照被检索的顺序返回的。最先返回的是 20 字节的数据项，然后分别返回 8 字节和 16 字节的数据项。直到第一个数据项（即 16 字节的数据项）返回后，空间才会被释放。

.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_read_ret_byte_buf.diag
    :caption: 在字节 buffer 中检索/返回数据
    :align: center

字节 buffer **不允许在返回之前进行多次检索** （每次检索必须在下一次检索之前返回结果）。使用 :cpp:func:`xRingbufferReceive` 或 :cpp:func:`xRingbufferReceiveFromISR` 时，会检索所有连续存储的数据。使用 :cpp:func:`xRingbufferReceiveUpTo` 或 :cpp:func:`xRingbufferReceiveUpToFromISR` 可限制检索的最大字节数。由于每次检索后都必须返回，因此数据一返回就会释放空间。

参考上图， buffer 尾部 38 字节连续存储的数据被检索、返回和释放。然后，下一次调用 :cpp:func:`xRingbufferReceive` 或 :cpp:func:`xRingbufferReceiveFromISR` 时，buffer 将绕回并对头部的 30 字节连续存储数据进行同样的处理。

使用队列集的环形 buffer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

使用 :cpp:func:`xRingbufferAddToQueueSetRead` 可以将环形 buffer 添加到 FreeRTOS 队列集中，这样每次环形 buffer 接收一个数据项或数据时，队列集都会收到通知。添加到队列集后，每次从环形 buffer 检索数据项时都应该先调用 :cpp:func:`xQueueSelectFromSet`。要检查选定的队列集成员是否为环形 buffer，调用 :cpp:func:`xRingbufferCanRead`。

以下示例演示了如何使用包含环形 buffer 的队列集：

.. code-block:: c

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

    ...

        //创建环形 buffer 和队列集
        RingbufHandle_t buf_handle = xRingbufferCreate(1028, RINGBUF_TYPE_NOSPLIT);
        QueueSetHandle_t queue_set = xQueueCreateSet(3);

        //向队列集中添加环形 buffer
        if (xRingbufferAddToQueueSetRead(buf_handle, queue_set) != pdTRUE) {
            printf("Failed to add to queue set\n");
        }

    ...

        //阻塞队列集
        QueueSetMemberHandle_t member = xQueueSelectFromSet(queue_set, pdMS_TO_TICKS(1000));

        //检查成员是否为环形 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);

            //处理数据项
            ...

        } else {
            ...
        }

使用静态分配的环形 buffer
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

:cpp:func:`xRingbufferCreateStatic` 可用于创建具有特定内存需求的环形 buffer（如在外部 RAM 中分配的环形 buffer）。环形 buffer 使用的所有内存块都必须在创建之前手动分配，然后传递给 :cpp:func:`xRingbufferCreateStatic` 以初始化为环形 buffer。这些内存块中包括：

- 环形 buffer 的数据结构类型 :cpp:type:`StaticRingbuffer_t`。
- 环形 buffer 的存储区域，大小为 ``xBufferSize``。注意，对于不可分割和可分割 buffer，``xBufferSize`` 必须为 32 位对齐大小。

这些块的分配方式取决于具体的需求。例如，静态声明所有块，或动态分配为具有特定功能的块，如外部 RAM。

.. note::

    当删除通过 :cpp:func:`xRingbufferCreateStatic` 创建的环形 buffer 时，:cpp:func:`vRingbufferDelete` 函数不会释放任何内存块。释放内存必须在调用 :cpp:func:`vRingbufferDelete` 后手动完成。

下面的代码片段演示了一个完全在外部 RAM 中分配的环形 buffer：

.. code-block:: c

    #include "freertos/ringbuf.h"
    #include "freertos/semphr.h"
    #include "esp_heap_caps.h"

    #define BUFFER_SIZE     400      //32 位对齐大小
    #define BUFFER_TYPE     RINGBUF_TYPE_NOSPLIT
    ...

    //将 环形 buffer 数据结构体和存储区分配到外部 RAM 中
    StaticRingbuffer_t *buffer_struct = (StaticRingbuffer_t *)heap_caps_malloc(sizeof(StaticRingbuffer_t), MALLOC_CAP_SPIRAM);
    uint8_t *buffer_storage = (uint8_t *)heap_caps_malloc(sizeof(uint8_t)*BUFFER_SIZE, MALLOC_CAP_SPIRAM);

    //使用手动分配的内存创建环形 buffer
    RingbufHandle_t handle = xRingbufferCreateStatic(BUFFER_SIZE, BUFFER_TYPE, buffer_storage, buffer_struct);

    ...

    //使用后删除环形 buffer
    vRingbufferDelete(handle);

    //手动释放所有内存块
    free(buffer_struct);
    free(buffer_storage);


.. ------------------------------------------- ESP-IDF Tick and Idle Hooks ---------------------------------------------

ESP-IDF tick 钩子 和 idle 钩子
----------------------------------

FreeRTOS 允许应用程序在编译时提供一个 tick 钩子和一个 idle 钩子：

- FreeRTOS tick 钩子可以通过 :ref:`CONFIG_FREERTOS_USE_TICK_HOOK` 选项启用。应用程序必须提供 ``void vApplicationTickHook( void )`` 回调。
- FreeRTOS idle 钩子可以通过 :ref:`CONFIG_FREERTOS_USE_IDLE_HOOK` 选项启用。应用程序必须提供 ``void vApplicationIdleHook( void )`` 回调。

然而，FreeRTOS tick 钩子和 idle 钩子有以下不足：

- FreeRTOS 钩子是在编译时注册的
- 每种钩子只能注册一个
- 在多核目标芯片上，FreeRTOS 钩子是对称的，即每个内核的 tick 中断和 idle 任务最终都会调用同一个钩子

因此，ESP-IDF 提供了 tick 钩子和 idle 钩子来补充 FreeRTOS tick 和 idle 钩子的功能。ESP-IDF 钩子具有以下功能：

- 钩子可以在运行时注册和注销
- 可以注册多个钩子。每个内核中，同一类型的钩子最多可以注册 8 个
- 在多核目标芯片上，钩子可以是不对称的，即可以为每个内核注册不同的钩子

使用以下 API 注册和注销 ESP-IDF 钩子：

- 对于 tick 钩子：

    - 用 :cpp:func:`esp_register_freertos_tick_hook` 或 :cpp:func:`esp_register_freertos_tick_hook_for_cpu` 注册
    - 用 :cpp:func:`esp_deregister_freertos_tick_hook` 或 :cpp:func:`esp_deregister_freertos_tick_hook_for_cpu` 注销

- 对于 idle 钩子：

    - 使用 :cpp:func:`esp_register_freertos_idle_hook` 或 :cpp:func:`esp_register_freertos_idle_hook_for_cpu` 注册
    - 使用 :cpp:func:`esp_deregister_freertos_idle_hook` 或 :cpp:func:`esp_deregister_freertos_idle_hook_for_cpu` 注销

.. note::

    在 cache 被禁用时，tick 中断仍保持活动，因此任何 tick 钩子（FreeRTOS 或 ESP-IDF）函数都必须放在内部 RAM 中。请参考 :ref:`SPI flash API documentation <iram-safe-interrupt-handlers>` 了解详情。

.. -------------------------------------------------- TLSP Callback ----------------------------------------------------

TLSP 删除回调
-----------------------

原生 FreeRTOS 提供了线程本地存储指针 (TLSP) 功能，这些指针直接存储在特定任务的任务控制块 (TCB) 中。TLSP 允许每个任务拥有自己的数据结构指针集合。在原生 FreeRTOS 中：

- 在任务创建后，需调用 :cpp:func:`vTaskSetThreadLocalStoragePointer` 设置任务的 TLSP。
- 在任务的生命周期中，需调用 :cpp:func:`pvTaskGetThreadLocalStoragePointer` 获取任务的 TLSP。
- 在删除任务前，需释放 TLSP 指向的内存。

然而，为了能够欧自动释放 TLSP 内存，ESP-IDF 额外提供了 TLSP 删除回调功能。当删除任务时，这些删除回调函数会被自动调用，从而清除 TLSP 内存，无需在每个任务的代码中显式添加内存清除逻辑。

设置 TLSP 删除回调的方式与设置 TLSP 类似。

- :cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback` 设置了特定的 TLSP 及其关联的回调。
- 调用原生 FreeRTOS 函数 :cpp:func:`vTaskSetThreadLocalStoragePointer` 只会将 TLSP 的关联删除回调设置为 `NULL`，也就是说，在任务删除期间不会调用该 TLSP 的回调。

在实现 TLSP 回调时，应注意以下几点：

- 回调 **绝对不能尝试阻塞或让出**，并且应尽可能缩短临界区的时间。
- 回调是在删除任务的内存即将被释放前调用的。因此，回调可以通过 :cpp:func:`vTaskDelete` 本身调用，也可以从空闲任务中调用。

.. --------------------------------------------- ESP-IDF Additional API ------------------------------------------------

.. _freertos-idf-additional-api:

IDF 附加 API
------------------

:component_file:`freertos/esp_additions/include/freertos/idf_additions.h` 头文件包含了 ESP-IDF 添加的与 FreeRTOS 相关的辅助函数。通过 ``#include "freertos/idf_additions.h"`` 可添加此头文件。

.. ------------------------------------------ Component Specific Properties --------------------------------------------

组件专用功能
-----------------------------

除了基本 CMake 构建属性中提供的标准组件变量外，FreeRTOS 组件还提供了参数（目前只有一个参数）以简化与其他模块的集成：

- `ORIG_INCLUDE_PATH` - 包含指向 freeRTOS 根包含文件夹的绝对路径。因此可以直接用 `#include "FreeRTOS.h"` 引用头文件，而无需使用 `#include "freertos/FreeRTOS.h"`。


.. -------------------------------------------------- API Reference ----------------------------------------------------

API 参考
-------------

环形 buffer API
^^^^^^^^^^^^^^^

.. include-build-file:: inc/ringbuf.inc

钩子 API
^^^^^^^^^

.. include-build-file:: inc/esp_freertos_hooks.inc

附加 API
^^^^^^^^^^^^^^

.. include-build-file:: inc/idf_additions.inc