FreeRTOS任务状态获取

uxTaskGetSystemState()

在 FreeRTOS 中，uxTaskGetSystemState() 是一个 底层核心函数，用于获取系统中所有任务的 原始、详细状态数据（如任务句柄、名称、状态、优先级、栈使用情况等）。它不直接输出可读字符串，而是将数据填充到用户提供的结构体数组中，供开发者进行自定义处理（如生成自定义格式的任务列表、深度性能分析等）。

configUSE_TRACE_FACILITY必须在 FreeRTOSConfig.h 中定义为 1，才可使用 uxTaskGetSystemState()。uxTaskGetSystemState()为系统中的每个任务填充 TaskStatus_t 结构体。 TaskStatus_t 结构体包含任务句柄成员、任务名称、 任务优先级、任务状态以及任务消耗的总运行时间等。如需为单一任务（而非每个任务）填充 TaskStatus_t结构的版本，请参阅 vTaskGetInfo() 。

注意：使用该函数会导致调度器长时间处于挂起状态， 因此该函数仅用于调试。

参数：

• pxTaskStatusArray

  指向 TaskStatus_t 结构体数组的指针。数组必须至少包含 由 RTOS 控制的每个任务对应的一个 TaskStatus_t结构体。由 RTOS 控制的任务数量可以通过 uxTaskGetNumberOfTasks() API 函数确定。

• uxArraySize

  pxTaskStatusArray参数指向的数组的大小。此大小指定为 数组中的索引数量（数组中包含的 TaskStatus_t 结构体的数量）， 不是数组中的字节数。

• pulTotalRunTime

  如果 configGENERATE_RUN_TIME_STATS在 FreeRTOSConfig.h 中设置为 1，则 *pulTotalRunTime由 uxTaskGetSystemState()设置为目标启动以来的总运行时间 （由运行时统计时钟定义）。pulTotalRunTime可以 设置为 NULL，以忽略总运行时间值。

返回：

• TaskStatus_t 结构体（由 uxTaskGetSystemState() 填充）的数量。这个数量应等于 uxTaskGetNumberOfTasks()API 函数返回的数字， 但如果在 uxArraySize参数中传递的值太小，则该数量将为零。

UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray,  // 存储任务状态的结构体数组const UBaseType_t uxArraySize,           // 数组的最大容量（最多可存储的任务数）uint32_t * const pulTotalRunTime         // 总运行时间（可选，需开启运行时间统计）
);

参数与返回值

• pxTaskStatusArray：指向 TaskStatus_t 结构体数组的指针，用于存储每个任务的详细状态数据（需用户提前分配内存）。
• uxArraySize：pxTaskStatusArray 数组的最大容量（即最多能存储的任务数量，通常设为 uxTaskGetNumberOfTasks() 的返回值）。
• pulTotalRunTime：可选参数，指向一个 uint32_t 变量，用于存储系统总运行时间（仅当 configGENERATE_RUN_TIME_STATS = 1 时有效）。
• 返回值：UBaseType_t 类型，表示实际成功获取的任务数量（若数组容量不足，返回值可能小于 uxArraySize）。

核心作用

uxTaskGetSystemState() 的核心功能是 遍历系统中所有任务，将每个任务的原始状态数据（句柄、名称、状态、优先级等）填充到 TaskStatus_t 数组中。

与 vTaskList() 等高层函数不同，它不进行格式化输出，而是提供 “原始数据”，让开发者可以根据需求自定义处理（如筛选特定任务、计算自定义统计指标等），灵活性更高。

vTaskGetInfo()

在 FreeRTOS 中，vTaskGetInfo() 是一个用于 获取单个指定任务详细信息 的 API 函数。与 uxTaskGetSystemState()（获取所有任务信息）不同，它专注于单个任务，可获取其名称、状态、优先级、栈使用情况、运行时间等核心数据，是针对性调试单个任务的重要工具。

void vTaskGetInfo(TaskHandle_t xTask,                  // 目标任务的句柄TaskStatus_t *pxTaskStatus,          // 存储任务信息的结构体指针BaseType_t xGetFreeStackSpace,       // 是否计算当前空闲栈空间（pdTRUE/pdFALSE）eTaskState eState                    // 任务状态（可传入eInvalid获取实时状态）
);

参数与核心作用

• xTask：目标任务的句柄（TaskHandle_t 类型），通过 xTaskCreate() 或 xTaskGetHandle() 等方式获取。若传入 NULL，默认获取 当前运行任务 的信息。
• pxTaskStatus：指向 TaskStatus_t 结构体的指针，用于存储获取到的任务详细信息（需用户提前分配内存）。
• xGetFreeStackSpace：布尔值（pdTRUE/pdFALSE），指定是否计算任务当前的 空闲栈空间（非高水位线，而是当前实时剩余栈空间）：
  • pdTRUE：计算并填充 pxTaskStatus->usStackHighWaterMark 为当前空闲栈空间（单位：字）；
  • pdFALSE：不计算，该字段保持为栈高水位线（历史最小剩余栈空间）。
• eState：指定任务状态（eTaskState 枚举）：
  • 传入 eInvalid：函数会自动获取任务的 实时状态 并填充到 pxTaskStatus->eCurrentState；
  • 传入其他状态（如 eRunning）：强制将该状态填充到结构体（通常用于测试）。

核心作用

vTaskGetInfo() 的核心功能是 将指定任务的详细信息（名称、状态、优先级、栈使用等）填充到 TaskStatus_t 结构体中，供开发者针对性分析单个任务的行为（如栈溢出风险、优先级是否被动态修改、运行时间占比等）。

TaskStatus_t 结构体：信息载体

与 uxTaskGetSystemState() 相同，vTaskGetInfo() 填充的 TaskStatus_t 结构体包含单个任务的详细信息，关键成员如下：

typedef struct xTASK_STATUS
{/* The handle of the task to which the rest of the information in thestructure relates. */TaskHandle_t xHandle;/* A pointer to the task's name. This value will be invalid if the task wasdeleted since the structure was populated! */const char *pcTaskName;/* A number unique to the task. */UBaseType_t xTaskNumber;/* The state in which the task existed when the structure was populated. */eTaskState eCurrentState;/* The priority at which the task was running (may be inherited) when thestructure was populated. */UBaseType_t uxCurrentPriority;/* The priority to which the task will return if the task's current priorityhas been inherited to avoid unbounded priority inversion when obtaining amutex. Only valid if configUSE_MUTEXES is defined as 1 inFreeRTOSConfig.h. */UBaseType_t uxBasePriority;/* The total run time allocated to the task so far, as defined by the runtime stats clock. Only valid when configGENERATE_RUN_TIME_STATS isdefined as 1 in FreeRTOSConfig.h. */unsigned long ulRunTimeCounter;/* Points to the lowest address of the task's stack area. */StackType_t *pxStackBase;#if ( configRECORD_STACK_HIGH_ADDRESS == 1 )/* Points to the top address of the task's stack area. */StackType_t * pxTopOfStack;/* Points to the bottom address of the task's stack area. */StackType_t * pxEndOfStack;#endif/* The minimum amount of stack space that has remained for the task sincethe task was created. The closer this value is to zero the closer the taskhas come to overflowing its stack. */configSTACK_DEPTH_TYPE usStackHighWaterMark;
} TaskStatus_t;

xTaskGetApplicationTaskTag, xTaskGetApplicationTaskTagFromISR

在 FreeRTOS 中，xTaskGetApplicationTaskTag() 和 xTaskGetApplicationTaskTagFromISR() 是一对用于 获取任务 “应用标签”（Application Task Tag） 的 API 函数。“应用标签” 是一个用户可自定义的 32 位值（uint32_t），可关联到特定任务上，用于存储与任务相关的自定义信息（如任务类型标识、状态标记等）。两者的区别仅在于适用的上下文（任务 / 中断）。

