FreeRTOS 中文参考手册 /2 任务与调度器 API

第 2 章 · 原书 22–160 页 · 57 个函数任务与调度器 API

Chapter 2 · Task and Scheduler API

本章是全书最大的一章,覆盖任务本身的创建、删除、延时、挂起、优先级,调度器控制,中断与临界区宏,以及任务通知(task notification)与运行时统计。函数按字母序排列,排序时忽略返回类型前缀(详见第 1 章 1.2 节)。

先理清四个状态,后面每个函数都在它们之间搬运任务:

状态含义怎么进入怎么离开
Running 运行态正在占用 CPU 执行代码的任务。单核上任何时刻只有一个。被调度器选中被更高优先级任务抢占、主动阻塞/挂起、时间片用完
Ready 就绪态万事俱备,只等 CPU。创建、延时到期、事件到来、被恢复被调度器选中
Blocked 阻塞态在等事件或等超时,带超时参数,到期会自动醒。调用带超时的 API(延时、等队列、等信号量、等通知)事件到来或超时到期(自动)
Suspended 挂起态被完全冻结,不参与调度,也不会自动醒来。vTaskSuspend()只能由 vTaskResume() / xTaskResumeFromISR() 恢复
阻塞与挂起最容易被混淆:阻塞是“等”,时间是它的朋友(会自己醒);挂起是“冻”,只有别人来解冻。任务通知、队列、信号量都只能唤醒阻塞态的任务,对挂起态任务无效。

本章有三组函数特别容易混,记住分界线即可:

本章所有 *FromISR 版本的函数都遵循同一条铁律:pxHigherPriorityTaskWoken 必须先初始化为 pdFALSE,并必须在中断退出前交给 portYIELD_FROM_ISR() 处理。漏掉这一步,被唤醒的高优先级任务要等到下一次节拍中断才可能运行,实时性直接崩掉。

下面按原书顺序逐条说明。每条的“注意”部分保留了原书对该函数启用条件(INCLUDE_ 宏 / config 宏)的说明,配置不满足时这些函数不会被编译进来。

2.1portSWITCH_TO_USER_MODE()

任务 · MPU task.h
void portSWITCH_TO_USER_MODE( void );

说明

该函数只对 FreeRTOS 的 MPU 移植版本有效,即那些使用了内存保护单元(Memory Protection Unit)的移植,属于高级用法。

受限任务(MPU restricted task)由 xTaskCreateRestricted() 创建,创建时的参数决定该任务是 User(非特权)模式还是 Supervisor(特权)模式。一个 Supervisor 模式的任务调用 portSWITCH_TO_USER_MODE() 之后,就会把自己降为 User 模式任务,从此无法再访问受 MPU 保护的内核数据与其它任务的存储区。

注意

2.2vTaskAllocateMPURegions()

任务 · MPU task.h
void vTaskAllocateMPURegions( TaskHandle_t xTaskToModify,
                              const MemoryRegion_t * const xRegions );

参数

参数方向说明
xTaskToModifyin被修改的受限任务句柄(即要获得 xRegions 所定义存储区访问权限的那个任务)。句柄由 xTaskCreateRestricted() 的 pxCreatedTask 参数取得。传 NULL 表示修改调用者自己。
xRegionsinMemoryRegion_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;
Listing 3 · MPU 存储区描述结构

注意

2.3xTaskAbortDelay()

任务 task.h
BaseType_t xTaskAbortDelay( TaskHandle_t xTask );

参数

参数方向说明
xTaskin要被强制移出阻塞态的任务句柄。句柄可由 xTaskCreate() 的 pxCreatedTask 参数取得,或保存 xTaskCreateStatic() 的返回值,或用任务名调用 xTaskGetHandle() 取得。

返回值

任务确实从阻塞态被移出则返回 pdPASS;如果任务本来就不在阻塞态(因此没有被移出)则返回 pdFAIL。

说明

凡带超时参数的 API 都可能让调用任务进入阻塞态:任务要么单纯等待超时到期,要么一边等待事件一边等待超时,事件到来或超时到期后任务会自动回到就绪态。

注意

2.4xTaskCallApplicationTaskHook()

任务 · 钩子 task.h
BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameters );

参数

参数方向说明
xTaskin要调用其钩子函数的任务句柄。传 NULL 表示调用者自己的钩子函数。
pvParametersin传给钩子函数自身的参数。类型为 void*,因此可以按需强制转换成任意类型。

返回值

任务设置了钩子函数(即 task tag 非空)时,返回钩子函数的返回值;任务没有设置钩子函数时返回 pdFAIL。

说明

本函数属于高级用法。vTaskSetApplicationTaskTag() 可以给任务附加一个“标签”(tag)值,标签的含义由应用自己定义,内核通常不会去读它。

有一种特殊用法:把标签值设为一个“任务钩子”(或回调)函数的地址。此后用 xTaskCallApplicationTaskHook() 就能显式地调用这个钩子。钩子函数的原型必须与下面一致(原书 Listing 8):

static BaseType_t prvExampleTaskHook( void * pvParameter )
{
    /* 这里做你想做的事,例如输出调试 trace。 */
    return 0;
}
Listing 8 · 所有任务钩子函数都必须符合的原型

注意

2.5xTaskCatchUpTicks()

任务 · 时间 task.h
BaseType_t xTaskCatchUpTicks( TickType_t xTicksToCatchUp );

参数

参数方向说明
xTicksToCatchUpin由于关中断而漏掉的节拍中断个数。该值不会自动计算,必须由应用自己算出。

返回值

把节拍计数前移之后,如果有任务因此离开阻塞态并触发了一次上下文切换,返回 pdTrue;否则返回 pdFalse。

说明

当应用长时间关闭中断、导致节拍中断被漏掉时,用本函数把节拍计数(tick count)补正过来。

它与 vTaskStepTick() 的区别在于:vTaskStepTick() 只是安静地把计数加上去,而 xTaskCatchUpTicks() 在把计数前移的过程中,可能越过某个任务本应解除阻塞的时刻,从而让任务真正被唤醒。

注意

2.6xTaskCheckForTimeOut()

任务 · 超时 task.h
BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut,
                                TickType_t * const pxTicksToWait );

