Skip to content

Latest commit

 

History

History
481 lines (317 loc) · 24.8 KB

freertos_additions.rst

File metadata and controls

481 lines (317 loc) · 24.8 KB
Raw

FreeRTOS（附加功能）

:link_to_translation:en:[English]

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

目录

概述

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。

环形 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 中检索出来。因此，所有检索出的数据项也 必须 通过 :cppvRingbufferReturnItem 或 :cppvRingbufferReturnItemFromISR 返回到环形 buffer，以便将其从环形 buffer 中完全移除。

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

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

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

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

Note

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

Note

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

使用方法

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

#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");
    }

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

#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");
    }

以下示例演示了使用 :cppxRingbufferReceive 和 :cppvRingbufferReturnItem 从 不可分割环形 buffer 中检索和返回数据项：

...

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

以下示例演示了使用 :cppxRingbufferReceiveSplit 和 :cppvRingbufferReturnItem 从 可分割环形 buffer 中检索和返回数据项：

...

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

以下示例演示了使用 :cppxRingbufferReceiveUpTo 和 :cppvRingbufferReturnItem 从 字节 buffer 中检索和返回数据项：

...

    //从字节 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 安全版本，请调用 :cppxRingbufferSendFromISR、 :cppxRingbufferReceiveFromISR、 :cppxRingbufferReceiveSplitFromISR、 :cppxRingbufferReceiveUpToFromISR 和 :cppvRingbufferReturnItemFromISR。

Note

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

发送到环形 buffer

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

../../../_static/diagrams/ring-buffer/ring_buffer_send_non_byte_buf.diag

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

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

../../../_static/diagrams/ring-buffer/ring_buffer_send_byte_buf.diag

字节 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 字节的空间。

../../../_static/diagrams/ring-buffer/ring_buffer_send_acquire_complete.diag

然后填充 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 字节 的数据项。

../../../_static/diagrams/ring-buffer/ring_buffer_wrap_no_split.diag

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

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

../../../_static/diagrams/ring-buffer/ring_buffer_wrap_allow_split.diag

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

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

Note

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

../../../_static/diagrams/ring-buffer/ring_buffer_wrap_byte_buf.diag

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

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

检索/返回

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

../../../_static/diagrams/ring-buffer/ring_buffer_read_ret_non_byte_buf.diag

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

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

../../../_static/diagrams/ring-buffer/ring_buffer_read_ret_byte_buf.diag

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

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

使用队列集的环形 buffer

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

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

#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

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

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

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

Note

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

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

#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 钩子 和 idle 钩子

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

  • FreeRTOS tick 钩子可以通过 CONFIG_FREERTOS_USE_TICK_HOOK 选项启用。应用程序必须提供 void vApplicationTickHook( void ) 回调。
  • FreeRTOS idle 钩子可以通过 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 钩子：

    • 用 :cppesp_register_freertos_tick_hook 或 :cppesp_register_freertos_tick_hook_for_cpu 注册
    • 用 :cppesp_deregister_freertos_tick_hook 或 :cppesp_deregister_freertos_tick_hook_for_cpu 注销

  • 对于 idle 钩子：

    • 使用 :cppesp_register_freertos_idle_hook 或 :cppesp_register_freertos_idle_hook_for_cpu 注册
    • 使用 :cppesp_deregister_freertos_idle_hook 或 :cppesp_deregister_freertos_idle_hook_for_cpu 注销

Note

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

TLSP 删除回调

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

  • 在任务创建后，需调用 :cppvTaskSetThreadLocalStoragePointer 设置任务的 TLSP。
  • 在任务的生命周期中，需调用 :cpppvTaskGetThreadLocalStoragePointer 获取任务的 TLSP。
  • 在删除任务前，需释放 TLSP 指向的内存。

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

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

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

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

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

IDF 附加 API

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

组件专用功能

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

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

API 参考

环形 buffer API

inc/ringbuf.inc

钩子 API

inc/esp_freertos_hooks.inc

附加 API

inc/idf_additions.inc