TaskHookFunction_t xTaskGetApplicationTaskTag( TaskHandle_t xTask );
TaskHookFunction_t xTaskGetApplicationTaskTagFromISR( TaskHandle_t xTask );

configUSE_APPLICATION_TASK_TAG 必须定义为 1，这些函数才可用。

• 参数：xTask 是目标任务的句柄（TaskHandle_t 类型）。若传入 NULL，则返回 当前运行任务 的应用标签。
• 返回值：uint32_t 类型，即目标任务的应用标签（若任务不存在，返回值不确定）。

核心作用

这两个函数的核心功能是 获取关联到指定任务的 “应用标签”。“应用标签” 是 FreeRTOS 为用户预留的一个 32 位字段（存储在任务控制块 TCB 中），完全由用户自定义使用：

• 可通过 vTaskSetApplicationTaskTag() 函数为任务设置标签；
• 标签值无固定含义，可用于存储任务类型（如 0x01 表示通信任务，0x02 表示传感器任务）、状态标记（如 0x00 表示空闲，0x01 表示忙碌）等；
• FreeRTOS 内核不使用该标签，仅提供存储和获取的接口，灵活性极高。

与设置函数 vTaskSetApplicationTaskTag() 的配合

获取标签前，需先通过 vTaskSetApplicationTaskTag() 为任务设置标签

典型使用场景

1. 任务类型标识与区分

为不同类型的任务设置唯一标签，通过标签快速识别任务类型（无需依赖名称或句柄）：