参数

参数方向说明
pxTimeOutin-out指向记录超时判定所需信息(进入阻塞时的时间点、剩余时间)的结构。该结构需先用 vTaskSetTimeOutState() 初始化。
pxTicksToWaitin-out用来回传“调整后的剩余阻塞时间”:扣除已经阻塞掉的时间之后还剩多少。若返回 pdTRUE,说明剩余时间为 0,即已超时。

返回值

已超时返回 pdTRUE(此时剩余阻塞时间为 0);尚未超时返回 pdFALSE(pxTicksToWait 为剩余时间)。

说明

任务可以进入阻塞态等待某个事件,通常不会无限等待,而是带一个超时。若超时先到,任务就会被移出阻塞态。

问题在于:如果任务在等待同一个事件的过程中反复进出阻塞态(例如被信号量、队列多次唤醒又继续等),那么每次都要用同一个超时基准,才能保证总等待时间不超过最初指定的值。本函数就是为此而设的,属于高级用法:它判断相对于 pxTimeOut 记录的时间点是否已经超时,并把 pxTicksToWait 改成“还剩多少”。

注意

2.7xTaskCreate()

任务 task.h
BaseType_t xTaskCreate( TaskFunction_t pvTaskCode,
                         const char * const pcName,
                         unsigned short usStackDepth,
                         void *pvParameters,
                         UBaseType_t uxPriority,
                         TaskHandle_t *pxCreatedTask );

参数

参数方向说明
pvTaskCodein任务函数指针(本质上就是函数名)。任务函数是一个永不返回的 C 函数,通常写成死循环 for(;;)。原型必须为 void vTaskCode( void *pvParameters )。
pcNamein任务的描述名。主要用于调试,也可在 xTaskGetHandle() 中用名字换取句柄。最大长度由 configMAX_TASK_NAME_LEN 决定(含结尾的 NULL),超长会被截断。
usStackDepthin任务栈的深度。注意单位是“字”而不是字节:在 32 位 MCU 上 1 字 = 4 字节,因此 usStackDepth = 128 表示 512 字节栈。栈里同时存放任务局部变量、返回地址与寄存器现场。
pvParametersin传给任务函数的参数,类型 void*。可以是任意值的地址,也可以是强制转换后的整数。
uxPriorityin任务优先级,0 为最低(空闲任务的优先级)。数值越大优先级越高,最大合法值为 configMAX_PRIORITIES - 1,超过会被静默截到最大值。
pxCreatedTaskout用于回传新任务的句柄,之后可用它修改优先级、删除任务等。用不到时传 NULL 即可。

返回值

pdPASS 表示任务创建成功;errCOULD_NOT_ALLOCATE_REQUIRED_MEMORY 表示堆内存不足,无法为任务控制块(TCB)与栈分配空间。

说明

创建一个任务实例。每个任务都需要 RAM 存放任务状态(任务控制块 TCB)和栈。用 xTaskCreate() 创建时,这块 RAM 由 FreeRTOS 堆自动分配;用 xTaskCreateStatic() 创建时,RAM 由应用提供,因此多两个参数,但可以在编译期静态确定内存用量。

新创建的任务初始处于就绪态;如果它是当前优先级最高的就绪任务,会立即抢占成为运行态任务。任务既可以在调度器启动之前创建,也可以在启动之后创建。

注意

典型用法

void vTaskCode( void * pvParameters )
{
    for( ;; )
    {
        /* 任务主体 */
    }
}

TaskHandle_t xHandle = NULL;

xTaskCreate( vTaskCode,        /* 任务函数 */
             "NAME",           /* 任务名(调试用) */
             configMINIMAL_STACK_SIZE,  /* 栈深度,单位:字 */
             NULL,             /* 传给任务的参数 */
             tskIDLE_PRIORITY, /* 优先级 */
             &xHandle );       /* 回传的句柄,可传 NULL */

2.8xTaskCreateStatic()

任务 task.h
TaskHandle_t xTaskCreateStatic( TaskFunction_t pvTaskCode,
                                const char * const pcName,
                                uint32_t ulStackDepth,
                                void *pvParameters,
                                UBaseType_t uxPriority,
                                StackType_t *puxStackBuffer,
                                StaticTask_t *pxTaskBuffer );

参数

参数方向说明
pvTaskCodein任务函数指针,要求同 xTaskCreate()。
pcNamein任务名,要求同 xTaskCreate()。
ulStackDepthin栈深度,单位为“字”。因为栈由应用提供,这里只用于初始化栈结构。
pvParametersin传给任务函数的参数。
uxPriorityin任务优先级,超过 configMAX_PRIORITIES - 1 会被截断。
puxStackBufferin应用提供的栈数组,类型 StackType_t[],长度不得小于 ulStackDepth。
pxTaskBufferout应用提供的 StaticTask_t 结构,用作该任务的 TCB 存储区。

返回值

创建成功返回任务句柄(非 NULL);若 puxStackBuffer 或 pxTaskBuffer 为 NULL,则返回 NULL。

说明

用静态分配方式创建任务:栈数组与 TCB 结构由应用自己定义(通常是全局或 static 变量),内核不再调用 pvPortMalloc()。这是唯一一种在编译期就能确定任务内存占用的创建方式,适合不许动态分配、要求内存可审计的工程。

除此之外,行为与 xTaskCreate() 一致:新任务进入就绪态,可能立即抢占。

注意

典型用法

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

任务 · MPU task.h
BaseType_t xTaskCreateRestricted( TaskParameters_t *pxTaskDefinition,
                                    TaskHandle_t *pxCreatedTask );

参数

参数方向说明
pxTaskDefinitionin指向任务定义结构 TaskParameters_t 的指针,该结构把任务函数、名字、栈、参数、优先级、栈缓冲区以及 MPU 存储区一次性描述清楚。
pxCreatedTaskout回传新任务句柄,用不到可传 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;

注意

2.10vTaskDelay()

任务 · 延时 task.h
void vTaskDelay( TickType_t xTicksToDelay );

参数

