Modules

xTaskGetCurrentTaskHandle

task.h

TaskHandle_t xTaskGetCurrentTaskHandle( void );

必須將INCLUDE_xTaskGetCurrentTaskHandle設置爲1才能使用此功能。

返回值：

當前正在運行（正在調用）的任務的句柄。

xTaskGetIdleTaskHandle

task.h

TaskHandle_t xTaskGetIdleTaskHandle( void );

必須將INCLUDE_xTaskGetIdleTaskHandle設置爲1才能使用此功能。

返回值：

與空閒任務關聯的任務句柄。啓動RTOS計劃程序時，將自動創建空閒任務。

eTaskGetState

task.h

eTaskState eTaskGetState( TaskHandle_t xTask );

以枚舉類型返回執行eTaskGetState（）時任務存在的狀態。

必須在FreeRTOSConfig.h中將INCLUDE_eTaskGetState設置爲1，eTaskGetState（）纔可用。

另請參見vTaskGetInfo（）。

參數：

xTask

主題任務（正在查詢的任務）的句柄。

返回值：

下表列出了eTaskGetState（）將針對xTask參數引用的任務可能存在的每個可能狀態返回的值。

State	Returned Value
Ready	eReady
Running	eRunning（調用任務正在查詢自己的優先級）
Blocked	eBlocked
Suspended	eSuspended
Deleted	eDeleted（TCB的任務正在等待清理）

pcTaskGetName

task.h

char * pcTaskGetName( TaskHandle_t xTaskToQuery );

從任務的句柄中查找任務的名稱。

參數：

xTaskToQuery

正在查詢任務的句柄。可以將xTaskToQuery設置爲NULL來查詢調用任務的名稱。

返回值：

指向主題任務名稱的指針，該名稱是標準的以NULL結尾的C字符串。

xTaskGetHandle

task.h

TaskHandle_t xTaskGetHandle( const char *pcNameToQuery );

從任務名稱中查找任務的句柄。

注意：此功能需要相對較長的時間才能完成，並且每個任務只能調用一次。一旦獲得任務的句柄，就可以將其存儲在本地以供重複使用。

必須將FreeRTOSConfig.h中的INCLUDE_xTaskGetHandle設置爲1，才能使xTaskGetHandle（）可用。

參數：

pcNameToQuery

將爲其返回句柄的任務的文本名稱（作爲標準的C NULL終止字符串）。

有關設置任務文本名稱的信息，請參見xTaskCreate（）和xTaskCreateStatic（）API函數的pcName參數。

返回值：

如果可以找到具有在pcNameToQuery中傳遞的名稱的任務，則返回任務的句柄，否則返回NULL。

xTaskGetTickCount

task.h

volatile TickType_t xTaskGetTickCount( void );

無法從ISR調用此函數。改用xTaskGetTickCountFromISR（）。

返回值：

自調用vTaskStartScheduler以來的滴答計數。

xTaskGetTickCountFromISR

task.h

volatile TickType_t xTaskGetTickCountFromISR( void );

可以從ISR調用的xTaskGetTickCount（）版本。

返回值：

自調用vTaskStartScheduler以來的滴答計數。

xTaskGetSchedulerState

task.h

BaseType_t xTaskGetSchedulerState( void );

返回值：

以下常量之一（在task.h中定義）：taskSCHEDULER_NOT_STARTED，taskSCHEDULER_RUNNING，taskSCHEDULER_SUSPENDED。

要使此功能可用，必須在FreeRTOSConfig.h中將INCLUDE_xTaskGetSchedulerState或configUSE_TIMERS設置爲1。

uxTaskGetNumberOfTasks

task.h

UBaseType_t uxTaskGetNumberOfTasks( void );

返回值：

RTOS內核當前正在管理的任務數。這包括所有準備就緒，已阻止和已暫停的任務。空閒任務已刪除但尚未釋放的任務也將包括在計數中。

vTaskList

task.h

void vTaskList( char *pcWriteBuffer );

要使此功能可用，必須在FreeRTOSConfig.h中將configUSE_TRACE_FACILITY和configUSE_STATS_FORMATTING_FUNCTIONS定義爲1。有關更多信息，請參見配置部分。

