FreeRTOS 嵌入式 RTOS…

在基于 FreeRTOS 的嵌入式项目中创建任务、进行任务间通信、配置内核安全选项并用 OpenOCD/GDB 调试时使用。

适用场景

解决思路

1. 任务创建与优先级：包含 `FreeRTOS.h` 和 `task.h`；任务函数签名为 `void vMyTask(void *pvParameters)`，任务体用 `for(;;)` 且永不返回；用 `vTaskDelay(pdMS_TO_TICKS(500))` 让出 CPU 500ms。
2. 调用 `xTaskCreate(function, name, stack_depth_words, param, priority, handle)` 创建任务；栈深度单位是 word，不是 byte。
3. 在 `main` 末尾调用 `vTaskStartScheduler()` 启动调度器；堆足够时它不返回，后面放 `for(;;);` 作为兜底。
4. 优先级准则：`tskIDLE_PRIORITY`(0) 是空闲任务，不要阻塞在该优先级；ISR 延迟处理任务用最高优先级以快速响应中断；不要超过 `configMAX_PRIORITIES - 1`。
5. 队列：包含 `queue.h`；定义传输结构体（如 `SensorReading_t`）；用 `xQueueCreate(10, sizeof(SensorReading_t))` 在启动调度器前创建队列。
6. 生产者任务用 `xQueueSend(xSensorQueue, &reading, pdMS_TO_TICKS(10))` 发送，队列满时最多阻塞 10ms。
7. 消费者任务用 `xQueueReceive(xSensorQueue, &reading, portMAX_DELAY) == pdTRUE` 接收，可永久阻塞直到有数据。
8. 在 ISR 中发送队列用 `xQueueSendFromISR()`，并传入 `&xHigherPriorityTaskWoken`。
9. 信号量与互斥量：包含 `semphr.h`；二值信号量用于 ISR→任务通知：`xSemaphoreCreateBinary()`；ISR 中用 `xSemaphoreGiveFromISR(xSem, &xWoken)` 后调用 `portYIELD_FROM_ISR(xWoken)`；任务用 `xSemaphoreTake(xSem, portMAX_DELAY)` 等待。
10. 互斥量用于共享资源互斥访问，不能在 ISR 中使用：`xSemaphoreCreateMutex()`；`xSemaphoreTake(xMutex, pdMS_TO_TICKS(100)) == pdTRUE` 后访问共享资源，再 `xSemaphoreGive(xMutex)`。
11. 递归互斥量允许同一任务多次获取：`xSemaphoreCreateRecursiveMutex()`；用 `xSemaphoreTakeRecursive(...)` 和 `xSemaphoreGiveRecursive(...)`。
12. 对共享资源优先用互斥量而不是二值信号量，以获得优先级继承。
13. 栈溢出检测：在 `FreeRTOSConfig.h` 中设置 `configCHECK_FOR_STACK_OVERFLOW 2`（模式+水位）和 `configUSE_MALLOC_FAILED_HOOK 1`。
14. 实现 `vApplicationStackOverflowHook(TaskHandle_t xTask, char *pcTaskName)`：记录出问题的任务名然后停机，可调用 `configASSERT(0)`。
15. 实现 `vApplicationMallocFailedHook(void)`：调用 `configASSERT(0)`。
16. 运行时检查栈余量：`uxTaskGetStackHighWaterMark(xHandle)` 返回历史最小空闲栈 word 数；经验上保持余量 > 20 words。
17. 配置 `FreeRTOSConfig.h` 基础项：`configCPU_CLOCK_HZ`=`SystemCoreClock`；`configTICK_RATE_HZ`=1000；`configMAX_PRIORITIES`=8；`configMINIMAL_STACK_SIZE`=128（words）；`configTOTAL_HEAP_SIZE`=(16 * 1024)（bytes）；`configMAX_TASK_NAME_LEN`=16。
18. 配置调试/安全项：`configUSE_TRACE_FACILITY`=1；`configUSE_STATS_FORMATTING_FUNCTIONS`=1；`configCHECK_FOR_STACK_OVERFLOW`=2；`configUSE_MALLOC_FAILED_HOOK`=1；`configASSERT(x) if((x)==0) { taskDISABLE_INTERRUPTS(); for(;;); }`。
19. 配置功能项：`configUSE_MUTEXES`=1；`configUSE_RECURSIVE_MUTEXES`=1；`configUSE_COUNTING_SEMAPHORES`=1；`configUSE_TIMERS`=1；`configTIMER_TASK_STACK_DEPTH`=(configMINIMAL_STACK_SIZE * 2)。
20. 用 OpenOCD/GDB 调试：让 GDB 连接 OpenOCD 并启用 FreeRTOS 线程感知；OpenOCD 提供 FreeRTOS-aware RTOS 插件。
21. 在 `openocd.cfg` 中加入 `source [find rtos/FreeRTOS.cfg]`，多数目标可自动加载 FreeRTOS 感知。
22. GDB 会话命令：`info threads` 列出所有 FreeRTOS 任务；`thread 3` 切到任务 3；`bt` 查看该任务栈回溯；`frame 2` 查看指定栈帧。
23. 若启用 trace facility，可在 GDB 中用 `call vTaskList(buf)` 和 `printf("%s\n", buf)` 打印任务列表。
24. FreeRTOS v11（2024+）API：任务通知 v2 使用 `xTaskNotifyIndexed(xHandle, 0, ulValue, eSetValueWithOverwrite)` 和 `xTaskNotifyWaitIndexed(0, 0, ULONG_MAX, &ulNotified, portMAX_DELAY)`。
25. FreeRTOS v11 流缓冲区：`xStreamBufferSend(xStream, data, len, 0)`；`xStreamBufferSetTriggerLevel(xStream, 1)` 在收到 1 字节时唤醒接收者。
26. 编译时检查 `FreeRTOS.h` 的 `tskKERNEL_VERSION_NUMBER` 判断 API 是否可用。
27. ARM TrustZone（Cortex-M33/M55）安全/非安全世界拆分：包含 `secure_context.h`；调用 `SecureContext_Init()` 初始化安全上下文管理（安全侧或 NSC veneer）。
28. 为调用安全函数的任务分配安全上下文：`xTaskCreateSecure(vSecureTask, "SecTask", STACK, NULL, priority, &xHandle)`；MPU 定义 NSC 区域给 SG veneer。
29. TrustZone 集成前提/做法：需要 TrustZone-enabled MCU、安全固件分区、NSC linker section 放置。
30. FreeRTOS+TCP：包含 `FreeRTOS_IP.h` 和 `FreeRTOS_Sockets.h`；网络栈初始化 `FreeRTOS_IPInit` 后，用 `FreeRTOS_socket(FREERTOS_AF_INET, FREERTOS_SOCK_STREAM, FREERTOS_IPPROTO_TCP)` 创建 socket；用 `FreeRTOS_connect(xSocket, &xAddress, sizeof(xAddress))` 连接；用 `FreeRTOS_send(xSocket, buffer, len, 0)` 发送。
31. 在 `FreeRTOSIPConfig.h` 配置缓冲区数量和 TCP/IP 选项，例如 `ipconfigUSE_TCP`、`ipconfigNUM_NETWORK_BUFFER_DESCRIPTORS`；需要以太网 MAC 驱动和 FreeRTOS+TCP 缓冲区管理。
32. MPU 区域配置：对 Cortex-M with MPU，用 `TaskParameters_t` 定义受限任务，例如 `.pvTaskCode=vRestrictedTask`、`.pcName="Restricted"`、`.usStackDepth=configMINIMAL_STACK_SIZE`、`.pvParameters=NULL`、`.uxPriority=tskIDLE_PRIORITY + 1`、`.puxStackBuffer=stackBuffer`，并在 `.xRegions` 中设置如 `0x20000000/0x10000` 为 `tskMPU_REGION_READ_ONLY | tskMPU_REGION_EXECUTE_NEVER`，最后一个区域用 `0x00000000, 0, 0` 作为终止项；然后调用 `xTaskCreateRestricted(&xRestrictedTaskParams, &xHandle)`。
33. MPU 区域划分：为只读代码/数据、特权外设、任务私有栈分别定义独立 RAM 区域。
34. 参考与相关技能：OpenOCD 设置见 `skills/embedded/openocd-jtag`；`FreeRTOSConfig.h` 参考见 `references/freertos-config.md`；其他相关技能包括 `skills/embedded/openocd-jtag`、`skills/embedded/linker-scripts`、`skills/debuggers/gdb`、`skills/embedded/zephyr`。

适用边界 · 注意事项

• 不适用于裸机程序或未移植 FreeRTOS 的 MCU/平台。
• 不适用于使用其他 RTOS（如 Zephyr）的项目；那些项目应使用对应 RTOS 技能。
• 不适用于缺少 TrustZone/MPU/以太网 MAC 等硬件支持却要使用对应高级特性的场景。