参数方向说明
xTicksToDelayin调用任务在阻塞态中停留的节拍中断个数。例如节拍计数为 10000 时调用 vTaskDelay(100),任务立即进入阻塞态,直到计数到 10100 才回到就绪态。可用 pdMS_TO_TICKS() 把毫秒换算为节拍。

说明

把调用本函数的任务放入阻塞态,持续固定的节拍数。

特别注意:延时节拍数为 0 不会进入阻塞态,而是让调用任务向同优先级的其它就绪任务让出 CPU,等价于调用 taskYIELD()。

从调用 vTaskDelay() 到下一个节拍中断到来之间的剩余时间,会被算作完整的一个节拍,因此延时的最小分辨率在最坏情况下是一个完整的节拍周期。

注意

典型用法

/* 延时 500 ms(需知道节拍频率,configTICK_RATE_HZ) */
vTaskDelay( pdMS_TO_TICKS( 500 ) );

2.11vTaskDelayUntil()

任务 · 延时 task.h
void vTaskDelayUntil( TickType_t *pxPreviousWakeTime, TickType_t xTimeIncrement );

参数

参数方向说明
pxPreviousWakeTimein-out指向“上一次醒来的时刻”。该变量在函数内部自动更新,应用除首次初始化外不要手动改它(初始化时通常赋值为 xTaskGetTickCount() 的返回值)。
xTimeIncrementin周期长度,单位为节拍。它决定任务固定的执行频率,可用 pdMS_TO_TICKS() 由毫秒换算。

说明

把调用任务放入阻塞态,直到到达一个绝对时刻。周期性任务用它来获得恒定的执行频率。

它与 vTaskDelay() 的差别在于时间基准:vTaskDelay() 的唤醒时刻是“调用时刻 + 延时”,会累积任务执行时间带来的抖动;vTaskDelayUntil() 的唤醒时刻是绝对的,不管任务本次执行花了多久,下一次唤醒时间点都固定。

注意

典型用法

void vPeriodicTask( void *pvParameters )
{
    TickType_t xLastWakeTime = xTaskGetTickCount();  /* 必须先初始化 */
    const TickType_t xPeriod = pdMS_TO_TICKS( 10 );

    for( ;; )
    {
        /* 任务主体 */
        vTaskDelayUntil( &xLastWakeTime, xPeriod );   /* 绝对时间唤醒 */
    }
}

2.12vTaskDelete()

任务 task.h
void vTaskDelete( TaskHandle_t pxTask );

参数

参数方向说明
pxTaskin要删除的任务句柄。传 NULL 表示删除调用者自己。

说明

删除一个此前由 xTaskCreate() 或 xTaskCreateStatic() 创建的任务实例。任务被删除后就不复存在,也不会再进入运行态;已删除任务的句柄不可再使用。

删除任务时,释放其栈与 TCB 占用的内存是空闲任务的职责。因此只要用到 vTaskDelete(),就必须保证空闲任务能分到处理时间(即空闲任务必须能进入运行态)。

内核只会自动释放它自己分配给任务的内存。应用分配给任务的其它内存或资源(例如自己 malloc 的缓冲区、打开的文件、占用的外设),必须在删除前由应用显式释放。

注意

典型用法

/* 删除指定任务 */
vTaskDelete( xHandle );

/* 删除自己 —— 后面的语句不会执行 */
vTaskDelete( NULL );

2.13taskDISABLE_INTERRUPTS()

中断 · 宏 task.h
void taskDISABLE_INTERRUPTS( void );

说明

关闭中断。具体行为取决于移植版本:

/* 关中断(不嵌套,慎用) */
taskDISABLE_INTERRUPTS();
/* ... 极短的临界代码 ... */
taskENABLE_INTERRUPTS();

注意

2.14taskENABLE_INTERRUPTS()

中断 · 宏 task.h
void taskENABLE_INTERRUPTS( void );

说明

打开所有优先级的中断,即撤销 taskDISABLE_INTERRUPTS() 的效果。

同样不支持嵌套:两次 taskDISABLE_INTERRUPTS() 之后一次 taskENABLE_INTERRUPTS() 就会打开中断。需要嵌套时用 taskENTER_CRITICAL() / taskEXIT_CRITICAL()。

注意

2.15taskENTER_CRITICAL()

中断 · 宏 task.h
void taskENTER_CRITICAL( void );

说明

进入临界区;与之配对的是 taskEXIT_CRITICAL(),用于退出临界区。两者构成一个“可嵌套”的临界区实现:内部维护一个嵌套计数,只有最外层退出时才真正恢复中断。

临界区的本质是关闭中断——要么全局关闭,要么关闭到 configMAX_SYSCALL_INTERRUPT_PRIORITY 指定的优先级为止(视移植版本而定)。

taskENTER_CRITICAL();
/* 临界代码:不要调用会阻塞、会引起切换的 API */
taskEXIT_CRITICAL();

注意

2.16taskENTER_CRITICAL_FROM_ISR()

中断 · 宏 task.h
UBaseType_t taskENTER_CRITICAL_FROM_ISR( void );

返回值

返回调用时刻的中断屏蔽状态(旧的中断优先级掩码)。这个返回值必须保存下来,传给配对的 taskEXIT_CRITICAL_FROM_ISR(),否则退出时无法正确恢复中断状态。

说明

taskENTER_CRITICAL() 的中断安全版本,供中断服务程序(ISR)使用。在 ISR 中进入临界区调用它,退出临界区调用 taskEXIT_CRITICAL_FROM_ISR()。

实现方式与任务版一致:关闭中断,或关闭到 configMAX_SYSCALL_INTERRUPT_PRIORITY 指定的优先级为止。区别在于中断里不能依赖嵌套计数,所以用“保存—恢复”掩码的方式保证可重入。

注意

典型用法

void vAnInterruptHandler( void )
{
    UBaseType_t uxSavedInterruptStatus;

    uxSavedInterruptStatus = taskENTER_CRITICAL_FROM_ISR();
    /* 临界代码 */
    taskEXIT_CRITICAL_FROM_ISR( uxSavedInterruptStatus );
}

2.17taskEXIT_CRITICAL()

中断 · 宏 task.h
void taskEXIT_CRITICAL( void );

说明

