Preface
FreeRTOS provides a rich API function for operating queues, including queue creation and deletion, flexible enqueue and dequeue methods, enqueue and dequeue with interrupt protection, etc. Here are some details about these API functions.
1. Obtain the number of queued information
1.1 Function description
UBaseType_t uxQueueMessagesWaiting( QueueHandle_t xQueue );
Returns the number of information stored in the queue. The version with interrupt protection is uxQueueMessagesWaitingFromISR(), and the prototype is: UBaseType_t uxQueueMessagesWaitingFromISR( const QueueHandle_t xQueue ).
1.2 Parameter Description
xQueue: Queue handle
2. Get the free number of queues
2.1 Function description
UBaseType_t uxQueueSpacesAvailable( QueueHandle_t xQueue );
Returns the number of free queues.
2.2 Parameter description
xQueue: Queue handle
3. Delete the queue
3.1 Function description
void vQueueDelete( QueueHandle_t xQueue );
Delete the queue and free all memory allocated to the queue.
3.2 Parameter Description
xQueue: Queue handle
4. Reset the queue
4.1 Function description
BaseType_t xQueueReset( QueueHandle_t xQueue );
Reset the queue to its initial state.
4.2 Parameter Description
xQueue: Queue handle
4.3 Return value
FreeRTOSV7.2.0 and later versions always return pdPASS.
5. Create a queue
5.1 Function description
QueueHandle_t xQueueCreate (UBaseType_t uxQueueLength, UBaseType_t uxItemSize);
Create a new queue. Assigns the specified storage space to the new queue and returns the queue handle.
5.2 Parameter Description
usQueueLength: Number of queue items
uxItemSize: The size of each queue item, in bytes. Queue items are enqueued by copy rather than by reference, so the size of the queue items is required. Each queue item must have the same size.
5.3 Return value
The queue is successfully created and returns the queue handle, no will return 0.
5.4 Examples of usage
struct AMessage
{
portCHAR ucMessageID;
portCHAR ucData[ 20 ];
};
void vATask( void*pvParameters )
{
xQueueHandle xQueue1, xQueue2;
// Create a queue that can contain 10 unsigned long values. xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ));
if( xQueue1 ==0 )
{
// Queue creation failed and cannot be used }
// Create a queue that can contain 10 values of the Amessage structure pointer type. // This allows you to contain a large amount of data by passing pointer variables. xQueue2 =xQueueCreate( 10, sizeof( struct AMessage * ) );
if( xQueue2 ==0 )
{
// Queue creation failed and cannot be used }
// ... other code for the task. }6. Deliver queue items to queue
6.1 Function description
BaseType_txQueueSend(QueueHandle_t xQueue, const void * pvItemToQueue, TickType_t xTicksToWait );
It is actually a macro, and the function that is actually called is xQueueGenericSend(). This macro is defined for backward compatibility with FreeRTOS versions that do not contain functions xQueueSendToFront() and xQueueSendToBack() macros. It is equivalent to xQueueSendToBack().
This macro delivers a queue item to the end of the queue. Projects are enlisted in the form of copy, rather than in the form of reference. This macro must never be called in the interrupt service routine, and the same function can be accomplished using the version xQueueSendFromISR() with interrupt protection.
6.2 Parameter Description
xQueue: Queue handle.
pvItemToQueue: Pointer, pointing to the item to be enqueued. The number of bytes of items to be saved to a queue is determined when the queue is created. Therefore, the number of bytes to be copied from the area pointed to by the pointer pvItemToQueue to the queue storage area has also been determined.
xTicksToWait: If the queue is full, the maximum time the task waits for the queue to be idle. If the queue is full and xTicksToWait is set to 0, the function returns immediately. The time unit is the system beat clock cycle, so the macro portTICK_PERIOD_MS can be used to assist in calculating the real delay value. If INCLUDE_vTaskSuspend is set to 1 and the time-delay is specified to portMAX_DELAY, it will cause unlimited blocking of the task (no timeout).
6.3 Return value
The queue item is successfully enqueued and returns pdTRUE, otherwise it will return errQUEUE_FULL.
6.4 Examples of usage
struct AMessage
{
portCHAR ucMessageID;
portCHAR ucData[ 20 ];
}xMessage;
unsigned portLONG ulVar = 10UL;
void vATask( void *pvParameters )
{
xQueueHandle xQueue1, xQueue2;
struct AMessage *pxMessage;
/* Create a queue that can contain 10 unsigned long values. */
xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ) );
/* Create a queue that can contain 10 values of the Amessage structure pointer type.
This allows you to contain a large amount of data by passing pointer variables. */
xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );
// ...
if( xQueue1 != 0 )
{
/*1 unsigned long data is enqueued. If you need to wait for the queue space to become effective,
Will wait for up to 10 system beat cycles*/
if( xQueueSend( xQueue1, ( void * ) &ulVar, ( portTickType ) 10 ) !=pdPASS )
{
/*Message failed to join the queue*/
}
}
if( xQueue2 != 0 )
{
/* Send an object pointing to the structure Amessage, and if the queue is full, don't wait */
pxMessage = & xMessage;
xQueueSend( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0 );
}
//... Task remaining code. }7. Deliver queue items to the queue (with interrupt protection)
7.1 Function description
BaseType_t xQueueSendFromISR (QueueHandle_t xQueue,
const void *pvItemToQueue, BaseType_t *pxHigherPriorityTaskWoken);It is actually a macro, and the function that is actually called is xQueueGenericSendFromISR(). This macro is an interrupt protected version of xQueueSend(), used to interrupt service programs, equivalent to xQueueSendToBackFromISR().
Deliver a queue item to the tail of the queue in the interrupt service routine.
7.2 Parameter Description
xQueue: Queue handle.
pvItemToQueue: Pointer, pointing to the item to be enqueued. The number of bytes of items to be saved to a queue is determined when the queue is created. Therefore, the number of bytes to be copied from the area pointed to by the pointer pvItemToQueue to the queue storage area has also been determined.
pxHigherPriorityTaskWoken: If enqueue causes a task to be unlocked and the unlocked task priority is higher than the currently running task, the function sets *pxHigherPriorityTaskWoken to pdTRUE. If xQueueSendFromISR() sets this value to pdTRUE, a context switch is required before the interrupt exits.
Starting from FreeRTOS V7.3.0, pxHigherPriorityTaskWoken is called an optional parameter and can be set to NULL.
7.3 Return value
The item listed is successfully enqueued and returns pdTRUE, otherwise returns errQUEUE_FULL.
7.4 Examples of usage
void vBufferISR( void )
{
portCHARcIn;
portBASE_TYPE xHigherPriorityTaskWoken;
/* Initialization, no waking task*/
xHigherPriorityTaskWoken = pdFALSE;
/* Until the buffer is empty */
do
{
/* Get one byte of data from the buffer */
cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );
/* Deliver this data */
xQueueSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );
}while( portINPUT_BYTE( BUFFER_COUNT ) );
/* The buffer is empty here, if you need to perform a context switch*/
/*This function is also different depending on the transplant platform*/
portYIELD_FROM_ISR(xHigherPriorityTaskWoken);
}8. Deliver queue items to the tail of the queue
8.1 Function description
BaseType_t xQueueSendToBack(QueueHandle_t xQueue,
const void * pvItemToQueue, TickType_t xTicksToWait );It is actually a macro, and the function that is actually called is xQueueGenericSend(). This macro is equivalent to xQueueSend().
Deliver a queue item to the end of the queue. This macro can never be called in interrupts, and the same function can be accomplished using the version xQueueSendToBackFromISR () with interrupt protection.
8.2 Parameter Description
Same as xQueueSend().
8.3 Return value
Same as xQueueSend().
8.4 Examples of usage
Same as xQueueSend().
9. Deliver queue items to the tail of the queue (with interrupt protection)
9.1 Function Description
BaseType_t xQueueSendToBackFromISR (QueueHandle_t xQueue,
const void *pvItemToQueue, BaseType_t *pxHigherPriorityTaskWoken );It is actually a macro, and the function that is actually called is xQueueGenericSendFromISR(). This macro is an interrupt protected version of xQueueSendToBack(), used to interrupt service programs, equivalent to xQueueSendFromISR().
Deliver a queue item to the tail of the queue in the interrupt service routine.
9.2 Parameter Description
Same as QueueSendFromISR().
9.3 Return value
Same as QueueSendFromISR().
9.4 Examples of usage
Same as QueueSendFromISR().
10. Deliver queue items to the queue header
10.1 Function description
BaseType_t xQueueSendToFront(QueueHandle_t xQueue,
const void * pvItemToQueue,TickType_t xTicksToWait);It is actually a macro, and the function that is actually called is xQueueGenericSend().
This macro delivers a queue item to the queue header. This macro can never be called in the interrupt service routine, and the same function can be accomplished using the version xQueueSendToFrontFromISR () with interrupt protection.
10.2 Parameter Description
xQueue: Queue handle.
pvItemToQueue: Pointer, pointing to the item to be enqueued. The number of bytes of items to be saved to a queue is determined when the queue is created. Therefore, the number of bytes to be copied from the area pointed to by the pointer pvItemToQueue to the queue storage area has also been determined.
xTicksToWait: If the queue is full, the maximum time the task waits for the queue to be idle. If the queue is full and xTicksToWait is set to 0, the function returns immediately. The time unit is the system beat clock cycle, so the macro portTICK_PERIOD_MS can be used to assist in calculating the real delay value. If INCLUDE_vTaskSuspend is set to 1 and the time-delay is specified to portMAX_DELAY, it will cause unlimited blocking of the task (no timeout).
10.3 Return value
The queue item is successfully enqueued and returns pdTRUE, otherwise it will return errQUEUE_FULL.
11. Deliver queue items to the queue header (with interrupt protection)
11.1 Function Description
BaseType_t xQueueSendToFrontFromISR (QueueHandle_t xQueue,
const void *pvItemToQueue,BaseType_t *pxHigherPriorityTaskWoken);It is actually a macro, and the function that is actually called is xQueueGenericSendFromISR(). This macro is an interrupt-protected version of xQueueSendToFront() and is used to interrupt service programs.
11.2 Parameter Description
xQueue: Queue handle.
pvItemToQueue: Pointer, pointing to the item to be enqueued. The number of bytes of items to be saved to a queue is determined when the queue is created. Therefore, the number of bytes to be copied from the area pointed to by the pointer pvItemToQueue to the queue storage area has also been determined.
pxHigherPriorityTaskWoken: If enqueue causes a task to be unlocked and the unlocked task priority is higher than the currently running task, the function sets *pxHigherPriorityTaskWoken to pdTRUE. If xQueueSendFromISR() sets this value to pdTRUE, a context switch is required before the interrupt exits. Starting from FreeRTOS V7.3.0, pxHigherPriorityTaskWoken is called an optional parameter and can be set to NULL.
11.3 Return value
The item listed is successfully enqueued and returns pdTRUE, otherwise returns errQUEUE_FULL.
12. Read and remove queue items
12.1 Function description
BaseType_t xQueueReceive(QueueHandle_t xQueue,
void *pvBuffer,TickType_t xTicksToWait);It is actually a macro, and the function that is actually called is xQueueGenericReceive().
This macro reads a queue item from the queue and deletes the queue item from the queue. Reading queue items is done in copy form, not in reference form, so a buffer large enough to accommodate queue items must be provided. The parameter pvBuffer points to this buffer.
This macro can never be called in the interrupt service routine, and the same function can be accomplished using the version xQueueReceiveFromISR with interrupt protection.
12.2 Parameter Description
pxQueue: Queue handle.
pvBuffer: Point to a buffer for copying received list items.
xTicksToWait: When the queue of items to be received is empty, the maximum blocking time is allowed for task. If this parameter is set to 0, it means that the queue is empty and will be returned immediately. The unit of blocking time is the system beat cycle, and the macro portTICK_RATE_MS can assist in calculating the real blocking time. If INCLUDE_vTaskSuspend is set to 1 and the blocking time is set to portMAX_DELAY, it will cause unlimited blocking of the task (no timeout).
12.3 Return value
The list item is successfully received and returns pdTRUE, otherwise, it returns pdFALSE.
12.4 Examples of usage
struct AMessage
{
portCHAR ucMessageID;
portCHAR ucData[ 20 ];
} xMessage;
xQueueHandle xQueue;
// Create a queue and deliver a valuevoid vATask( void *pvParameters )
{
struct AMessage *pxMessage;
// Create a queue that can contain 10 values of the Amessage structure pointer type. // This allows you to contain a large amount of data by passing pointer variables. xQueue =xQueueCreate( 10, sizeof( struct AMessage * ) );
if( xQueue == 0)
{
// Failed to create a queue }
// ...
// Send a pointer to the structure object Amessage to the queue. If the queue is full, it will not wait. pxMessage = & xMessage;
xQueueSend(xQueue, ( void * ) &pxMessage, ( portTickType ) 0 );
// ... Other codes}
// This task receives a queue item from the queuevoidvADifferentTask( void *pvParameters )
{
struct AMessage *pxRxedMessage;
if( xQueue != 0)
{
// Receive a message from the created queue. If the message is invalid, block up to 10 system beat cycles. if(xQueueReceive( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) )
{
// Now pcRxedMessage points to the structure Amessage variable delivered by the vATask task }
}
// ... Other codes }13 Read and remove queue items (with interrupt protection)
13.1 Function description
BaseType_t xQueueReceiveFromISR (QueueHandle_t xQueue,
void *pvBuffer, BaseType_t *pxHigherPriorityTaskWoken);Read a queue item from the queue and delete the queue item from the queue. The function is the same as xQueueReceive() and is used to interrupt service functions.
13.2 Parameter Description
pxQueue: Queue handle.
pvBuffer: Point to a buffer for copying received list items.
pxHigherPriorityTaskWoken: If enqueue causes a task to be unlocked and the unlocked task priority is higher than the currently running task, the function sets *pxHigherPriorityTaskWoken to pdTRUE. If xQueueSendFromISR() sets this value to pdTRUE, a context switch is required before the interrupt exits. Starting from FreeRTOS V7.3.0, pxHigherPriorityTaskWoken is called an optional parameter and can be set to NULL.
13.3 Return value
The list item is successfully received and returns pdTRUE, otherwise, it returns pdFALSE.
13.4 Examples of usage
xQueueHandle xQueue;
/* This function creates a queue and delivers some values */
voidvAFunction( void *pvParameters )
{
portCHAR cValueToPost;
const portTickType xBlockTime = (portTickType )0xff;
/*Create a queue that can accommodate 10 portCHAR-type variables */
xQueue = xQueueCreate( 10, sizeof( portCHAR ) );
if( xQueue == 0 )
{
/* Queue creation failed */
}
/*…... */
/* Deliver some characters, used in ISR. If the queue is full, the task will block xBlockTime system beat cycles */
cValueToPost = 'a';
xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );
cValueToPost = 'b';
xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );
/*... Continue to deliver characters... This task will block when the queue is full*/
cValueToPost = 'c';
xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );
}
/* ISR: Output all characters received from the queue */
voidvISR_Routine( void )
{
portBASE_TYPE xTaskWokenByReceive = pdFALSE;
portCHAR cRxedChar;
while( xQueueReceiveFromISR( xQueue, ( void *) &cRxedChar, &xTaskWokenByReceive) )
{
/* Receive a string, output.*/
vOutputCharacter( cRxedChar );
/* If the task of sending characters to this queue is awakened after removing a string from the queue, the parameter xTaskWokenByReceive will be set to pdTRUE. No matter how many times this loop is repeated, it will only
One task was awakened. */
}
/*The buffer is empty here. If you need to perform a context switch, this function is also different depending on the porting platform */
portYIELD_FROM_ISR(xTaskWokenByReceive);
}14. Read but not remove queue items
14.1 Function description
BaseType_t xQueuePeek(QueueHandle_t xQueue,
void *pvBuffer, TickType_t xTicksToWait);It is actually a macro, and the function that is actually called is xQueueGenericReceive().
This macro reads a queue item from the queue, but does not remove the queue item from the queue. This macro must never be used in interrupt service routines. The same function can be accomplished using the version xQueuePeekFromIS() with interrupt protection.
14.2 Parameter Description
Same as xQueueReceive().
14.3 Return value
Same as xQueueReceive().
14.4 Examples of usage
Same as xQueueReceive().
15. Read but not remove queue items (with interrupt protection)
15.1 Function description
BaseType_t xQueuePeekFromISR(QueueHandle_t xQueue, void *pvBuffer,);
The function is the same as xQueuePeek() and is used to interrupt the service program.
15.2 Parameter Description
pxQueue: Queue handle. pvBuffer: Points to a buffer that copies the received list item.
15.3 Return value
The list item is successfully received and returns pdTRUE, otherwise, it returns pdFALSE.
16. Queue registration
16.1 Function description
void vQueueAddToRegistry(QueueHandle_t xQueue, char *pcQueueName,);
Assign a name to the queue and register it.
16.2 Parameter Description
xQueue: Queue handle
pcQueueName: The name assigned to the queue. This is just a string that helps in debugging. Queue registration only stores pointers to the queue name string, so this string must be static (global variables are stored alive in ROM/Flash) and cannot be defined on the stack.
Queue registration has two purposes, both of which are for debugging the RTOS kernel:
It allows the queue to have a relevant text name, which can be easily identified in GUI debugging; contains the information required by the debugger to locate each registered queue and semaphore.
Queue registration is only used for debuggers.
The macro configQUEUE_REGISTRY_SIZE defines the maximum number of queues and semaphores that can be registered. Queue and semaphore registration is only performed if you want to debug the kernel using visualization.
16.3 Examples of usage
void vAFunction( void )
{
xQueueHandle xQueue;
/*Create a queue that can accommodate 10 char type values */
xQueue = xQueueCreate( 10, sizeof( portCHAR ) );
/* We want to visually debug, so register it*/
vQueueAddToRegistry( xQueue, "AMeaningfulName" );
}17. Unregister
17.1 Function Description
void vQueueUnregisterQueue(QueueHandle_t xQueue);
Removes the specified queue from the queue registry.
17.2 Parameter Description
xQueue: Queue handle
18. Query whether the queue is empty (only used to interrupt service programs)
18.1 Function Description
BaseType_t xQueueIsQueueEmptyFromISR( const QueueHandle_t xQueue );
Query whether the queue is empty. This function is only used in ISR.
18.2 Parameter Description
xQueue: Queue handle
18.3 Return value
The queue is not empty and returns pdFALSE, and other values indicate that the queue is empty.
19. Query whether the queue is full (only used to interrupt service programs)
19.1 Function Description
BaseType_t xQueueIsQueueFullFromISR( const QueueHandle_t xQueue );
Query whether the queue is full, only for ISR.
19.2 Parameter Description
xQueue: Queue handle
19.3 Return value
The queue is not full returns pdFALSE, and other values indicate that the queue is full.
20. Deliver queue items to the tail of the queue
20.1 Function Description
BaseType_t xQueueOverwrite(QueueHandle_t xQueue, const void * pvItemToQueue);
It is actually a macro, and the function that is actually called is xQueueGenericSend(). This macro is another version of xQueueSendToBack(), which delivers a queue item to the end of the queue, and if the queue is full, it overwrites the previous queue item. It is generally used in queues with only one queue item. If the queue has more than 1 queue item, using this macro will trigger an assertion (if configASSERT() has been correctly defined). This macro must never be called in the interrupt service program, and the same function can be accomplished using the version xQueueOverwriteFromISR() with interrupt protection.
20.2 Parameter Description
xQueue: Queue handle.
pvItemToQueue: Pointer, pointing to the item to be enqueued. The number of bytes of items to be saved to a queue is determined when the queue is created. Therefore, the number of bytes to be copied from the area pointed to by the pointer pvItemToQueue to the queue storage area has also been determined.
20.3 Return value
Always return pdPASS.
20.4 Examples of usage
void vFunction( void *pvParameters )
{
QueueHandle_t xQueue;
unsigned long ulVarToSend, ulValReceived;
/*Create a queue and save an unsignedlong value. If there are more than 1 queue item in a queue, it is strongly recommended not to use xQueueOverwrite(). If using xQueueOverwrite(), an assertion will be triggered (in the case of configASSERT() being correctly defined). */
xQueue = xQueueCreate( 1, sizeof( unsigned long ) );
/* Use xQueueOverwrite(). Write 10*/ to the queue
ulVarToSend = 10;
xQueueOverwrite( xQueue, &ulVarToSend );
/*Read the value from the queue, but do not delete this value from the queue. */
ulValReceived = 0;
xQueuePeek( xQueue, &ulValReceived, 0 );
if( ulValReceived != 10 )
{
/* Handling error*/
}
/*The queue is still full here. Use xQueueOverwrite() to overwrite the queue, write the value 100 */
ulVarToSend = 100;
xQueueOverwrite( xQueue, &ulVarToSend );
/* Read value from queue*/
xQueueReceive( xQueue, &ulValReceived, 0 );
if( ulValReceived != 100 )
{
/*Processing error */
}
/* ... */
}21 Overlayed queue items to the tail of the queue (with interrupt protection)
21.1 Function Description
BaseType_t xQueueOverwriteFromISR (QueueHandle_t xQueue, const void * pvItemToQueue,
BaseType_t *pxHigherPriorityTaskWoken);It is actually a macro, and the function that is actually called is xQueueGenericSendFromISR(). The function of this macro is the same as xQueueOverwrite() and is used in interrupt service programs.
21.2 Parameter Description
xQueue: Queue handle.
pvItemToQueue: Pointer, pointing to the item to be enqueued. The number of bytes of items to be saved to a queue is determined when the queue is created. Therefore, the number of bytes to be copied from the area pointed to by the pointer pvItemToQueue to the queue storage area has also been determined.
pxHigherPriorityTaskWoken: If enqueue causes a task to be unlocked and the unlocked task priority is higher than the currently running task, the function sets *pxHigherPriorityTaskWoken to pdTRUE. If xQueueSendFromISR() sets this value to pdTRUE, a context switch is required before the interrupt exits. Starting from FreeRTOS V7.3.0, pxHigherPriorityTaskWoken is called an optional parameter and can be set to NULL.
21.3 Return value
Always return pdPASS.
The above is the detailed explanation of the API functions of the FreeRTOS real-time operating system queue. For more information about the FreeRTOS queue API functions, please pay attention to my other related articles!