1-taskYIELD

请求上下文切换到其他任务

task. h

taskYIELD() 用于请求切换上下文到另一个任务。 但是， 除非存在其他任务，其优先级等于或高于调用 taskYIELD() 的任务的优先级， 否则 RTOS 调度器将选择 调用了 taskYIELD() 的任务并使其再次运行。

如果 configUSE_PREEMPTION 设置 为 1，则 RTOS 调度器将始终运行 能够运行的优先级最高的任务，因此调用 taskYIELD() 将永远无法 切换到一个优先级更高的任务。

2-taskDISABLE_INTERRUPTS()

task. h

如果使用的移植支持 configMAX_SYSCALL_INTERRUPT_PRIORITY（ 或 configMAX_API_CALL_INTERRUPT_PRIORITY）常量，那么 taskDISABLE_interrupts 将 禁用所有中断，或在 configMAX_SYSCALL_INTRUPT_PROJECT 设置之前屏蔽（禁用）中断。 检查 taskDISABLE_INTERRUPTS 在使用的移植中的实现。

如果使用的移植不支持 configMAX_SYSCALL_INTERRUPT_PRIORITY 常量， 那么 taskDISABLE_INTERRUPTS() 将对所有可屏蔽的中断进行全局禁用。

通常情况下不会直接调用该宏，而是使用 taskENTER_CRITICAL() 和 taskEXIT_CRITICAL() 来替代。

3-taskENABLE_INTERRUPTS()

task. h
启用微控制器中断的宏。

通常情况下不会直接调用该宏，而是使用 taskENTER_CRITICAL() 和 taskEXIT_CRITICAL() 来替代。

4-taskENTER_CRITICAL()/taskEXIT_CRITICAL()

task. hvoid taskENTER_CRITICAL( void );
void taskEXIT_CRITICAL( void );

通过调用 taskENTER_CRITICAL() 进入临界区，随后 通过调用 taskEXIT_CRITICAL() 退出临界区。

宏 taskENTER_CRITICAL() 和 taskEXIT_CRITICAL() 提供了一个基本 临界区实现，只需禁用中断即可使其全局运作， 或在特定的中断优先级范围内运作。

如果所使用的 FreeRTOS 移植未使用 configMAX_SYSCALL_INTERRUPT_PRIORITY 内核配置常量（也称为 configMAX_API_CALL_INTERRUPT_PRIORITY），则调用 taskENTER_CRITICAL() 将 全局禁用中断。 如果所使用的 FreeRTOS 移植 使用了 configMAX_SYSCALL_INTERRUPT_PRIORITY 内核配置常量， 则调用 taskENTER_CRITICAL() 会将中断保留在 由已禁用的 configMAX_SYSCALL_INTERRUPT_PRIORITY 设置的中断优先级一下， 并启用所有更高优先级的中断。

抢占式上下文切换仅在中断内发生， 在中断被禁用时不会发生。 因此，可保证 调用 taskENTER_CRITICAL() 的任务维持在运行状态，直到 退出临界区，除非任务明确试图阻塞或让出 （它不应在临界区的内部进行该操作）。

对 taskENTER_CRITICAL() 和 taskEXIT_CRITICAL() 的调用旨在嵌套。 因此，只有在执行了一次对 taskEXIT_CRITICAL() 的调用， 用于所有先前的 taskENTER_CRITICAL() 调用之后， 才会退出临界区。

临界区必须保持非常短，否则将影响 中断响应时间。 每次 taskENTER_CRITICAL() 调用都必须紧密配合 taskEXIT_CRITICAL() 调用。

不得从临界区调用 FreeRTOS API 函数。
taskENTER_CRITICAL() 和 taskEXIT_CRITICAL() 不得从中断服务程序 (ISR) 调用

4.1用法示例：