退出由 taskENTER_CRITICAL() 进入的临界区。内部把嵌套计数减 1,减到 0 时才真正恢复进入临界区之前的中断使能状态。

注意

2.18taskEXIT_CRITICAL_FROM_ISR()

中断 · 宏 task.h
void taskEXIT_CRITICAL_FROM_ISR( UBaseType_t uxSavedInterruptStatus );

参数

参数方向说明
uxSavedInterruptStatusin必须使用配对的 taskENTER_CRITICAL_FROM_ISR() 返回的那个值。

说明

退出由 taskENTER_CRITICAL_FROM_ISR() 进入的临界区,并按 uxSavedInterruptStatus 恢复中断屏蔽状态。

注意

2.19xTaskGetApplicationTaskTag()

任务 · 钩子 task.h
TaskHookFunction_t xTaskGetApplicationTaskTag( TaskHandle_t xTask );

参数

参数方向说明
xTaskin要查询的任务句柄。传 NULL 表示查询调用者自己的标签值。

返回值

被查询任务的“标签”(tag)值,类型 TaskHookFunction_t(本质是一个函数指针类型)。

说明

返回与任务关联的标签值。标签的含义与用途完全由应用定义,内核正常情况下不会访问它。本函数属于高级用法。

标签值可以存放一个函数指针:此时它就相当于“给任务挂了个回调”,可用 xTaskCallApplicationTaskHook() 调用。常见的用法是配合 traceTASK_SWITCHED_IN() 宏做执行轨迹(trace)记录。

注意

2.20xTaskGetCurrentTaskHandle()

任务 task.h
TaskHandle_t xTaskGetCurrentTaskHandle( void );

返回值

当前处于运行态的任务(也就是调用者自己)的句柄。

说明

返回正在运行的任务的句柄。因为只有运行态的任务能执行代码,所以返回值一定是调用者自己的句柄。

典型用途:把“我自己的句柄”传给别人,让别的任务/中断以后能通知我、删除我或修改我的优先级。

注意

典型用法

TaskHandle_t xSelf = xTaskGetCurrentTaskHandle();
/* 例如交给中断处理程序,让它在事件到来时通知本任务 */
xTaskToNotify = xSelf;

2.21xTaskGetIdleTaskHandle()

任务 task.h
TaskHandle_t xTaskGetIdleTaskHandle( void );

返回值

空闲任务的句柄。

说明

返回空闲任务(Idle task)的句柄。空闲任务在调度器启动时由内核自动创建,优先级为 0,作用是“没有别的任务可运行时”占用 CPU,并负责回收被删除任务的内存。

若配置了 configUSE_IDLE_HOOK,可以在空闲钩子里调用本函数做统计或低功耗处理。

注意

2.22xTaskGetHandle()

任务 task.h
TaskHandle_t xTaskGetHandle( const char *pcNameToQuery );

参数

参数方向说明
pcNameToQueryin要查询的任务名,标准以 NULL 结尾的 C 字符串。名字必须与创建时的 pcName 完全一致。

返回值

找到同名任务则返回其句柄;没有匹配的任务则返回 NULL。

说明

任务在创建时(xTaskCreate() / xTaskCreateStatic())的 pcName 参数给了它一个人类可读的名字,本函数就是拿这个名字反查任务句柄。

它只是“名字到句柄”的查表,不创建任务,也不保证唯一。

注意

典型用法

TaskHandle_t xHandle = xTaskGetHandle( "LOGGER" );
if( xHandle != NULL ) { vTaskPrioritySet( xHandle, 3 ); }

2.23uxTaskGetNumberOfTasks()

任务 task.h
UBaseType_t uxTaskGetNumberOfTasks( void );

返回值

调用时刻受 FreeRTOS 内核管理的任务总数,包含挂起态、阻塞态、就绪态任务,也包含空闲任务与定时器服务任务。

说明

返回当前内核中的任务总数。用途之一是:调用 uxTaskGetSystemState() 之前先用它算出需要多大的 TaskStatus_t 数组。

注意

2.24vTaskGetRunTimeStats()

任务 · 统计 task.h
void vTaskGetRunTimeStats( char *pcWriteBuffer );

参数

参数方向说明
pcWriteBufferin用于接收格式化表格的字符缓冲区。函数不做任何越界检查,缓冲区必须足够大。

说明

把 FreeRTOS 收集到的任务运行时间统计格式化成人类可读的表格,写入 pcWriteBuffer。表格包含三列:任务名、该任务占用的绝对时间、占总运行时间的百分比。

原始数据来自 xTaskGetSystemState(),本函数只是排版。它是为了方便而提供的工具函数,不属于内核本体。

原书 Figure 1 给出了一张典型的输出表:

Task            Abs Time      % Time
----------------------------------------
IDLE            2580501       99%
Tmr Svc         0             0%
DEMO            0             0%
图 1 · vTaskGetRunTimeStats() 输出的示例表格

注意

2.25xTaskGetSchedulerState()

调度器 task.h
BaseType_t xTaskGetSchedulerState( void );

返回值

返回下列三个常量之一:taskSCHEDULER_NOT_STARTED(调度器尚未启动,仅在 vTaskStartScheduler() 之前调用本函数时返回)、taskSCHEDULER_RUNNING(调度器已启动且正常运行)、taskSCHEDULER_SUSPENDED(调度器已启动,但被 vTaskSuspendAll() 挂起)。

说明

查询调度器当前的状态。常用于断言式检查:例如某段代码只在调度器启动后才能执行时,先判断状态再操作。

注意

2.26uxTaskGetStackHighWaterMark()

任务 · 调试 task.h
UBaseType_t uxTaskGetStackHighWaterMark( TaskHandle_t xTask );

参数

参数方向说明
xTaskin要查询栈水位的任务句柄。传 NULL 表示查询调用者自己。

返回值

该任务自创建以来剩余栈空间的最小值(单位为“字”,不是字节)。这个值越接近 0,说明栈越接近溢出。

说明

每个任务都有自己的栈,大小在创建时确定。任务执行、中断嵌套都会消耗栈。本函数查询的是“历史最低水位”,即栈曾经用到的最深处距离栈底还剩多少。

