1-任務產量

請求上下文切換到其他任務

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. h

void 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 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 退貨：

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 RTOS
     scheduler
     xTaskCreate( 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- vTask掛起全部

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 use
        taskENTER_CRITICAL()/taskEXIT_CRITICAL() as the length of the operation may
        cause 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-x任務簡歷全部

task. h
BaseType_t xTaskResumeAll（ void ）;

恢復通過調用 vTaskSuspendAll() 掛起的調度器。

xTaskResumeAll() 僅恢復調度器， 不會取消掛起 之前通過調用 vTaskSuspend() 而掛起的任務。

9.1 退貨：

如果恢復調度器導致了上下文切換，則返回 pdTRUE，否則返回 pdFALSE。

9.2 用法示例：

void vTask1( void * pvParameters )
 {
     for( ;; )
     {
         /* Task code goes here. */


         /* ... */


         /* At some point the task wants to perform a long operation
         during which it does not want to get swapped out.  It cannot
         use taskENTER_CRITICAL ()/taskEXIT_CRITICAL () as the length
         of 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 critical
         sections as we have all the microcontroller processing time.
         During this time interrupts will still operate and the real
         time RTOS kernel tick count will be maintained. */


         /* ... */


         /* The operation is complete.  Restart the RTOS kernel.  We want to force
         a context switch - but there is no point if resuming the scheduler
         caused a context switch already. */
         if( !xTaskResumeAll () )
         {
              taskYIELD ();
         }
     }
 }

10-vTaskStepTick

task. h
void 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 operational
    while 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 power
    state at the time the kernel next needs to execute.  The interrupt must be
    generated from a source that is remains operational when the microcontroller
    is in a low power state. */
    vSetWakeTimeInterrupt( xExpectedIdleTime );


    /* Enter the low power state. */
    prvSleep();


    /* Determine how long the microcontroller was actually in a low power state
    for, which will be less than xExpectedIdleTime if the microcontroller was
    brought out of low power mode by an interrupt other than that configured by
    the vSetWakeTimeInterrupt() call.  Note that the scheduler is suspended
    before portSUPPRESS_TICKS_AND_SLEEP() is called, and resumed when
    portSUPPRESS_TICKS_AND_SLEEP() returns.  Therefore no other tasks will
    execute until this function completes. */
    ulLowPowerTimeAfterSleep = ulGetExternalTime();


    /* Correct the kernels tick count to account for the time the microcontroller
    spent 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 退貨：

如果增加滴答計數，任務會解除阻塞態并執行上下文切換， 則返回 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();


}