/*临界段的函数应用. */
void vDemoFunction( void )
{/* 进入临界区。在本例中，这个函数本身是从一个临界区中调用的，因此进入这个临界区将导致嵌套深度为2。 */taskENTER_CRITICAL();/* 执行此处临界区所保护的操作。 *//* 退出临界区。在本例中，这个函数本身是从临界区调用的，因此对taskEXIT_CRITICAL()的调用将使嵌套计数减少1，但不会导致启用中断。 */taskEXIT_CRITICAL();
}/* 从临界区中调用vDemoFunction()的任务。 */
void vTask1( void * pvParameters )
{for( ;; ){/* 在这里执行一些功能。 *//* 调用taskENTER_CRITICAL()创建临界区。*/taskENTER_CRITICAL();/* 执行需要临界区的代码。 *//* 对taskENTER_CRITICAL()的调用可以嵌套，因此调用包含自己对taskENTER_CRITICAL()和taskEXIT_CRITICAL()调用的函数是安全的。*/vDemoFunction();/* 事件需要进入临界区的操作已经完成，需要退出临界区。在调用taskEXIT_CRITICAL()之后，嵌套深度将为零，因此中断将被重新启用。 */taskEXIT_CRITICAL();}
}

5-taskENTER_CRITICAL_FROM_ISR()/taskEXIT_CRITICAL_FROM_ISR()

task. h

UBaseType_t taskENTER_CRITICAL_FROM_ISR( void );
void taskEXIT_CRITICAL_FROM_ISR( UBaseType_t uxSavedInterruptStatus );

taskENTER_CRITICAL() and taskEXIT_CRITICAL() 版本 可用于中断服务程序 (ISR)。

在 ISR 中，通过调用 taskENTER_CRITICAL_FROM_ISR() 进入临界区， 然后通过调用 taskEXIT_CRITICAL_FROM_ISR() 退出。

taskENTER_CRITICAL_FROM_ISR() 宏和 taskEXIT_CRITICAL_FROM_ISR() 宏提供了 基本临界区的实现，只需禁用中断即可使其全局运作， 可以是全局禁用，也可以是禁用到特定的中断优先级。

如果使用的 FreeRTOS 移植支持中断嵌套，则调用 taskENTER_CRITICAL_FROM_ISR() 将在内核配置常量 configMAX_SYSCALL_INTERRUPT_PRIORITY 设置的中断优先级或以下级别禁用中断，并 启用所有其他中断优先级。 如果使用的 FreeRTOS 移植不支持中断嵌套，则 taskENTER_CRITICAL_FROM_ISR() 和 taskEXIT_CRITICAL_FROM_ISR() 将不起作用。

调用 taskENTER_CRITICAL_FROM_ISR() 和 taskEXIT_CRITICAL_FROM_ISR() 旨在用于嵌套，但宏的使用方式的语义不同于 taskENTER_CRITICAL() 和 taskEXIT_CRITICAL() 等效项。

临界区必须保持非常短，否则将影响 更高优先级的中断的响应时间，会导致该中断嵌套。 每次 taskENTER_CRITICAL_FROM_ISR() 调用都必须紧密配合 taskEXIT_CRITICAL_FROM_ISR() 调用一起使用。

不得从临界区调用 FreeRTOS API 函数。

5.1参数：

uxSavedInterruptStatus taskEXIT_CRITICAL_FROM_ISR() 将 uxSavedInterruptStatus 作为其 唯一参数。 作为 uxSavedInterruptStatus 参数使用的值 必须是从匹配的 taskENTER_CRITICAL_FROM_ISR() 调用返回的值。
taskENTER_CRITICAL_FROM_ISR() 不采用任何 参数。

5.2 Returns:

taskENTER_CRITICAL_FROM_ISR() 返回调用宏之前的中断掩码状态 。 taskENTER_CRITICAL_FROM_ISR() 返回的值 必须作为 uxSavedInterruptStatus 参数用于匹配的 taskEXIT_CRITICAL_FROM_ISR() 调用。
taskEXIT_CRITICAL_FROM_ISR() 不返回值。

5.3 用法示例：