它回答的是工程上最要紧的问题:这个任务的栈到底该开多大?经验做法是先给一个较大的栈,跑完所有最坏路径后看水位,再据此收小。

注意

典型用法

UBaseType_t uxHighWater = uxTaskGetStackHighWaterMark( NULL );
printf( "剩余栈:%u 字(约 %u 字节)\n", uxHighWater, uxHighWater * sizeof(StackType_t) );

2.27eTaskGetState()

任务 · 调试 task.h
eTaskState eTaskGetState( TaskHandle_t pxTask );

参数

参数方向说明
pxTaskin要查询的任务句柄。

返回值

返回该任务在调用时刻的状态枚举值,见下表。

说明

以枚举类型返回任务当前所处的状态。相比之下,uxTaskGetSystemState() / vTaskGetTaskInfo() 能一次性拿到更多信息;若只关心状态,用本函数更轻。

返回值含义
eRunning运行态:任务正在执行(只有调用者自己可能返回它)
eReady就绪态:可以运行,但当前有更高优先级任务在跑
eBlocked阻塞态:等待事件或等待超时
eSuspended挂起态:被 vTaskSuspend() 挂起,或创建后尚未启动调度器
eDeleted待删除:任务已被删除,但其内存尚未被空闲任务回收
eInvalid无效:句柄无效(部分版本返回)

注意

2.28uxTaskGetSystemState()

任务 · 调试 task.h
UBaseType_t uxTaskGetSystemState( TaskStatus_t * const pxTaskStatusArray,
                                   const UBaseType_t uxArraySize,
                                   unsigned long * const pulTotalRunTime );

参数

参数方向说明
pxTaskStatusArrayoutTaskStatus_t 数组,函数为系统中的每个任务填入一项。数组元素个数不得少于任务总数,任务总数可用 uxTaskGetNumberOfTasks() 取得。
uxArraySizein数组大小,单位是元素个数(而不是字节数)。
pulTotalRunTimeout回传自调度器启动以来的总运行时间,单位由运行时间统计时钟决定。若 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;
Listing 51 · TaskStatus_t 结构定义

注意

2.29vTaskGetTaskInfo()

任务 · 调试 task.h
void vTaskGetTaskInfo( TaskHandle_t xTask,
                        TaskStatus_t *pxTaskStatus,
                        BaseType_t xGetFreeStackSpace,
                        eTaskState eState );

参数

参数方向说明
xTaskin要查询的任务句柄。
pxTaskStatusout指向 TaskStatus_t 变量,由函数填充。
xGetFreeStackSpacein是否计算栈水位。计算需要遍历整个栈,比较耗时;不需要时传 pdFALSE 可显著加快。
eStatein要写入结构中的状态值。通常传 eTaskGetState( xTask ) 的结果,避免函数内部重复查询。

说明

为单个任务填充 TaskStatus_t 结构。与 uxTaskGetSystemState() 相比,它不遍历所有任务,适合在运行时监控某一个关键任务。

注意

2.30pvTaskGetThreadLocalStoragePointer()

任务 · TLS task.h
void *pvTaskGetThreadLocalStoragePointer( TaskHandle_t xTaskToQuery,
                                          BaseType_t xIndex );

参数

参数方向说明
xTaskToQueryin要读取其线程局部存储的任务句柄。传 NULL 表示读自己的。
xIndexin线程局部存储数组中的下标,取值范围 0 ~ (configNUM_THREAD_LOCAL_STORAGE_POINTERS - 1)。

返回值

从该任务线程局部存储数组的 xIndex 位置读到(并返回)的指针值。

说明

线程局部存储(Thread Local Storage,TLS)让应用把“只属于某个任务”的数据指针存在该任务的 TCB 里。每个任务都有各自的一份指针数组,数组长度由 FreeRTOSConfig.h 中的 configNUM_THREAD_LOCAL_STORAGE_POINTERS 决定。

例如库函数需要“每个任务各自的上下文”时,就用 TLS 存指针,而不用全局变量。

注意

2.31pcTaskGetName()

任务 task.h
char * pcTaskGetName( TaskHandle_t xTaskToQuery );

参数

参数方向说明
xTaskToQueryin要查询的任务句柄。传 NULL 表示查询调用者自己。

返回值

指向该任务名字符串的指针(标准以 NULL 结尾的 C 字符串)。

说明

查询任务的人类可读名称。名字是创建任务时(xTaskCreate() / xTaskCreateStatic())通过 pcName 参数设定的。

调试与日志里打印任务名,比打印句柄直观得多;本函数就是为此准备的。

注意

2.32xTaskGetTickCount()

时间 task.h
TickType_t xTaskGetTickCount( void );

返回值

调用时刻的节拍计数值(tick count)。

说明

节拍计数是调度器启动以来发生的节拍中断总数。本函数返回当前值,也就是内核的“时间刻度”。

典型用途:记录事件发生时间、计算两段代码之间的耗时、给 vTaskDelayUntil() 初始化基准时间。

注意

典型用法

TickType_t xStart = xTaskGetTickCount();
/* ... 一段代码 ... */
TickType_t xElapsed = xTaskGetTickCount() - xStart;   /* 无符号相减,溢出也正确 */

2.33xTaskGetTickCountFromISR()

时间 · 中断 task.h
TickType_t xTaskGetTickCountFromISR( void );

返回值

调用时刻的节拍计数值。

说明

xTaskGetTickCount() 的中断安全版本,可在中断服务程序中调用。

注意

2.34vTaskList()

任务 · 调试 task.h
void vTaskList( char *pcWriteBuffer );

参数

参数方向说明
pcWriteBufferin用于接收表格文本的缓冲区。函数不做边界检查,缓冲区必须足够大。

说明

把调用时刻系统中每个任务的状态整理成人类可读的表格,写入 pcWriteBuffer。原书 Figure 2 给出一张典型输出(任务名、状态、优先级、栈水位、任务编号):

Name        State  Prio  Stack  Num
---------------------------------------
IDLE        R      0     85     3
Tmr Svc     R      2     90     4
DEMO        B      1     240    2
图 2 · vTaskList() 输出的示例表格

注意

2.35xTaskNotify()

任务 · 通知 task.h
BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify,
                        uint32_t ulValue,
                        eNotifyAction eAction );

