FreeRTOS 常用 API

1. 堆栈使用情况查询

`uxTaskGetStackHighWaterMark()`

功能：获取任务的最小剩余堆栈空间（高水位线），单位字节。
参数：任务句柄（NULL 表示当前任务）。
返回值：历史最小剩余堆栈值（接近 0 表示堆栈即将溢出）。
示例：

UBaseType_t highWaterMark = uxTaskGetStackHighWaterMark(NULL); 
if (highWaterMark < 100) {
    printf("警告：堆栈剩余不足 100 字节！\n");
}

2. 堆内存剩余查询

`xPortGetFreeHeapSize()`

功能：获取当前未分配的 Heap 剩余空间（字节）。
返回值：剩余堆内存大小（依赖 heap_x.c 实现）。
源码参考：

size_t xPortGetFreeHeapSize(void) {
    return xFreeBytesRemaining; // 实际变量名因 heap_x 方案不同可能变化
}

使用场景：动态内存分配前检查资源。
示例：

size_t freeHeap = xPortGetFreeHeapSize();
if (freeHeap < 2048) {
    printf("Heap 空间不足！剩余：%d 字节\n", freeHeap);
}

3. 任务管理核心 API

功能	API	说明
创建任务	`xTaskCreate()`	动态分配堆栈创建任务（需启用 `configSUPPORT_DYNAMIC_ALLOCATION=1`）。
创建静态任务	`xTaskCreateStatic()`	使用预分配内存创建任务（堆栈由用户提供）。
删除任务	`vTaskDelete()`	终止任务并释放资源（任务句柄设为 `NULL`）。
任务延时	`vTaskDelay(pdMS_TO_TICKS(ms))`	相对延时（单位：Tick）。
绝对周期延时	`vTaskDelayUntil(&lastWakeTime, period)`	精确控制任务周期（避免漂移）。
挂起任务	`vTaskSuspend(handle)`	暂停指定任务（`NULL` 表示当前任务）。
恢复任务	`vTaskResume(handle)`	唤醒被挂起的任务。
设置优先级	`vTaskPrioritySet(handle, newPriority)`	动态调整任务优先级（`0` 为最低）。
获取优先级	`uxTaskPriorityGet(handle)`	返回任务当前优先级。

4. 调度器控制 API

功能	API	说明
启动调度器	`vTaskStartScheduler()`	启动内核调度，从此任务开始执行（通常在主函数末尾调用）。
挂起调度器	`vTaskSuspendAll()`	暂停所有任务调度（用于临界区保护）。
恢复调度器	`xTaskResumeAll()`	恢复调度（返回暂停期间的调度请求次数）。

5. 任务状态查询

功能	API	说明
获取任务状态	`eTaskGetState(handle)`	返回任务状态（如 `eRunning`, `eReady`, `eBlocked`, `eSuspended`）。
获取当前任务句柄	`xTaskGetCurrentTaskHandle()`	返回正在运行的任务句柄。
获取任务总数	`uxTaskGetNumberOfTasks()`	返回当前系统任务总数（包括就绪/阻塞/挂起状态）。

6. 任务通知（高效IPC）

需启用 configUSE_TASK_NOTIFICATIONS=1

功能 API 说明

发送通知 xTaskNotifyGive(handle) 快速唤醒任务（类似二进制信号量）。

等待通知 ulTaskNotifyTake(pdTRUE, portMAX_DELAY) 阻塞等待通知（清零通知值）。

扩展通知 xTaskNotify(handle, value, action) 支持携带 32 位数据和多种覆盖模式（如 eSetValueWithOverwrite）。

功能	API	说明
发送通知	`xTaskNotifyGive(handle)`	快速唤醒任务（类似二进制信号量）。
等待通知	`ulTaskNotifyTake(pdTRUE, portMAX_DELAY)`	阻塞等待通知（清零通知值）。
扩展通知	`xTaskNotify(handle, value, action)`	支持携带 32 位数据和多种覆盖模式（如 `eSetValueWithOverwrite`）。

关键注意事项

堆栈溢出：
- 定期检查 uxTaskGetStackHighWaterMark()，确保剩余空间 > 安全阈值（如 10% 总堆栈）。
- 在 FreeRTOSConfig.h 中启用 configCHECK_FOR_STACK_OVERFLOW 进行溢出检测。
动态内存风险：
- 频繁分配/释放可能引发碎片，优先使用静态分配（xTaskCreateStatic()）。
任务优先级：
- 优先级 0（最低）到 configMAX_PRIORITIES-1（最高），避免空闲任务（IDLE）被阻塞。
中断安全：
- 在 ISR 中使用 FromISR 结尾的 API（如 xTaskResumeFromISR()）。

附：Heap 管理方案选择FreeRTOS 提供 5 种 heap_x.c 方案：

heap_1.c：简单（不支持释放）

heap_2.c：基本分配/释放（可能碎片化）

heap_3.c：线程安全版 malloc/free

heap_4.c：推荐（碎片合并）

heap_5.c：支持非连续内存区域
通过 FreeRTOSConfig.h 中的 configAPPLICATION_ALLOCATED_HEAP 可自定义堆地址。