/* 从ISR调用的函数。 */
void vDemoFunction( void )
{
UBaseType_t uxSavedInterruptStatus;/* 进入临界区。在这个例子中，这个函数本身是从一个临界区中调用的，所以进入这个临界区将导致嵌套深度为2。将taskENTER_CRITICAL_FROM_ISR()返回的值保存到本地堆栈变量中，以便将其传递给taskEXIT_CRITICAL_FROM_ISR()。*/uxSavedInterruptStatus = taskENTER_CRITICAL_FROM_ISR();/* 执行临界区保护的操作。 *//* 退出临界区。在这个例子中，这个函数本身是从临界区调用的，所以中断在uxSavedInterruptStatus中存储值之前就已经被禁用了，因此将uxSavedInterruptStatus传递给taskEXIT_CRITICAL_FROM_ISR()不会导致中断被重新启用。*/taskEXIT_CRITICAL_FROM_ISR( uxSavedInterruptStatus );
}/* 从中断服务例程中调用vDemoFunction()的任务。*/
void vDemoISR( void )
{
UBaseType_t uxSavedInterruptStatus;/* 调用taskENTER_CRITICAL_FROM_ISR()创建一个临界区，将返回值保存到本地堆栈变量中。*/uxSavedInterruptStatus = taskENTER_CRITICAL_FROM_ISR();/* 执行需要临界区的代码。 *//* 对taskENTER_CRITICAL_FROM_ISR()的调用可以嵌套，因此可以安全地调用函数，该函数包含对taskENTER_CRITICAL_FROM_ISR()和taskEXIT_CRITICAL_FROM_ISR()。 */vDemoFunction();/* 事件需要进入临界区的操作已经完成，需要退出临界区。假设中断在进入这个ISR时被启用，保存在uxSavedInterruptStatus中的值将导致中断被重新启用。*/taskEXIT_CRITICAL_FROM_ISR( uxSavedInterruptStatus );
}

6-vTaskStartScheduler

task. h
void vTaskStartScheduler( void );

启动 RTOS 调度器。调用后，RTOS 内核可以控制在何时执行哪些任务。

空闲任务和可选的 定时器守护进程任务会自动创建（当 RTOS 调度器启动时）。

vTaskStartScheduler() 仅在没有足够的 RTOS 堆 可用来创建空闲或定时器守护进程任务时才会返回。

所有 RTOS 演示应用程序项目都包含使用 vTaskStartScheduler() 的示例，通常 位于 main.c 的 main() 函数中。