参数

参数方向说明
xTaskToNotifyin被通知的任务句柄。
ulValuein用于更新接收任务通知值的 32 位数据。具体怎么用取决于 eAction。
eActionin通知动作,决定如何更新接收任务的通知值,取值见下表。

返回值

当 eAction 为 eSetValueWithoutOverwrite 且接收任务的通知值未被更新时返回 pdFAIL;其它情况一律返回 pdPASS。

说明

每个任务都有一个 32 位通知值,任务创建时初始化为 0。任务通知是一种直接发给某个任务的轻量事件机制:它既能解除接收任务的阻塞,又能顺带更新接收任务的通知值。

与信号量/队列相比,任务通知不需要额外的内核对象,速度更快、占用 RAM 更少;代价是它只能“一对一”定向发送,不能像队列那样缓存多条消息。

xTaskNotify() 提供五种更新方式,由 eAction 选择:

eAction 取值含义
eNoAction只通知(解除阻塞),通知值不变。常用于把通知当作二值信号量使用。
eSetBits把 ulValue 中置 1 的位按位或进接收任务的通知值,可实现“事件位”语义。
eIncrement把接收任务的通知值加 1,ulValue 被忽略。等价于 xTaskNotifyGive()。
eSetValueWithOverwrite用 ulValue 无条件覆盖接收任务的通知值(覆盖式)。
eSetValueWithoutOverwrite仅当接收任务当前没有未读通知时才写入 ulValue;否则不写入并返回 pdFAIL。

注意

典型用法

/* 把一个数值发给接收任务 */
xTaskNotify( xReceiver, 42, eSetValueWithOverwrite );

/* 只置位 bit3,当作事件标志用 */
xTaskNotify( xReceiver, ( 1 << 3 ), eSetBits );

2.36xTaskNotifyAndQuery()

任务 · 通知 task.h
BaseType_t xTaskNotifyAndQuery( TaskHandle_t xTaskToNotify,
                                 uint32_t ulValue,
                                 eNotifyAction eAction,
                                 uint32_t *pulPreviousNotifyValue );

参数

参数方向说明
xTaskToNotifyin被通知的任务句柄。
ulValuein用于更新接收任务通知值的数据,含义取决于 eAction。
eActionin通知动作,取值同 xTaskNotify()。
pulPreviousNotifyValueout回传接收任务在被更新之前的通知值。不需要时可传 NULL。

返回值

同 xTaskNotify():eAction 为 eSetValueWithoutOverwrite 且未更新时返回 pdFAIL,其余返回 pdPASS。

说明

与 xTaskNotify() 相同,只是多了一个出参,把接收任务“更新前的通知值”回传给你。当通知值被当作递增计数器使用时,发送方常常需要知道它原来的值。

注意

2.37xTaskNotifyAndQueryFromISR()

任务 · 通知 · 中断 task.h
BaseType_t xTaskNotifyAndQueryFromISR( TaskHandle_t xTaskToNotify,
                                        uint32_t ulValue,
                                        eNotifyAction eAction,
                                        uint32_t *pulPreviousNotifyValue,
                                        BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xTaskToNotifyin被通知的任务句柄。
ulValuein更新通知值所用的数据。
eActionin通知动作,取值同 xTaskNotify()。
pulPreviousNotifyValueout回传更新前的通知值,不需要可传 NULL。
pxHigherPriorityTaskWokenout必须初始化为 pdFALSE。若本次通知解除了一个优先级高于当前任务的阻塞任务,该变量会被置为 pdTRUE,此时中断返回前应请求一次上下文切换(portYIELD_FROM_ISR)。

返回值

同 xTaskNotify()。

说明

xTaskNotifyAndQuery() 的中断安全版本,可在 ISR 中调用。

注意

2.38xTaskNotifyFromISR()

任务 · 通知 · 中断 task.h
BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify,
                                uint32_t ulValue,
                                eNotifyAction eAction,
                                BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xTaskToNotifyin被通知的任务句柄。
ulValuein更新通知值所用的数据。
eActionin通知动作,取值同 xTaskNotify()。
pxHigherPriorityTaskWokenout初始化为 pdFALSE;若通知唤醒了更高优先级的任务则被置为 pdTRUE。

返回值

同 xTaskNotify()。

说明

xTaskNotify() 的中断安全版本。中断里给任务发事件、同时携带数据时用它。

注意

典型用法

void vISR( void )
{
    BaseType_t xHigherPriorityTaskWoken = pdFALSE;

    xTaskNotifyFromISR( xTaskToNotify, ulData, eSetValueWithOverwrite,
                        &xHigherPriorityTaskWoken );

    portYIELD_FROM_ISR( xHigherPriorityTaskWoken );
}

2.39xTaskNotifyGive()

任务 · 通知 task.h
BaseType_t xTaskNotifyGive( TaskHandle_t xTaskToNotify );

参数

参数方向说明
xTaskToNotifyin被通知的任务句柄,其通知值将被加 1。

返回值

本函数是宏,内部以 eIncrement 调用 xTaskNotify(),因此恒返回 pdPASS。

说明

当通知值被用作二值或计数信号量的轻量替代品时,用这个宏来“给”(give)通知。它等价于 xSemaphoreGive(),但不需要信号量对象,速度更快。

接收方应配对使用 ulTaskNotifyTake(),而不是 xTaskNotifyWait()。

注意

典型用法

/* 发送方 */
xTaskNotifyGive( xWorkerHandle );

/* 接收方(在任务里) */
ulTaskNotifyTake( pdTRUE, portMAX_DELAY );

2.40vTaskNotifyGiveFromISR()

任务 · 通知 · 中断 task.h
void vTaskNotifyGiveFromISR( TaskHandle_t xTaskToNotify,
                              BaseType_t *pxHigherPriorityTaskWoken );

参数

参数方向说明
xTaskToNotifyin被通知的任务句柄,其通知值将被加 1。
pxHigherPriorityTaskWokenout必须初始化为 pdFALSE。若通知使被通知任务离开阻塞态且其优先级高于当前任务,则被置为 pdTRUE。

说明

xTaskNotifyGive() 的中断安全版本。中断里“给”一次信号时用它,例如 GPIO 中断通知一个处理任务。

注意

典型用法

void vUartISR( void )
{
    BaseType_t xWoken = pdFALSE;
    vTaskNotifyGiveFromISR( xUartTask, &xWoken );
    portYIELD_FROM_ISR( xWoken );
}

2.41xTaskNotifyStateClear()

任务 · 通知 task.h
BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );

