FreeRTOS API Queue

Started by tha, December 23, 2021, 06:14:24 AM

Previous topic - Next topic

tha

https://www.freertos.org/a00118.html

xQueueReceive
[Queue Management]

queue. h

BaseType_t xQueueReceive(
                               QueueHandle_t xQueue,
                               void *pvBuffer,
                               TickType_t xTicksToWait
                            );


นี้เป็น a macro ที่เรียก the xQueueGenericReceive() function.

รับ an item จาก a queue. The item ถูกรับโดยการคัดลอกดังนั้น a buffer ขนาดเพียงพอต้องถูกจัดให้มี. จำนวน bytes ที่คัดลอกลงใน the buffer ถูกกำหนดแล้วเมื่อตอน the queue ถูกสร้าง.

ฟังชั่นนี้ต้องไม่ถูกใช้ใน an interrupt service routine. ดู xQueueReceiveFromISR สำหรับทางเลือกอีกทางที่สามารถ.

Parameters:

     xQueue                 The handle to the queue ซึ่ง the item จะถูกรับจาก.

     pvBuffer                Pointer ไปยัง the buffer ซึ่ง the received item จะถูกคัดลอกลงใน.

     xTicksToWait        จำนวนสูงสุดของเวลาที่ the task ควรบล็อกรอสำหรับ an item ที่จะรับหาก the queue ว่างในขณะที่เรียก.
                                    การเซ็ต xTicksToWait เป็น 0 จะเป็นเหตุให้ the function ส่งคืนกลับทันทีถ้า the queue ว่าง. The time
                                    ถูกกำหนดเป็น tick periods ดังนั้น the constant portTICK_PERIOD_MS ควรถูกใช้เพื่อแปลงเป็น real
                                    time ถ้าสิ่งนี้ถูกต้องการ.

                                     ถ้า INCLUDE_vTaskSuspend ถูกเซ็ตเป็น '1' ดังนั้นการระบุ the block time เป็น portMAX_DELAY
                                     จะเป็นเหตุให้ the task ถูกบล็อกโดยไม่มีกำหนด (โดยไม่มี a timeout).

Returns:

     pdTRUE ถ้า the item ถูกรับสำเร็จ, ถ้าเป็นอย่างอื่น errQUEUE_FULL.

Example usage:
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)

tha

https://www.freertos.org/a00120.html

xQueueReceiveFromISR
[Queue Management]

queue. h

BaseType_t xQueueReceiveFromISR
                (
                    QueueHandle_t xQueue,
                    void *pvBuffer,
                    BaseType_t *pxHigherPriorityTaskWoken
                );


รับ an item จาก a queue. มันจะปลอดภัยในการใช้ฟังชั่นนี้จากภายใน an interrupt service routine.

Parameters:

     xQueue                                      The handle to the queue ซึ่ง the item จะถูกรับจาก.

     pvBuffer                                     Pointer ไปยัง the buffer ซึ่ง the received item จะถูกคัดลอกลงใน.

     pxHigherPriorityTaskWoken   A task อาจถูกบล็อกรอสำหรับ space กลายมาเป็นมีให้ใช้ประโยชน์บน the queue. ถ้า
                                                         xQueueReceiveFromISR เป็นเหตุให้ a task ดังกล่าวปลดบล็อก
                                                         *pxHigherPriorityTaskWoken จะได้รับการเซ็ตเป็น pdTRUE, ถ้าเป็นอย่างอื่น
                                                         *pxHigherPriorityTaskWoken จะยังคงไม่เปลี่ยน.

                                                         จาก FreeRTOS V7.3.0 pxHigherPriorityTaskWoken เป็น an optional
                                                         parameter และสามารถถูกเซ็ตเป็น NULL.

Returns:

     pdTRUE ถ้า an item ถูกรับจาก the queue สำเร็จแล้ว, ถ้าเป็นอย่างอื่น pdFALSE.

Example usage:
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)

tha

https://www.freertos.org/xQueueOverwrite.html

xQueueOverwrite
[Queue Management]

