---
type: concept
title: FreeRTOS 任务 API 详解
tags: [freertos, rtos, task, api, concept]
created: 2026-07-12
---

# FreeRTOS 任务 API 详解

## 任务创建与删除

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

### 动态创建 `xTaskCreate()`

```c
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()`

```c
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()`

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

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

## 任务挂起与恢复

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

## 任务状态查询

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

![Task list output](../raw/FreeRTOS/尚硅谷FreeRTOS教程/assets/freertos_task_list_output.png)

## 相关页面

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