参数

参数方向说明
xTaskin要清除待处理通知的任务句柄。传 NULL 表示清除调用者自己。

返回值

该任务原本有未处理的通知则返回 pdPASS;没有则返回 pdFAIL。

说明

任务的“通知待处理(pending)”是一种状态,与通知值本身是两回事:任务正在阻塞等待通知时收到通知,它会立即离开阻塞态,该通知不再挂起;但任务没有在等待时收到通知,这条通知就会挂起(状态置为 pending),等它下次调用 xTaskNotifyWait() 时立刻返回。

本函数只清除“待处理”这个状态标记,不改变通知值。要连同值一起清,用 ulTaskNotifyValueClear()。

注意

2.42ulTaskNotifyTake()

任务 · 通知 task.h
uint32_t ulTaskNotifyTake( BaseType_t xClearCountOnExit, TickType_t xTicksToWait );

参数

参数方向说明
xClearCountOnExitin传 pdFALSE 时,退出前把通知值减 1(等价于计数信号量被 take 一次);传 pdTRUE 时,退出前把通知值清 0(等价于二值信号量被取走)。
xTicksToWaitin通知值为 0 时,任务在阻塞态中等待的最长节拍数。可用 portMAX_DELAY 表示无限等待(需 INCLUDE_vTaskSuspend 为 1)。

返回值

通知值在被减 1 或清 0 之前的值。返回值大于 0 说明确实取到了一次通知;返回 0 说明超时(或等待被打断)。

说明

当通知值被用作二值/计数信号量的轻量替代品时,接收方用它来“取”(take)通知。它会在通知值为 0 时阻塞等待,直到收到通知或超时。

发送方可以是任务(xTaskNotifyGive())或中断(vTaskNotifyGiveFromISR())。

注意

典型用法

void vWorker( void *pvParameters )
{
    for( ;; )
    {
        /* 作为二值信号量:等一次信号,取到后清 0 */
        ulTaskNotifyTake( pdTRUE, portMAX_DELAY );

        /* 处理事件 */
    }
}

2.43ulTaskNotifyValueClear()

任务 · 通知 task.h
uint32_t ulTaskNotifyValueClear( TaskHandle_t xTask,
                                  uint32_t ulBitsToClear );

参数

参数方向说明
xTaskin要清除其通知值中某些位的任务句柄。传 NULL 表示调用者自己。
ulBitsToClearin位掩码:某位为 1 表示把任务通知值中对应的位清 0。传 0xFFFFFFFF 即把整个通知值清 0。

返回值

清除之前该任务通知值的原值。

说明

按位清除目标任务通知值中的某些位,返回清除前的值。常用于“事件位”式用法:处理完某个事件后把对应位清掉。

注意

2.44xTaskNotifyWait()

任务 · 通知 task.h
BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry,
                             uint32_t ulBitsToClearOnExit,
                             uint32_t *pulNotificationValue,
                             TickType_t xTicksToWait );

参数

参数方向说明
ulBitsToClearOnEntryin进入函数时(在开始等待之前)要清除的位。调用时若已有挂起通知则不清除。传 0xFFFFFFFF 表示进入时把通知值整体清 0。
ulBitsToClearOnExitin函数返回前要清除的位。位为 1 表示清除对应位;传 0xFFFFFFFF 表示返回前把通知值清 0。
pulNotificationValueout回传通知值(在按 ulBitsToClearOnExit 清除之前的值)。不需要可传 NULL。
xTicksToWaitin等待通知的最长节拍数。0 表示不等待(只查当前是否已有挂起通知);portMAX_DELAY 表示无限等待。

返回值

收到通知(或调用时已有挂起通知)返回 pdTRUE;等待超时返回 pdFALSE。

说明

通用版的通知接收函数:在通知值为 0(且无挂起通知)时进入阻塞态等待,可用两个掩码参数精确控制“进门前清哪些位、出门前清哪些位”,并把通知值读出来。

它是任务通知最完整的接收方式,适合把通知值当成“事件位图 + 附带数据”使用。

注意

典型用法

uint32_t ulValue = 0;
/* 进入时清全部,退出时清 bit0,取回通知值 */
BaseType_t xGot = xTaskNotifyWait( 0xFFFFFFFF, 0x01, &ulValue, pdMS_TO_TICKS( 100 ) );

2.45uxTaskPriorityGet()

任务 · 优先级 task.h
UBaseType_t uxTaskPriorityGet( TaskHandle_t pxTask );

参数

参数方向说明
pxTaskin要查询的任务句柄。传 NULL 表示查询调用者自己。

返回值

调用时刻该任务的优先级。若任务因持有互斥量而继承了更高优先级,返回的是当前(继承后)的优先级。

说明

查询任务当前的优先级。数值越大优先级越高,0 为最低。

注意

2.46vTaskPrioritySet()

任务 · 优先级 task.h
void vTaskPrioritySet( TaskHandle_t pxTask, UBaseType_t uxNewPriority );

参数

参数方向说明
pxTaskin要修改优先级的任务句柄。传 NULL 表示修改调用者自己。
uxNewPriorityin新优先级。最大合法值为 configMAX_PRIORITIES - 1,超过会被静默截断为最大值。

说明

修改任务的优先级。优先级在任务的生命周期内可以随意调整,这是实现“按需临时提升优先级”的常用手段。

如果修改后的优先级使目标任务成为最高优先级的就绪任务,会立即发生一次上下文切换(调用者可能被抢占)。

注意

2.47vTaskResume()

任务 · 挂起 task.h
void vTaskResume( TaskHandle_t pxTaskToResume );

参数

参数方向说明
pxTaskToResumein要恢复的任务句柄。该任务此前必须是被 vTaskSuspend() 置入挂起态的。

说明

