目錄
xQueueCreate
QueueHandle_t xQueueCreate( UBaseType_t uxQueueLength,
UBaseType_t uxItemSize );
創建一個新隊列並返回一個句柄，通過該句柄可以引用該隊列。 要使 此RTOS API函數可用，必須在FreeRTOSConfig.h 中將configSUPPORT_DYNAMIC_ALLOCATION設置爲1，或將其保留爲未定義狀態（在這種情況下，它將默認爲1）。
每個隊列都需要RAM，該RAM用於保存隊列狀態以及保存隊列（隊列存儲區域）中包含的項目。如果使用xQueueCreate（）創建了隊列，則從FreeRTOS堆中自動分配所需的RAM 。如果使用xQueueCreateStatic（）創建隊列 ，則應用程序編寫器將提供RAM，這會導致大量參數，但允許在編譯時靜態分配RAM。有關更多信息，請參見靜態與動態分配頁面。
參數：
| uxQueueLength | 隊列一次可以容納的最大項目數。 |
| uxItemSize | 存放隊列中每個項目所需的大小（以字節爲單位）。
項目按副本而不是引用排隊，因此這是將爲每個排隊的項目複製的字節數。隊列中的每個項目都必須具有相同的大小。 |
返回值：
如果隊列創建成功，則返回創建隊列的句柄。如果無法分配創建隊列所需的內存，則返回NULL。
用法示例：
struct AMessage
{
char ucMessageID;
char ucData[ 20 ];
};
void vATask( void *pvParameters )
{
QueueHandle_t xQueue1, xQueue2;
/* Create a queue capable of containing 10 unsigned long values. */
xQueue1 = xQueueCreate( 10, sizeof( unsigned long ) );
if( xQueue1 == NULL )
{
/* Queue was not created and must not be used. */
}
/* Create a queue capable of containing 10 pointers to AMessage
structures. These are to be queued by pointers as they are
relatively large structures. */
xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
if( xQueue2 == NULL )
{
/* Queue was not created and must not be used. */
}
/* ... Rest of task code. */
}
xQueueCreateStatic
QueueHandle_t xQueueCreateStatic(
UBaseType_t uxQueueLength,
UBaseType_t uxItemSize,
uint8_t *pucQueueStorageBuffer,
StaticQueue_t *pxQueueBuffer );
創建一個新隊列並返回一個句柄，通過該句柄可以引用該隊列。 必須在FreeRTOSConfig.h 中將configSUPPORT_STATIC_ALLOCATION設置爲1，此RTOS API函數纔可用。
每個隊列都需要RAM，該RAM用於保存隊列狀態以及保存隊列（隊列存儲區域）中包含的項目。v則此RAM是從FreeRTOS堆中自動分配的。如果使用xQueueCreateStatic（）創建隊列，則應用程序編寫器將提供RAM，這會導致大量參數，但允許在編譯時靜態分配RAM。有關更多信息，請參見靜態與動態分配頁面。
參數：
| uxQueueLength | 隊列一次可以容納的最大項目數。 |
| uxItemSize | 存放隊列中每個項目所需的大小（以字節爲單位）。
項目按副本而不是引用排隊，因此這是將爲每個排隊的項目複製的字節數。隊列中的每個項目都必須具有相同的大小。 |
| pucQueueStorageBuffer | 如果uxItemSize不爲零，則pucQueueStorageBuffer必須指向一個uint8_t數組，該數組至少足夠大以容納一次可以存在於隊列中的最大項目數，即（uxQueueLength * uxItemSize）字節。如果uxItemSize爲零，則pucQueueStorageBuffer可以爲NULL。 |
| pxQueueBuffer | 必須指向類型爲StaticQueue_t的變量，該變量將用於保存隊列的數據結構。 |
返回值：
如果隊列創建成功，則返回創建隊列的句柄。如果pxQueueBuffer爲NULL，則返回NULL。
用法示例：
/* The queue is to be created to hold a maximum of 10 uint64_t
variables. */
#define QUEUE_LENGTH 10
#define ITEM_SIZE sizeof( uint64_t )
/* The variable used to hold the queue's data structure. */
static StaticQueue_t xStaticQueue;
/* The array to use as the queue's storage area. This must be at least
uxQueueLength * uxItemSize bytes. */
uint8_t ucQueueStorageArea[ QUEUE_LENGTH * ITEM_SIZE ];
void vATask( void *pvParameters )
{
QueueHandle_t xQueue;
/* Create a queue capable of containing 10 uint64_t values. */
xQueue = xQueueCreateStatic( QUEUE_LENGTH,
ITEM_SIZE,
ucQueueStorageArea,
&xStaticQueue );
/* pxQueueBuffer was not NULL so xQueue should not be NULL. */
configASSERT( xQueue );
}
xQueueSend
BaseType_t xQueueSend( QueueHandle_t xQueue, const void * pvItemToQueue, TickType_t xTicksToWait );
這是一個調用xQueueGenericSend（）的宏。包含它是爲了與不包含xQueueSendToFront（）和xQueueSendToBack（）宏的FreeRTOS版本向後兼容。它等效於xQueueSendToBack（）。
將項目發佈到隊列中。該項目按副本而不是參考排隊。不得從中斷服務程序中調用此函數。有關在ISR中可以使用的替代方法，請參見See xQueueSendFromISR()。
參數：
| xQueue | 要在其上發佈項目的隊列的句柄。 |
| pvItemToQueue | 指向要放在隊列中的項目的指針。創建隊列時已定義了隊列將要容納的項目的大小，因此，這許多字節將從pvItemToQueue複製到隊列存儲區域。 |
| xTicksToWait | 如果任務已滿，則該任務應阻止等待空間在隊列上可用的最長時間。如果隊列已滿並且xTicksToWait設置爲0，則調用將立即返回。時間以滴答週期定義，因此如果需要，應使用常數portTICK_PERIOD_MS轉換爲實時。如果將INCLUDE_vTaskSuspend設置爲'1'，則將阻止時間指定爲portMAX_DELAY將導致任務無限期地阻止（無超時）。 |
返回：如果項目已成功發佈，則返回 pdTRUE，否則返回errQUEUE_FULL。
用法示例：
struct AMessage
{
char ucMessageID;
char ucData[ 20 ];
} xMessage;
unsigned long ulVar = 10UL;
void vATask( void *pvParameters )
{
QueueHandle_t xQueue1, xQueue2;
struct AMessage *pxMessage;
/* Create a queue capable of containing 10 unsigned long values. */
xQueue1 = xQueueCreate( 10, sizeof( unsigned long ) );
/* Create a queue capable of containing 10 pointers to AMessage structures.
These should be passed by pointer as they contain a lot of data. */
xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
/* ... */
if( xQueue1 != 0 )
{
/* Send an unsigned long. Wait for 10 ticks for space to become
available if necessary. */
if( xQueueSend( xQueue1,
( void * ) &ulVar,
( TickType_t ) 10 ) != pdPASS )
{
/* Failed to post the message, even after 10 ticks. */
}
}
if( xQueue2 != 0 )
{
/* Send a pointer to a struct AMessage object. Don't block if the
queue is already full. */
pxMessage = & xMessage;
xQueueSend( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 );
}
/* ... Rest of task code. */
}
xQueueSendFromISR
BaseType_t xQueueSendFromISR ( QueueHandle_t xQueue, const void *pvItemToQueue, BaseType_t *pxHigherPriorityTaskWoken );
這是一個調用xQueueGenericSendFromISR（）的宏。包含它是爲了與不包含xQueueSendToBackFromISR（）和xQueueSendToFrontFromISR（）宏的FreeRTOS版本向後兼容。
將項目發佈到隊列的後面。在中斷服務程序中可以安全地使用此功能。
項目通過複製而不是引用進行排隊，因此最好僅將小項目排隊，尤其是從ISR調用時。在大多數情況下，最好存儲一個指向正在排隊的項目的指針。
參數：
| xQueue | 要在其上發佈項目的隊列的句柄。 |
| pvItemToQueue | 指向要放在隊列中的項目的指針。創建隊列時已定義了隊列將要容納的項目的大小，因此，這許多字節將從pvItemToQueue複製到隊列存儲區域。 |
| pxHigherPriorityTaskWoken | 如果發送到隊列導致任務取消阻止，並且未阻止任務的優先級高於當前運行的任務，則xQueueSendFromISR（）將* pxHigherPriorityTaskWoken設置爲pdTRUE。如果xQueueSendFromISR（）將此值設置爲pdTRUE，則應在退出中斷之前請求上下文切換。
從FreeRTOS V7.3.0開始，pxHigherPriorityTaskWoken是可選參數，可以設置爲NULL。 |
返回值：
如果數據已成功發送到隊列，則爲pdTRUE，否則爲errQUEUE_FULL。
緩衝IO的示例用法（ISR每次調用可以獲得多個值）：
void vBufferISR( void )
{
char cIn;
BaseType_t xHigherPriorityTaskWoken;
/* We have not woken a task at the start of the ISR. */
xHigherPriorityTaskWoken = pdFALSE;
/* Loop until the buffer is empty. */
do
{
/* Obtain a byte from the buffer. */
cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
/* Post the byte. */
xQueueSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
} while( portINPUT_BYTE( BUFFER_COUNT ) );
/* Now the buffer is empty we can switch context if necessary. */
if( xHigherPriorityTaskWoken )
{
/* Actual macro used here is port specific. */
taskYIELD_FROM_ISR ();
}
}
xQueueSendToBack
BaseType_t xQueueSendToBack( QueueHandle_t xQueue, const void * pvItemToQueue, TickType_t xTicksToWait );
這是一個調用xQueueGenericSend（）的宏。它等效於xQueueSend（）。
將項目發佈到隊列的後面。該項目按副本而不是參考排隊。不得從中斷服務程序中調用此函數。有關在ISR中可以使用的替代方法，請參見xQueueSendToBackFromISR（）。
參數：
| xQueue | 要在其上發佈項目的隊列的句柄。 |
| pvItemToQueue | 指向要放在隊列中的項目的指針。創建隊列時已定義了隊列將要容納的項目的大小，因此，這許多字節將從pvItemToQueue複製到隊列存儲區域。 |
| xTicksToWait | 如果任務已滿，則該任務應阻止等待空間在隊列上可用的最長時間。如果將其設置爲0，則調用將立即返回。時間以滴答週期定義，因此如果需要，應使用常數portTICK_PERIOD_MS轉換爲實時。如果將INCLUDE_vTaskSuspend設置爲'1'，則將阻止時間指定爲portMAX_DELAY將導致任務無限期地阻止（無超時）。 |
返回值：
如果項目已成功發佈，則爲pdTRUE，否則爲errQUEUE_FULL。
用法示例：
struct AMessage
{
char ucMessageID;
char ucData[ 20 ];
} xMessage;
unsigned long ulVar = 10UL;
void vATask( void *pvParameters )
{
QueueHandle_t xQueue1, xQueue2;
struct AMessage *pxMessage;
/* Create a queue capable of containing 10 unsigned long values. */
xQueue1 = xQueueCreate( 10, sizeof( unsigned long ) );
/* Create a queue capable of containing 10 pointers to AMessage
structures. These should be passed by pointer as they contain a lot of
data. */
xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
/* ... */
if( xQueue1 != 0 )
{
/* Send an unsigned long. Wait for 10 ticks for space to become
available if necessary. */
if( xQueueSendToBack( xQueue1,
( void * ) &ulVar,
( TickType_t ) 10 ) != pdPASS )
{
/* Failed to post the message, even after 10 ticks. */
}
}
if( xQueue2 != 0 )
{
/* Send a pointer to a struct AMessage object. Don't block if the
queue is already full. */
pxMessage = & xMessage;
xQueueSendToBack( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 );
}
/* ... Rest of task code. */
}
xQueueSendToBackFromISR
BaseType_t xQueueSendToBackFromISR
(
QueueHandle_t xQueue,
const void *pvItemToQueue,
BaseType_t *pxHigherPriorityTaskWoken
);
這是一個調用xQueueGenericSendFromISR（）的宏。
將項目發佈到隊列的後面。在中斷服務程序中可以安全地使用此功能。
項目通過複製而不是引用進行排隊，因此最好僅將小項目排隊，尤其是從ISR調用時。
參數：
| xQueue | 要在其上發佈項目的隊列的句柄。 |
| pvItemToQueue | 指向要放在隊列中的項目的指針。創建隊列時已定義了隊列將要容納的項目的大小，因此，這許多字節將從pvItemToQueue複製到隊列存儲區域。 |
| pxHigherPriorityTaskWoken | 如果發送到隊列導致任務取消阻止，並且未阻止的任務的優先級高於當前運行的任務，則xQueueSendTobackFromISR（）會將* pxHigherPriorityTaskWoken設置爲pdTRUE。如果xQueueSendToBackFromISR（）將此值設置爲pdTRUE，則應在退出中斷之前請求上下文切換。
從FreeRTOS V7.3.0開始，pxHigherPriorityTaskWoken是可選參數，可以設置爲NULL。 |
返回值：
如果發送到隊列成功，則爲pdPASS，否則爲errQUEUE_FULL。
緩衝IO的示例用法（ISR每次調用可以獲得多個值）：
void vBufferISR( void )
{
char cIn;
BaseType_t xHigherPriorityTaskWoken;
/* We have not woken a task at the start of the ISR. */
xHigherPriorityTaskWoken = pdFALSE;
/* Loop until the buffer is empty. */
do
{
/* Obtain a byte from the buffer. */
cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
/* Post the byte. */
xQueueSendToBackFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
} while( portINPUT_BYTE( BUFFER_COUNT ) );
/* Now the buffer is empty we can switch context if necessary. */
if( xHigherPriorityTaskWoken )
{
/* Actual macro used here is port specific. */
taskYIELD_FROM_ISR ();
}
}
xQueueSendToFront
BaseType_t xQueueSendToFront( QueueHandle_t xQueue,
const void * pvItemToQueue,
TickType_t xTicksToWait );
這是一個調用xQueueGenericSend（）的宏。
將項目發佈到隊列的最前面。該項目按副本而不是參考排隊。不得從中斷服務程序中調用此函數。有關可以在ISR中使用的替代方法，請參見xQueueSendToFrontFromISR（）。
參數：
| xQueue | 要在其上發佈項目的隊列的句柄。 |
| pvItemToQueue | 指向要放在隊列中的項目的指針。創建隊列時已定義了隊列將要容納的項目的大小，因此，這許多字節將從pvItemToQueue複製到隊列存儲區域。 |
| xTicksToWait | 如果任務已滿，則該任務應阻止等待空間在隊列上可用的最長時間。如果將其設置爲0，則調用將立即返回。時間以滴答週期定義，因此如果需要，應使用常數portTICK_PERIOD_MS轉換爲實時。
如果將INCLUDE_vTaskSuspend設置爲'1'，則將阻止時間指定爲portMAX_DELAY將導致任務無限期地阻止（無超時）。 |
返回值：
如果項目已成功發佈，則爲pdTRUE，否則爲errQUEUE_FULL。
用法示例：
struct AMessage
{
char ucMessageID;
char ucData[ 20 ];
} xMessage;
unsigned long ulVar = 10UL;
void vATask( void *pvParameters )
{
QueueHandle_t xQueue1, xQueue2;
struct AMessage *pxMessage;
/* Create a queue capable of containing 10 unsigned long values. */
xQueue1 = xQueueCreate( 10, sizeof( unsigned long ) );
/* Create a queue capable of containing 10 pointers to AMessage
structures. These should be passed by pointer as they contain a lot of
data. */
xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
/* ... */
if( xQueue1 != 0 )
{
/* Send an unsigned long. Wait for 10 ticks for space to become
available if necessary. */
if( xQueueSendToFront( xQueue1,
( void * ) &ulVar,
( TickType_t ) 10 ) != pdPASS )
{
/* Failed to post the message, even after 10 ticks. */
}
}
if( xQueue2 != 0 )
{
/* Send a pointer to a struct AMessage object. Don't block if the
queue is already full. */
pxMessage = & xMessage;
xQueueSendToFront( xQueue2, ( void * ) &pxMessage, ( TickType_t ) 0 );
}
/* ... Rest of task code. */
}
xQueueSendToFrontFromISR
BaseType_t xQueueSendToFrontFromISR
(
QueueHandle_t xQueue,
const void *pvItemToQueue,
BaseType_t *pxHigherPriorityTaskWoken
);
這是一個調用xQueueGenericSendFromISR（）的宏。
將項目發佈到隊列的最前面。在中斷服務程序中可以安全地使用此功能。
通過複製而不是引用將項目排隊，因此最好只發送小項目，或者發送指向該項目的指針。
參數：
| xQueue | 要在其上發佈項目的隊列的句柄。 |
| pvItemToQueue | 指向要放在隊列中的項目的指針。創建隊列時已定義了隊列將要容納的項目的大小，因此，這許多字節將從pvItemToQueue複製到隊列存儲區域。 |
| pxHigherPriorityTaskWoken | 如果發送到隊列導致任務取消阻止，並且未阻止任務的優先級高於當前運行的任務，則xQueueSendToFrontFromISR（）會將* pxHigherPriorityTaskWoken設置爲pdTRUE。如果xQueueSendToFrontFromISR（）將此值設置爲pdTRUE，則應在退出中斷之前請求上下文切換。
從FreeRTOS V7.3.0開始，pxHigherPriorityTaskWoken是可選參數，可以設置爲NULL。 |
返回值：
如果數據已成功發送到隊列，則爲pdPass，否則爲errQUEUE_FULL。
用法示例：
void vBufferISR( void )
{
char cIn;
BaseType_t xHigherPriorityTaskWoken;
/* We have not woken a task at the start of the ISR. */
xHigherPriorityTaskWoken = pdFALSE;
/* Obtain a byte from the buffer. */
cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
if( cIn == EMERGENCY_MESSAGE )
{
/* Post the byte to the front of the queue. */
xQueueSendToFrontFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
}
else
{
/* Post the byte to the back of the queue. */
xQueueSendToBackFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
}
/* Did sending to the queue unblock a higher priority task? */
if( xHigherPriorityTaskWoken )
{
/* Actual macro used here is port specific. */
taskYIELD_FROM_ISR ();
}
}
xQueueReceive
BaseType_t xQueueReceive(
QueueHandle_t xQueue,
void *pvBuffer,
TickType_t xTicksToWait
);
這是一個調用xQueueGenericReceive（）函數的宏。
從隊列中接收項目。該項目以副本形式接收，因此必須提供足夠大小的緩衝區。創建隊列時定義了複製到緩衝區中的字節數。
不得在中斷服務程序中使用此功能。另請參見xQueueReceiveFromISR。
參數：
| xQueue | 從中接收項目的隊列的句柄。 |
| pvBuffer | 指向將接收的項目複製到其中的緩衝區的指針。 |
| xTicksToWait | 如果在調用時隊列爲空，任務應等待等待接收項目的最長時間。如果隊列爲空，則將xTicksToWait設置爲0將導致該函數立即返回。時間以滴答週期定義，因此如果需要，應使用常數portTICK_PERIOD_MS轉換爲實時。如果將INCLUDE_vTaskSuspend設置爲'1'，則將阻止時間指定爲portMAX_DELAY將導致任務無限期地阻止（無超時）。 |
返回值：
如果從隊列成功接收到項目，則爲pdTRUE，否則爲pdFALSE。
用法示例：(演示如何發送和接收結構以及指向結構的指針)
/* Define a variable of type struct AMMessage. The examples below demonstrate
how to pass the whole variable through the queue, and as the structure is
moderately large, also how to pass a reference to the variable through a queue. */
struct AMessage
{
char ucMessageID;
char ucData[ 20 ];
} xMessage;
/* Queue used to send and receive complete struct AMessage structures. */
QueueHandle_t xStructQueue = NULL;
/* Queue used to send and receive pointers to struct AMessage structures. */
QueueHandle_t xPointerQueue = NULL;
void vCreateQueues( void )
{
xMessage.ucMessageID = 0xab;
memset( &( xMessage.ucData ), 0x12, 20 );
/* Create the queue used to send complete struct AMessage structures. This can
also be created after the schedule starts, but care must be task to ensure
nothing uses the queue until after it has been created. */
xStructQueue = xQueueCreate(
/* The number of items the queue can hold. */
10,
/* Size of each item is big enough to hold the
whole structure. */
sizeof( xMessage ) );
/* Create the queue used to send pointers to struct AMessage structures. */
xPointerQueue = xQueueCreate(
/* The number of items the queue can hold. */
10,
/* Size of each item is big enough to hold only a
pointer. */
sizeof( &xMessage ) );
if( ( xStructQueue == NULL ) || ( xPointerQueue == NULL ) )
{
/* One or more queues were not created successfully as there was not enough
heap memory available. Handle the error here. Queues can also be created
statically. */
}
}
/* Task that writes to the queues. */
void vATask( void *pvParameters )
{
struct AMessage *pxPointerToxMessage;
/* Send the entire structure to the queue created to hold 10 structures. */
xQueueSend( /* The handle of the queue. */
xStructQueue,
/* The address of the xMessage variable. sizeof( struct AMessage )
bytes are copied from here into the queue. */
( void * ) &xMessage,
/* Block time of 0 says don't block if the queue is already full.
Check the value returned by xQueueSend() to know if the message
was sent to the queue successfully. */
( TickType_t ) 0 );
/* Store the address of the xMessage variable in a pointer variable. */
pxPointerToxMessage = &xMessage;
/* Send the address of xMessage to the queue created to hold 10 pointers. */
xQueueSend( /* The handle of the queue. */
xPointerQueue,
/* The address of the variable that holds the address of xMessage.
sizeof( &xMessage ) bytes are copied from here into the queue. As the
variable holds the address of xMessage it is the address of xMessage
that is copied into the queue. */
( void * ) &pxPointerToxMessage,
( TickType_t ) 0 );
/* ... Rest of task code goes here. */
}
/* Task that reads from the queues. */
void vADifferentTask( void *pvParameters )
{
struct AMessage xRxedStructure, *pxRxedPointer;
if( xStructQueue != NULL )
{
/* Receive a message from the created queue to hold complex struct AMessage
structure. Block for 10 ticks if a message is not immediately available.
The value is read into a struct AMessage variable, so after calling
xQueueReceive() xRxedStructure will hold a copy of xMessage. */
if( xQueueReceive( xStructQueue,
&( xRxedStructure ),
( TickType_t ) 10 ) == pdPASS )
{
/* xRxedStructure now contains a copy of xMessage. */
}
}
if( xPointerQueue != NULL )
{
/* Receive a message from the created queue to hold pointers. Block for 10
ticks if a message is not immediately available. The value is read into a
pointer variable, and as the value received is the address of the xMessage
variable, after this call pxRxedPointer will point to xMessage. */
if( xQueueReceive( xPointerQueue,
&( pxRxedPointer ),
( TickType_t ) 10 ) == pdPASS )
{
/* *pxRxedPointer now points to xMessage. */
}
}
/* ... Rest of task code goes here. */
}
xQueueReceiveFromISR
BaseType_t xQueueReceiveFromISR
(
QueueHandle_t xQueue,
void *pvBuffer,
BaseType_t *pxHigherPriorityTaskWoken
);
從隊列中接收項目。在中斷服務程序中可以安全地使用此功能。
參數：
| xQueue | 從中接收項目的隊列的句柄。 |
| pvBuffer | 指向將接收的項目複製到其中的緩衝區的指針。 |
| pxHigherPriorityTaskWoken | 可能會阻塞任務，以等待隊列上的可用空間。如果xQueueReceiveFromISR使此類任務解除阻止，則* pxHigherPriorityTaskWoken將被設置爲pdTRUE，否則* pxHigherPriorityTaskWoken將保持不變。
從FreeRTOS V7.3.0開始，pxHigherPriorityTaskWoken是可選參數，可以設置爲NULL。 |
返回值：
如果從隊列成功接收到項目，則爲pdTRUE，否則爲pdFALSE。
用法示例：
QueueHandle_t xQueue;
/* Function to create a queue and post some values. */
void vAFunction( void *pvParameters )
{
char cValueToPost;
const TickType_t xTicksToWait = ( TickType_t )0xff;
/* Create a queue capable of containing 10 characters. */
xQueue = xQueueCreate( 10, sizeof( char ) );
if( xQueue == 0 )
{
/* Failed to create the queue. */
}
/* ... */
/* Post some characters that will be used within an ISR. If the queue
is full then this task will block for xTicksToWait ticks. */
cValueToPost = 'a';
xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );
cValueToPost = 'b';
xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );
/* ... keep posting characters ... this task may block when the queue
becomes full. */
cValueToPost = 'c';
xQueueSend( xQueue, ( void * ) &cValueToPost, xTicksToWait );
}
/* ISR that outputs all the characters received on the queue. */
void vISR_Routine( void )
{
BaseType_t xTaskWokenByReceive = pdFALSE;
char cRxedChar;
while( xQueueReceiveFromISR( xQueue,
( void * ) &cRxedChar,
&xTaskWokenByReceive) )
{
/* A character was received. Output the character now. */
vOutputCharacter( cRxedChar );
/* If removing the character from the queue woke the task that was
posting onto the queue xTaskWokenByReceive will have been set to
pdTRUE. No matter how many times this loop iterates only one
task will be woken. */
}
if( xTaskWokenByReceive != pdFALSE )
{
/* We should switch context so the ISR returns to a different task.
NOTE: How this is done depends on the port you are using. Check
the documentation and examples for your port. */
taskYIELD ();
}
}
uxQueueMessagesWaiting
UBaseType_t uxQueueMessagesWaiting( QueueHandle_t xQueue );
Return the number of messages stored in a queue.
Parameters:
| xQueue | A handle to the queue being queried. |
Returns:
The number of messages available in the queue.
uxQueueMessagesWaitingFromISR
UBaseType_t uxQueueMessagesWaiting( QueueHandle_t xQueue );
A version of uxQueueMessagesWaiting() that can be called from an ISR. Return the number of messages stored in a queue.
Parameters:
| xQueue | A handle to the queue being queried. |
Returns:
The number of messages available in the queue.
uxQueueSpacesAvailable
UBaseType_t uxQueueSpacesAvailable( QueueHandle_t xQueue );
Return the number of free spaces in a queue.
Parameters:
| xQueue | A handle to the queue being queried. |
Returns:
The number of free spaces available in the queue.
vQueueDelete
void vQueueDelete( QueueHandle_t xQueue );
Delete a queue – freeing all the memory allocated for storing of items placed on the queue.
Parameters:
| xQueue | A handle to the queue to be deleted. |
xQueueReset
BaseType_t xQueueReset( QueueHandle_t xQueue );
Resets a queue to its original empty state.
Parameters:
| xQueue | The handle of the queue being reset |
Returns:
Since FreeRTOS V7.2.0 xQueueReset() always returns pdPASS.
xQueueIsQueueEmptyFromISR
BaseType_t xQueueIsQueueEmptyFromISR( const QueueHandle_t xQueue );
Queries a queue to determine if the queue is empty. This function should only be used in an ISR.
Parameters:
| xQueue | The handle of the queue being queried |
Returns:
pdFALSE if the queue is not empty, or pdTRUE if the queue is empty.
xQueueIsQueueFullFromISR
BaseType_t xQueueIsQueueFullFromISR( const QueueHandle_t xQueue );
Queries a queue to determine if the queue is full. This function should only be used in an ISR.
Parameters:
| xQueue | The handle of the queue being queried |
Returns:
pdFALSE if the queue is not full, or pdTRUE if the queue is full.
xQueueOverwrite
BaseType_t xQueueOverwrite(
QueueHandle_t xQueue,
const void * pvItemToQueue
);
這是一個調用xQueueGenericSend（）函數的宏。
xQueueSendToBack（）的 版本，即使隊列已滿，該版本也將寫入隊列，從而覆蓋隊列中已保存的數據。
xQueueOverwrite（）用於長度爲1的隊列，這意味着隊列爲空或已滿。
不得從中斷服務程序（ISR）調用此函數。有關在ISR中可以使用的替代方法，請參見xQueueOverwriteFromISR（）。
參數：
| xQueue | 要將數據發送到的隊列的句柄。 |
| pvItemToQueue | 指向要放在隊列中的項目的指針。創建隊列時定義了隊列將容納的項目大小 ，並且會將許多字節從pvItemToQueue複製到隊列存儲區域。 |
返回值：
xQueueOverwrite（）是一個調用xQueueGenericSend（）的宏，因此它的返回值與xQueueSendToFront（）相同。但是，pdPASS是唯一可以返回的值，因爲即使隊列已滿，xQueueOverwrite（）也會寫入隊列。
用法示例：
void vFunction( void *pvParameters )
{
QueueHandle_t xQueue;
unsigned long ulVarToSend, ulValReceived;
/* Create a queue to hold one unsigned long value. It is strongly
recommended *not* to use xQueueOverwrite() on queues that can
contain more than one value, and doing so will trigger an assertion
if configASSERT() is defined. */
xQueue = xQueueCreate( 1, sizeof( unsigned long ) );
/* Write the value 10 to the queue using xQueueOverwrite(). */
ulVarToSend = 10;
xQueueOverwrite( xQueue, &ulVarToSend );
/* Peeking the queue should now return 10, but leave the value 10 in
the queue. A block time of zero is used as it is known that the
queue holds a value. */
ulValReceived = 0;
xQueuePeek( xQueue, &ulValReceived, 0 );
if( ulValReceived != 10 )
{
/* Error, unless another task removed the value. */
}
/* The queue is still full. Use xQueueOverwrite() to overwrite the
value held in the queue with 100. */
ulVarToSend = 100;
xQueueOverwrite( xQueue, &ulVarToSend );
/* This time read from the queue, leaving the queue empty once more.
A block time of 0 is used again. */
xQueueReceive( xQueue, &ulValReceived, 0 );
/* The value read should be the last value written, even though the
queue was already full when the value was written. */
if( ulValReceived != 100 )
{
/* Error unless another task is using the same queue. */
}
/* ... */
}
xQueueOverwriteFromISR
BaseType_t xQueueOverwrite
(
QueueHandle_t xQueue,
const void * pvItemToQueue
BaseType_t *pxHigherPriorityTaskWoken
);
這是一個調用xQueueGenericSendFromISR（）函數的宏。
可以在ISR中使用 的xQueueOverwrite（）版本。xQueueOverwriteFromISR（）與xQueueSendToBackFromISR（）類似，但是即使隊列已滿，它也會寫入隊列，從而覆蓋隊列中已保存的數據。
xQueueOverwriteFromISR（）適用於長度爲1的隊列，這意味着隊列爲空或已滿。
參數：
| xQueue | 要將數據發送到的隊列的句柄。 |
| pvItemToQueue | 指向要放在隊列中的項目的指針。創建隊列時定義了隊列將容納的項目大小 ，並且會將許多字節從pvItemToQueue複製到隊列存儲區域。 |
| pxHigherPriorityTaskWoken | 如果發送到隊列導致任務取消阻止，並且未阻止的任務的優先級高於當前運行的任務，則xQueueOverwriteFromISR（）會將* pxHigherPriorityTaskWoken設置爲pdTRUE。如果xQueueOverwriteFromISR（）將此值設置爲pdTRUE，則應在退出中斷之前請求上下文切換。有關正在使用的端口，請參考文檔的“中斷服務例程”部分。 |
返回值：
xQueueOverwriteFromISR（）是調用xQueueGenericSendFromISR（）的宏，因此具有與xQueueSendToFrontFromISR（）相同的返回值。但是，pdPASS是唯一可以返回的值，因爲即使隊列已滿，xQueueOverwriteFromISR（）也會寫入隊列。
用法示例：
QueueHandle_t xQueue;
void vFunction( void *pvParameters )
{
/* Create a queue to hold one unsigned long value. It is strongly
recommended not to use xQueueOverwriteFromISR() on queues that can
contain more than one value, and doing so will trigger an assertion
if configASSERT() is defined. */
xQueue = xQueueCreate( 1, sizeof( unsigned long ) );
}
void vAnInterruptHandler( void )
{
/* xHigherPriorityTaskWoken must be set to pdFALSE before it is used. */
BaseType_t xHigherPriorityTaskWoken = pdFALSE;
unsigned long ulVarToSend, ulValReceived;
/* Write the value 10 to the queue using xQueueOverwriteFromISR(). */
ulVarToSend = 10;
xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );
/* The queue is full, but calling xQueueOverwriteFromISR() again will still
pass because the value held in the queue will be overwritten with the
new value. */
ulVarToSend = 100;
xQueueOverwriteFromISR( xQueue, &ulVarToSend, &xHigherPriorityTaskWoken );
/* Reading from the queue will now return 100. */
/* ... */
if( xHigherPrioritytaskWoken == pdTRUE )
{
/* Writing to the queue caused a task to unblock and the unblocked task
has a priority higher than or equal to the priority of the currently
executing task (the task this interrupt interrupted). Perform a
context switch so this interrupt returns directly to the unblocked
task. */
portYIELD_FROM_ISR(); /* or portEND_SWITCHING_ISR() depending on the
port.*/
}
}
xQueuePeek
BaseType_t xQueuePeek(
QueueHandle_t xQueue,
void *pvBuffer,
TickType_t xTicksToWait
);
這是一個調用xQueueGenericReceive（）函數的宏。
從隊列中接收項目而不從隊列中刪除該項目。該項目以副本形式接收，因此必須提供足夠大小的緩衝區。創建隊列時定義了複製到緩衝區中的字節數。
成功接收的項目保留在隊列中，因此將在下一次調用或對xQueueReceive（）的調用中再次返回。
不得在中斷服務程序中使用此宏。
參數：
| xQueue | 從中接收項目的隊列的句柄。 |
| pvBuffer | 指向將接收的項目複製到其中的緩衝區的指針。它必須至少足夠大，以容納創建隊列時定義的隊列項目的大小。 |
| xTicksToWait | 如果在調用時隊列爲空，任務應等待等待接收項目的最長時間。時間以滴答週期定義，因此如果需要，應使用常數portTICK_PERIOD_MS轉換爲實時。
如果將INCLUDE_vTaskSuspend設置爲'1'，則將阻止時間指定爲portMAX_DELAY將導致任務無限期地阻止（無超時）。 |
返回值：
如果已成功從隊列中接收（窺視）某項，則爲pdTRUE，否則爲pdFALSE。
用法示例：
struct AMessage
{
char ucMessageID;
char ucData[ 20 ];
} xMessage;
QueueHandle_t xQueue;
// Task to create a queue and post a value.
void vATask( void *pvParameters )
{
struct AMessage *pxMessage;
// Create a queue capable of containing 10 pointers to AMessage structures.
// These should be passed by pointer as they contain a lot of data.
xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );
if( xQueue == 0 )
{
// Failed to create the queue.
}
// ...
// Send a pointer to a struct AMessage object. Don't block if the
// queue is already full.
pxMessage = & xMessage;
xQueueSend( xQueue, ( void * ) &pxMessage, ( TickType_t ) 0 );
// ... Rest of task code.
}
// Task to peek the data from the queue.
void vADifferentTask( void *pvParameters )
{
struct AMessage *pxRxedMessage;
if( xQueue != 0 )
{
// Peek a message on the created queue. Block for 10 ticks if a
// message is not immediately available.
if( xQueuePeek( xQueue, &( pxRxedMessage ), ( TickType_t ) 10 ) )
{
// pcRxedMessage now points to the struct AMessage variable posted
// by vATask, but the item still remains on the queue.
}
}
// ... Rest of task code.
}
xQueuePeekFromISR
BaseType_t xQueuePeekFromISR(
QueueHandle_t xQueue,
void *pvBuffer,
);
可以從中斷服務例程（ISR）使用 的xQueuePeek（）版本。
從隊列中接收項目而不從隊列中刪除該項目。該項目以副本形式接收，因此必須提供足夠大小的緩衝區。創建隊列時定義了複製到緩衝區中的字節數。
成功接收的項目保留在隊列中，因此將在下一次調用或對任何隊列接收功能的調用中再次返回。
參數：
| xQueue | 從中接收項目的隊列的句柄。 |
| pvBuffer | 指向將接收的項目複製到其中的緩衝區的指針。它必須至少足夠大，以容納創建隊列時定義的隊列項目的大小。 |
返回值：
如果已成功從隊列中接收（偷看）某項，則爲pdTRUE，否則爲pdFALSE。
vQueueAddToRegistry
void vQueueAddToRegistry(
QueueHandle_t xQueue,
char *pcQueueName,
);
爲隊列分配名稱，並將隊列添加到註冊表。
參數：
| xQueue | 隊列的句柄被添加到註冊表中。 |
| pcQueueName | 要分配給隊列的名稱。這只是用於方便調試的文本字符串。隊列註冊表僅存儲指向該字符串的指針，因此該字符串必須是持久性的（全局的，最好是在ROM / Flash中），而不是在堆棧上定義的。 |
隊列註冊表具有兩個目的，這兩個目的都與RTOS內核感知的調試相關聯：
- 它允許將文本名稱與隊列關聯，以便在調試GUI中輕鬆識別隊列。
- 它包含調試器查找每個已註冊隊列和信號量所需的信息。
除非使用的是RTOS內核感知調試器，否則隊列註冊表沒有任何用途。
configQUEUE_REGISTRY_SIZE定義可以註冊的最大隊列和信號量。僅需要註冊要使用RTOS內核感知調試器查看的隊列和信號量。
用法示例：
void vAFunction( void )
{
QueueHandle_t xQueue;
/* Create a queue big enough to hold 10 chars. */
xQueue = xQueueCreate( 10, sizeof( char ) );
/* We want this queue to be viewable in a RTOS kernel aware debugger,
so register it. */
vQueueAddToRegistry( xQueue, "AMeaningfulName" );
}
vQueueUnregisterQueue
void vQueueUnregisterQueue(
QueueHandle_t xQueue,
);
從隊列註冊表中刪除隊列。
參數：
| xQueue | 從註冊表中刪除隊列的句柄。 |
隊列註冊表具有兩個目的，這兩個目的都與RTOS內核感知的調試相關聯：
- 它允許將文本名稱與隊列關聯，以便在調試GUI中輕鬆識別隊列。
- 它包含調試器查找每個已註冊隊列和信號量所需的信息。
除非使用的是RTOS內核感知調試器，否則隊列註冊表沒有任何用途。
configQUEUE_REGISTRY_SIZE定義可以註冊的最大隊列和信號量。僅需要註冊要使用RTOS內核感知調試器查看的隊列和信號量。
void vAFunction( void )
{
QueueHandle_t xQueue;
/* Create a queue big enough to hold 10 chars. */
xQueue = xQueueCreate( 10, sizeof( char ) );
/* We want this queue to be viewable in a RTOS kernel aware debugger,
so register it. */
vQueueAddToRegistry( xQueue, "AMeaningfulName" );
/* The queue gets used here. */
/* At some later time, the queue is going to be deleted, first
remove it from the registry. */
vQueueUnregisterQueue( xQueue );
vQueueDelete( xQueue );
}
pcQueueGetName
const char * pcQueueGetName( QueueHandle_t xQueue )
從隊列的句柄中查找隊列名稱。
如果隊列已添加到隊列註冊表中，則僅具有名稱。
參數：
| xQueue | 正在查詢的隊列的句柄。 |
返回值：
如果xQueue引用的隊列在隊列註冊表中，則返回隊列的文本名稱，否則返回NULL。