FreeRTOS kernel objects 示例

📁 源码位置: samples/subsys/freertos/kernel_objects 查看源码

功能说明

该示例用于在实际板子上验证 FreeRTOS 常见内核对象和基础调度能力是否正常工作。示例不依赖外部外设，适合通过串口日志判断结果。

硬件连接

无需额外硬件连接，使用开发板板载烧录/日志接口查看 UART0 日志即可。

测试内容

  1. Task 创建、优先级调度和任务删除

  2. Queue FIFO 顺序和数据完整性

  3. Binary semaphore 跨任务同步

  4. Counting semaphore token 计数

  5. Mutex 对共享计数器的互斥保护

  6. Recursive mutex 嵌套加锁和解锁

  7. Event group bit 同步

  8. Software timer 回调执行

  9. Direct-to-task notification 通知投递

编译

重要提示：编译前需要先确认当前示例支持的目标板型，然后将板型标识传给 -DBOARD。请按以下方式选择：

  1. 确认示例限制：查看当前示例 README 中的硬件连接和注意事项，确认是否限定板型。

  2. 参考示例配置：查看相关示例目录下的 sample.yaml，确认支持的板型。

  3. 填写板型标识：SDK 内置板型的标识为 boards/ 下的目录名。例如实际使用的板型目录为 boards/<板型名称>/，则编译参数填写为 -DBOARD=<板型名称>。

在 SDK 根目录执行编译，并将命令中的 <示例路径> 和 <板型名称> 替换为实际值。

Linux 使用 build.sh：

# 通用命令
./build.sh -C -S samples/<示例路径> -DBOARD=<板型名称>

# 示例：使用 arcs_evb 开发板
./build.sh -C -S samples/<示例路径> -DBOARD=arcs_evb

Windows PowerShell 使用 build.ps1：

# 通用命令
.\build.ps1 -C -S samples/<示例路径> -DBOARD=<板型名称>

# 示例：使用 arcs_evb 开发板
.\build.ps1 -C -S samples/<示例路径> -DBOARD=arcs_evb

Note

确保已安装对应平台的工具链和 ListenAI 开发工具包。Windows 环境请先执行 .\env.ps1 或直接使用 .\build.ps1 自动加载环境。

注意事项：-DBOARD 填写的是板型标识，不是芯片系列名称。如果示例有板型专用配置或额外编译参数，以示例 README 中的说明为准。

也可以直接在 SDK 根目录执行，通过 BOARD 选择 ARCS 或 VenusA 开发板：

./build.sh -C -S samples/subsys/freertos/kernel_objects -DBOARD=arcs_evb
./build.sh -C -S samples/subsys/freertos/kernel_objects -DBOARD=venusa_rd_evb

烧录

编译完成后，使用 SDK tools/burn 目录下的 cskburn 工具烧录固件。请先根据目标板型和当前示例确定芯片系列、串口设备、烧录地址和固件路径。

Linux：

# 通用命令
./tools/burn/cskburn -C <芯片系列> -s <串口设备> -b 3000000 <烧录地址> <固件路径>

# 示例：使用 arcs_evb 开发板
./tools/burn/cskburn -s /dev/ttyUSB0 -b 3000000 0x0 build/arcs.bin -C arcs

Windows PowerShell：

# 通用命令
.\tools\burn\cskburn.exe -C <芯片系列> -s <串口号> -b 3000000 <烧录地址> <固件路径>

# 示例：使用 arcs_evb 开发板
.\tools\burn\cskburn.exe -C arcs -s COM7 -b 3000000 0x0 .\build\arcs.bin

Note

烧录参数说明：

  • -s /dev/ttyUSB0 / -s COM7：串口设备路径，需要根据实际情况修改 - Linux 系统：通常是 /dev/ttyUSB0 或 /dev/ttyACM0 - 可通过 ls /dev/tty* 命令查看可用串口设备 - Windows 系统：通常是 COM7、COM8 等，可在“设备管理器”的“端口”中查看 - 不同开发板或 USB 转串口芯片可能使用不同的设备名

  • -b 3000000：烧录波特率（3Mbps）

  • 0x0：烧录起始地址

  • build/arcs.bin / .\build\arcs.bin：编译生成的固件路径

  • -C arcs：芯片类型

注意事项：

  • 确保开发板已正确连接到电脑

  • 如果无法识别串口设备，请检查 USB 连接线是否正常，或尝试其他 USB 端口

预期输出

串口日志中应看到每个测试项的 PASS，以及最终 PASS 总结：

I/freertos_test [...] === FreeRTOS kernel objects test START ===
I/freertos_test [...] PASS: task create and priority order
I/freertos_test [...] PASS: queue FIFO
I/freertos_test [...] PASS: binary semaphore
I/freertos_test [...] PASS: counting semaphore
I/freertos_test [...] PASS: mutex
I/freertos_test [...] PASS: recursive mutex
I/freertos_test [...] PASS: event group
I/freertos_test [...] PASS: software timer
I/freertos_test [...] PASS: task notification
I/freertos_test [...] === FreeRTOS kernel objects test PASS ===

若任一测试失败，会打印 FAIL: 日志，并以 === FreeRTOS kernel objects test FAIL === 结束。

核心 API

API

说明

xTaskCreate() / vTaskDelete()

创建和删除任务

xQueueCreate() / xQueueSend() / xQueueReceive()

创建队列并收发数据

xSemaphoreCreateBinary()

创建二值信号量

xSemaphoreCreateCounting()

创建计数信号量

xSemaphoreCreateMutex() / xSemaphoreCreateRecursiveMutex()

创建普通互斥锁和递归互斥锁

xEventGroupCreate() / xEventGroupWaitBits()

创建事件组并等待事件位

xTimerCreate() / xTimerStart()

创建并启动软件定时器

xTaskNotifyGive()

向任务发送直接通知

CI 判定

sample.yaml 使用 UART runner，并通过以下最终日志判断成功：

=== FreeRTOS kernel objects test PASS ===

注意事项

  1. 原生 API：本示例使用 FreeRTOS 原生 API，目标是直接验证内核对象行为。

  2. 日志模式：本示例关闭异步日志，避免日志后台任务干扰任务调度顺序和故障定位。

  3. 任务退出：测试任务在 vTaskDelete(NULL) 后不会从任务入口函数返回，避免 RISC-V 软件中断延迟触发时跳转到 configTASK_RETURN_ADDRESS。

  4. 实板判定：涉及测试工程变更时，最终完成判定必须在实际板子上运行并抓取串口日志。