第 2 章 · 原书 22–160 页 · 57 个函数任务与调度器 API
本章是全书最大的一章,覆盖任务本身的创建、删除、延时、挂起、优先级,调度器控制,中断与临界区宏,以及任务通知(task notification)与运行时统计。函数按字母序排列,排序时忽略返回类型前缀(详见第 1 章 1.2 节)。
先理清四个状态,后面每个函数都在它们之间搬运任务:
| 状态 | 含义 | 怎么进入 | 怎么离开 |
|---|---|---|---|
| Running 运行态 | 正在占用 CPU 执行代码的任务。单核上任何时刻只有一个。 | 被调度器选中 | 被更高优先级任务抢占、主动阻塞/挂起、时间片用完 |
| Ready 就绪态 | 万事俱备,只等 CPU。 | 创建、延时到期、事件到来、被恢复 | 被调度器选中 |
| Blocked 阻塞态 | 在等事件或等超时,带超时参数,到期会自动醒。 | 调用带超时的 API(延时、等队列、等信号量、等通知) | 事件到来或超时到期(自动) |
| Suspended 挂起态 | 被完全冻结,不参与调度,也不会自动醒来。 | vTaskSuspend() | 只能由 vTaskResume() / xTaskResumeFromISR() 恢复 |
本章有三组函数特别容易混,记住分界线即可:
- 临界区类:taskENTER_CRITICAL() / taskEXIT_CRITICAL() 在任务里用;带 _FROM_ISR 的在中断里用;taskDISABLE_INTERRUPTS() / taskENABLE_INTERRUPTS() 不能嵌套,能不用就不用。
- 挂起类:vTaskSuspend() 冻结的是“某个任务”;vTaskSuspendAll() 冻结的是“调度器”(所有任务都不再切换,但中断照常)。
- 通知类:xTaskNotify() 系列是“带数据的定向事件”,比信号量快、省 RAM,但只能一对一;对等的信号量语义用 xTaskNotifyGive() / ulTaskNotifyTake() 这一对。
本章所有 *FromISR 版本的函数都遵循同一条铁律:pxHigherPriorityTaskWoken 必须先初始化为 pdFALSE,并必须在中断退出前交给 portYIELD_FROM_ISR() 处理。漏掉这一步,被唤醒的高优先级任务要等到下一次节拍中断才可能运行,实时性直接崩掉。
下面按原书顺序逐条说明。每条的“注意”部分保留了原书对该函数启用条件(INCLUDE_ 宏 / config 宏)的说明,配置不满足时这些函数不会被编译进来。
2.1portSWITCH_TO_USER_MODE()
void portSWITCH_TO_USER_MODE( void );
说明
该函数只对 FreeRTOS 的 MPU 移植版本有效,即那些使用了内存保护单元(Memory Protection Unit)的移植,属于高级用法。
受限任务(MPU restricted task)由 xTaskCreateRestricted() 创建,创建时的参数决定该任务是 User(非特权)模式还是 Supervisor(特权)模式。一个 Supervisor 模式的任务调用 portSWITCH_TO_USER_MODE() 之后,就会把自己降为 User 模式任务,从此无法再访问受 MPU 保护的内核数据与其它任务的存储区。
注意
- 该宏没有反向操作:不能把一个 User 模式任务再提回 Supervisor 模式。要换模式只能删掉任务重新创建。
2.2vTaskAllocateMPURegions()
void vTaskAllocateMPURegions( TaskHandle_t xTaskToModify,
const MemoryRegion_t * const xRegions );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTaskToModify | in | 被修改的受限任务句柄(即要获得 xRegions 所定义存储区访问权限的那个任务)。句柄由 xTaskCreateRestricted() 的 pxCreatedTask 参数取得。传 NULL 表示修改调用者自己。 |
| xRegions | in | MemoryRegion_t 结构数组。数组长度由移植版本相关的常量 portNUM_CONFIGURABLE_REGIONS 决定,Cortex-M3 移植中该常量为 3。数组中的每个元素为任务定义一块 MPU 存储区。 |
说明
为 MPU 受限任务定义一组内存保护单元(MPU)区域。MPU 存储区可以在任务创建时(xTaskCreateRestricted())分配,之后在运行期用本函数重新定义或重新分配。
MemoryRegion_t 的定义如下(原书 Listing 3):
typedef struct xMEMORY_REGION
{
void *pvBaseAddress;
unsigned long ulLengthInBytes;
unsigned long ulParameters;
} MemoryRegion_t;
注意
- pvBaseAddress 与 ulLengthInBytes 分别是存储区起始地址与长度,二者必须同时满足 MPU 对容量与对齐的要求——尤其是容量与对齐必须等于同一个 2 的幂。
- ulParameters 定义访问权限,可以按位或组合:portMPU_REGION_READ_WRITE、portMPU_REGION_PRIVILEGED_READ_ONLY、portMPU_REGION_READ_ONLY、portMPU_REGION_PRIVILEGED_READ_WRITE、portMPU_REGION_CACHEABLE_BUFFERABLE、portMPU_REGION_EXECUTE_NEVER。
2.3xTaskAbortDelay()
BaseType_t xTaskAbortDelay( TaskHandle_t xTask );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTask | in | 要被强制移出阻塞态的任务句柄。句柄可由 xTaskCreate() 的 pxCreatedTask 参数取得,或保存 xTaskCreateStatic() 的返回值,或用任务名调用 xTaskGetHandle() 取得。 |
返回值
任务确实从阻塞态被移出则返回 pdPASS;如果任务本来就不在阻塞态(因此没有被移出)则返回 pdFAIL。
说明
凡带超时参数的 API 都可能让调用任务进入阻塞态:任务要么单纯等待超时到期,要么一边等待事件一边等待超时,事件到来或超时到期后任务会自动回到就绪态。
- 任务调用 vTaskDelay() 后进入阻塞态,直到参数指定的节拍数过去才回到就绪态;
- 任务在通知值为 0 时调用 ulTaskNotifyTake(),会进入阻塞态,直到收到通知或超时到期。
注意
- xTaskAbortDelay() 的作用是:即使任务等待的事件还没发生、超时也还没到期,也能把它从阻塞态强行拉回就绪态。
- 任务处于阻塞态时对调度器不可见,也不占用任何处理时间,因此本函数不会“打断”正在运行的任务。
- INCLUDE_xTaskAbortDelay 必须在 FreeRTOSConfig.h 中置 1,本函数才可用。
2.4xTaskCallApplicationTaskHook()
BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameters );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTask | in | 要调用其钩子函数的任务句柄。传 NULL 表示调用者自己的钩子函数。 |
| pvParameters | in | 传给钩子函数自身的参数。类型为 void*,因此可以按需强制转换成任意类型。 |
返回值
任务设置了钩子函数(即 task tag 非空)时,返回钩子函数的返回值;任务没有设置钩子函数时返回 pdFAIL。
说明
本函数属于高级用法。vTaskSetApplicationTaskTag() 可以给任务附加一个“标签”(tag)值,标签的含义由应用自己定义,内核通常不会去读它。
有一种特殊用法:把标签值设为一个“任务钩子”(或回调)函数的地址。此后用 xTaskCallApplicationTaskHook() 就能显式地调用这个钩子。钩子函数的原型必须与下面一致(原书 Listing 8):
static BaseType_t prvExampleTaskHook( void * pvParameter )
{
/* 这里做你想做的事,例如输出调试 trace。 */
return 0;
}
注意
- 钩子函数原型固定,返回 BaseType_t,参数为 void*。
- 是否设置钩子由应用自行约定,内核不会主动调用;要自己调用时才用本函数。
2.5xTaskCatchUpTicks()
BaseType_t xTaskCatchUpTicks( TickType_t xTicksToCatchUp );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTicksToCatchUp | in | 由于关中断而漏掉的节拍中断个数。该值不会自动计算,必须由应用自己算出。 |
返回值
把节拍计数前移之后,如果有任务因此离开阻塞态并触发了一次上下文切换,返回 pdTrue;否则返回 pdFalse。
说明
当应用长时间关闭中断、导致节拍中断被漏掉时,用本函数把节拍计数(tick count)补正过来。
它与 vTaskStepTick() 的区别在于:vTaskStepTick() 只是安静地把计数加上去,而 xTaskCatchUpTicks() 在把计数前移的过程中,可能越过某个任务本应解除阻塞的时刻,从而让任务真正被唤醒。
注意
- 漏掉的节拍数必须由应用根据实际关闭中断的时长换算,内核不会替你估算。
- 补正过程若引起任务解除阻塞,函数返回 pdTrue,调用方一般紧接着要处理一次上下文切换。
2.6xTaskCheckForTimeOut()
BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut,
TickType_t * const pxTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxTimeOut | in-out | 指向记录超时判定所需信息(进入阻塞时的时间点、剩余时间)的结构。该结构需先用 vTaskSetTimeOutState() 初始化。 |
| pxTicksToWait | in-out | 用来回传“调整后的剩余阻塞时间”:扣除已经阻塞掉的时间之后还剩多少。若返回 pdTRUE,说明剩余时间为 0,即已超时。 |
返回值
已超时返回 pdTRUE(此时剩余阻塞时间为 0);尚未超时返回 pdFALSE(pxTicksToWait 为剩余时间)。
说明
任务可以进入阻塞态等待某个事件,通常不会无限等待,而是带一个超时。若超时先到,任务就会被移出阻塞态。
问题在于:如果任务在等待同一个事件的过程中反复进出阻塞态(例如被信号量、队列多次唤醒又继续等),那么每次都要用同一个超时基准,才能保证总等待时间不超过最初指定的值。本函数就是为此而设的,属于高级用法:它判断相对于 pxTimeOut 记录的时间点是否已经超时,并把 pxTicksToWait 改成“还剩多少”。
注意
- 典型用法是在一个循环里等待事件:每轮重新计算剩余时间,返回 pdTRUE 就跳出循环。
- pxTimeOut 必须由 vTaskSetTimeOutState() 初始化,且只在一次完整的等待过程中有效。
2.7xTaskCreate()
BaseType_t xTaskCreate( TaskFunction_t pvTaskCode,
const char * const pcName,
unsigned short usStackDepth,
void *pvParameters,
UBaseType_t uxPriority,
TaskHandle_t *pxCreatedTask );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pvTaskCode | in | 任务函数指针(本质上就是函数名)。任务函数是一个永不返回的 C 函数,通常写成死循环 for(;;)。原型必须为 void vTaskCode( void *pvParameters )。 |
| pcName | in | 任务的描述名。主要用于调试,也可在 xTaskGetHandle() 中用名字换取句柄。最大长度由 configMAX_TASK_NAME_LEN 决定(含结尾的 NULL),超长会被截断。 |
| usStackDepth | in | 任务栈的深度。注意单位是“字”而不是字节:在 32 位 MCU 上 1 字 = 4 字节,因此 usStackDepth = 128 表示 512 字节栈。栈里同时存放任务局部变量、返回地址与寄存器现场。 |
| pvParameters | in | 传给任务函数的参数,类型 void*。可以是任意值的地址,也可以是强制转换后的整数。 |
| uxPriority | in | 任务优先级,0 为最低(空闲任务的优先级)。数值越大优先级越高,最大合法值为 configMAX_PRIORITIES - 1,超过会被静默截到最大值。 |
| pxCreatedTask | out | 用于回传新任务的句柄,之后可用它修改优先级、删除任务等。用不到时传 NULL 即可。 |
返回值
pdPASS 表示任务创建成功;errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY 表示堆内存不足,无法为任务控制块(TCB)与栈分配空间。
说明
创建一个任务实例。每个任务都需要 RAM 存放任务状态(任务控制块 TCB)和栈。用 xTaskCreate() 创建时,这块 RAM 由 FreeRTOS 堆自动分配;用 xTaskCreateStatic() 创建时,RAM 由应用提供,因此多两个参数,但可以在编译期静态确定内存用量。
新创建的任务初始处于就绪态;如果它是当前优先级最高的就绪任务,会立即抢占成为运行态任务。任务既可以在调度器启动之前创建,也可以在启动之后创建。
注意
- configSUPPORT_DYNAMIC_ALLOCATION 必须置 1(或干脆不定义),本函数才可用。
- 堆总量由 FreeRTOSConfig.h 中的 configTOTAL_HEAP_SIZE 决定(heap_1/2/4)。分配失败时可挂接 vApplicationMallocFailedHook() 回调捕获,剩余堆量可用 xPortGetFreeHeapSize() 查询。
- 栈深度按“字”计,这是初学者最常见的踩坑点:写成字节会导致栈溢出而不报错。
典型用法
void vTaskCode( void * pvParameters )
{
for( ;; )
{
/* 任务主体 */
}
}
TaskHandle_t xHandle = NULL;
xTaskCreate( vTaskCode, /* 任务函数 */
"NAME", /* 任务名(调试用) */
configMINIMAL_STACK_SIZE, /* 栈深度,单位:字 */
NULL, /* 传给任务的参数 */
tskIDLE_PRIORITY, /* 优先级 */
&xHandle ); /* 回传的句柄,可传 NULL */
2.8xTaskCreateStatic()
TaskHandle_t xTaskCreateStatic( TaskFunction_t pvTaskCode,
const char * const pcName,
uint32_t ulStackDepth,
void *pvParameters,
UBaseType_t uxPriority,
StackType_t *puxStackBuffer,
StaticTask_t *pxTaskBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pvTaskCode | in | 任务函数指针,要求同 xTaskCreate()。 |
| pcName | in | 任务名,要求同 xTaskCreate()。 |
| ulStackDepth | in | 栈深度,单位为“字”。因为栈由应用提供,这里只用于初始化栈结构。 |
| pvParameters | in | 传给任务函数的参数。 |
| uxPriority | in | 任务优先级,超过 configMAX_PRIORITIES - 1 会被截断。 |
| puxStackBuffer | in | 应用提供的栈数组,类型 StackType_t[],长度不得小于 ulStackDepth。 |
| pxTaskBuffer | out | 应用提供的 StaticTask_t 结构,用作该任务的 TCB 存储区。 |
返回值
创建成功返回任务句柄(非 NULL);若 puxStackBuffer 或 pxTaskBuffer 为 NULL,则返回 NULL。
说明
用静态分配方式创建任务:栈数组与 TCB 结构由应用自己定义(通常是全局或 static 变量),内核不再调用 pvPortMalloc()。这是唯一一种在编译期就能确定任务内存占用的创建方式,适合不许动态分配、要求内存可审计的工程。
除此之外,行为与 xTaskCreate() 一致:新任务进入就绪态,可能立即抢占。
注意
- configSUPPORT_STATIC_ALLOCATION 必须置 1,本函数才可用。
- 启用静态分配后还要实现 vApplicationGetIdleTaskMemory()(以及启用定时器时的 vApplicationGetTimerTaskMemory()),因为空闲任务与定时器服务任务的 TCB/栈也必须由应用提供。
- 栈缓冲区通常声明为 static StackType_t xStack[ STACK_SIZE ];,TCB 声明为 static StaticTask_t xTCB; 并保持生命周期覆盖整个任务。
典型用法
static StackType_t xTaskStack[ configMINIMAL_STACK_SIZE ];
static StaticTask_t xTaskTCB;
TaskHandle_t h = xTaskCreateStatic( vTaskCode, "STATIC",
configMINIMAL_STACK_SIZE, NULL,
tskIDLE_PRIORITY,
xTaskStack, &xTaskTCB );
2.9xTaskCreateRestricted()
BaseType_t xTaskCreateRestricted( TaskParameters_t *pxTaskDefinition,
TaskHandle_t *pxCreatedTask );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxTaskDefinition | in | 指向任务定义结构 TaskParameters_t 的指针,该结构把任务函数、名字、栈、参数、优先级、栈缓冲区以及 MPU 存储区一次性描述清楚。 |
| pxCreatedTask | out | 回传新任务句柄,用不到可传 NULL。 |
返回值
pdPASS 表示创建成功;其它值表示无法按指定参数创建,通常是堆内存不足。
说明
创建一个受 MPU 限制的任务(仅适用于 MPU 移植版本)。与 xTaskCreate() 相比,本函数允许在创建的同时为任务指定若干 MPU 存储区,从而实现“任务只能访问自己的数据”的隔离。新任务进入就绪态,若无更高优先级任务可运行则立即成为运行态。
任务定义结构 TaskParameters_t 如下(原书 Listing 18):
typedef struct xTASK_PARAMETERS
{
TaskFunction_t pvTaskCode;
const signed char * const pcName;
unsigned short usStackDepth;
void *pvParameters;
UBaseType_t uxPriority;
portSTACK_TYPE *puxStackBuffer;
MemoryRegion_t xRegions[ portNUM_CONFIGURABLE_REGIONS ];
} TaskParameters_t;
注意
- 调用者应为特权模式任务,否则无法创建受限任务。
- xRegions 数组的元素个数由 portNUM_CONFIGURABLE_REGIONS 决定(Cortex-M3 为 3)。
2.10vTaskDelay()
void vTaskDelay( TickType_t xTicksToDelay );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTicksToDelay | in | 调用任务在阻塞态中停留的节拍中断个数。例如节拍计数为 10000 时调用 vTaskDelay(100),任务立即进入阻塞态,直到计数到 10100 才回到就绪态。可用 pdMS_TO_TICKS() 把毫秒换算为节拍。 |
说明
把调用本函数的任务放入阻塞态,持续固定的节拍数。
特别注意:延时节拍数为 0 不会进入阻塞态,而是让调用任务向同优先级的其它就绪任务让出 CPU,等价于调用 taskYIELD()。
从调用 vTaskDelay() 到下一个节拍中断到来之间的剩余时间,会被算作完整的一个节拍,因此延时的最小分辨率在最坏情况下是一个完整的节拍周期。
注意
- INCLUDE_vTaskDelay 必须置 1。
- 阻塞期间任务不占用 CPU,比空循环等待省电、也利于低优先级任务运行。
典型用法
/* 延时 500 ms(需知道节拍频率,configTICK_RATE_HZ) */ vTaskDelay( pdMS_TO_TICKS( 500 ) );
2.11vTaskDelayUntil()
void vTaskDelayUntil( TickType_t *pxPreviousWakeTime, TickType_t xTimeIncrement );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxPreviousWakeTime | in-out | 指向“上一次醒来的时刻”。该变量在函数内部自动更新,应用除首次初始化外不要手动改它(初始化时通常赋值为 xTaskGetTickCount() 的返回值)。 |
| xTimeIncrement | in | 周期长度,单位为节拍。它决定任务固定的执行频率,可用 pdMS_TO_TICKS() 由毫秒换算。 |
说明
把调用任务放入阻塞态,直到到达一个绝对时刻。周期性任务用它来获得恒定的执行频率。
它与 vTaskDelay() 的差别在于时间基准:vTaskDelay() 的唤醒时刻是“调用时刻 + 延时”,会累积任务执行时间带来的抖动;vTaskDelayUntil() 的唤醒时刻是绝对的,不管任务本次执行花了多久,下一次唤醒时间点都固定。
注意
- INCLUDE_vTaskDelayUntil 必须置 1。
- 如果某次任务执行时间超过了 xTimeIncrement,函数会立即返回(相当于超期),并给出警告性的行为;此时周期已经无法保持,需要重新设计任务负载。
- pxPreviousWakeTime 必须一直有效(通常是任务内的局部或静态变量,任务栈上的就绪变量即可,但要求地址稳定)。
典型用法
void vPeriodicTask( void *pvParameters )
{
TickType_t xLastWakeTime = xTaskGetTickCount(); /* 必须先初始化 */
const TickType_t xPeriod = pdMS_TO_TICKS( 10 );
for( ;; )
{
/* 任务主体 */
vTaskDelayUntil( &xLastWakeTime, xPeriod ); /* 绝对时间唤醒 */
}
}
2.12vTaskDelete()
void vTaskDelete( TaskHandle_t pxTask );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxTask | in | 要删除的任务句柄。传 NULL 表示删除调用者自己。 |
说明
删除一个此前由 xTaskCreate() 或 xTaskCreateStatic() 创建的任务实例。任务被删除后就不复存在,也不会再进入运行态;已删除任务的句柄不可再使用。
删除任务时,释放其栈与 TCB 占用的内存是空闲任务的职责。因此只要用到 vTaskDelete(),就必须保证空闲任务能分到处理时间(即空闲任务必须能进入运行态)。
内核只会自动释放它自己分配给任务的内存。应用分配给任务的其它内存或资源(例如自己 malloc 的缓冲区、打开的文件、占用的外设),必须在删除前由应用显式释放。
注意
- 删除自身(传 NULL)后不会返回,之后的代码不会执行。
- 大量频繁创建/删除任务会让空闲任务成为内存回收的瓶颈,必要时可改用静态创建或任务复用(task pool)方案。
典型用法
/* 删除指定任务 */ vTaskDelete( xHandle ); /* 删除自己 —— 后面的语句不会执行 */ vTaskDelete( NULL );
2.13taskDISABLE_INTERRUPTS()
void taskDISABLE_INTERRUPTS( void );
说明
关闭中断。具体行为取决于移植版本:
- 如果移植版本不使用 configMAX_SYSCALL_INTERRUPT_PRIORITY(某些移植叫 configMAX_API_CALL_INTERRUPT_PRIORITY),调用后会全局关闭中断。
- 如果使用了 configMAX_SYSCALL_INTERRUPT_PRIORITY,则只会关闭“优先级不高于该常量”的中断,优先级更高的中断仍然有效——这是为了保证高优先级中断的实时性不被内核影响。
/* 关中断(不嵌套,慎用) */ taskDISABLE_INTERRUPTS(); /* ... 极短的临界代码 ... */ taskENABLE_INTERRUPTS();
注意
- configMAX_SYSCALL_INTERRUPT_PRIORITY 通常定义在 FreeRTOSConfig.h 中。
- taskDISABLE_INTERRUPTS() 与 taskENABLE_INTERRUPTS() 不支持嵌套:连调两次关闭,只需一次开启就会把中断打开。需要嵌套语义时应改用 taskENTER_CRITICAL() / taskEXIT_CRITICAL()。
- 部分 FreeRTOS API 内部会使用临界区,并在嵌套计数为 0 时重新打开中断——即使你之前手动关过中断。因此在关闭中断的状态下不要调用 FreeRTOS API。
2.14taskENABLE_INTERRUPTS()
void taskENABLE_INTERRUPTS( void );
说明
打开所有优先级的中断,即撤销 taskDISABLE_INTERRUPTS() 的效果。
同样不支持嵌套:两次 taskDISABLE_INTERRUPTS() 之后一次 taskENABLE_INTERRUPTS() 就会打开中断。需要嵌套时用 taskENTER_CRITICAL() / taskEXIT_CRITICAL()。
注意
- 在已经关闭中断的情况下调用 FreeRTOS API 是不推荐的:API 内部的临界区可能在计数为 0 时把中断重新打开。
2.15taskENTER_CRITICAL()
void taskENTER_CRITICAL( void );
说明
进入临界区;与之配对的是 taskEXIT_CRITICAL(),用于退出临界区。两者构成一个“可嵌套”的临界区实现:内部维护一个嵌套计数,只有最外层退出时才真正恢复中断。
临界区的本质是关闭中断——要么全局关闭,要么关闭到 configMAX_SYSCALL_INTERRUPT_PRIORITY 指定的优先级为止(视移植版本而定)。
taskENTER_CRITICAL(); /* 临界代码:不要调用会阻塞、会引起切换的 API */ taskEXIT_CRITICAL();
注意
- taskENTER_CRITICAL() 不得在中断服务程序内调用;中断里请用 taskENTER_CRITICAL_FROM_ISR()。
- 临界区越长,中断延迟越大,实时性越差。临界区里只做几条指令能完成的事,绝不要在里面延时、等待或调用可能阻塞的 API。
- 临界区可以嵌套,但配对必须严格成对;漏掉一次 taskEXIT_CRITICAL() 会导致中断永远关闭。
2.16taskENTER_CRITICAL_FROM_ISR()
UBaseType_t taskENTER_CRITICAL_FROM_ISR( void );
返回值
返回调用时刻的中断屏蔽状态(旧的中断优先级掩码)。这个返回值必须保存下来,传给配对的 taskEXIT_CRITICAL_FROM_ISR(),否则退出时无法正确恢复中断状态。
说明
taskENTER_CRITICAL() 的中断安全版本,供中断服务程序(ISR)使用。在 ISR 中进入临界区调用它,退出临界区调用 taskEXIT_CRITICAL_FROM_ISR()。
实现方式与任务版一致:关闭中断,或关闭到 configMAX_SYSCALL_INTERRUPT_PRIORITY 指定的优先级为止。区别在于中断里不能依赖嵌套计数,所以用“保存—恢复”掩码的方式保证可重入。
注意
- 必须成对使用,并且要把 enter 的返回值原样交给 exit。
- ISR 中长时间关闭中断会直接影响中断响应延迟,临界区应尽可能短。
典型用法
void vAnInterruptHandler( void )
{
UBaseType_t uxSavedInterruptStatus;
uxSavedInterruptStatus = taskENTER_CRITICAL_FROM_ISR();
/* 临界代码 */
taskEXIT_CRITICAL_FROM_ISR( uxSavedInterruptStatus );
}
2.17taskEXIT_CRITICAL()
void taskEXIT_CRITICAL( void );
说明
退出由 taskENTER_CRITICAL() 进入的临界区。内部把嵌套计数减 1,减到 0 时才真正恢复进入临界区之前的中断使能状态。
注意
- 不得在中断服务程序中调用;ISR 中请用 taskEXIT_CRITICAL_FROM_ISR()。
- 与 taskENTER_CRITICAL() 次数必须严格一致。多退一次会让内核的嵌套计数错乱,后续临界区失效。
2.18taskEXIT_CRITICAL_FROM_ISR()
void taskEXIT_CRITICAL_FROM_ISR( UBaseType_t uxSavedInterruptStatus );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| uxSavedInterruptStatus | in | 必须使用配对的 taskENTER_CRITICAL_FROM_ISR() 返回的那个值。 |
说明
退出由 taskENTER_CRITICAL_FROM_ISR() 进入的临界区,并按 uxSavedInterruptStatus 恢复中断屏蔽状态。
注意
- 恢复的是“进入临界区之前”的状态,而不是无条件打开中断,因此 ISR 里嵌套调用也是安全的。
2.19xTaskGetApplicationTaskTag()
TaskHookFunction_t xTaskGetApplicationTaskTag( TaskHandle_t xTask );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTask | in | 要查询的任务句柄。传 NULL 表示查询调用者自己的标签值。 |
返回值
被查询任务的“标签”(tag)值,类型 TaskHookFunction_t(本质是一个函数指针类型)。
说明
返回与任务关联的标签值。标签的含义与用途完全由应用定义,内核正常情况下不会访问它。本函数属于高级用法。
标签值可以存放一个函数指针:此时它就相当于“给任务挂了个回调”,可用 xTaskCallApplicationTaskHook() 调用。常见的用法是配合 traceTASK_SWITCHED_IN() 宏做执行轨迹(trace)记录。
注意
- 标签值与任务通知(task notification)是两套完全独立的东西,不要混淆:通知值是 32 位整数并由内核管理,标签值由应用完全支配。
- 标签值的类型是函数指针,若要存别的类型需要强制转换。
2.20xTaskGetCurrentTaskHandle()
TaskHandle_t xTaskGetCurrentTaskHandle( void );
返回值
当前处于运行态的任务(也就是调用者自己)的句柄。
说明
返回正在运行的任务的句柄。因为只有运行态的任务能执行代码,所以返回值一定是调用者自己的句柄。
典型用途:把“我自己的句柄”传给别人,让别的任务/中断以后能通知我、删除我或修改我的优先级。
注意
- INCLUDE_xTaskGetCurrentTaskHandle 必须置 1。
- 中断里不能调用(中断不属于任何任务)。
典型用法
TaskHandle_t xSelf = xTaskGetCurrentTaskHandle(); /* 例如交给中断处理程序,让它在事件到来时通知本任务 */ xTaskToNotify = xSelf;
2.21xTaskGetIdleTaskHandle()
TaskHandle_t xTaskGetIdleTaskHandle( void );
返回值
空闲任务的句柄。
说明
返回空闲任务(Idle task)的句柄。空闲任务在调度器启动时由内核自动创建,优先级为 0,作用是“没有别的任务可运行时”占用 CPU,并负责回收被删除任务的内存。
若配置了 configUSE_IDLE_HOOK,可以在空闲钩子里调用本函数做统计或低功耗处理。
注意
- INCLUDE_xTaskGetIdleTaskHandle 必须置 1。
- 每个核(在 SMP 移植中)各有一个空闲任务,本函数返回当前核的空闲任务句柄。
2.22xTaskGetHandle()
TaskHandle_t xTaskGetHandle( const char *pcNameToQuery );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pcNameToQuery | in | 要查询的任务名,标准以 NULL 结尾的 C 字符串。名字必须与创建时的 pcName 完全一致。 |
返回值
找到同名任务则返回其句柄;没有匹配的任务则返回 NULL。
说明
任务在创建时(xTaskCreate() / xTaskCreateStatic())的 pcName 参数给了它一个人类可读的名字,本函数就是拿这个名字反查任务句柄。
它只是“名字到句柄”的查表,不创建任务,也不保证唯一。
注意
- 本函数执行时间相对较长,建议每个任务名只查一次,把结果存起来复用。
- 如果有多个任务同名,函数行为未定义。
- INCLUDE_xTaskGetHandle 必须置 1。
典型用法
TaskHandle_t xHandle = xTaskGetHandle( "LOGGER" );
if( xHandle != NULL ) { vTaskPrioritySet( xHandle, 3 ); }
2.23uxTaskGetNumberOfTasks()
UBaseType_t uxTaskGetNumberOfTasks( void );
返回值
调用时刻受 FreeRTOS 内核管理的任务总数,包含挂起态、阻塞态、就绪态任务,也包含空闲任务与定时器服务任务。
说明
返回当前内核中的任务总数。用途之一是:调用 uxTaskGetSystemState() 之前先用它算出需要多大的 TaskStatus_t 数组。
注意
- 返回值包含空闲任务,所以即使你一个任务都没创建,返回值也≥1(启用定时器时≥2)。
- 这是瞬时快照,函数返回后任务数可能立即变化。
2.24vTaskGetRunTimeStats()
void vTaskGetRunTimeStats( char *pcWriteBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pcWriteBuffer | in | 用于接收格式化表格的字符缓冲区。函数不做任何越界检查,缓冲区必须足够大。 |
说明
把 FreeRTOS 收集到的任务运行时间统计格式化成人类可读的表格,写入 pcWriteBuffer。表格包含三列:任务名、该任务占用的绝对时间、占总运行时间的百分比。
原始数据来自 xTaskGetSystemState(),本函数只是排版。它是为了方便而提供的工具函数,不属于内核本体。
原书 Figure 1 给出了一张典型的输出表:
Task Abs Time % Time ---------------------------------------- IDLE 2580501 99% Tmr Svc 0 0% DEMO 0 0%
注意
- configGENERATE_RUN_TIME_STATS 与 configUSE_STATS_FORMATTING_FUNCTIONS 必须都置 1。
- 还需要实现两个宏:portCONFIGURE_TIMER_FOR_RUN_TIME_STATS() 与 portGET_RUN_TIME_COUNTER_VALUE(),后者通常用一个比节拍中断频率高 10~100 倍的硬件定时器提供计数。
- 百分比是整数,耗时为 0 的任务会显示 0%,并非统计失败。
2.25xTaskGetSchedulerState()
BaseType_t xTaskGetSchedulerState( void );
返回值
返回下列三个常量之一:taskSCHEDULER_NOT_STARTED(调度器尚未启动,仅在 vTaskStartScheduler() 之前调用本函数时返回)、taskSCHEDULER_RUNNING(调度器已启动且正常运行)、taskSCHEDULER_SUSPENDED(调度器已启动,但被 vTaskSuspendAll() 挂起)。
说明
查询调度器当前的状态。常用于断言式检查:例如某段代码只在调度器启动后才能执行时,先判断状态再操作。
注意
- INCLUDE_xTaskGetSchedulerState 必须置 1。
- 返回值是“那一刻”的快照,多任务环境下不要假设它在下一个语句时仍然成立。
2.26uxTaskGetStackHighWaterMark()
UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTask | in | 要查询栈水位的任务句柄。传 NULL 表示查询调用者自己。 |
返回值
该任务自创建以来剩余栈空间的最小值(单位为“字”,不是字节)。这个值越接近 0,说明栈越接近溢出。
说明
每个任务都有自己的栈,大小在创建时确定。任务执行、中断嵌套都会消耗栈。本函数查询的是“历史最低水位”,即栈曾经用到的最深处距离栈底还剩多少。
它回答的是工程上最要紧的问题:这个任务的栈到底该开多大?经验做法是先给一个较大的栈,跑完所有最坏路径后看水位,再据此收小。
注意
- 返回值单位是字。32 位平台上 ×4 才是字节数。
- 本函数执行时间较长,建议只在测试/调试版本中使用。
- INCLUDE_uxTaskGetStackHighWaterMark 必须置 1。
- 注意:它统计的是“历史上最小值”。若测试时没跑到最坏路径,测出来的数字会偏大,栈仍可能在现场溢出。
典型用法
UBaseType_t uxHighWater = uxTaskGetStackHighWaterMark( NULL ); printf( "剩余栈:%u 字(约 %u 字节)\n", uxHighWater, uxHighWater * sizeof(StackType_t) );
2.27eTaskGetState()
eTaskState eTaskGetState( TaskHandle_t pxTask );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxTask | in | 要查询的任务句柄。 |
返回值
返回该任务在调用时刻的状态枚举值,见下表。
说明
以枚举类型返回任务当前所处的状态。相比之下,uxTaskGetSystemState() / vTaskGetTaskInfo() 能一次性拿到更多信息;若只关心状态,用本函数更轻。
| 返回值 | 含义 |
|---|---|
| eRunning | 运行态:任务正在执行(只有调用者自己可能返回它) |
| eReady | 就绪态:可以运行,但当前有更高优先级任务在跑 |
| eBlocked | 阻塞态:等待事件或等待超时 |
| eSuspended | 挂起态:被 vTaskSuspend() 挂起,或创建后尚未启动调度器 |
| eDeleted | 待删除:任务已被删除,但其内存尚未被空闲任务回收 |
| eInvalid | 无效:句柄无效(部分版本返回) |
注意
- INCLUDE_eTaskGetState 必须置 1。
- 当任务被删除但内存尚未回收时,句柄仍可能“有效”,此时会返回 eDeleted;用它去调用别的 API 是危险的。
2.28uxTaskGetSystemState()
UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray,
const UBaseType_t uxArraySize,
unsigned long * const pulTotalRunTime );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxTaskStatusArray | out | TaskStatus_t 数组,函数为系统中的每个任务填入一项。数组元素个数不得少于任务总数,任务总数可用 uxTaskGetNumberOfTasks() 取得。 |
| uxArraySize | in | 数组大小,单位是元素个数(而不是字节数)。 |
| pulTotalRunTime | out | 回传自调度器启动以来的总运行时间,单位由运行时间统计时钟决定。若 configGENERATE_RUN_TIME_STATS 为 0 则此参数无意义,可传 NULL。 |
返回值
实际填充的 TaskStatus_t 结构个数。正常情况下应等于 uxTaskGetNumberOfTasks() 的返回值,如果传入的数组太小则会小于该值。
说明
为系统中的每个任务填充一个 TaskStatus_t 结构,其中含有任务句柄、名字、优先级、状态、累计运行时间等信息(结构定义见下)。这是任务级调试/监控的数据源,vTaskList() 与 vTaskGetRunTimeStats() 的输出都由它派生。
typedef struct xTASK_STATUS
{
TaskHandle_t xHandle; /* 任务句柄 */
const signed char *pcTaskName; /* 任务名(注意:任务已被删除时该指针失效) */
UBaseType_t xTaskNumber; /* 任务唯一编号 */
eTaskState eCurrentState; /* 当前状态 */
UBaseType_t uxCurrentPriority; /* 当前优先级(可能因继承而提高) */
UBaseType_t uxBasePriority; /* 基础优先级(仅在 configUSE_MUTEXES 为 1 时有效) */
unsigned long ulRunTimeCounter; /* 累计运行时间(仅在 configGENERATE_RUN_TIME_STATS 为 1 时有效) */
StackType_t *pxStackBase; /* 栈基址(栈最低地址) */
unsigned short usStackHighWaterMark; /* 栈水位(最小值) */
} TaskStatus_t;
注意
- configUSE_TRACE_FACILITY 必须置 1,本函数才可用。
- 它是调试用途:执行期间调度器会长时间处于挂起状态,实时性会受影响。
- 只想查单个任务时用 vTaskGetTaskInfo(),开销小得多。
2.29vTaskGetTaskInfo()
void vTaskGetTaskInfo( TaskHandle_t xTask,
TaskStatus_t *pxTaskStatus,
BaseType_t xGetFreeStackSpace,
eTaskState eState );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTask | in | 要查询的任务句柄。 |
| pxTaskStatus | out | 指向 TaskStatus_t 变量,由函数填充。 |
| xGetFreeStackSpace | in | 是否计算栈水位。计算需要遍历整个栈,比较耗时;不需要时传 pdFALSE 可显著加快。 |
| eState | in | 要写入结构中的状态值。通常传 eTaskGetState( xTask ) 的结果,避免函数内部重复查询。 |
说明
为单个任务填充 TaskStatus_t 结构。与 uxTaskGetSystemState() 相比,它不遍历所有任务,适合在运行时监控某一个关键任务。
注意
- configUSE_TRACE_FACILITY 必须置 1。
- 函数的最后两个参数是为性能而设的开关:不需要栈水位就传 pdFALSE,状态已知就直接把自己算出的状态传进来。
2.30pvTaskGetThreadLocalStoragePointer()
void *pvTaskGetThreadLocalStoragePointer( TaskHandle_t xTaskToQuery,
BaseType_t xIndex );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTaskToQuery | in | 要读取其线程局部存储的任务句柄。传 NULL 表示读自己的。 |
| xIndex | in | 线程局部存储数组中的下标,取值范围 0 ~ (configNUM_THREAD_LOCAL_STORAGE_POINTERS - 1)。 |
返回值
从该任务线程局部存储数组的 xIndex 位置读到(并返回)的指针值。
说明
线程局部存储(Thread Local Storage,TLS)让应用把“只属于某个任务”的数据指针存在该任务的 TCB 里。每个任务都有各自的一份指针数组,数组长度由 FreeRTOSConfig.h 中的 configNUM_THREAD_LOCAL_STORAGE_POINTERS 决定。
例如库函数需要“每个任务各自的上下文”时,就用 TLS 存指针,而不用全局变量。
注意
- 必须先调用 vTaskSetThreadLocalStoragePointer() 写入,才读到有意义的值;未写入时初值为 0。
- 数组下标越界不会报错,会读到 TCB 之外的内存,务必自己保证 0 ≤ xIndex < configNUM_THREAD_LOCAL_STORAGE_POINTERS。
- 内存需要自己管理:TLS 只保存指针,不负责分配和释放所指向的对象。
2.31pcTaskGetName()
char * pcTaskGetName( TaskHandle_t xTaskToQuery );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTaskToQuery | in | 要查询的任务句柄。传 NULL 表示查询调用者自己。 |
返回值
指向该任务名字符串的指针(标准以 NULL 结尾的 C 字符串)。
说明
查询任务的人类可读名称。名字是创建任务时(xTaskCreate() / xTaskCreateStatic())通过 pcName 参数设定的。
调试与日志里打印任务名,比打印句柄直观得多;本函数就是为此准备的。
注意
- 返回的是任务内部字符串的指针,不是副本,不要试图修改它,也不要释放它。
- 任务被删除后该指针失效。
2.32xTaskGetTickCount()
TickType_t xTaskGetTickCount( void );
返回值
调用时刻的节拍计数值(tick count)。
说明
节拍计数是调度器启动以来发生的节拍中断总数。本函数返回当前值,也就是内核的“时间刻度”。
典型用途:记录事件发生时间、计算两段代码之间的耗时、给 vTaskDelayUntil() 初始化基准时间。
注意
- 一个节拍代表多长时间,取决于 FreeRTOSConfig.h 中的 configTICK_RATE_HZ。例如 configTICK_RATE_HZ = 1000 时,1 tick = 1 ms。
- 用 pdMS_TO_TICKS() 把毫秒换算成节拍,不要手写换算公式(节拍频率可能不是 1000)。
- 节拍计数会溢出回零(TickType_t 为 32 位时约 49 天 @1kHz),这不影响内核正常工作;但你自己用“结束时间 - 开始时间”算耗时时,要考虑溢出:用无符号减法即可天然正确。
典型用法
TickType_t xStart = xTaskGetTickCount(); /* ... 一段代码 ... */ TickType_t xElapsed = xTaskGetTickCount() - xStart; /* 无符号相减,溢出也正确 */
2.33xTaskGetTickCountFromISR()
TickType_t xTaskGetTickCountFromISR( void );
返回值
调用时刻的节拍计数值。
说明
xTaskGetTickCount() 的中断安全版本,可在中断服务程序中调用。
注意
- 任务里请用 xTaskGetTickCount();ISR 里必须用本函数。
- 若在中断里调用更高层 API 时已经处理过 tick 递增(例如部分移植的 tick hook),注意时序一致性,一般在 ISR 开头取一次时间戳即可。
2.34vTaskList()
void vTaskList( char *pcWriteBuffer );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pcWriteBuffer | in | 用于接收表格文本的缓冲区。函数不做边界检查,缓冲区必须足够大。 |
说明
把调用时刻系统中每个任务的状态整理成人类可读的表格,写入 pcWriteBuffer。原书 Figure 2 给出一张典型输出(任务名、状态、优先级、栈水位、任务编号):
Name State Prio Stack Num --------------------------------------- IDLE R 0 85 3 Tmr Svc R 2 90 4 DEMO B 1 240 2
注意
- configUSE_TRACE_FACILITY 与 configUSE_STATS_FORMATTING_FUNCTIONS 必须都为 1。
- 执行期间会关闭中断,对硬实时应用可能不可接受,建议只在调试版本中使用。
- 它是工具函数,不属于内核本体,原始数据来自 uxTaskGetSystemState()。
2.35xTaskNotify()
BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify,
uint32_t ulValue,
eNotifyAction eAction );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTaskToNotify | in | 被通知的任务句柄。 |
| ulValue | in | 用于更新接收任务通知值的 32 位数据。具体怎么用取决于 eAction。 |
| eAction | in | 通知动作,决定如何更新接收任务的通知值,取值见下表。 |
返回值
当 eAction 为 eSetValueWithoutOverwrite 且接收任务的通知值未被更新时返回 pdFAIL;其它情况一律返回 pdPASS。
说明
每个任务都有一个 32 位通知值,任务创建时初始化为 0。任务通知是一种直接发给某个任务的轻量事件机制:它既能解除接收任务的阻塞,又能顺带更新接收任务的通知值。
与信号量/队列相比,任务通知不需要额外的内核对象,速度更快、占用 RAM 更少;代价是它只能“一对一”定向发送,不能像队列那样缓存多条消息。
xTaskNotify() 提供五种更新方式,由 eAction 选择:
| eAction 取值 | 含义 |
|---|---|
| eNoAction | 只通知(解除阻塞),通知值不变。常用于把通知当作二值信号量使用。 |
| eSetBits | 把 ulValue 中置 1 的位按位或进接收任务的通知值,可实现“事件位”语义。 |
| eIncrement | 把接收任务的通知值加 1,ulValue 被忽略。等价于 xTaskNotifyGive()。 |
| eSetValueWithOverwrite | 用 ulValue 无条件覆盖接收任务的通知值(覆盖式)。 |
| eSetValueWithoutOverwrite | 仅当接收任务当前没有未读通知时才写入 ulValue;否则不写入并返回 pdFAIL。 |
注意
- 若把通知值当作二值/计数信号量使用,请改用更简单的 xTaskNotifyGive(),接收方用 ulTaskNotifyTake()。
- configUSE_TASK_NOTIFICATIONS 默认开启;置 0 可从编译中移除该功能(每个任务可省 8 字节),此时所有 xTaskNotify* API 都不可用。
- 通知不会排队:接收任务未读的通知会被新动作按 eAction 规则覆盖或累加,这与队列不同。
典型用法
/* 把一个数值发给接收任务 */ xTaskNotify( xReceiver, 42, eSetValueWithOverwrite ); /* 只置位 bit3,当作事件标志用 */ xTaskNotify( xReceiver, ( 1 << 3 ), eSetBits );
2.36xTaskNotifyAndQuery()
BaseType_t xTaskNotifyAndQuery( TaskHandle_t xTaskToNotify,
uint32_t ulValue,
eNotifyAction eAction,
uint32_t *pulPreviousNotifyValue );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTaskToNotify | in | 被通知的任务句柄。 |
| ulValue | in | 用于更新接收任务通知值的数据,含义取决于 eAction。 |
| eAction | in | 通知动作,取值同 xTaskNotify()。 |
| pulPreviousNotifyValue | out | 回传接收任务在被更新之前的通知值。不需要时可传 NULL。 |
返回值
同 xTaskNotify():eAction 为 eSetValueWithoutOverwrite 且未更新时返回 pdFAIL,其余返回 pdPASS。
说明
与 xTaskNotify() 相同,只是多了一个出参,把接收任务“更新前的通知值”回传给你。当通知值被当作递增计数器使用时,发送方常常需要知道它原来的值。
注意
- 接收方若正在用 xTaskNotifyWait() 等待通知,则回传的是等待前的值,注意语义。
- 这个“读旧值 + 写新值”是在同一个临界区内完成的,因此是原子的。
2.37xTaskNotifyAndQueryFromISR()
BaseType_t xTaskNotifyAndQueryFromISR( TaskHandle_t xTaskToNotify,
uint32_t ulValue,
eNotifyAction eAction,
uint32_t *pulPreviousNotifyValue,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTaskToNotify | in | 被通知的任务句柄。 |
| ulValue | in | 更新通知值所用的数据。 |
| eAction | in | 通知动作,取值同 xTaskNotify()。 |
| pulPreviousNotifyValue | out | 回传更新前的通知值,不需要可传 NULL。 |
| pxHigherPriorityTaskWoken | out | 必须初始化为 pdFALSE。若本次通知解除了一个优先级高于当前任务的阻塞任务,该变量会被置为 pdTRUE,此时中断返回前应请求一次上下文切换(portYIELD_FROM_ISR)。 |
返回值
同 xTaskNotify()。
说明
xTaskNotifyAndQuery() 的中断安全版本,可在 ISR 中调用。
注意
- pxHigherPriorityTaskWoken 必须初始化为 pdFALSE 再传入,且必须在中断返回前处理它的结果,否则被唤醒的高优先级任务要等到下一个节拍才运行。
2.38xTaskNotifyFromISR()
BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify,
uint32_t ulValue,
eNotifyAction eAction,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTaskToNotify | in | 被通知的任务句柄。 |
| ulValue | in | 更新通知值所用的数据。 |
| eAction | in | 通知动作,取值同 xTaskNotify()。 |
| pxHigherPriorityTaskWoken | out | 初始化为 pdFALSE;若通知唤醒了更高优先级的任务则被置为 pdTRUE。 |
返回值
同 xTaskNotify()。
说明
xTaskNotify() 的中断安全版本。中断里给任务发事件、同时携带数据时用它。
注意
- 把通知值当信号量用时,中断里应改用更简单的 vTaskNotifyGiveFromISR()。
- pxHigherPriorityTaskWoken 的用法与上一条相同:中断返回前根据它决定是否切换任务。
典型用法
void vISR( void )
{
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
xTaskNotifyFromISR( xTaskToNotify, ulData, eSetValueWithOverwrite,
&xHigherPriorityTaskWoken );
portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}
2.39xTaskNotifyGive()
BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTaskToNotify | in | 被通知的任务句柄,其通知值将被加 1。 |
返回值
本函数是宏,内部以 eIncrement 调用 xTaskNotify(),因此恒返回 pdPASS。
说明
当通知值被用作二值或计数信号量的轻量替代品时,用这个宏来“给”(give)通知。它等价于 xSemaphoreGive(),但不需要信号量对象,速度更快。
接收方应配对使用 ulTaskNotifyTake(),而不是 xTaskNotifyWait()。
注意
- configUSE_TASK_NOTIFICATIONS 必须为 1(默认)。
- 通知值只有 32 位,计数上限受此限制;需要大量计数时还是用计数信号量。
- 只能定向发给已知句柄的任务,没有“多家等待”的语义。
典型用法
/* 发送方 */ xTaskNotifyGive( xWorkerHandle ); /* 接收方(在任务里) */ ulTaskNotifyTake( pdTRUE, portMAX_DELAY );
2.40vTaskNotifyGiveFromISR()
void vTaskNotifyGiveFromISR( TaskHandle_t xTaskToNotify,
BaseType_t *pxHigherPriorityTaskWoken );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTaskToNotify | in | 被通知的任务句柄,其通知值将被加 1。 |
| pxHigherPriorityTaskWoken | out | 必须初始化为 pdFALSE。若通知使被通知任务离开阻塞态且其优先级高于当前任务,则被置为 pdTRUE。 |
说明
xTaskNotifyGive() 的中断安全版本。中断里“给”一次信号时用它,例如 GPIO 中断通知一个处理任务。
注意
- 接收方仍需用 ulTaskNotifyTake()。
- pxHigherPriorityTaskWoken 必须在中断返回前由 portYIELD_FROM_ISR() 处理。
典型用法
void vUartISR( void )
{
BaseType_t xWoken = pdFALSE;
vTaskNotifyGiveFromISR( xUartTask, &xWoken );
portYIELD_FROM_ISR( xWoken );
}
2.41xTaskNotifyStateClear()
BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTask | in | 要清除待处理通知的任务句柄。传 NULL 表示清除调用者自己。 |
返回值
该任务原本有未处理的通知则返回 pdPASS;没有则返回 pdFAIL。
说明
任务的“通知待处理(pending)”是一种状态,与通知值本身是两回事:任务正在阻塞等待通知时收到通知,它会立即离开阻塞态,该通知不再挂起;但任务没有在等待时收到通知,这条通知就会挂起(状态置为 pending),等它下次调用 xTaskNotifyWait() 时立刻返回。
本函数只清除“待处理”这个状态标记,不改变通知值。要连同值一起清,用 ulTaskNotifyValueClear()。
注意
- 它不消耗通知值,也不影响通知值中的位——这点常被误解。
- 典型用法:丢弃一条已经过期的通知,避免下次等待时立刻“假成功”。
2.42ulTaskNotifyTake()
uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xClearCountOnExit | in | 传 pdFALSE 时,退出前把通知值减 1(等价于计数信号量被 take 一次);传 pdTRUE 时,退出前把通知值清 0(等价于二值信号量被取走)。 |
| xTicksToWait | in | 通知值为 0 时,任务在阻塞态中等待的最长节拍数。可用 portMAX_DELAY 表示无限等待(需 INCLUDE_vTaskSuspend 为 1)。 |
返回值
通知值在被减 1 或清 0 之前的值。返回值大于 0 说明确实取到了一次通知;返回 0 说明超时(或等待被打断)。
说明
当通知值被用作二值/计数信号量的轻量替代品时,接收方用它来“取”(take)通知。它会在通知值为 0 时阻塞等待,直到收到通知或超时。
发送方可以是任务(xTaskNotifyGive())或中断(vTaskNotifyGiveFromISR())。
注意
- 参数 xClearCountOnExit 决定了它的“信号量类型”:pdTRUE → 二值信号量语义;pdFALSE → 计数信号量语义。
- configUSE_TASK_NOTIFICATIONS 必须为 1。
- 作为二值信号量用时,连续多次 give 只会留下一次“有效”(因为退出时清零),这与二值信号量行为一致。
典型用法
void vWorker( void *pvParameters )
{
for( ;; )
{
/* 作为二值信号量:等一次信号,取到后清 0 */
ulTaskNotifyTake( pdTRUE, portMAX_DELAY );
/* 处理事件 */
}
}
2.43ulTaskNotifyValueClear()
uint32_t ulTaskNotifyValueClear( TaskHandle_t xTask,
uint32_t ulBitsToClear );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTask | in | 要清除其通知值中某些位的任务句柄。传 NULL 表示调用者自己。 |
| ulBitsToClear | in | 位掩码:某位为 1 表示把任务通知值中对应的位清 0。传 0xFFFFFFFF 即把整个通知值清 0。 |
返回值
清除之前该任务通知值的原值。
说明
按位清除目标任务通知值中的某些位,返回清除前的值。常用于“事件位”式用法:处理完某个事件后把对应位清掉。
注意
- 它清的是值,不清“待处理(pending)”标记;要清挂起状态用 xTaskNotifyStateClear()。
- 清除操作是原子的(在临界区内完成)。
2.44xTaskNotifyWait()
BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry,
uint32_t ulBitsToClearOnExit,
uint32_t *pulNotificationValue,
TickType_t xTicksToWait );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| ulBitsToClearOnEntry | in | 进入函数时(在开始等待之前)要清除的位。调用时若已有挂起通知则不清除。传 0xFFFFFFFF 表示进入时把通知值整体清 0。 |
| ulBitsToClearOnExit | in | 函数返回前要清除的位。位为 1 表示清除对应位;传 0xFFFFFFFF 表示返回前把通知值清 0。 |
| pulNotificationValue | out | 回传通知值(在按 ulBitsToClearOnExit 清除之前的值)。不需要可传 NULL。 |
| xTicksToWait | in | 等待通知的最长节拍数。0 表示不等待(只查当前是否已有挂起通知);portMAX_DELAY 表示无限等待。 |
返回值
收到通知(或调用时已有挂起通知)返回 pdTRUE;等待超时返回 pdFALSE。
说明
通用版的通知接收函数:在通知值为 0(且无挂起通知)时进入阻塞态等待,可用两个掩码参数精确控制“进门前清哪些位、出门前清哪些位”,并把通知值读出来。
它是任务通知最完整的接收方式,适合把通知值当成“事件位图 + 附带数据”使用。
注意
- 若只是把通知当二值/计数信号量用,请改用更简单的 ulTaskNotifyTake()。
- “进入时清除”只在本次调用没有已经挂起的通知时发生——这是为了保证挂起的通知不会被吞掉。
- xTicksToWait 为 0 时函数依然会检查一次是否有挂起通知,可当作轮询使用。
典型用法
uint32_t ulValue = 0; /* 进入时清全部,退出时清 bit0,取回通知值 */ BaseType_t xGot = xTaskNotifyWait( 0xFFFFFFFF, 0x01, &ulValue, pdMS_TO_TICKS( 100 ) );
2.45uxTaskPriorityGet()
UBaseType_t uxTaskPriorityGet( TaskHandle_t pxTask );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxTask | in | 要查询的任务句柄。传 NULL 表示查询调用者自己。 |
返回值
调用时刻该任务的优先级。若任务因持有互斥量而继承了更高优先级,返回的是当前(继承后)的优先级。
说明
查询任务当前的优先级。数值越大优先级越高,0 为最低。
注意
- INCLUDE_uxTaskPriorityGet 必须置 1。
- 想知道“基础优先级”(不含优先级继承)需用 uxTaskGetSystemState() / vTaskGetTaskInfo() 的 uxBasePriority 字段。
2.46vTaskPrioritySet()
void vTaskPrioritySet( TaskHandle_t pxTask, UBaseType_t uxNewPriority );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxTask | in | 要修改优先级的任务句柄。传 NULL 表示修改调用者自己。 |
| uxNewPriority | in | 新优先级。最大合法值为 configMAX_PRIORITIES - 1,超过会被静默截断为最大值。 |
说明
修改任务的优先级。优先级在任务的生命周期内可以随意调整,这是实现“按需临时提升优先级”的常用手段。
如果修改后的优先级使目标任务成为最高优先级的就绪任务,会立即发生一次上下文切换(调用者可能被抢占)。
注意
- INCLUDE_vTaskPrioritySet 必须置 1。
- 如果任务正持有互斥量而处于优先级继承状态,本函数设置的是基础优先级,当前优先级可能仍高于它。
- 不要在临界区或调度器挂起期间调用(它会请求切换)。
2.47vTaskResume()
void vTaskResume( TaskHandle_t pxTaskToResume );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxTaskToResume | in | 要恢复的任务句柄。该任务此前必须是被 vTaskSuspend() 置入挂起态的。 |
说明
把任务从挂起态转为就绪态。挂起态是一种“完全冻结”的状态:任务不参与调度,也不因超时醒来;只有被显式 resume 才会重新进入就绪态。
注意区分“挂起”与“阻塞”:阻塞是等事件/等超时,会自动醒来;挂起必须别人来解。
注意
- INCLUDE_vTaskSuspend 必须置 1。
- 如果目标任务当前不在挂起态,本次调用没有效果(不会报错)。
- 恢复后的任务若优先级高于当前任务,会立即抢占。
2.48xTaskResumeAll()
BaseType_t xTaskResumeAll( void );
返回值
若本次恢复导致调度器真正回到活动态并且因此发生了一次挂起的上下文切换,返回 pdTRUE;否则返回 pdFALSE(包括嵌套调用尚未回到最外层、以及没有待处理的切换的情况)。
说明
撤销一次 vTaskSuspendAll(),使调度器从挂起态回到活动态。
调度器挂起期间中断仍然开着,但不会发生任务切换;期间若有切换请求,会被记为“待处理”,直到调度器恢复时才执行。
注意
- vTaskSuspendAll() 可以嵌套,调用 xTaskResumeAll() 的次数必须与之一致,才会真正恢复调度。
- 只能在任务中调用,不能在调度器启动之前或在中断里调用。
- 调度器挂起期间不得调用其它 FreeRTOS API。
2.49xTaskResumeFromISR()
BaseType_t xTaskResumeFromISR( TaskHandle_t pxTaskToResume );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxTaskToResume | in | 要恢复的任务句柄。 |
返回值
若被恢复任务的优先级等于或高于被中断的那个任务,返回 pdTRUE(表示需要一次上下文切换);否则返回 pdFALSE。
说明
vTaskResume() 的中断安全版本:在中断里把挂起的任务恢复为就绪态。
注意
- INCLUDE_vTaskSuspend 与 INCLUDE_xTaskResumeFromISR 必须都为 1。
- 返回值应交给 portYIELD_FROM_ISR() 处理,否则高优先级任务可能延迟运行。
- 不要在中断里用它恢复“正在等事件”的任务——那类任务应该由事件 API 唤醒。
典型用法
void vISR( void )
{
if( xTaskResumeFromISR( xSuspendedTask ) == pdTRUE )
{
portYIELD_FROM_ISR( pdTRUE );
}
}
2.50vTaskSetApplicationTaskTag()
void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxTagValue );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTask | in | 要设置标签的任务句柄。传 NULL 表示设置调用者自己。 |
| pxTagValue | in | 要写入的标签值,类型为函数指针 TaskHookFunction_t。若想存非函数指针的值,需强制转换。 |
说明
给任务附加一个“标签”值,含义完全由应用定义,内核平时不会用它。属于高级用法。
最常见的用途是把标签设成一个任务钩子(回调)函数的地址,之后用 xTaskCallApplicationTaskHook() 调用它;配合 traceTASK_SWITCHED_IN() 可以做执行轨迹追踪。
注意
- 标签值与任务通知值互不相干,不要混为一谈。
- 任务被删除时标签随之消失,不涉及任何资源释放。
2.51vTaskSetThreadLocalStoragePointer()
void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet,
BaseType_t xIndex,
void *pvValue );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTaskToSet | in | 要写入 TLS 的任务句柄。传 NULL 表示写自己的。 |
| xIndex | in | 数组下标,范围 0 ~ (configNUM_THREAD_LOCAL_STORAGE_POINTERS - 1)。 |
| pvValue | in | 要保存的指针值(可以是任意对象的地址)。 |
说明
把指针写进任务的线程局部存储数组,使这份数据只属于该任务。每个任务拥有一份指针数组,长度由 configNUM_THREAD_LOCAL_STORAGE_POINTERS 定义。
注意
- 内核只保存指针,不分配、也不释放它指向的内存。
- 下标越界会写坏 TCB,务必保证在范围内。
- configNUM_THREAD_LOCAL_STORAGE_POINTERS 为 0(默认)时该功能被编译掉,本函数不可用。
2.52vTaskSetTimeOutState()
void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxTimeOut | out | 用它回传并初始化超时状态结构(记录起始节拍与剩余时间)。 |
说明
在用 xTaskCheckForTimeOut() 之前,必须先用本函数记录“本次等待的起点”。属于高级用法,服务于“同一个超时基准、多次进出阻塞态”的场景。
注意
- TimeOut_t 结构由内核定义,应用不要自己去填充它的成员。
- 一次等待流程里调用一次即可;重复调用会重置基准,等于把超时时间累加变长。
2.53vTaskStartScheduler()
void vTaskStartScheduler( void );
说明
启动 FreeRTOS 调度器。调用之前,执行的是 main() 及其调用的函数(内核处于“初始化”态);调用之后,只有任务和中断会执行,main() 的后续代码不会再有执行机会。
启动时,内核从已创建的任务中挑出优先级最高的就绪任务让它进入运行态,并自动创建空闲任务(必要时还会创建定时器服务任务)。
注意
- 启动后不会返回。若堆内存不足以创建空闲任务,vTaskStartScheduler() 会返回(并可能触发 malloc 失败钩子)——这是唯一可能返回的情形。
- 启动调度器前创建的任务,如果想要“先挂起”,可用 vTaskSuspend() 提前挂起它。
- 启动前可以用硬件初始化、创建队列/信号量等;启动后就只能在任务里做了。
典型用法
int main( void )
{
prvHardwareInit();
xTaskCreate( vTask1, "T1", configMINIMAL_STACK_SIZE, NULL, 1, NULL );
vTaskStartScheduler(); /* 不会返回 */
for( ;; ); /* 只有启动失败才会走到这里 */
}
2.54vTaskStepTick()
void vTaskStepTick( TickType_t xTicksToJump );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| xTicksToJump | in | 需要向前补上的节拍数(对应低功耗睡眠期间本应发生的节拍中断数)。 |
说明
在 tickless 低功耗模式下,MCU 睡眠期间节拍中断不会发生。醒来后调用本函数把节拍计数补上,使内核的时间刻度与真实时间保持一致。
与 xTaskCatchUpTicks() 的区别:本函数不会让任何任务因跨过超时时刻而解除阻塞,只做计数补偿。
注意
- configUSE_TICKLESS_IDLE 必须置 1,本函数才可用。
- 通常只在 portSUPPRESS_TICKS_AND_SLEEP() 的实现中调用,普通应用不需要直接用它。
2.55vTaskSuspend()
void vTaskSuspend( TaskHandle_t pxTaskToSuspend );
参数
| 参数 | 方向 | 说明 |
|---|---|---|
| pxTaskToSuspend | in | 要挂起的任务句柄。传 NULL 表示挂起调用者自己。 |
说明
把任务置入挂起态。挂起态的任务不参与调度、不消费 CPU、不会因超时自动醒来,只能由 vTaskResume() / xTaskResumeFromISR() 显式恢复。
任务挂起自己不返回(后续语句不会执行),直到被别的任务或中断恢复。
注意
- INCLUDE_vTaskSuspend 必须置 1。
- 自 FreeRTOS 6.1.0 起,可以在调度器启动之前挂起任务,效果是该任务以挂起态“出生”。
- 挂起持有互斥量的任务可能导致优先级继承关系异常,尽量避免。
2.56vTaskSuspendAll()
void vTaskSuspendAll( void );
说明
挂起调度器:中断保持开启,但不再发生任务切换。这适合“需要较长时间独占 CPU、但又不能关中断”的场合(例如更新一个较大的数据结构)。
期间若发生切换请求,会被记为待处理,直到调用 xTaskResumeAll() 才执行。
注意
- 可以嵌套,但 vTaskSuspendAll() 与 xTaskResumeAll() 的次数必须配平。
- 只能在任务中调用,不能在调度器启动前或中断里调用。
- 挂起调度器期间不要调用其它 FreeRTOS API(它们可能要求切换或操作就绪列表)。
- 与临界区的区别:临界区关中断,短而快;挂起调度器不关中断,适合较长但不希望被打断的逻辑。
2.57taskYIELD()
void taskYIELD( void );
说明
主动让出 CPU 给同优先级的其它任务。让出(yield)是指任务在自己的时间片用完之前自愿离开运行态,这不是被抢占。
调用后调度器会挑一个同优先级的就绪任务来运行;如果没有,调用者自己会立刻回到运行态(等于什么也没做)。
注意
- 只能在已运行的任务中调用,不能在调度器启动前调用。
- 调度器只会选同优先级任务,因为若存在更高优先级就绪任务,调用者根本不可能正在运行。
- vTaskDelay(0) 等价于 taskYIELD()。