Obsidian-Knowledge-Base/wiki/freertos-task-api.md

---

type: concept title: FreeRTOS 任务 API 详解 tags: [freertos, rtos, task, api, concept]

created: 2026-07-12

FreeRTOS 任务 API 详解

任务创建与删除

API 函数	描述
xTaskCreate()	动态方式创建任务
xTaskCreateStatic()	静态方式创建任务
vTaskDelete()	删除任务

动态创建 xTaskCreate()

BaseType_t xTaskCreate(
    TaskFunction_t pxTaskCode,       // 任务函数指针
    const char * const pcName,       // 任务名
    const configSTACK_DEPTH_TYPE usStackDepth, // 堆栈大小（单位 4 字节）
    void * const pvParameters,       // 参数
    UBaseType_t uxPriority,          // 优先级 0 ~ configMAX_PRIORITIES-1
    TaskHandle_t * const pxCreatedTask // 任务句柄（TCB）
);

创建步骤：配置 configSUPPORT_DYNAMIC_ALLOCATION=1 → 定义入口参数 → 编写任务函数。

内部实现：申请堆栈和 TCB 内存 → TCB 成员赋值 → 添加新任务到就绪列表。

任务控制块（TCB） 关键成员：

• pxTopOfStack：任务栈栈顶（必须为 TCB 第一成员）
• xStateListItem / xEventListItem：状态/事件列表项
• uxPriority：任务优先级
• pxStack：任务栈起始地址
• pcTaskName：任务名字

静态创建 xTaskCreateStatic()

TaskHandle_t xTaskCreateStatic(
    TaskFunction_t pxTaskCode,
    const char * const pcName,
    const uint32_t ulStackDepth,
    void * const pvParameters,
    UBaseType_t uxPriority,
    StackType_t * const puxStackBuffer,   // 用户分配堆栈
    StaticTask_t * const pxTaskBuffer      // 用户分配 TCB
);

需额外配置 configSUPPORT_STATIC_ALLOCATION=1，并实现空闲任务 & 定时器任务的内存接口函数：

• vApplicationGetIdleTaskMemory()
• vApplicationGetTimerTaskMemory()

任务删除 vTaskDelete()

void vTaskDelete(TaskHandle_t xTaskToDelete);  // NULL 表示删除自身

空闲任务负责释放被删除任务中由系统分配的内存。用户申请的内存需在删除前提前释放。

任务挂起与恢复

API 函数	描述
vTaskSuspend()	挂起任务（可恢复）
vTaskResume()	恢复被挂起的任务
xTaskResumeFromISR()	在中断中恢复挂起的任务
vTaskSuspendAll()	挂起调度器（不关闭中断）
xTaskResumeAll()	恢复调度器

任务状态查询

API 函数	描述
uxTaskPriorityGet()	获取任务优先级
vTaskPrioritySet()	设置任务优先级
uxTaskGetNumberOfTasks()	获取系统中任务的数量
uxTaskGetSystemState()	获取所有任务状态
vTaskGetInfo()	获取指定任务信息
xTaskGetCurrentTaskHandle()	获取当前任务句柄
xTaskGetHandle()	根据任务名获取任务句柄
uxTaskGetStackHighWaterMark()	获取栈历史剩余最小值
eTaskGetState()	获取任务状态
vTaskList()	表格形式获取所有任务信息
vTaskGetRunTimeStats()	获取任务运行时间

相关页面

• [[source-freertos|尚硅谷 FreeRTOS 教程 - 资料页]]
• [[freertos-task-scheduling|任务调度与状态管理]]
• [[freertos-interrupt-time|中断管理与时间管理]]