注意：此功能將在其持續時間內禁用中斷。它不適合正常的應用程序運行時使用，而是作爲調試輔助。

vTaskList（）調用uxTaskGetSystemState（），然後將uxTaskGetSystemState（）生成的原始數據格式化爲人類可讀（ASCII）表，該表顯示每個任務的狀態，包括任務堆棧的高水位標記（高水位標記越小，任務越接近其堆棧溢出）。單擊此處查看生成的輸出示例。

在ASCII表中，以下字母用於表示任務的狀態：

“ B” –已屏蔽
“ R” –準備就緒
“ D”-已刪除（正在等待清理）
“ S” –暫停或被阻止，沒有超時

vTaskList（）是僅出於方便目的而提供的實用程序函數。它不被視爲內核的一部分。有關實用程序函數的信息，請參見vTaskGetRunTimeStats（），該實用程序函數會生成類似的運行時任務利用率信息表。

參數：

pcWriteBuffer

將上述詳細信息寫入ASCII格式的緩衝區。假定此緩衝區足夠大以包含生成的報告。每個任務大約40個字節就足夠了。

vTaskStartTrace

task.h

void vTaskStartTrace( char * pcBuffer, unsigned long ulBufferSize );

【此功能與FreeRTOS V7.1.0中已刪除的舊版跟蹤實用程序有關，用戶可能會發現更易於使用且功能更強大的更新的跟蹤掛鉤宏。】

啓動RTOS內核活動跟蹤。跟蹤記錄何時運行哪個任務的標識。

跟蹤文件以二進制格式存儲。單獨的DOS實用程序convtrce.exe可用於將其轉換爲製表符分隔的文本文件，該文件可在電子表格中查看和繪製。

參數：

pcBuffer	跟蹤將寫入其中的緩衝區。
ulBufferSize	pcBuffer的大小（以字節爲單位）。跟蹤將一直持續到緩衝區已滿或調用ulTaskEndTrace（）爲止。

ulTaskEndTrace

task.h

unsigned long ulTaskEndTrace( void );

【此功能與FreeRTOS V7.1.0中已刪除的舊版跟蹤實用程序有關，用戶可能會發現更易於使用且功能更強大的更新的跟蹤掛鉤宏。】

停止RTOS內核活動跟蹤。請參見vTaskStartTrace（）。

返回值：

已寫入跟蹤緩衝區的字節數。

vTaskGetRunTimeStats

task.h

void vTaskGetRunTimeStats( char *pcWriteBuffer );

有關此功能的完整說明，請參見“運行時統計”頁面。

爲了使此功能可用，必須將configGENERATE_RUN_TIME_STATS和configUSE_STATS_FORMATTING_FUNCTIONS都定義爲1。然後，應用程序還必須提供portCONFIGURE_TIMER_FOR_RUN_TIME_STATS（）和portGET_RUN_TIME_COUNTER_VALUE的定義，以配置外設定時器/計數器並分別返回定時器的當前計數值。計數器應至少是滴答計數頻率的10倍。

注意：此功能將在其持續時間內禁用中斷。它不適合正常的應用程序運行時使用，而是作爲調試輔助。

vTaskGetRunTimeStats（）調用uxTaskGetSystemState（），然後將uxTaskGetSystemState（）生成的原始數據格式化爲人類可讀（ASCII）表，該表顯示每個任務在運行狀態下所花費的時間（每個任務所消耗的CPU時間）。數據以絕對值和百分比值形式提供。絕對值的分辨率取決於應用程序提供的運行時統計時鐘的頻率。

vTaskGetRunTimeStats（）是僅出於方便目的而提供的實用程序函數。它不被視爲內核的一部分。有關生成每個任務狀態信息的實用程序功能，請參見vTaskList（）。

參數：

pcWriteBuffer

執行時間將以ASCII形式寫入的緩衝區。假定此緩衝區足夠大以包含生成的報告。每個任務大約40個字節就足夠了。

vTaskGetIdleRunTimeCounter

task.h

TickType_t xTaskGetIdleRunTimeCounter( void );

