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）。

关键注意事项

  1. 堆栈溢出：

    • 定期检查 uxTaskGetStackHighWaterMark()，确保剩余空间 > 安全阈值（如 10% 总堆栈）。
    • 在 FreeRTOSConfig.h 中启用 configCHECK_FOR_STACK_OVERFLOW 进行溢出检测。

  2. 动态内存风险：

    • 频繁分配/释放可能引发碎片，优先使用静态分配（xTaskCreateStatic()）。

  3. 任务优先级：

    • 优先级 0（最低）到 configMAX_PRIORITIES-1（最高），避免空闲任务（IDLE）被阻塞。

  4. 中断安全：

    • 在 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 可自定义堆地址。