queue.h

BaseType_t xQueueOverwrite(
                                 QueueHandle_t xQueue,
                                 const void * pvItemToQueue
                              );


นี้คือ a macro ที่เรียก the xQueueGenericSend() function.

A version of xQueueSendToBack() ที่จะเขียนไปยัง the queue ถึงแม้ว่า the queue เต็ม, เขียนทับ data ที่ถูกเก็บใน the queue แล้ว.

xQueueOverwrite() ถูกมุ่งหมายสำหรับใช้กับ queues ที่มีความยาวหนึ่งเดียว, หมายความว่า the queue จะเป็นอย่างใดอย่างหนึ่ง ว่างเปล่าหรือเต็ม.

ฟังชั่นนี้ต้องไม่ถูกเรียกจาก an interrupt service routine (ISR). ดู xQueueOverwriteFromISR() สำหรับทางเลือกอีกทางซึ่งอาจถูกใช้ใน an ISR.

Parameters:

     xQueue                     The handle to the queue ซึ่ง the data จะถูกส่งถึง.

     pvItemToQueue       A pointer ไปยัง the item ที่ถูกวางบน the queue. ขนาดของ the items ที่ the queue จะเก็บถูก
                                        กำหนดไว้แล้วเมื่อตอน the queue ถูกสร้าง, และนั่น bytes จำนวนมากนี้จะถูกคัดลอกจาก
                                        pvItemToQueue ลงใน the queue storage area.

Returns:

     xQueueOverwrite() เป็น a macro ที่เรียก xQueueGenericSend(), และดังนั้นจึงมี return values เดียวกันกับ
     xQueueSendToFront(). อย่างไรก็ตาม, pdPASS เป็น the only value ที่สามารถถูกส่งคืนกลับเพราะว่า xQueueOverwrite() จะ
     เขียนไปยัง the queue ถึงแม้เมื่อ the queue เต็มแล้วก็ตาม.

Example usage:
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)


tha

https://www.freertos.org/xQueueOverwriteFromISR.html

xQueueOverwriteFromISR
[Queue Management]

queue.h

BaseType_t xQueueOverwrite
                   (
                      QueueHandle_t xQueue,
                      const void * pvItemToQueue
                      BaseType_t *pxHigherPriorityTaskWoken
                    );


นี้เป็น a macro ที่เรียก the xQueueGenericSendFromISR() function.

A version of xQueueOverwrite() ที่สามารถถูกใช้ใน an ISR. xQueueOverwriteFromISR() คล้ายกันกับ xQueueSendToBackFromISR(), แต่จะเขียนไปยัง the queue ถึงแม้ว่า the queue จะเต็ม, เขียนทับ data ที่ถูกเก็บใน the queue แล้ว.

xQueueOverwriteFromISR() ถูกมุ่งหมายสำหรับใช้กับ queues ที่มีความยาวหนึ่งเดียว, หมายความว่า the queue จะเป็นอย่างใดอย่างหนึ่ง ว่างเปล่าหรือเต็ม.

Parameters:

     xQueue                                        The handle to the queue ซึ่ง the data จะถูกส่งถึง.

     pvItemToQueue                          A pointer ไปยัง the item ที่ถูกวางบน the queue. ขนาดของ the items ที่ the queue
                                                           จะเก็บถูกกำหนดไว้แล้วเมื่อตอน the queue ถูกสร้าง, และนั่น bytes จำนวนมากนี้จะถูก
                                                           คัดลอกจาก pvItemToQueue ลงใน the queue storage area.

     pxHigherPriorityTaskWoken     xQueueOverwriteFromISR() จะเซ็ต *pxHigherPriorityTaskWoken เป็น pdTRUE ถ้า
                                                            การส่งไปยัง the queue เป็นเหตุให้ a task ปลดบล็อก, และ the unblocked task มี
                                                            a priority สูงกว่า the currently running task. ถ้า
                                                            xQueueOverwriteFromISR() เซ็ตค่านี้เป็น dTRUE ดังนั้น a context switch ควร
                                                            ถูกร้องขอก่อน the interrupt จะถูกออก. อ้างอิงถึง the Interrupt Service
                                                            Routines section of the documentation สำหรับ the port ที่กำลังถูกใช้เพื่อดูวิธีที่
                                                            ถูกทำอย่างไร

