Directory title
- 1. Queue characteristics
- 2. Queue function
-
- 2.1. Create queue
- 2.2. Write queue
- 2.3. Read queue
- 2.4. Reset queue
- 2.5. Delete queue
- 3. Queue set
-
- 3.1. Queue set creation
- 3.2. Add queues to queue sets
- 3.3. Read queue set
1. Queue characteristics
Queues can be used to directly transmit information “Task to task“, “Task to interrupt“, and “Interrupt to task“.
Queues have the following characteristics:
- The queue can have several data:
- The size of each data is fixed
- Specify the number of data and data size of the queue when creating the queue
- Queue data operation FIFO (first in, first out)
- The queue has its own Buffer
- If the data is too large, you can send the data address
Using queues to transfer data can cause tasks to enter a blocking state when reading and writing are unsuccessful (Queue is full/empty), improving CPU operating efficiency.
When there are multiple tasks waiting for the read/write queue, the task with the highest priority will enter the ready state first; if multiple tasks have the same priority, the task that has been waiting the longest will enter the ready state first.
2. Queue function
Queue usage process: create queue, write queue, read queue, delete queue
2.1. Create queue
Queue creation is similar to task creation, and is divided into dynamic memory allocation and static memory allocation.
- Dynamically allocate memory:
QueueHandle_t xQueueCreate( UBaseType_t uxQueueLength, UBaseType_t uxItemSize );
Parameter | Description |
---|---|
uxQueueLength | The maximum number of data that the queue can store |
uxItemSize | The memory size (bytes) allocated to each data |
Return value | Non-zero: success and return handle; null: insufficient memory, creation failed |
- Static allocation of memory: The memory allocated to the queue needs to be created in advance
QueueHandle_t xQueueCreateStatic( UBaseType_t uxQueueLength, UBaseType_t uxItemSize, uint8_t *pucQueueStorageBuffer, StaticQueue_t *pxQueueBuffer );
Parameter | Description |
---|---|
uxQueueLength | The maximum number of data that the queue can store |
uxItemSize | The memory size (bytes) allocated to each data |
pucQueueStorageBuffer | pucQueueStorageBuffer points to a uint8_t array |
pxQueueBuffer | Execute a StaticQueue_t structure to save Queue data structure |
Return value | Non-zero: success and return handle; null: insufficient memory, creation failed |
Usage examples:
uint8_t ucQueueStorage[ QUEUE_LENGTH * sizeof(ITEM_SIZE)];//Used to save queue data StaticQueue_t xQueueBuffer;//Structure used to save the queue QueueHandle_t xQueueHandle_1;//Queue handle void Task1(void *pvParam) {<!-- --> xQueueHandle_1 = xQueueCreateStatic(QUEUE_LENGHT, ITEM_SIZE, ucQueueStorage, & amp;xQueueBuffer); }
2.2. Write Queue
There are two sets of functions for writing queues, used in tasks and used in ISR.
Interrupts can only use API functions ending with “FromISR”.
//Write data to the end of the queue BaseType_t xQueueSend( QueueHandle_t xQueue, const void * pvItemToQueue, TickType_t xTicksToWait ); BaseType_t xQueueSendFromISR( QueueHandle_t xQueue, const void *pvItemToQueue, BaseType_t *pxHigherPriorityTaskWoken );
Parameter Description:
Parameter | Description |
---|---|
xQueue | Queue handle, which queue to write to |
pvItemToQueue | Data pointer, write the value of this data to the queue |
xTicksToWait | If the queue is full, the task can enter the blocking state, xTicksToWait represents the blocking time. If set to 0, it will return directly; if set to portMAX_DELAY, it will wait until there is space to write |
pxHigherPriorityTaskWoken | If joining the queue results in a The task is unlocked, and the unlocked task has a higher priority than the currently interrupted task. If *pxHigherPriorityTaskWoken is set to pdTRUE, a context switch is required before the interrupt exits to execute the awakened higher priority task. |
Return value | pdPASS: The data was successfully written to the queue errQUEUE_FULL: The writing failed because the queue is full and the blocking time has expired |
Example:
BaseType_t xHigherPriorityTaskWoken =pdFALSE; xQueueSendFromISR(g_xQueueRotary, & amp;rdata, & amp;xHigherPriorityTaskWoken); portYIELD_FROM_ISR(xHigherPriorityTaskWoken); //If it is pdTRUE, start task scheduling.
2.3, Read Queue
BaseType_t xQueueReceive( QueueHandle_t xQueue, void * const pvBuffer, TickType_t xTicksToWait ); BaseType_t xQueueReceiveFromISR( QueueHandle_t xQueue, void * const pvBuffer, BaseType_t * const pxHigherPriorityTaskWoken );
Parameter Description:
Parameter | Description |
---|---|
xQueue | Queue handle, which queue to read |
pvBuffer | Buffer pointer, write the value in the queue to this Buffer |
xTicksToWait | If the queue is empty, the data cannot be read and the task can enter the blocking state. xTicksToWait represents the maximum blocking time (Tick Count). If set to 0, it will return directly; if set to portMAX_DELAY, it will wait until data can be read |
pxHigherPriorityTaskWoken | If reading the queue results in a The task is unlocked, and the unlocked task has a higher priority than the currently interrupted task. If *pxHigherPriorityTaskWoken is set to pdTRUE, a context switch is required before the interrupt exits to execute the awakened higher priority task. |
Return value | pdTRUE: Reception successful pdFALSE: Reception failed |
2.4. Reset queue
BaseType_t xQueueReset(QueueHandle_t pxQueue);
Parameter | Description |
---|---|
pxQueue | Queue handle, indicating the queue to be reset |
Return value | pdPASS: Reset successful |
Parameter | Description |
---|---|
pxQueue | Queue handle, indicating the queue to be deleted |
This function is used to delete queues created using dynamic methods, which releases recycled resources and avoids memory leaks.
3. Queue set
Queue sets are suitable for situations where multiple senders and multiple data (signal) types send data (signal) to the same receiver.
A queue set can contain queues and some semaphores. Through queue sets, one task can monitor multiple communication components and obtain signals and data from multiple communication components.
3.1, Queue set creation
QueueSetHandle_t xQueueCreateSet( const UBaseType_t uxEventQueueLength)
Parameter | Description |
---|---|
uxEventQueueLength | The length of the queue set, the maximum number of data (queue handle) that can be stored |
Return value | Success: Return handle failed: NULL, insufficient memory |
3.2. Add queues to queue sets
BaseType_t xQueueAddToSet( QueueSetMemberHandle_t xQueueOrSemaphore, QueueSetHandle_t xQueueSet );
Parameters | Description |
---|---|
xQueueOrSemaphore | The dui’leiduilei handle to be added |
xQueueSet | The handle of the queue set |
Return value | Success: pdTRUE Failure: pdFALSE |
3.3. Read queue set
QueueSetMemberHandle_t xQueueSelectFromSet( QueueSetHandle_t xQueueSet, TickType_t const xTicksToWait );
Parameters | Description |
---|---|
xQueueSet | The handle of the queue set |
xTicksToWait | Blocking time, 0~portMAX_DELAY |
Return value | |
td> | Success: Failed to read queue handle: NULL |