返回空閒任務的運行時計數器。此功能可用於確定空閒任務接收了多少CPU時間。有關運行時狀態功能的完整說明，請參見“運行時狀態”頁面。

爲了使該功能可用，必須將configGENERATE_RUN_TIME_STATS和INCLUDE_xTaskGetIdleTaskHandle都定義爲1。然後，應用程序還必須提供portCONFIGURE_TIMER_FOR_RUN_TIME_STATS（）和portGET_RUN_TIME_COUNTER_VALUE的定義，以配置外設定時器/計數器並分別返回定時器的當前計數值。建議使計時器至少是滴答計數頻率的10倍。

vTaskSetApplicationTaskTag

task. h

void vTaskSetApplicationTaskTag(
                        TaskHandle_t xTask,
                        TaskHookFunction_t pxTagValue );

必須將configUSE_APPLICATION_TASK_TAG定義爲1，此功能才能使用。有關更多信息，請參見RTOS配置文檔。

可以爲每個任務分配一個“標籤”值。該值僅用於應用程序– RTOS內核本身不以任何方式使用它。 RTOS跟蹤宏文檔頁面提供了一個很好的示例，說明應用程序如何使用此功能。

參數：

xTask	爲其分配了標籤值的任務的句柄。將xTask傳遞爲NULL會將標記分配給調用任務。
pxTagValue	分配給任務標籤的值。這是TaskHookFunction_t類型，允許將功能指針分配爲標籤，儘管實際上可以分配任何值。請參見下面的示例。

用法示例：

/* In this example an integer is set as the task tag value.  
See the RTOS trace hook macros documentation page for an
example how such an assignment can be used. */
void vATask( void *pvParameters )
{
  /* Assign a tag value of 1 to myself. */
  vTaskSetApplicationTaskTag( NULL, ( void * ) 1 );

  for( ;; )
  {
    /* Rest of task code goes here. */
  }
}
/***********************************************/

/* In this example a callback function is being assigned as the task tag.
First define the callback function - this must have type TaskHookFunction_t
as per this example. */
static BaseType_t prvExampleTaskHook( void * pvParameter )
{
  /* Perform some action - this could be anything from logging a value,
  updating the task state, outputting a value, etc. */

  return 0;
}


/* Now define the task that sets prvExampleTaskHook as its hook/tag value.
This is in fact registering the task callback, as described on the
xTaskCallApplicationTaskHook() documentation page. */
void vAnotherTask( void *pvParameters )
{
  /* Register our callback function. */
  vTaskSetApplicationTaskTag( NULL, prvExampleTaskHook );

  for( ;; )
  {
    /* Rest of task code goes here. */
  }
}

/* As an example use of the hook (callback) we can get the RTOS kernel to call the
hook function of each task that is being switched out during a reschedule. */
#define traceTASK_SWITCHED_OUT() xTaskCallApplicationTaskHook( pxCurrentTCB, 0 )

xTaskCallApplicationTaskHook

task. h

BaseType_t xTaskCallApplicationTaskHook( TaskHandle_t xTask, void *pvParameter );

必須將configUSE_APPLICATION_TASK_TAG定義爲1，此功能才能使用。有關更多信息，請參見RTOS配置文檔。

可以爲每個任務分配一個“標籤”值。通常，此值僅供應用程序使用，RTOS內核不會訪問它。但是，可以使用標記將鉤子（或回調）函數分配給任務-通過調用xTaskCallApplicationTaskHook（）執行鉤子函數。每個任務可以定義自己的回調，也可以根本不定義回調。

儘管可以使用第一個函數參數來調用任何任務的鉤子函數，但是任務鉤子函數最常見的用法是使用跟蹤鉤子宏，如以下示例所示。

任務掛鉤函數必須具有TaskHookFunction_t類型，即帶有void *參數，並返回BaseType_t類型的值。 void *參數可用於將任何信息傳遞給hook函數。

參數：

xTask	正在調用其掛鉤函數的任務的句柄。將NULL作爲xTask傳遞時，將調用與當前正在執行的任務相關聯的hook函數。
pvParameter	傳遞給掛鉤函數的值。這可以是指向結構的指針，也可以只是數字值。