Returns:

     xQueueOverwriteFromISR() เป็น a macro ที่เรียก xQueueGenericSendFromISR(), และดังนั้นจึงมี return values
     เดียวกันกับ xQueueSendToFrontFromISR(). อย่างไรก็ตาม, pdPASS เป็น the only value ที่สามารถถูกส่งคืนกลับเพราะว่า
     xQueueOverwriteFromISR() จะเขียนไปยัง the queue ถึงแม้เมื่อ the queue เต็มแล้วก็ตาม.

Example usage:
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)

tha

https://www.freertos.org/xQueuePeek.html

xQueuePeek
[Queue Management]

queue.h

BaseType_t xQueuePeek(
                             QueueHandle_t xQueue,
                             void *pvBuffer,
                             TickType_t xTicksToWait
                         );


นี้เป็น a macro ที่เรียก the xQueueGenericReceive() function.

รับ an item จาก a queue โดยไม่ได้เอา the item ออกจาก the queue. The item ถูกรับโดยการคัดลอกดังนั้น a buffer ขนาดเพียงพอต้องถูกจัดให้มี. จำนวน bytes ที่คัดลอกลงใน the buffer ถูกกำหนดแล้วเมื่อ the queue ถูกสร้าง.

items ที่รับสำเร็จยังคงอยู่บน the queue ดังนั้นจะถูกส่งคืนกลับอีกครั้งโดยการเรียกถัดไป, หรือการเรียก xQueueReceive().

มาโครนี้ต้องไม่ถูกใช้ใน an interrupt service routine.

Parameters:

     xQueue                 The handle to the queue ซึ่ง the item จะถูกรับจาก.

     pvBuffer                Pointer ไปยัง the buffer ซึ่ง the received item จะถูกคัดลอกลงใน. นี้ต้องอย่างน้อยใหญ่เพียงพอที่จะเก็บ
                                     ขนาดของ the queue item ที่กำหนดเมื่อตอนที่ the queue ถูกสร้าง.

     xTicksToWait        จำนวนสูงสุดของเวลาที่ the task ควรบล็อกรอสำหรับ an item ที่จะรับหาก the queue ว่างในขณะที่เรียก.
                                     The time ถูกกำหนดเป็น tick periods ดังนั้น the constant portTICK_PERIOD_MS ควรถูกใช้เพื่อ
                                     แปลงเป็น real time ถ้าสิ่งนี้ถูกต้องการ.

                                     ถ้า INCLUDE_vTaskSuspend ถูกเซ็ตเป็น '1' ดังนั้นการระบุ the block time เป็น portMAX_DELAY
                                     จะเป็นเหตุให้ the task ถูกบล็อกโดยไม่มีกำหนด (โดยไม่มี a timeout).

Returns:

     pdTRUE ถ้า the item ถูกรับ(peeked)สำเร็จจาก the queue, ถ้าเป็นอย่างอื่น errQUEUE_FULL.

Example usage:
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)

tha

https://www.freertos.org/xQueuePeekFromISR.html

xQueuePeekFromISR
[Queue Management]

queue.h

BaseType_t xQueuePeekFromISR(
                                 QueueHandle_t xQueue,
                                 void *pvBuffer,
                                );


A version of xQueuePeek() ที่สามารถถูกใช้จาก an interrupt service routine (ISR).

รับ an item จาก a queue โดยไม่ได้เอา the item ออกจาก the queue. The item ถูกรับโดยการคัดลอกดังนั้น a buffer ขนาดเพียงพอต้องถูกจัดให้มี. จำนวน bytes ที่คัดลอกลงใน the buffer ถูกกำหนดแล้วเมื่อ the queue ถูกสร้าง.