6.1 用法示例：

 void vAFunction( void ){// Tasks can be created before or after starting the RTOSschedulerxTaskCreate( vTaskCode,"NAME",STACK_SIZE,NULL,tskIDLE_PRIORITY,NULL );// Start the real time scheduler.vTaskStartScheduler();// Will not get here unless there is insufficient RAM.}

7-vTaskEndScheduler

task. h
void vTaskEndScheduler( void );

注意： 这仅适用于 x86 Real Mode PC 移植。

停止 RTOS 内核滴答。所有已创建的任务将自动删除，多任务处理（抢占式或协作式）将停止。然后从调用 vTaskStartScheduler() 的位置恢复执行，就像 vTaskStartScheduler() 刚刚返回一样。

有关使用 vTaskEndScheduler() 的示例，请参阅 demo/PC 目录中的演示应用程序文件 main.c。

vTaskEndScheduler() 需要在可移植层中定义一个退出函数（有关 PC 移植，请参阅 port.c 中的 vPortEndScheduler()）。这将执行硬件特定的操作，例如停止 RTOS 内核滴答。

vTaskEndScheduler() 将释放 RTOS 内核分配的所有资源，但不会释放应用程序任务分配的资源。

7.1 示例用法：

 void vTaskCode( void * pvParameters ){for( ;; ){// Task code goes here.// At some point we want to end the real time kernel processing // so call ...vTaskEndScheduler ();}}void vAFunction( void ){// Create at least one task before starting the RTOS kernel.xTaskCreate( vTaskCode, "NAME", STACK_SIZE, NULL, tskIDLE_PRIORITY, NULL );// Start the real time kernel with preemption.vTaskStartScheduler();// Will only get here when the vTaskCode () task has called // vTaskEndScheduler ().  When we get here we are back to single task // execution.}

8- vTaskSuspendAll

task. h
void vTaskSuspendAll( void );

挂起调度器。 挂起调度器会阻止上下文切换，但会让中断处于启用状态。 如果调度器被挂起时，中断请求切换上下文，那么请求将会被挂起。而且只有在调度器恢复（取消挂起）时才会执行。

在 vTaskSuspendAll() 之后调用 xTaskResumeAll() 会转换调度器的状态，取消其阻塞状态。

vTaskSuspendAll() 可以嵌套调用。 调用 xTaskResumeAll() 的次数必须与先前调用 vTaskSuspendAll() 的次数相同，然后调度器将取消挂起状态并重新进入活动状态。

xTaskResumeAll() 只能在正在执行的任务中调用，因此不能在调度器处于初始化状态时（启动计划程序之前）调用。

不得在调度器挂起时调用其他 FreeRTOS API 函数。

调度器挂起时，禁止调用可能切换上下文的 API 函数（例如 vTaskDelayUntil()、xQueueSend() 等等） 。

8.1 用法示例：

/* A function that suspends then resumes the scheduler. */
void vDemoFunction( void )
{/* This function suspends the scheduler.  When it is called from vTask1 the scheduler is already suspended, so this call creates a nesting depth of 2. */vTaskSuspendAll();/* Perform an action here. *//* As calls to vTaskSuspendAll() are nested, resuming the scheduler here will not cause the scheduler to re-enter the active state. */xTaskResumeAll();
}void vTask1( void * pvParameters )
{for( ;; ){/* Perform some actions here. *//* At some point the task wants to perform an operation during which it does not want to get swapped out, or it wants to access data which is also accessed from another task (but not from an interrupt).  It cannot usetaskENTER_CRITICAL()/taskEXIT_CRITICAL() as the length of the operation maycause interrupts to be missed. *//* Prevent the scheduler from performing a context switch. */vTaskSuspendAll();/* Perform the operation here.  There is no need to use critical sections as the task has all the processing time other than that utilized by interrupt service routines.*/           /* Calls to vTaskSuspendAll() can be nested so it is safe to call a (non API) function which also contains calls to vTaskSuspendAll().  API functions should not be called while the scheduler is suspended. */vDemoFunction();/* The operation is complete.  Set the scheduler back into the Active state. */if( xTaskResumeAll() == pdTRUE ){/* A context switch occurred within xTaskResumeAll(). */}else{/* A context switch did not occur within xTaskResumeAll(). */}}
}

9-xTaskResumeAll

task. h
BaseType_t xTaskResumeAll( void );

恢复通过调用 vTaskSuspendAll() 挂起的调度器。

xTaskResumeAll() 仅恢复调度器， 不会取消挂起 之前通过调用 vTaskSuspend() 而挂起的任务。

9.1 Returns:

如果恢复调度器导致了上下文切换，则返回 pdTRUE，否则返回 pdFALSE。

9.2 用法示例：

 void vTask1( void * pvParameters ){for( ;; ){/* Task code goes here. *//* ... *//* At some point the task wants to perform a long operationduring which it does not want to get swapped out.  It cannotuse taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the lengthof the operation may cause interrupts to be missed -including the ticks.Prevent the RTOS kernel swapping out the task. */vTaskSuspendAll();/* Perform the operation here.  There is no need to use criticalsections as we have all the microcontroller processing time.During this time interrupts will still operate and the realtime RTOS kernel tick count will be maintained. *//* ... *//* The operation is complete.  Restart the RTOS kernel.  We want to forcea context switch - but there is no point if resuming the schedulercaused a context switch already. */if( !xTaskResumeAll () ){taskYIELD ();}}}

10-vTaskStepTick

task.hvoid vTaskStepTick( TickType_t xTicksToJump );

如果 RTOS 配置为使用无滴答空闲功能， 则只要空闲任务是唯一能够执行的任务， 滴答中断就会停止，并且微控制器会进入低功耗状态。 在退出低功率状态时， 必须校正滴答计数值， 以包含停止时所经过的时间。

如果 FreeRTOS 移植包含默认 portSUPPRESS_TICKS_AND_SLEEP() 实现， 则会在内部使用 vTaskStepTick() 来确保 滴答计数值正确。 vTaskStepTick() 是一个公共 API 函数， 可用于覆盖默认的 portSUPPRESS_TICKS_AND_SLEEP() 实现， 如果正在使用的移植不提供默认值， 则提供 portSUPPRESS_TICKS_AND_SLEEP()。

必须将 configUSE_TICKLESS_IDLE 配置常量设置为 1， vTaskStepTick() 才可用。

10.1 参数：

xTicksToJump 自滴答中断停止以来经过的 RTOS 滴答数 。 为确保正常运行， 该参数必须小于或 等于 portSUPPRESS_TICKS_AND_SLEEP() 参数。

10.2 用法示例：

该示例演示了对多个函数的调用。 仅 vTaskStepTick() 是 FreeRTOS API 的一部分。 其他函数特定于 所用硬件上可用的时钟和节能模式，因此必须 由应用程序编写者提供。

/* First define the portSUPPRESS_TICKS_AND_SLEEP().  The parameter is the time,
in ticks, until the kernel next needs to execute. */
#define portSUPPRESS_TICKS_AND_SLEEP( xIdleTime ) vApplicationSleep( xIdleTime )/* Define the function that is called by portSUPPRESS_TICKS_AND_SLEEP(). */
void vApplicationSleep( TickType_t xExpectedIdleTime )
{
unsigned long ulLowPowerTimeBeforeSleep, ulLowPowerTimeAfterSleep;/* Read the current time from a time source that will remain operationalwhile the microcontroller is in a low power state. */ulLowPowerTimeBeforeSleep = ulGetExternalTime();/* Stop the timer that is generating the tick interrupt. */prvStopTickInterruptTimer();/* Configure an interrupt to bring the microcontroller out of its low powerstate at the time the kernel next needs to execute.  The interrupt must begenerated from a source that is remains operational when the microcontrolleris in a low power state. */vSetWakeTimeInterrupt( xExpectedIdleTime );/* Enter the low power state. */prvSleep();/* Determine how long the microcontroller was actually in a low power statefor, which will be less than xExpectedIdleTime if the microcontroller wasbrought out of low power mode by an interrupt other than that configured bythe vSetWakeTimeInterrupt() call.  Note that the scheduler is suspendedbefore portSUPPRESS_TICKS_AND_SLEEP() is called, and resumed whenportSUPPRESS_TICKS_AND_SLEEP() returns.  Therefore no other tasks willexecute until this function completes. */ulLowPowerTimeAfterSleep = ulGetExternalTime();/* Correct the kernels tick count to account for the time the microcontrollerspent in its low power state. */vTaskStepTick( ulLowPowerTimeAfterSleep - ulLowPowerTimeBeforeSleep );/* Restart the timer that is generating the tick interrupt. */prvStartTickInterruptTimer();
}

11- xTaskCatchUpTicks

task.h  
BaseType_t xTaskCatchUpTicks( TickType_t xTicksToCatchUp );

在应用程序代码长时间禁用中断后， 更正滴答计数值。 此函数与 vTaskStepTick() 类似， 但与 vTaskStepTick() 不同的是，此函数可以增加滴答计数， 使其超过应将任务从阻塞态中移除的时间。这意味着 xTaskCatchUpTicks() 可从 阻塞态中移除任务。

11.1 参数：

xTicksToCatchUp 由于中断被禁用而错过的滴答中断数。 此值不会自动计算， 必须由应用程序编写者计算。

11.2 Returns:

如果增加滴答计数，任务会解除阻塞态并执行上下文切换， 则返回 pdTRUE。 否则返回 pdFALSE。

11.3 用法示例：

void vExampleFunction( void )
{unsigned long ulTimeBefore, ulTimeAfter;/* Read the current time before arbitrary processing takes place. */ulTimeBefore = ulGetExternalTime();/* Stop the timer that is generating the tick interrupt. */prvStopTickInterruptTimer();/* Perform some arbitrary processing. */arbitrary_processing();/* Read the current time for computing elapsed time since ticks were disabled. */ulTimeAfter = ulGetExternalTime();if ( xTaskCatchUpTicks( ulTimeAfter - ulTimeBefore ) == pdTRUE ) {/* Moving the tick count forward resulted in a context switch. */}/* Restart the timer that is generating the tick interrupt. */prvStartTickInterruptTimer();}