用法示例：

/* In this example a callback function is being assigned as the task tag.
First define the callback function - this must have type TaskHookFunction_t
as per this example. */
static BaseType_t prvExampleTaskHook( void * pvParameter )
{
   /* Perform some action - this could be anything from logging a value,
   updating the task state, outputting a value, etc. */

   return 0;
}

/* Now define the task that sets prvExampleTaskHook as its hook/tag value.
This is in fact registering the task callback, as described on the
xTaskCallApplicationTaskHook() documentation page. */
void vAnotherTask( void *pvParameters )
{
   /* Register our callback function. */
   vTaskSetApplicationTaskTag( NULL, prvExampleTaskHook );

   for( ;; )
   {
      /* Rest of task code goes here. */
   }
}


/* As an example use of the hook (callback) we can get the RTOS kernel to
call the hook function of each task that is being switched out during a
reschedule. */
#define traceTASK_SWITCHED_OUT() xTaskCallApplicationTaskHook( pxCurrentTCB, 0 )

vTaskSetThreadLocalStoragePointer

task. h

void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet,
                                        BaseType_t xIndex,
                                        void *pvValue )

在任務的線程本地存儲陣列中設置一個值。

此功能僅適用於高級用戶。

參數：

xTaskToSet

線程本地數據正在寫入的任務的句柄。通過使用NULL作爲參數值，任務可以寫入其自己的線程本地數據。

xIndex

線程本地存儲陣列中要寫入數據的索引。

可用數組索引的數量由FreeRTOSConfig.h中的configNUM_THREAD_LOCAL_STORAGE_POINTERS編譯時配置常量設置。

pvValue

要寫入由xIndex參數指定的索引的值。

用法示例：

請參閱線程本地存儲陣列文檔頁面上提供的示例。

pvTaskGetThreadLocalStoragePointer

task. h

void *pvTaskGetThreadLocalStoragePointer(
                                 TaskHandle_t xTaskToQuery,
                                 BaseType_t xIndex );

從任務的線程本地存儲陣列中檢索值。

此功能僅適用於高級用戶。

參數：

xTaskToQuery

從中讀取線程本地數據的任務的句柄。通過使用NULL作爲參數值，任務可以讀取自己的線程本地數據。

xIndex

到線程本地存儲陣列中的索引，將從中讀取數據。

可用數組索引的數量由FreeRTOSConfig.h中的configNUM_THREAD_LOCAL_STORAGE_POINTERS編譯時配置常量設置。

返回值：

存儲在任務xTaskToQuery的線程本地存儲數組的索引位置xIndex中的值。

用法示例：

請參閱線程本地存儲陣列文檔頁面上提供的示例。

vTaskSetTimeOutState()

task.h

void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut );

此功能僅適用於高級用戶。

任務可以進入阻止狀態以等待事件。通常，任務不會無限期地處於“阻塞”狀態，而是將指定超時期限。如果超時時間在任務等待事件發生之前到期，則該任務將從“阻塞”狀態中刪除。

如果任務在等待事件發生時多次進入和退出“阻止”狀態，則必須調整每次任務進入“阻止”狀態所用的超時時間，以確保在“阻止”狀態下花費的所有時間總計不超過最初指定的超時期限。 xTaskCheckForTimeOut（）執行調整時要考慮偶發計數溢出之類的偶發事件，否則這會使手動調整容易出錯。

vTaskSetTimeOutState（）與xTaskCheckForTimeOut（）一起使用。調用vTaskSetTimeOutState（）設置初始條件，之後可以調用xTaskCheckForTimeOut（）來檢查超時條件，並在未發生超時的情況下調整剩餘的塊時間。

參數：

pxTimeOut

指向結構的指針，該結構將被初始化以保存確定是否發生超時所必需的信息。

用法示例：

xTaskCheckForTimeOut（）文檔頁面上提供了一個示例。

xTaskCheckForTimeOut()

task.h

BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut,
                                 TickType_t * const pxTicksToWait );

此功能僅適用於高級用戶。