把任务从挂起态转为就绪态。挂起态是一种“完全冻结”的状态:任务不参与调度,也不因超时醒来;只有被显式 resume 才会重新进入就绪态。

注意区分“挂起”与“阻塞”:阻塞是等事件/等超时,会自动醒来;挂起必须别人来解。

注意

2.48xTaskResumeAll()

调度器 task.h
BaseType_t xTaskResumeAll( void );

返回值

若本次恢复导致调度器真正回到活动态并且因此发生了一次挂起的上下文切换,返回 pdTRUE;否则返回 pdFALSE(包括嵌套调用尚未回到最外层、以及没有待处理的切换的情况)。

说明

撤销一次 vTaskSuspendAll(),使调度器从挂起态回到活动态。

调度器挂起期间中断仍然开着,但不会发生任务切换;期间若有切换请求,会被记为“待处理”,直到调度器恢复时才执行。

注意

2.49xTaskResumeFromISR()

任务 · 挂起 · 中断 task.h
BaseType_t xTaskResumeFromISR( TaskHandle_t pxTaskToResume );

参数

参数方向说明
pxTaskToResumein要恢复的任务句柄。

返回值

若被恢复任务的优先级等于或高于被中断的那个任务,返回 pdTRUE(表示需要一次上下文切换);否则返回 pdFALSE。

说明

vTaskResume() 的中断安全版本:在中断里把挂起的任务恢复为就绪态。

注意

典型用法

void vISR( void )
{
    if( xTaskResumeFromISR( xSuspendedTask ) == pdTRUE )
    {
        portYIELD_FROM_ISR( pdTRUE );
    }
}

2.50vTaskSetApplicationTaskTag()

任务 · 钩子 task.h
void vTaskSetApplicationTaskTag( TaskHandle_t xTask, TaskHookFunction_t pxTagValue );

参数

参数方向说明
xTaskin要设置标签的任务句柄。传 NULL 表示设置调用者自己。
pxTagValuein要写入的标签值,类型为函数指针 TaskHookFunction_t。若想存非函数指针的值,需强制转换。

说明

给任务附加一个“标签”值,含义完全由应用定义,内核平时不会用它。属于高级用法。

最常见的用途是把标签设成一个任务钩子(回调)函数的地址,之后用 xTaskCallApplicationTaskHook() 调用它;配合 traceTASK_SWITCHED_IN() 可以做执行轨迹追踪。

注意

2.51vTaskSetThreadLocalStoragePointer()

任务 · TLS task.h
void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet,
                                        BaseType_t xIndex,
                                        void *pvValue );

参数

参数方向说明
xTaskToSetin要写入 TLS 的任务句柄。传 NULL 表示写自己的。
xIndexin数组下标,范围 0 ~ (configNUM_THREAD_LOCAL_STORAGE_POINTERS - 1)。
pvValuein要保存的指针值(可以是任意对象的地址)。

说明

把指针写进任务的线程局部存储数组,使这份数据只属于该任务。每个任务拥有一份指针数组,长度由 configNUM_THREAD_LOCAL_STORAGE_POINTERS 定义。

注意

2.52vTaskSetTimeOutState()

任务 · 超时 task.h
void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut );

参数

参数方向说明
pxTimeOutout用它回传并初始化超时状态结构(记录起始节拍与剩余时间)。

说明

在用 xTaskCheckForTimeOut() 之前,必须先用本函数记录“本次等待的起点”。属于高级用法,服务于“同一个超时基准、多次进出阻塞态”的场景。

注意

2.53vTaskStartScheduler()

调度器 task.h
void vTaskStartScheduler( void );

说明

启动 FreeRTOS 调度器。调用之前,执行的是 main() 及其调用的函数(内核处于“初始化”态);调用之后,只有任务和中断会执行,main() 的后续代码不会再有执行机会。

启动时,内核从已创建的任务中挑出优先级最高的就绪任务让它进入运行态,并自动创建空闲任务(必要时还会创建定时器服务任务)。

注意

典型用法

int main( void )
{
    prvHardwareInit();
    xTaskCreate( vTask1, "T1", configMINIMAL_STACK_SIZE, NULL, 1, NULL );

    vTaskStartScheduler();   /* 不会返回 */

    for( ;; );               /* 只有启动失败才会走到这里 */
}

2.54vTaskStepTick()

时间 · 低功耗 task.h
void vTaskStepTick( TickType_t xTicksToJump );

参数

参数方向说明
xTicksToJumpin需要向前补上的节拍数(对应低功耗睡眠期间本应发生的节拍中断数)。

说明

在 tickless 低功耗模式下,MCU 睡眠期间节拍中断不会发生。醒来后调用本函数把节拍计数补上,使内核的时间刻度与真实时间保持一致。

与 xTaskCatchUpTicks() 的区别:本函数不会让任何任务因跨过超时时刻而解除阻塞,只做计数补偿。

注意

2.55vTaskSuspend()

任务 · 挂起 task.h
void vTaskSuspend( TaskHandle_t pxTaskToSuspend );

参数

参数方向说明
pxTaskToSuspendin要挂起的任务句柄。传 NULL 表示挂起调用者自己。

说明

把任务置入挂起态。挂起态的任务不参与调度、不消费 CPU、不会因超时自动醒来,只能由 vTaskResume() / xTaskResumeFromISR() 显式恢复。

任务挂起自己不返回(后续语句不会执行),直到被别的任务或中断恢复。

注意

2.56vTaskSuspendAll()

调度器 task.h
void vTaskSuspendAll( void );

说明

挂起调度器:中断保持开启,但不再发生任务切换。这适合“需要较长时间独占 CPU、但又不能关中断”的场合(例如更新一个较大的数据结构)。

期间若发生切换请求,会被记为待处理,直到调用 xTaskResumeAll() 才执行。

注意

2.57taskYIELD()

调度器 · 宏 task.h
void taskYIELD( void );

说明

主动让出 CPU 给同优先级的其它任务。让出(yield)是指任务在自己的时间片用完之前自愿离开运行态,这不是被抢占。

调用后调度器会挑一个同优先级的就绪任务来运行;如果没有,调用者自己会立刻回到运行态(等于什么也没做)。

注意