// 定义任务类型标签
#define TASK_TYPE_COMM  0x01  // 通信任务
#define TASK_TYPE_SENSOR 0x02 // 传感器任务
#define TASK_TYPE_CTRL  0x03  // 控制任务// 创建通信任务并设置标签
TaskHandle_t comm_handle;
xTaskCreate(comm_task, "comm", 128, NULL, 2, &comm_handle);
vTaskSetApplicationTaskTag(comm_handle, TASK_TYPE_COMM);  // 设置标签为通信类型// 在监控任务中通过标签识别类型
void monitor_task(void *pvParam) {TaskHandle_t task_handles[] = {comm_handle, sensor_handle, ctrl_handle};while(1) {for (uint8_t i=0; i<3; i++) {// 获取任务标签uint32_t ulTag = xTaskGetApplicationTaskTag(task_handles[i]);const char *type_str;switch(ulTag) {case TASK_TYPE_COMM:   type_str = "Communication"; break;case TASK_TYPE_SENSOR: type_str = "Sensor"; break;case TASK_TYPE_CTRL:   type_str = "Control"; break;default:               type_str = "Unknown"; break;}// 输出任务类型char msg[100];sprintf(msg, "Task %s: Type = %s\r\n", pcTaskGetName(task_handles[i]), type_str);USART1_SendString((uint8_t*)msg);}vTaskDelay(pdMS_TO_TICKS(1000));}
}

2. 中断中根据任务标签处理事件

在中断服务函数中，通过任务标签判断被中断的任务类型，执行针对性处理：

// 全局变量：存储控制任务句柄
TaskHandle_t ctrl_handle;// 定时器中断服务函数
void TIM2_IRQHandler(void) {if (TIM_GetITStatus(TIM2, TIM_IT_Update) != RESET) {// 获取被中断的任务（当前任务）的标签uint32_t ulTag = xTaskGetApplicationTaskTagFromISR(NULL);// 若被中断的是控制任务，执行紧急处理if (ulTag == TASK_TYPE_CTRL) {// 例如：记录中断发生时控制任务的状态ctrl_interrupt_count++;}TIM_ClearITPendingBit(TIM2, TIM_IT_Update);}
}

3. 任务状态标记（替代全局变量）

用标签存储任务的动态状态（如 “正常 / 异常”），避免使用全局变量：

// 定义状态标签
#define TASK_STATUS_NORMAL 0x00
#define TASK_STATUS_ERROR  0x01// 传感器任务：发生错误时更新标签
void sensor_task(void *pvParam) {while(1) {if (sensor_error_detected()) {// 发生错误，更新自身标签为异常状态vTaskSetApplicationTaskTag(NULL, TASK_STATUS_ERROR);  // NULL表示当前任务USART1_SendString((uint8_t*)"Sensor error detected!\r\n");} else {vTaskSetApplicationTaskTag(NULL, TASK_STATUS_NORMAL);}vTaskDelay(pdMS_TO_TICKS(100));}
}// 监控任务：通过标签检查传感器任务状态
void error_monitor_task(void *pvParam) {while(1) {uint32_t ulStatus = xTaskGetApplicationTaskTag(sensor_handle);if (ulStatus == TASK_STATUS_ERROR) {USART1_SendString((uint8_t*)"Warning: Sensor task in error state!\r\n");}vTaskDelay(pdMS_TO_TICKS(500));}
}

注意事项

1. 上下文区分

   • xTaskGetApplicationTaskTag() 仅能在 任务上下文 中调用；
   • xTaskGetApplicationTaskTagFromISR() 仅能在 中断服务函数（ISR） 中调用，避免中断与任务上下文的并发冲突。

2. 标签的初始值任务创建时，应用标签的初始值为 0（除非通过 vTaskSetApplicationTaskTag() 显式修改）。

3. 任务删除后的有效性若任务已被 vTaskDelete() 删除，通过其句柄调用这两个函数会返回不确定的值（因任务控制块 TCB 可能已被释放），需避免使用无效句柄。

4. 与其他任务标识的配合应用标签可与任务名称（pcTaskGetName()）、句柄（TaskHandle_t）配合使用：

   • 名称用于可读性标识；
   • 句柄用于任务操作（挂起、优先级修改等）；
   • 标签用于自定义状态 / 类型标识，三者互补。

总结

xTaskGetApplicationTaskTag() 和 xTaskGetApplicationTaskTagFromISR() 是 FreeRTOS 中用于 获取任务自定义标签 的 API，分别适用于任务和中断上下文。它们的核心价值是提供一个灵活的自定义字段，用于存储任务类型、状态等信息，简化多任务系统中的任务识别和状态管理。

使用时需注意上下文区分，结合 vTaskSetApplicationTaskTag() 进行标签设置，并确保任务句柄有效。合理使用这对函数可提升多任务系统的灵活性和可维护性。

vTaskSetApplicationTaskTag

在 FreeRTOS 中，vTaskSetApplicationTaskTag() 是用于 为任务设置 “应用标签”（Application Task Tag） 的 API 函数。这个 “标签” 本质是一个可自定义的 32 位值（通常是函数指针或整数），存储在任务控制块（TCB）中，完全由用户支配，可用于关联与任务相关的自定义信息（如钩子函数、状态标记、类型标识等）

configUSE_APPLICATION_TASK_TAG必须定义为 1，才可使用此函数。

void vTaskSetApplicationTaskTag(TaskHandle_t xTask,                // 目标任务句柄TaskHookFunction_t pxTagValue      // 要设置的标签值（函数指针类型，实际可存储任意32位值）
);

参数解析

1. xTask：

   • 目标任务的句柄（TaskHandle_t 类型）。若传入 NULL，则为 当前正在运行的任务 设置标签。
   • 句柄需有效（指向未被删除的任务），否则操作无效（可能导致未定义行为）。

2. pxTagValue：

   • 表面类型是 TaskHookFunction_t（FreeRTOS 定义的函数指针类型：typedef void (*TaskHookFunction_t)(void);），但本质上可存储 任意 32 位值（整数、指针等）。
   • 这是因为在 32 位系统中，函数指针与 uint32_t 长度相同，FreeRTOS 内核仅将其作为 “32 位存储空间” 使用，不强制其为函数指针。

核心作用

vTaskSetApplicationTaskTag() 的核心功能是 将用户自定义的 32 位值（标签）关联到指定任务。这个标签的用途完全由用户决定，常见场景包括：

• 存储任务类型标识（如 “通信任务”“控制任务”）；
• 关联任务专属的钩子函数（如任务切换时触发的回调）；
• 记录任务的动态状态（如 “正常”“异常”“忙碌”）；
• 存储与任务相关的上下文数据指针（如任务专属的缓冲区地址）。

与获取函数的配合

设置标签后，可通过以下函数获取标签值：

• 任务上下文：xTaskGetApplicationTaskTag(xTask)
• 中断上下文：xTaskGetApplicationTaskTagFromISR(xTask)

典型使用场景

1. 为任务关联 “类型标识”

通过标签区分任务类型，便于批量管理或监控：

// 定义任务类型标签（用整数表示）
#define TASK_TYPE_UART   0x0001  // UART通信任务
#define TASK_TYPE_I2C    0x0002  // I2C传感器任务
#define TASK_TYPE_CONTROL 0x0003 // 控制任务// 创建UART任务并设置类型标签
TaskHandle_t uart_task_handle;
xTaskCreate(uart_task, "uart", 128, NULL, 2, &uart_task_handle);
vTaskSetApplicationTaskTag(uart_task_handle, (TaskHookFunction_t)TASK_TYPE_UART);  // 存储类型// 在监控任务中通过标签识别类型
void monitor_task(void *pvParam) {while(1) {// 获取UART任务的标签uint32_t task_type = (uint32_t)xTaskGetApplicationTaskTag(uart_task_handle);if (task_type == TASK_TYPE_UART) {USART1_SendString((uint8_t*)"UART task is active\r\n");}vTaskDelay(pdMS_TO_TICKS(1000));}
}

2. 关联任务专属钩子函数

将标签设为函数指针，在特定时机（如任务切换时）调用该钩子函数：

// 定义UART任务的钩子函数（例如：任务切换时打印状态）
void uart_task_hook(void) {USART1_SendString((uint8_t*)"UART task is switching\r\n");
}// 创建UART任务并关联钩子函数
void uart_task_init(void) {TaskHandle_t uart_handle;xTaskCreate(uart_task, "uart", 128, NULL, 2, &uart_handle);// 将标签设为钩子函数指针vTaskSetApplicationTaskTag(uart_handle, uart_task_hook);
}// 在任务切换时调用钩子函数（需结合调度器钩子实现）
void vApplicationSwitchContextHook(void) {// 获取当前运行任务的标签（钩子函数）TaskHookFunction_t pxHook = xTaskGetApplicationTaskTag(NULL);if (pxHook != NULL) {pxHook();  // 调用钩子函数}
}

3. 记录任务动态状态

用标签存储任务的实时状态（如 “空闲”“忙碌”“错误”），避免使用全局变量：

// 定义状态标签
#define TASK_STATE_IDLE   0x00  // 空闲
#define TASK_STATE_BUSY   0x01  // 忙碌
#define TASK_STATE_ERROR  0x02  // 错误// 传感器任务：动态更新自身状态标签
void sensor_task(void *pvParam) {while(1) {if (sensor_data_ready()) {vTaskSetApplicationTaskTag(NULL, (TaskHookFunction_t)TASK_STATE_BUSY);  // 忙碌process_sensor_data();  // 处理数据vTaskSetApplicationTaskTag(NULL, (TaskHookFunction_t)TASK_STATE_IDLE);  // 恢复空闲} else if (sensor_error()) {vTaskSetApplicationTaskTag(NULL, (TaskHookFunction_t)TASK_STATE_ERROR);  // 错误}vTaskDelay(pdMS_TO_TICKS(50));}
}// 监控任务：检查传感器任务状态
void sensor_monitor(void *pvParam) {TaskHandle_t sensor_handle = xTaskGetHandle("sensor");while(1) {uint32_t state = (uint32_t)xTaskGetApplicationTaskTag(sensor_handle);if (state == TASK_STATE_ERROR) {USART1_SendString((uint8_t*)"Sensor task error!\r\n");}vTaskDelay(pdMS_TO_TICKS(100));}
}

注意事项

1. TaskHookFunction_t 的本质该类型定义为函数指针（void (*)(void)），但 FreeRTOS 内核并不强制其指向有效函数。在实际使用中，可将其视为 32 位通用存储空间，存储整数、指针等任意 32 位数据（只需强制类型转换即可）。

2. 上下文限制vTaskSetApplicationTaskTag() 仅能在 任务上下文 中调用，禁止在中断服务函数（ISR）中使用。若需在 ISR 中修改任务标签，需通过任务间接实现（如 ISR 发送消息给任务，由任务调用该函数）。

3. 任务删除后的标签无效若任务已被 vTaskDelete() 删除，其 TCB 可能被释放，此时通过无效句柄设置标签会导致未定义行为（如内存错误）。设置前需确保任务句柄有效。

4. 初始值任务创建时，标签的初始值为 NULL（0），除非通过 vTaskSetApplicationTaskTag() 显式修改。

5. 与其他任务属性的区别标签是完全独立的自定义字段，与任务的优先级、状态、名称等内核管理的属性无关，不会影响 FreeRTOS 的调度逻辑。

总结

vTaskSetApplicationTaskTag() 是 FreeRTOS 提供的一个高度灵活的 API，用于为任务设置自定义标签（32 位值）。该标签可存储任务类型、状态、钩子函数等任意信息，完全由用户支配，是扩展任务功能、简化多任务管理的实用工具。

使用时需注意：通过类型转换存储任意 32 位数据，仅在任务上下文调用，确保任务句柄有效。合理使用该函数可显著提升多任务系统的可扩展性和可维护性。

xTaskCallApplicationTaskHook

在 FreeRTOS 中，xTaskCallApplicationTaskHook() 是一个用于 调用任务关联的 “应用钩子函数”（Application Task Hook） 的 API 函数。它与 vTaskSetApplicationTaskTag() 配合使用：前者用于为任务设置一个钩子函数（作为 “应用标签”），后者用于触发该钩子函数的执行，实现任务专属的自定义逻辑（如日志记录、状态回调等）。

configUSE_APPLICATION_TASK_TAG 必须定义为 1，此函数才可用。

可为每个任务分配“标签”值。通常情况下，该值仅供应用程序使用， RTOS 内核不会访问它。不过，也可以使用该标签为任务分配钩子（或回调）函数， 通过调用xTaskCallApplicationTaskHook() 来执行钩子函数。每个 任务都可定义自己的回调，或者干脆不定义回调。

尽管可以使用第一个函数参数来调用任何任务的钩子函数， 任务钩子函数最常用的是跟踪钩子宏，如下例所示。

任务钩子函数必须具有 TaskHookFunction_t 类型，即接受一个 void * 参数， 并返回一个 BaseType_t 类型的值。void * 参数可用于向钩子函数传递任何信息。

参数：

• xTask

  其钩子函数被调用的任务的句柄。传递 NULL 作为 xTask 将调用 与当前执行的任务相关的钩子函数。

• pvParameter

  要传递给钩子函数的值。这可以是指向一个结构体的指针，也可以是一个数值。

函数原型与核心作用

函数原型

BaseType_t xTaskCallApplicationTaskHook(TaskHandle_t xTask,        // 目标任务句柄uint32_t ulParameter       // 传递给钩子函数的参数
);

参数与返回值

• xTask：目标任务的句柄（TaskHandle_t 类型）。若传入 NULL，则调用 当前运行任务 的钩子函数。
• ulParameter：传递给钩子函数的 32 位参数（用户自定义，如状态码、数据指针等）。
• 返回值：BaseType_t 类型，通常是钩子函数的返回值（若钩子函数无返回值，可能返回 pdTRUE 表示调用成功）。

核心作用

xTaskCallApplicationTaskHook() 的核心功能是：触发执行指定任务通过 vTaskSetApplicationTaskTag() 设置的钩子函数，并传递参数。

这里的 “钩子函数” 是用户定义的函数，需符合特定原型（通常为 uint32_t (*TaskHookFunction_t)(uint32_t ulParam);），存储在任务的 “应用标签” 中（通过 vTaskSetApplicationTaskTag() 关联）。调用该函数时，FreeRTOS 会取出任务标签中的函数指针，执行该函数并传入 ulParameter 参数。

与 vTaskSetApplicationTaskTag() 的配合

使用 xTaskCallApplicationTaskHook() 前，需先通过 vTaskSetApplicationTaskTag() 为任务设置钩子函数（作为标签）。步骤如下：

1. 定义钩子函数（符合参数和返回值要求）：

   // 示例：任务的钩子函数（打印参数并返回状态）
   uint32_t task_hook_function(uint32_t ulParam) {USART1_SendString((uint8_t*)"Hook called with param: ");USART1_SendByte(ulParam + '0');  // 简化输出参数USART1_SendString((uint8_t*)"\r\n");return 0xAA;  // 返回自定义值
   }
   

2. 为任务设置钩子函数（作为应用标签）：

   TaskHandle_t test_task_handle;
   xTaskCreate(test_task, "test", 128, NULL, 2, &test_task_handle);
   // 将钩子函数设置为任务的应用标签
   vTaskSetApplicationTaskTag(test_task_handle, (TaskHookFunction_t)task_hook_function);
   

3. 调用钩子函数：

   // 调用test_task的钩子函数，传递参数0x05
   uint32_t ulResult = xTaskCallApplicationTaskHook(test_task_handle, 0x05);
   

典型使用场景

xTaskCallApplicationTaskHook() 适用于 需要触发任务专属回调逻辑 的场景，例如：

1. 任务状态通知与回调

当外部事件发生时，调用任务的钩子函数通知其处理，避免使用全局变量或消息队列：

// 传感器任务的钩子函数：处理外部触发的校准事件
uint32_t sensor_calibrate_hook(uint32_t ulParam) {USART1_SendString((uint8_t*)"Sensor calibrating...\r\n");perform_calibration(ulParam);  // 使用参数（如校准模式）return 1;  // 返回校准成功
}// 创建传感器任务并设置钩子
void sensor_task_init() {TaskHandle_t sensor_handle;xTaskCreate(sensor_task, "sensor", 128, NULL, 2, &sensor_handle);vTaskSetApplicationTaskTag(sensor_handle, (TaskHookFunction_t)sensor_calibrate_hook);
}// 外部控制任务：触发传感器校准
void control_task(void *pvParam) {TaskHandle_t sensor_handle = xTaskGetHandle("sensor");while(1) {if (calibration_triggered()) {// 调用传感器任务的钩子函数，传递校准模式（1=快速校准）uint32_t result = xTaskCallApplicationTaskHook(sensor_handle, 1);if (result == 1) {USART1_SendString((uint8_t*)"Calibration successful\r\n");}}vTaskDelay(pdMS_TO_TICKS(1000));}
}

2. 任务调试与日志记录

为任务设置钩子函数用于输出调试信息，需要时通过 xTaskCallApplicationTaskHook() 触发：

// 调试钩子函数：输出任务当前栈使用情况
uint32_t debug_stack_hook(uint32_t ulParam) {uint16_t stack_high_water = uxTaskGetStackHighWaterMark(NULL);  // 当前任务的栈高水位线char msg[50];sprintf(msg, "Stack high watermark: %u words\r\n", stack_high_water);USART1_SendString((uint8_t*)msg);return stack_high_water;  // 返回栈高水位线
}// 为多个任务设置调试钩子
void init_debug_hooks() {vTaskSetApplicationTaskTag(task1_handle, (TaskHookFunction_t)debug_stack_hook);vTaskSetApplicationTaskTag(task2_handle, (TaskHookFunction_t)debug_stack_hook);
}// 调试任务：定期触发其他任务的调试钩子
void debug_task(void *pvParam) {while(1) {USART1_SendString((uint8_t*)"Checking task1 stack...\r\n");xTaskCallApplicationTaskHook(task1_handle, 0);  // 调用task1的钩子USART1_SendString((uint8_t*)"Checking task2 stack...\r\n");xTaskCallApplicationTaskHook(task2_handle, 0);  // 调用task2的钩子vTaskDelay(pdMS_TO_TICKS(5000));}
}

注意事项

1. 钩子函数的原型匹配钩子函数需符合 uint32_t (*)(uint32_t) 原型（参数和返回值为 32 位），否则调用时会导致栈错误或未定义行为。

2. 任务标签必须是有效函数指针若通过 vTaskSetApplicationTaskTag() 设置的标签不是函数指针（如整数），调用 xTaskCallApplicationTaskHook() 会触发非法函数调用（通常导致 HardFault）。

3. 上下文限制

   • xTaskCallApplicationTaskHook() 仅能在 任务上下文 中调用；
   • 若需在中断中调用，需使用中断安全版本（如 xTaskCallApplicationTaskHookFromISR()，具体取决于 FreeRTOS 移植）。

4. 钩子函数应简短钩子函数属于被调用任务的执行逻辑，应避免长时间阻塞（如无 vTaskDelay() 或阻塞操作），否则会影响任务的实时性。

5. 任务有效性检查调用前需确保 xTask 是有效句柄（任务未被删除），否则会访问无效内存（导致系统崩溃）。可通过 xTaskGetHandle() 验证句柄有效性。

总结

xTaskCallApplicationTaskHook() 是 FreeRTOS 中用于 触发任务专属钩子函数 的 API，与 vTaskSetApplicationTaskTag() 配合，实现任务自定义回调逻辑。它的核心价值是提供一种灵活的任务间通信或事件触发方式，无需依赖全局变量或消息队列。

使用时需注意：确保钩子函数原型正确、任务句柄有效，仅在任务上下文调用，并保持钩子函数简短高效。合理使用该函数可简化任务间协作，提升系统的模块化程度。

uxTaskGetStackHighWaterMark, uxTaskGetStackHighWaterMark2

uxTaskGetStackHighWaterMark2()是 uxTaskGetStackHighWaterMark()的一个版本， 后者返回用户可定义的类型，以删除 8 位架构上 UBaseType_t类型的数据类型宽度限制。随着任务的执行和中断的处理，任务使用的堆栈会增加和缩小。 uxTaskGetStackHighWaterMark()返回任务开始执行后任务可用的最小剩余堆栈空间量—— 即任务堆栈达到最大（最深）值时未使用的堆栈量。这就是 所谓的堆栈“高水位线”。

INCLUDE_uxTaskGetStackHighWaterMark必须定义为 1，uxTaskGetStackHighWaterMark函数才可用，INCLUDE_uxTaskGetStackHighWaterMark2必须定义为 1，uxTaskGetStackHighWaterMark2函数才可用。

在 FreeRTOS 中，uxTaskGetStackHighWaterMark() 和 uxTaskGetStackHighWaterMark2() 是用于 获取任务栈 “高水位线”（Stack High Water Mark） 的 API 函数。“高水位线” 表示任务从创建到当前运行过程中 剩余的最小栈空间（即栈使用量的最大值对应的剩余空间），是监控栈溢出风险的核心工具。两者功能一致，主要区别在于返回值类型（适配不同的栈大小需求）。

UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask );configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2( TaskHandle_t xTask );

参数：

• xTask

  正在查询的任务的句柄。任务可以通过传递 NULL 作为 xTask 参数来查询自己的高水位标记。

返回：

返回的值是以字为单位的高水位标记（例如，在 32 位计算机上， 返回值为 1 表示有 4 个字节的堆栈未使用）。如果返回值为零， 则任务可能已溢出堆栈。如果返回值接近于零，则任务已接近堆栈溢出。

vTaskSetThreadLocalStoragePointer

在 FreeRTOS 中，vTaskSetThreadLocalStoragePointer() 是用于 为任务设置 “线程本地存储指针（Thread Local Storage Pointer, TLS）” 的 API 函数。“线程本地存储” 是每个任务独有的存储空间，用于存储仅与该任务相关的私有数据（如任务专属缓冲区、状态标记、上下文信息等），避免使用全局变量导致的多任务冲突，提高线程安全性。

一、函数原型与核心参数

函数原型

void vTaskSetThreadLocalStoragePointer(TaskHandle_t xTask,        // 目标任务句柄BaseType_t xIndex,         // 本地存储指针的索引（0 ~ configNUM_THREAD_LOCAL_STORAGE_POINTERS-1）void *pvValue              // 要存储的指针值（任务私有数据的地址）
);

参数解析

1. xTask：目标任务的句柄（TaskHandle_t 类型）。若传入 NULL，则为 当前运行的任务 设置本地存储指针。

2. xIndex：本地存储指针的索引（非负整数），范围为 0 到 configNUM_THREAD_LOCAL_STORAGE_POINTERS - 1。

   • 该最大值由 FreeRTOSConfig.h 中的 configNUM_THREAD_LOCAL_STORAGE_POINTERS 配置（需 ≥1 才能启用 TLS 功能）；
   • 每个索引对应任务的一个 “私有指针槽位”，不同索引可存储不同类型的私有数据（如索引 0 存缓冲区，索引 1 存状态）。

3. pvValue：要存储的指针值（void* 类型），通常指向任务的私有数据（如缓冲区、结构体实例等）。FreeRTOS 仅存储指针本身，不管理指针指向的内存（需用户手动分配和释放）。

核心作用

vTaskSetThreadLocalStoragePointer() 的核心功能是 为指定任务的特定索引位置存储一个私有指针。该指针仅对该任务可见，其他任务无法通过相同索引访问（每个任务的 TLS 空间独立），从而实现任务私有数据的隔离存储。

二、与获取函数的配合

设置 TLS 指针后，可通过 vTaskGetThreadLocalStoragePointer() 函数获取指针值：

void *vTaskGetThreadLocalStoragePointer(TaskHandle_t xTask,        // 目标任务句柄（NULL 表示当前任务）BaseType_t xIndex          // 存储指针的索引
);

三、典型使用场景

vTaskSetThreadLocalStoragePointer() 适用于 需要为每个任务分配私有数据 的场景，例如：

1. 任务私有缓冲区（避免全局变量冲突）

多个相同功能的任务（如多串口接收任务）需各自的接收缓冲区，通过 TLS 存储缓冲区指针，避免全局变量竞争：

// 在FreeRTOSConfig.h中配置TLS索引数量
#define configNUM_THREAD_LOCAL_STORAGE_POINTERS 1  // 至少1个索引// 任务函数：每个任务有自己的接收缓冲区
void uart_rx_task(void *pvParam) {// 为当前任务分配私有缓冲区（128字节）uint8_t *pRxBuffer = pvPortMalloc(128);if (pRxBuffer == NULL) {USART1_SendString((uint8_t*)"Malloc failed for rx buffer\r\n");vTaskDelete(NULL);}// 将缓冲区指针存储到当前任务的TLS索引0中vTaskSetThreadLocalStoragePointer(NULL, 0, pRxBuffer);while(1) {// 从TLS中获取当前任务的私有缓冲区uint8_t *pLocalBuffer = (uint8_t*)vTaskGetThreadLocalStoragePointer(NULL, 0);// 使用缓冲区接收数据（示例）uint32_t rx_len = uart_receive(pLocalBuffer, 128);USART1_SendString((uint8_t*)"Received: ");USART1_SendBuffer(pLocalBuffer, rx_len);vTaskDelay(pdMS_TO_TICKS(100));}
}// 创建两个串口接收任务（共享函数，但各有私有缓冲区）
void create_uart_tasks() {xTaskCreate(uart_rx_task, "uart1_rx", 128, NULL, 2, NULL);xTaskCreate(uart_rx_task, "uart2_rx", 128, NULL, 2, NULL);
}

2. 任务上下文信息传递

在中断或其他任务中，通过 TLS 索引获取目标任务的私有上下文信息（如任务状态、配置参数等）：

// 定义任务上下文结构体
typedef struct {uint32_t task_id;       // 任务IDuint8_t  status;        // 任务状态（0=空闲，1=忙碌）void (*callback)(void); // 任务专属回调函数
} TaskContext_t;// 初始化任务时设置上下文到TLS
void init_task_with_context(TaskHandle_t xTask, uint32_t id) {// 分配上下文结构体TaskContext_t *pContext = pvPortMalloc(sizeof(TaskContext_t));pContext->task_id = id;pContext->status = 0;pContext->callback = task_callback;// 将上下文指针存储到TLS索引1vTaskSetThreadLocalStoragePointer(xTask, 1, pContext);
}// 监控任务：获取其他任务的上下文信息
void monitor_task(void *pvParam) {TaskHandle_t task1 = xTaskGetHandle("task1");while(1) {// 从task1的TLS索引1获取上下文TaskContext_t *pContext = (TaskContext_t*)vTaskGetThreadLocalStoragePointer(task1, 1);if (pContext != NULL) {char msg[100];sprintf(msg, "task1 ID: %u, Status: %u\r\n", pContext->task_id, pContext->status);USART1_SendString((uint8_t*)msg);}vTaskDelay(pdMS_TO_TICKS(500));}
}

3. 多实例任务的状态隔离

同一任务函数被创建多个实例时，通过 TLS 存储每个实例的独立状态（避免用全局变量区分实例）：

// 任务函数（多实例）
void counter_task(void *pvParam) {// 为当前实例分配计数器（私有状态）uint32_t *pCounter = pvPortMalloc(sizeof(uint32_t));*pCounter = 0;// 存储到TLS索引0vTaskSetThreadLocalStoragePointer(NULL, 0, pCounter);while(1) {// 获取当前实例的计数器uint32_t *pLocalCounter = (uint32_t*)vTaskGetThreadLocalStoragePointer(NULL, 0);(*pLocalCounter)++;  // 自增// 输出当前实例的计数（通过任务名称区分实例）char msg[100];sprintf(msg, "%s count: %u\r\n", pcTaskGetName(NULL), *pLocalCounter);USART1_SendString((uint8_t*)msg);vTaskDelay(pdMS_TO_TICKS(1000));}
}// 创建两个计数器任务实例
void create_counter_tasks() {xTaskCreate(counter_task, "counter1", 128, NULL, 1, NULL);xTaskCreate(counter_task, "counter2", 128, NULL, 1, NULL);
}

四、注意事项

1. 配置依赖必须在 FreeRTOSConfig.h 中定义 configNUM_THREAD_LOCAL_STORAGE_POINTERS 且值 ≥1，否则 TLS 功能不可用（函数会被编译器忽略）：

   #define configNUM_THREAD_LOCAL_STORAGE_POINTERS 2  // 支持2个TLS索引
   

2. 索引范围限制xIndex 必须在 0 到 configNUM_THREAD_LOCAL_STORAGE_POINTERS - 1 范围内，超出范围的设置无效（不会存储指针，也不会报错）。

3. 内存管理责任pvValue 指向的内存需由用户手动管理：

   • 任务删除前，需从 TLS 中取出指针并释放（避免内存泄漏）；
   • 若指针指向栈内存，需确保任务运行时栈不被释放（通常建议用动态内存 pvPortMalloc() 分配）。

4. 默认值任务创建时，所有 TLS 索引的指针默认值为 NULL，需通过 vTaskSetThreadLocalStoragePointer() 显式设置。

5. 任务删除时的清理任务被 vTaskDelete() 删除后，其 TLS 指针会自动失效，但指针指向的内存不会被自动释放。因此，任务删除前需手动清理：

   // 任务退出前清理TLS内存
   void cleanup_task(TaskHandle_t xTask) {// 释放索引0的缓冲区void *pBuffer = vTaskGetThreadLocalStoragePointer(xTask, 0);if (pBuffer != NULL) {vPortFree(pBuffer);}// 释放索引1的上下文void *pContext = vTaskGetThreadLocalStoragePointer(xTask, 1);if (pContext != NULL) {vPortFree(pContext);}
   }
   

总结

vTaskSetThreadLocalStoragePointer() 是 FreeRTOS 中实现 “线程本地存储（TLS）” 的核心 API，用于为任务的特定索引设置私有指针，实现任务专属数据的隔离存储。它避免了全局变量的多任务冲突，提高了系统的模块化和线程安全性。

使用时需注意：配置 configNUM_THREAD_LOCAL_STORAGE_POINTERS 启用功能，控制索引范围，手动管理指针指向的内存，并在任务删除前清理资源。合理使用 TLS 可显著简化多任务系统中私有数据的管理。

pvTaskGetThreadLocalStoragePointer

void *pvTaskGetThreadLocalStoragePointer(TaskHandle_t xTaskToQuery,BaseType_t xIndex );

参数：

• xTaskToQuery

  正在读取线程本地数据的任务句柄。任务可以通过使用 NULL 作为参数值自行读取其线程本地数据。

• xIndex

  读取数据的线程本地存储数组的索引。

  可用数组索引的数量由 configNUM_THREAD_LOCAL_STORAGE_POINTERS 编译时配置常量（位于 FreeRTOSConfig.h 中）设置。

返回：

存储在任务 xTaskToQuery 的线程本地存储数组的索引位置 xIndex 中的值。

用法示例：

请参阅线程本地存储数组 文档页面。

vTaskSetTimeOutState()

在 FreeRTOS 中，vTaskSetTimeOutState() 是一个用于 初始化或重置 “超时状态结构体（TimeOut_t）” 的 API 函数。它通常与 xTaskCheckForTimeOut() 配合使用，用于自定义超时检测（例如：在循环中执行操作时，判断是否超过指定的等待时间），提供比 vTaskDelay() 更灵活的超时控制。

函数原型与核心参数

函数原型

void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut );

• 参数：pxTimeOut 是指向 TimeOut_t 结构体的指针，用于存储超时状态信息（需用户提前分配内存，通常为栈上变量）。
• 返回值：无

核心作用

vTaskSetTimeOutState() 的核心功能是 初始化 TimeOut_t 结构体，记录当前系统的 Tick 数（作为超时检测的 “起始时间”），并为后续的超时判断提供基准。

TimeOut_t 结构体是超时检测的 “状态载体”，内部包含超时计算所需的关键信息（如起始 Tick 数、剩余超时 Tick 数等）。调用 vTaskSetTimeOutState() 后，结构体被初始化为 “未超时” 状态，后续通过 xTaskCheckForTimeOut() 可基于该结构体判断是否已超时。

与 xTaskCheckForTimeOut() 的配合使用

vTaskSetTimeOutState() 需与 xTaskCheckForTimeOut() 配合，才能完成超时检测。两者的典型使用流程如下：

1. 定义 TimeOut_t 结构体（通常在栈上分配）；
2. 调用 vTaskSetTimeOutState() 初始化结构体（记录起始 Tick 数）；
3. 在循环中执行操作，并定期调用 xTaskCheckForTimeOut() 检查是否超时：
   • 若未超时，xTaskCheckForTimeOut() 会更新结构体的 xRemainingTime（剩余超时时间），返回 pdFALSE；
   • 若已超时，返回 pdTRUE，可退出循环。

使用场景

vTaskSetTimeOutState() 适用于 需要在等待过程中执行其他操作，并自定义超时判断的场景（而非单纯阻塞等待）。例如：

1. 等待外部事件超时（非阻塞等待）

等待某个外部信号（如传感器数据就绪），同时在等待过程中执行其他操作（如 LED 闪烁），并设置超时时间：

void wait_for_sensor_task(void *pvParam) {const TickType_t xTimeoutTicks = pdMS_TO_TICKS(5000);  // 超时时间5000ms（5秒）TimeOut_t xTimeOut;  // 超时状态结构体while(1) {// 初始化超时状态（记录当前Tick数作为起始时间）vTaskSetTimeOutState(&xTimeOut);// 循环等待传感器数据就绪，最多等待5秒BaseType_t xSensorReady = pdFALSE;while (xSensorReady == pdFALSE) {// 检查传感器是否就绪xSensorReady = sensor_is_ready();if (xSensorReady == pdFALSE) {// 未就绪，执行其他操作（如闪烁LED）led_toggle();// 检查是否超时（传入超时结构体和总超时Tick数）if (xTaskCheckForTimeOut(&xTimeOut, &xTimeoutTicks) == pdTRUE) {// 超时处理USART1_SendString((uint8_t*)"Wait for sensor timed out!\r\n");break;  // 退出等待循环}// 短暂延时（避免CPU占用过高）vTaskDelay(pdMS_TO_TICKS(100));}}if (xSensorReady == pdTRUE) {// 传感器就绪，处理数据USART1_SendString((uint8_t*)"Sensor data ready, processing...\r\n");process_sensor_data();}vTaskDelay(pdMS_TO_TICKS(1000));}
}

2. 带超时的多步骤操作

在一系列连续操作中，若总耗时超过指定时间则中断操作：

void multi_step_task(void *pvParam) {const TickType_t xTotalTimeout = pdMS_TO_TICKS(3000);  // 总超时3秒TimeOut_t xTimeOut;while(1) {// 初始化超时状态vTaskSetTimeOutState(&xTimeOut);BaseType_t xSuccess = pdTRUE;// 步骤1：配置外设configure_peripheral();// 检查步骤1后是否超时if (xTaskCheckForTimeOut(&xTimeOut, &xTotalTimeout) == pdTRUE) {xSuccess = pdFALSE;}// 步骤2：发送数据（仅当未超时）if (xSuccess) {send_data();if (xTaskCheckForTimeOut(&xTimeOut, &xTotalTimeout) == pdTRUE) {xSuccess = pdFALSE;}}// 步骤3：接收响应（仅当未超时）if (xSuccess) {receive_response();if (xTaskCheckForTimeOut(&xTimeOut, &xTotalTimeout) == pdTRUE) {xSuccess = pdFALSE;}}// 结果处理if (xSuccess) {USART1_SendString((uint8_t*)"Multi-step operation completed\r\n");} else {USART1_SendString((uint8_t*)"Multi-step operation timed out\r\n");}vTaskDelay(pdMS_TO_TICKS(2000));}
}

注意事项

1. TimeOut_t 结构体的分配结构体需在调用 vTaskSetTimeOutState() 前分配内存（通常为栈上变量，或全局变量），且在超时检测期间需保持有效（未被释放或覆盖）。

2. 超时时间的单位超时时间（xTimeoutTicks）的单位是 Tick，需通过 pdMS_TO_TICKS(ms) 宏将毫秒转换为 Tick 数（依赖 configTICK_RATE_HZ 配置）。

3. xTaskCheckForTimeOut() 的副作用xTaskCheckForTimeOut() 会修改 TimeOut_t 结构体的 xRemainingTime 成员（更新为剩余超时时间），因此结构体的状态会随每次调用动态变化。

4. 与阻塞超时的区别

   • 带有超时参数的函数（如 xQueueReceive(xQueue, &data, xTimeout)）是 阻塞等待，期间任务会被挂起，不占用 CPU；
   • vTaskSetTimeOutState() + xTaskCheckForTimeOut() 是 非阻塞 / 轮询等待，任务可在等待期间执行其他操作（如示例中的 LED 闪烁），但会占用更多 CPU 时间。

5. 超时判断的精度超时判断的精度受系统 Tick 周期限制（与 configTICK_RATE_HZ 相关），实际超时时间可能比设置值多 1 个 Tick 周期（因 Tick 中断触发时机）。

总结

vTaskSetTimeOutState() 是 FreeRTOS 中用于 初始化超时状态结构体 的 API，与 xTaskCheckForTimeOut() 配合，实现灵活的自定义超时检测。它适用于需要在等待过程中执行其他操作的场景，提供了比阻塞超时函数更灵活的时间控制。

使用时需注意：正确分配 TimeOut_t 结构体，通过 pdMS_TO_TICKS() 转换超时时间单位，理解 xTaskCheckForTimeOut() 对结构体状态的修改，并根据需求选择阻塞或非阻塞超时方式。

xTaskCheckForTimeOut()

在 FreeRTOS 中，xTaskCheckForTimeOut() 是一个用于 检查是否已超过指定超时时间 的 API 函数。它与 vTaskSetTimeOutState() 配合使用，通过监控系统 Tick 数的变化，判断从 “超时起始时间” 到当前是否已超过预设的超时时间，主要用于 非阻塞场景下的自定义超时控制（例如：在轮询操作中判断是否超时，同时允许执行其他任务）。

函数原型与核心参数

函数原型

BaseType_t xTaskCheckForTimeOut(TimeOut_t * const pxTimeOut,         // 超时状态结构体（已通过vTaskSetTimeOutState()初始化）TickType_t * const pxRemainingTicks  // 剩余的超时Tick数（会被函数更新）
);

参数与返回值

• pxTimeOut：指向 TimeOut_t 结构体的指针，该结构体需先通过 vTaskSetTimeOutState() 初始化（记录超时起始 Tick 数）。
• pxRemainingTicks：指向 TickType_t 变量的指针，输入为 “总超时 Tick 数”，输出为 “当前剩余的超时 Tick 数”（若未超时）。
• 返回值：BaseType_t 类型
  • pdTRUE：已超时（从起始时间到当前的时间超过了 pxRemainingTicks 输入值）；
  • pdFALSE：未超时（更新 pxRemainingTicks 为剩余时间）。

核心作用

xTaskCheckForTimeOut() 的核心功能是：

1. 计算从 vTaskSetTimeOutState() 初始化（记录起始 Tick 数）到当前的 已流逝 Tick 数；
2. 判断已流逝时间是否超过 pxRemainingTicks 输入的总超时时间：
   • 若未超过：更新 pxRemainingTicks 为 “剩余超时 Tick 数”（总超时 - 已流逝），返回 pdFALSE；
   • 若已超过：返回 pdTRUE，表示超时。

该函数通过无符号整数的模运算特性，自动处理 Tick 计数器的溢出（与 xTaskGetTickCount() 的溢出处理逻辑一致），确保超时判断在 Tick 溢出后仍正确。

与 vTaskSetTimeOutState() 的配合流程

xTaskCheckForTimeOut() 必须与 vTaskSetTimeOutState() 配合使用，完整流程如下：

1. 定义并初始化 TimeOut_t 结构体：

   TimeOut_t xTimeOut;  // 超时状态结构体（通常在栈上分配）
   vTaskSetTimeOutState(&xTimeOut);  // 初始化，记录当前Tick数作为起始时间
   

2. 设置总超时时间（Tick 数）：

   TickType_t xTotalTimeout = pdMS_TO_TICKS(3000);  // 总超时时间3000ms（3秒）
   

3. 在循环中检查超时：

   while (/* 等待条件未满足 */) {// 检查是否超时if (xTaskCheckForTimeOut(&xTimeOut, &xTotalTimeout) == pdTRUE) {// 超时处理：退出循环或执行错误逻辑break;}// 未超时：执行其他操作（如轮询、LED闪烁等）vTaskDelay(pdMS_TO_TICKS(100));  // 短暂延时，避免CPU占用过高
   }
   

使用场景

xTaskCheckForTimeOut() 适用于 需要在等待过程中执行其他操作，且需自定义超时判断 的场景（非单纯阻塞等待），例如：

1. 非阻塞等待外部设备响应

等待传感器或外设响应时，在等待期间执行状态刷新、LED 指示等操作，并设置超时：

void wait_for_peripheral_task(void *pvParam) {while(1) {TimeOut_t xTimeOut;// 初始化超时状态（记录当前时间）vTaskSetTimeOutState(&xTimeOut);// 总超时时间：2000ms（2秒）TickType_t xRemaining = pdMS_TO_TICKS(2000);// 等待外设就绪标志BaseType_t xReady = pdFALSE;while (xReady == pdFALSE) {// 检查外设是否就绪xReady = peripheral_is_ready();if (xReady == pdFALSE) {// 未就绪：检查是否超时if (xTaskCheckForTimeOut(&xTimeOut, &xRemaining) == pdTRUE) {// 超时处理USART1_SendString((uint8_t*)"Peripheral response timed out!\r\n");break;}// 未超时：执行其他操作（如闪烁LED）led_toggle();// 短暂延时（100ms）vTaskDelay(pdMS_TO_TICKS(100));}}if (xReady == pdTRUE) {// 外设就绪：处理数据USART1_SendString((uint8_t*)"Peripheral ready, processing data...\r\n");}vTaskDelay(pdMS_TO_TICKS(1000));}
}

2. 带超时的多步轮询操作

在一系列轮询操作中，若总耗时超过超时时间则中断流程：

void multi_poll_task(void *pvParam) {while(1) {TimeOut_t xTimeOut;vTaskSetTimeOutState(&xTimeOut);// 总超时：5000ms（5秒）TickType_t xRemaining = pdMS_TO_TICKS(5000);BaseType_t xSuccess = pdTRUE;// 步骤1：轮询设备Awhile (!deviceA_is_ready()) {if (xTaskCheckForTimeOut(&xTimeOut, &xRemaining) == pdTRUE) {xSuccess = pdFALSE;break;}vTaskDelay(pdMS_TO_TICKS(50));}// 步骤2：轮询设备B（仅当步骤1未超时）if (xSuccess) {while (!deviceB_is_ready()) {if (xTaskCheckForTimeOut(&xTimeOut, &xRemaining) == pdTRUE) {xSuccess = pdFALSE;break;}vTaskDelay(pdMS_TO_TICKS(50));}}// 结果处理if (xSuccess) {USART1_SendString((uint8_t*)"All devices ready!\r\n");} else {USART1_SendString((uint8_t*)"Device poll timed out!\r\n");}vTaskDelay(pdMS_TO_TICKS(2000));}
}

注意事项

1. TimeOut_t 结构体的初始化必须先通过 vTaskSetTimeOutState() 初始化 pxTimeOut 结构体（记录起始 Tick 数），否则 xTaskCheckForTimeOut() 的判断会不准确（可能直接返回超时）。

2. pxRemainingTicks 的双向作用

   • 输入：pxRemainingTicks 指向的变量需初始化为 “总超时 Tick 数”（如 pdMS_TO_TICKS(3000)）；
   • 输出：若未超时，该变量会被更新为 “剩余的超时 Tick 数”（可用于后续判断或延时）。

3. 自动处理 Tick 溢出与 xTaskGetTickCount() 类似，xTaskCheckForTimeOut() 利用无符号整数的模运算特性，即使 Tick 计数器溢出（从 0xFFFFFFFF 到 0），仍能正确计算已流逝时间和剩余时间。

4. 与阻塞超时函数的区别

   • 阻塞超时函数（如 xQueueReceive(xQueue, &data, xTimeout)）：任务在超时期间会被挂起，不占用 CPU；
   • xTaskCheckForTimeOut()：任务在等待期间不会被挂起，可执行其他操作（如轮询、状态更新），但会消耗更多 CPU 时间（适用于需要 “等待 + 并行操作” 的场景）。

5. 超时精度超时判断的精度受系统 Tick 周期限制（configTICK_RATE_HZ）。例如：若 Tick 周期为 1ms（configTICK_RATE_HZ=1000），则最小超时精度为 1ms；实际超时时间可能比设置值多 1 个 Tick 周期（因 Tick 中断触发时机）。

6. 避免频繁调用若在循环中未添加延时（vTaskDelay()），xTaskCheckForTimeOut() 会被高频调用，导致 CPU 占用率过高。建议在循环中添加短暂延时（如 10~100ms），平衡响应速度和 CPU 消耗。

总结

xTaskCheckForTimeOut() 是 FreeRTOS 中用于 非阻塞超时检测 的核心 API，与 vTaskSetTimeOutState() 配合，实现灵活的超时判断。它适用于需要在等待期间执行其他操作的场景（如轮询、状态更新），通过监控 Tick 数变化判断是否超时，并自动处理 Tick 溢出。

使用时需注意：初始化 TimeOut_t 结构体，正确设置总超时时间，理解 pxRemainingTicks 的双向作用，并根据需求平衡 CPU 消耗与响应速度。合理使用该函数可显著提升系统在复杂等待场景下的灵活性。

eTaskConfirmSleepModeStatus

在 FreeRTOS 中，eTaskConfirmSleepModeStatus() 是一个用于 判断系统是否可以安全进入低功耗睡眠模式 的函数。它通常在空闲任务（Idle Task）的钩子函数（vApplicationIdleHook()）中使用，帮助开发者决定是否可以让 MCU 进入低功耗状态（如停止模式、休眠模式等），以减少系统功耗。

函数原型与核心作用

函数原型

eSleepModeStatus eTaskConfirmSleepModeStatus( void );

• 参数：无
• 返回值：eSleepModeStatus 枚举类型，可能的取值如下：
  • eAbortSleep：系统不能进入睡眠模式（存在未阻塞的任务，需要继续调度）；
  • eSleep：系统可以进入睡眠模式（所有用户任务均处于阻塞或挂起状态，仅空闲任务运行）。

核心作用

eTaskConfirmSleepModeStatus() 的核心功能是 检查当前系统中除空闲任务外的所有用户任务是否均处于 “阻塞” 或 “挂起” 状态：

• 若所有用户任务都处于阻塞（eBlocked）或挂起（eSuspended）状态，说明当前没有需要调度的任务，系统可以安全进入低功耗睡眠模式（返回 eSleep）；
• 若存在任何用户任务处于就绪（eReady）或运行（eRunning）状态，说明系统需要继续调度，不能进入睡眠（返回 eAbortSleep）。

使用场景：低功耗模式设计

FreeRTOS 的空闲任务是系统中优先级最低的任务（优先级 0），当所有其他任务都阻塞或挂起时，空闲任务会持续运行。此时可通过 eTaskConfirmSleepModeStatus() 判断是否可以让 MCU 进入低功耗模式，以节省功耗。

典型使用流程如下：

1. 实现空闲任务钩子函数（vApplicationIdleHook()），该函数会在空闲任务运行时被周期性调用；
2. 在钩子函数中调用 eTaskConfirmSleepModeStatus() 检查系统状态；
3. 若返回 eSleep，则执行低功耗模式配置（如关闭外设时钟、进入 STOP 模式等）；
4. 睡眠结束后（如被中断唤醒），系统恢复正常运行，调度器继续工作。

示例代码

以 STM32 进入 STOP 模式（低功耗）为例：

// 空闲任务钩子函数：在空闲时尝试进入低功耗模式
void vApplicationIdleHook( void ) {// 检查系统是否可以进入睡眠模式if (eTaskConfirmSleepModeStatus() == eSleep) {// 1. 准备进入低功耗：关闭非必要外设USART_DeInit(USART1);SPI_I2S_DeInit(SPI1);// 2. 进入 STOP 模式（低功耗），等待中断唤醒PWR_EnterSTOPMode(PWR_Regulator_LowPower, PWR_STOPEntry_WFI);  // WFI：等待中断// 3. 从睡眠唤醒后：恢复系统时钟和外设SystemClock_Config();  // 重新配置系统时钟USART1_Init(115200);   // 恢复串口SPI1_Init();           // 恢复SPI}
}

注意事项

1. 仅在空闲任务钩子中调用eTaskConfirmSleepModeStatus() 设计用于空闲任务的钩子函数（vApplicationIdleHook()），因只有此时系统才可能处于 “所有用户任务阻塞” 的状态。在其他任务中调用该函数没有意义（可能返回错误结果）。

2. 低功耗模式的唤醒源进入睡眠模式前，需确保有有效的唤醒源（如外部中断、定时器中断等），否则系统可能无法唤醒。唤醒后，FreeRTOS 调度器会继续运行，处理唤醒后的任务。

3. 与调度器的配合进入睡眠模式前，无需暂停调度器（vTaskSuspendAll()），因为 eTaskConfirmSleepModeStatus() 已确认所有用户任务均阻塞，此时调度器本身处于 “等待任务就绪” 的状态，睡眠唤醒后调度器可直接恢复工作。

4. 依赖系统配置空闲任务钩子函数 vApplicationIdleHook() 需要在 FreeRTOSConfig.h 中开启以下配置才能生效：

   #define configUSE_IDLE_HOOK 1  // 开启空闲任务钩子
   

5. 睡眠模式的选择具体进入哪种低功耗模式（如 STOP、STANDBY 等）取决于 MCU 型号和应用需求，eTaskConfirmSleepModeStatus() 仅提供 “是否可以睡眠” 的判断，不负责低功耗模式的具体配置（需用户自行实现）。

总结

eTaskConfirmSleepModeStatus() 是 FreeRTOS 中用于 低功耗模式设计 的辅助函数，通过判断系统中用户任务的状态，确定是否可以安全进入睡眠模式。它通常与空闲任务钩子函数配合使用，在系统空闲时触发低功耗操作，显著降低 MCU 的功耗。

使用时需注意：仅在 vApplicationIdleHook() 中调用，确保唤醒源有效，开启 configUSE_IDLE_HOOK 配置，并根据硬件需求实现低功耗模式的具体配置与恢复逻辑