xTaskCheckForTimeOut（）與vTaskSetTimeOutState（）一起使用。調用vTaskSetTimeOutState（）設置初始條件，之後可以調用xTaskCheckForTimeOut（）來檢查超時條件，並在未發生超時的情況下調整剩餘的塊時間。

參數：

pxTimeOut	指向結構的指針，該結構保存確定是否發生超時所需的信息。使用vTaskSetTimeOutState（）初始化pxTimeOut。
pxTicksToWait	用於傳遞調整後的阻止時間，這是考慮到已經處於“阻止”狀態的時間之後剩餘的阻止時間。

返回值：

如果返回pdTRUE，則沒有塊時間剩餘，並且發生了超時。

如果返回pdFALSE，則剩餘一些塊時間，因此不會發生超時。

用法示例：

/* Driver library function used to receive uxWantedBytes from an Rx buffer that
is filled by a UART interrupt.  If there are not enough bytes in the Rx buffer
then the task enters the Blocked state until it is notified that more data has
been placed into the buffer.  If there is still not enough data then the task
re-enters the Blocked state, and xTaskCheckForTimeOut() is used to re-calculate
the Block time to ensure the total amount of time spent in the Blocked state does
not exceed MAX_TIME_TO_WAIT. This continues until either the buffer contains at
least uxWantedBytes bytes, or the total amount of time spent in the Blocked state
reaches MAX_TIME_TO_WAIT – at which point the task reads however many bytes are
available up to a maximum of uxWantedBytes. */
size_t xUART_Receive( uint8_t *pucBuffer, size_t uxWantedBytes )
{
size_t uxReceived = 0;
TickType_t xTicksToWait = MAX_TIME_TO_WAIT;
TimeOut_t xTimeOut;


   /* Initialize xTimeOut.  This records the time at which this function was
   entered. */
   vTaskSetTimeOutState( &xTimeOut );


   /* Loop until the buffer contains the wanted number of bytes, or a timeout
   occurs. */
   while( UART_bytes_in_rx_buffer( pxUARTInstance ) < uxWantedBytes )
   {
      /* The buffer didn't contain enough data so this task is going to
      enter the Blocked state.  Adjusting xTicksToWait to account for any time
      that has been spent in the Blocked state within this function so far to
      ensure the total amount of time spent in the Blocked state does not exceed
      MAX_TIME_TO_WAIT. */
      if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) != pdFALSE )
      {
         /* Timed out before the wanted number of bytes were available, exit the
         loop. */
         break;
      }


      /* Wait for a maximum of xTicksToWait ticks to be notified that the receive
      interrupt has placed more data into the buffer. */
      ulTaskNotifyTake( pdTRUE, xTicksToWait );
   }


   /* Attempt to read uxWantedBytes from the receive buffer into pucBuffer.  The
   actual number of bytes read (which might be less than uxWantedBytes) is
   returned. */
   uxReceived = UART_read_from_receive_buffer( pxUARTInstance,
                                               pucBuffer,
                                               uxWantedBytes );



   return uxReceived;
}

FreeRTOS API參考——任務實用程序

Modules

xTaskGetCurrentTaskHandle

xTaskGetIdleTaskHandle

eTaskGetState

pcTaskGetName

xTaskGetHandle

xTaskGetTickCount

xTaskGetTickCountFromISR

xTaskGetSchedulerState

uxTaskGetNumberOfTasks

vTaskList

vTaskStartTrace

ulTaskEndTrace

vTaskGetRunTimeStats

vTaskGetIdleRunTimeCounter

vTaskSetApplicationTaskTag

xTaskCallApplicationTaskHook

vTaskSetThreadLocalStoragePointer

pvTaskGetThreadLocalStoragePointer

vTaskSetTimeOutState()

xTaskCheckForTimeOut()

一步一步來：MQTT服務器搭建、MQTT客戶端使用

FreeRTOS API參考——任務實用程序

iBeacon廣播數據格式

FreeRTOS API參考——內核控制

iBeacon入門

https://yachay.unat.edu.pe/blog/index.php?comment_area=format_blog&comment_component=blog&comment_co

linux以太網驅動總結