items ที่รับสำเร็จยังคงอยู่บน the queue ดังนั้นจะถูกส่งคืนกลับอีกครั้งโดยการเรียกถัดไป, หรือการเรียก queue receive function ใดๆ.

Parameters:

     xQueue                 The handle to the queue ซึ่ง the item จะถูกรับจาก.

     pvBuffer                Pointer ไปยัง the buffer ซึ่ง the received item จะถูกคัดลอกลงใน. นี้ต้องอย่างน้อยใหญ่เพียงพอที่จะเก็บ
                                    ขนาดของ the queue item ที่กำหนดเมื่อตอนที่ the queue ถูกสร้าง.

Returns:

     pdTRUE ถ้า the item ถูกรับ(peeked)สำเร็จจาก the queue, ถ้าเป็นอย่างอื่น errQUEUE_FULL.

tha

https://www.freertos.org/vQueueAddToRegistry.html

vQueueAddToRegistry
[Queue Management]

queue.h

void vQueueAddToRegistry(
                             QueueHandle_t xQueue,
                             char *pcQueueName,
                         );


กำหนดชื่อให้กับ a queue และเพิ่ม the queue ไปยัง the registry.

Parameters:

     xQueue                      The handle of the queue ที่กำลังถูกเพิ่มไปยัง the registry.

     pcQueueName         ชื่อที่ถูกกำหนดให้กับ the queue. นี้เป็นแค่ a text string ที่ใช้เพื่อความสะดวกในการดีบัก. The queue
                                         registry เพียงเก็บ a pointer ไปยัง the string, ดังนั้น the string จะต้องคงอยู่ (a global, หรือควร
                                         เป็นใน ROM/Flash ดีกว่า), ไม่ถูกกำหนดบน the stack.

The queue registry มีจุดประสงค์สองประการ, ซึ่งทั้งสองถูกเกี่ยวข้องกับ RTOS kernel aware debugging:

     1. มันยอมให้ a textual name ถูกเกี่ยวข้องกันกับ a queue เพื่อ queue identification ได้ง่ายภายใน a debugging GUI.

     2. มันบรรจุ the information ที่ต้องการโดย a debugger เพื่อหาตำแหน่งแต่ละ queue and semaphore ที่ลงทะเบียนไว้.

The queue registry จะไม่มีความหมายเว้นแต่คุณกำลังใช้ a RTOS kernel aware debugger.

configQUEUE_REGISTRY_SIZE กำหนดจำนวนสูงสุดของ queues and semaphores ที่สามารถถูก registered. มีเพียง the queues and semaphores ที่คุณต้องการดูโดยใช้ a RTOS kernel aware debugger เท่านั้นที่จำเป็นต้องถูก registered.


tha

https://www.freertos.org/vQueueUnregisterQueue.html

vQueueUnregisterQueue
[Queue Management]

queue.h

void vQueueUnregisterQueue(
                             QueueHandle_t xQueue,
                           );


เอา a queue ออกจาก the queue registry.

Parameters:

     xQueue              The handle of the queue ที่กำลังถูกเอาออกจาก the registry

The queue registry มีจุดประสงค์สองประการ, ซึ่งทั้งสองถูกเกี่ยวข้องกับ RTOS kernel aware debugging:

     1. มันยอมให้ a textual name ถูกเกี่ยวข้องกันกับ a queue เพื่อ queue identification ได้ง่ายภายใน a debugging GUI.

     2. มันบรรจุ the information ที่ต้องการโดย a debugger เพื่อหาตำแหน่งแต่ละ queue and semaphore ที่ลงทะเบียนไว้.

The queue registry จะไม่มีความหมายเว้นแต่คุณกำลังใช้ a RTOS kernel aware debugger.

configQUEUE_REGISTRY_SIZE กำหนดจำนวนสูงสุดของ queues and semaphores ที่สามารถถูก registered. มีเพียง the queues and semaphores ที่คุณต้องการดูโดยใช้ a RTOS kernel aware debugger เท่านั้นที่จำเป็นต้องถูก registered.