FreeRTOS API Queue

  • 24 Replies
  • 255 Views
*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API Queue
« Reply #8 on: December 24, 2021, 05:56:49 am »
https://www.freertos.org/a00116.html

xQueueCreate
[Queue Management]

queue. h

QueueHandle_t xQueueCreate( UBaseType_t uxQueueLength,
                             UBaseType_t uxItemSize );


สร้าง a new queue และส่งคืนกลับ a handle ซึ่ง the queue สามารถถูกอ้างอิงถึง. configSUPPORT_DYNAMIC_ALLOCATION ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h, หรือทิ้งไว้ไม่กำหนด (ซึ่งในกรณีนี้มันจะเริ่มต้นเป็น 1), สำหรับ RTOS API function นี้มีให้ใช้เป็นประโยชน์.

แต่ละ queue ต้องการ RAM ที่ถูกใช้เพื่อเก็บ the queue state, และเพื่อเก็บ the items ที่ถูกบรรจุใน the queue (the queue storage area). ถ้า a queue ถูกสร้างโดยใช้ xQueueCreate() ดังนั้น RAM ที่ต้องการถูกจัดสรรโดยอัตโนมัติจาก the FreeRTOS heap. ถ้า a queue ถูกสร้างโดยใช้ xQueueCreateStatic() ดังนั้น the RAM ถูกจัดให้มีโดย the application writer, ซึ่งส่งผลให้จำนวนของ parameters มีมากขึ้น, แต่ยอมให้ the RAM ถูกจัดสรรแบบคงที่ที่ compile time. ดู the Static Vs Dynamic allocation page เพื่อข้อมูลที่มากขึ้น.

Parameters:

     uxQueueLength          จำนวนสูงสุดของ items ที่ the queue สามารถเก็บได้ในแต่ละครั้ง.

     uxItemSize                   ขนาด, เป็น bytes, ที่ต้องการเพื่อเก็บแต่ละ item ใน the queue.

                                           Items ถูกจัดคิวโดยการคัดลอก ไม่ใช่โดยการอ้างอิง, ดังนั้นนี้เป็นจำนวนของ bytes ที่จะถูกคัดลอก
                                           สำหรับแต่ละ queued item. แต่ละ item ใน the queue ต้องมีขนาดเดียวกัน.

Returns:

     ถ้า the queue ถูกสร้างสำเร็จดังนั้น a handle to the created queue จะถูกส่งคืนกลับ. ถ้า the memory ที่ต้องการเพื่อสร้าง the queue ไม่สามารถถูกจัดสรร
     ได้ดังนั้น NULL จะถูกส่งคืนกลับ.


*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API Queue
« Reply #9 on: December 24, 2021, 08:14:51 am »
https://www.freertos.org/xQueueCreateStatic.html

xQueueCreateStatic
[Queue Management]

queue. h

QueueHandle_t xQueueCreateStatic(
                             UBaseType_t uxQueueLength,
                             UBaseType_t uxItemSize,
                             uint8_t *pucQueueStorageBuffer,
                             StaticQueue_t *pxQueueBuffer );


สร้าง a new queue และส่งคืนกลับ a handle ซึ่ง the queue สามารถถูกอ้างอิงถึง. configSUPPORT_DYNAMIC_ALLOCATION ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h, หรือทิ้งไว้ไม่กำหนด (ซึ่งในกรณีนี้มันจะเริ่มต้นเป็น 1), สำหรับ RTOS API function นี้มีให้ใช้เป็นประโยชน์.

แต่ละ queue ต้องการ RAM ที่ถูกใช้เพื่อเก็บ the queue state, และเพื่อเก็บ the items ที่ถูกบรรจุใน the queue (the queue storage area). ถ้า a queue ถูกสร้างโดยใช้ xQueueCreate() ดังนั้น RAM ที่ต้องการถูกจัดสรรโดยอัตโนมัติจาก the FreeRTOS heap. ถ้า a queue ถูกสร้างโดยใช้ xQueueCreateStatic() ดังนั้น the RAM ถูกจัดให้มีโดย the application writer, ซึ่งส่งผลให้จำนวนของ parameters มีมากขึ้น, แต่ยอมให้ the RAM ถูกจัดสรรแบบคงที่ที่ compile time. ดู the Static Vs Dynamic allocation page เพื่อข้อมูลที่มากขึ้น.

Parameters:

     uxQueueLength                   จำนวนสูงสุดของ items ที่ the queue สามารถเก็บได้ในแต่ละครั้ง.

     uxItemSize                            ขนาด, เป็น bytes, ที่ต้องการเพื่อเก็บแต่ละ item ใน the queue.

                                                    Items ถูกจัดคิวโดยการคัดลอก ไม่ใช่โดยการอ้างอิง, ดังนั้นนี้เป็นจำนวนของ bytes ที่จะถูกคัด
                                                    ลอกสำหรับแต่ละ queued item. แต่ละ item ใน the queue ต้องมีขนาดเดียวกัน.

     pucQueueStorageBuffer   ถ้า uxItemSize ไม่เป็นศูนย์ดังนั้น pucQueueStorageBuffer ต้องชี้ไปยัง a uint8_t array ที่อย่าง
                                                   น้อยเพียงพอที่จะเก็บ the maximum number of items ที่สามารถอยุ่ใน the queue ใน
                                                   เวลาใดเวลาหนึ่ง - ซึ่งก็คือ ( uxQueueLength * uxItemSize ) bytes. ถ้า uxItemSize
                                                   เป็นศูนย์ดังนั้น pucQueueStorageBuffer สามารถเป็น NULL.

     pxQueueBuffer                  ต้องชี้ไปยังตัวแปรของชนิด StaticQueue_t, ซึ่งจะถูกใช้เก็บ the queue's data structure.

Returns:

      ถ้า the queue ถูกสร้างสำเร็จดังนั้น a handle to the created queue จะถูกส่งคืนกลับ. ถ้า pxQueueBuffer เป็น NULL ดังนั้น NULL จะถูกส่งคืนกลับ.


*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API Queue
« Reply #10 on: December 24, 2021, 10:01:26 am »
https://www.freertos.org/a00117.html

xQueueSend
[Queue Management]

queue.h

BaseType_t xQueueSend(
                            QueueHandle_t xQueue,
                            const void * pvItemToQueue,
                            TickType_t xTicksToWait
                         );


นี้คือ a macro ที่เรียก xQueueGenericSend(). มันถูกรวมไว้สำหรับความเข้ากันได้แบบย้อนหลังกับ versions of FreeRTOS ที่ไม่รวม the xQueueSendToFront() and xQueueSendToBack() macros. มันเทียบเท่ากับ xQueueSendToBack().

โพสต์ an item ใน a queue. The item ถูกจัดคิวโดยการคัดลอก, ไม่ใช่โดยการอ้างอิง. ฟังชั่นนี้ต้องไม่ถูกเรียกจาก an interrupt service routine. ดู xQueueSendFromISR() สำหรับทางเลือกอีกทางซึ่งอาจถูกใช้ใน an ISR.

Parameters:

     xQueue                     The handle to the queue ที่ the item จะถูกโพสต์.

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

     xTicksToWait             จำนวนสูงสุดของเวลาที่ the task ควรบล็อกรอสำหรับ space กลายมาเป็นมีให้ใช้ประโยชน์บน the queue,
                                         หากมันเต็มแล้ว. การเรียกจะส่งคืนกลับทันทีถ้า the queue เต็มและ xTicksToWait ถูกเซ็ตเป็น 0. 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:
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)

*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API Queue
« Reply #11 on: December 24, 2021, 04:19:17 pm »
https://www.freertos.org/a00119.html

xQueueSendFromISR
[Queue Management]

queue.h

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

 
นี้คือ a macro ที่เรียก xQueueGenericSendFromISR(). มันถูกรวมไว้สำหรับความเข้ากันได้แบบย้อนหลังกับเวอร์ชันของ FreeRTOS ที่ไม่ได้รวม the xQueueSendToBackFromISR() and xQueueSendToFrontFromISR() macros.

โพสต์ an item ลงในด้านหลังของ a queue. มันจะปลอดภัยในการใช้ฟังชั่นนี้จากภายใน an interrupt service routine.

Items ถูกจัดคิวโดยการคัดลอกไม่ใช่โดยการอ้างอิงดังนั้นมันจะดีกว่าที่จะจัดคิวเฉพาะ items เล็กๆ, โดยเฉพาะอย่างยิ่งเมื่อถูกเรียกจาก an ISR. ในกรณีส่วนใหญ่มันจะดีกว่าที่จะเก็บ a pointer ไปยัง the item ที่กำลังถูกจัดคิว.

Parameters:

     xQueue                                        The handle to the queue ที่ the item จะถูกโพสต์.

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

     pxHigherPriorityTaskWoken   xQueueSendFromISR() จะเซ็ต *pxHigherPriorityTaskWoken เป็น pdTRUE ถ้าการส่งไป
                                                         ยัง the queue เป็นเหตุให้ a task ปลดบล็อก, และ the unblocked task มี a priority
                                                         สูงกว่า the currently running task. ถ้า xQueueSendFromISR() เซ็ตค่านี้เป็น
                                                         pdTRUE ดังนั้น a context switch ควรถูกร้องขอก่อน the interrupt จะถูก ออก.

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

Returns:

     pdTRUE ถ้า the data ถูกส่งไปยัง the queue สำเร็จแล้ว, ถ้าเป็นอย่างอื่น errQUEUE_FULL.

ตัวอย่างการใช้สำหรับ buffered IO (โดยที่ the ISR สามารถได้รับมากกว่าหนึ่งค่าต่อการเรียก):
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)

*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API Queue
« Reply #12 on: December 24, 2021, 05:20:19 pm »
https://www.freertos.org/xQueueSendToBack.html

xQueueSendToBack
[Queue Management]

queue.h

BaseType_t xQueueSendToBack(
                                   QueueHandle_t xQueue,
                                   const void * pvItemToQueue,
                                   TickType_t xTicksToWait
                               );


นี้เป็น a macro ที่เรียก xQueueGenericSend(). มันเทียบเท่ากับ xQueueSend().

โพสต์ an item ไปยังด้านหลังของ a queue. The item ถูกจัดคิวโดยการคัดลอก, ไม่ใช่โดยการอ้างอิง. ฟังชั่นนี้ต้องไม่ถูกเรียกจาก an interrupt service routine. ดู xQueueSendFromISR() สำหรับทางเลือกอีกทางซึ่งอาจถูกใช้ใน an ISR.

Parameters:

     xQueue                     The handle to the queue ที่ the item จะถูกโพสต์.

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

     xTicksToWait             จำนวนสูงสุดของเวลาที่ the task ควรบล็อกรอสำหรับ space กลายมาเป็นมีให้ใช้ประโยชน์บน the queue,
                                         หากมันเต็มแล้ว. การเรียกจะส่งคืนกลับทันทีถ้าสิ่งนี้ถูกเซ็ตเป็น 0. 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:
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)

*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API Queue
« Reply #13 on: December 25, 2021, 05:41:46 am »
https://www.freertos.org/xQueueSendToBackFromISR.html

xQueueSendToBackFromISR
[Queue Management]

queue.h

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


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

โพสต์ an item ไปยังด้านหลังของ a queue. มันจะปลอดภัยในการใช้ฟังชั่นนี้จากภายใน an interrupt service routine.

Items ถูกจัดคิวโดยการคัดลอกไม่ใช่โดยการอ้างอิงดังนั้นมันจะดีกว่าที่จะจัดคิวเฉพาะ items เล็กๆ, โดยเฉพาะอย่างยิ่งเมื่อถูกเรียกจาก an ISR.

Parameters:

     xQueue                                        The handle to the queue ที่ the item จะถูกโพสต์.

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

     pxHigherPriorityTaskWoken   xQueueSendFromISR() จะเซ็ต *pxHigherPriorityTaskWoken เป็น pdTRUE ถ้าการส่งไป
                                                          ยัง the queue เป็นเหตุให้ a task ปลดบล็อก, และ the unblocked task มี a
                                                          priority สูงกว่า the currently running task. ถ้า xQueueSendFromISR() เซ็ตค่า
                                                          นี้เป็น pdTRUE ดังนั้น a context switch ควรถูกร้องขอก่อน the interrupt จะถูกออก.

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

Returns:

     pdTRUE ถ้า the data ถูกส่งไปยัง the queue สำเร็จแล้ว, ถ้าเป็นอย่างอื่น errQUEUE_FULL.

ตัวอย่างการใช้สำหรับ buffered IO (โดยที่ the ISR สามารถได้รับมากกว่าหนึ่งค่าต่อการเรียก):
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)

*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API Queue
« Reply #14 on: December 25, 2021, 09:12:16 am »
https://www.freertos.org/xQueueSendToFront.html

xQueueSendToFront
[Queue Management]

queue.h

BaseType_t xQueueSendToFront( QueueHandle_t xQueue,
                               const void * pvItemToQueue,
                               TickType_t xTicksToWait );


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

โพสต์ an item ไปยังด้านหน้าของ a queue. The item ถูกจัดคิวโดยการคัดลอก, ไม่ใช่โดยการอ้างอิง. ฟังชั่นนี้ต้องไม่ถูกเรียกจาก an interrupt service routine. ดู xQueueSendToFrontFromISR () สำหรับทางเลือกอีกทางซึ่งอาจถูกใช้ใน an ISR.

Parameters:

     xQueue                      The handle to the queue ที่ the item จะถูกโพสต์.

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

     xTicksToWait             จำนวนสูงสุดของเวลาที่ the task ควรบล็อกรอสำหรับ space กลายมาเป็นมีให้ใช้ประโยชน์บน the queue,
                                         หากมันเต็มแล้ว. การเรียกจะส่งคืนกลับทันทีถ้าสิ่งนี้ถูกเซ็ตเป็น 0. 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:
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)

*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API Queue
« Reply #15 on: December 25, 2021, 10:25:18 am »
https://www.freertos.org/xQueueSendToFrontFromISR.html

xQueueSendToFrontFromISR
[Queue Management]

queue.h

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


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

โพสต์ an item ไปยังด้านหน้าของ a queue. มันจะปลอดภัยในการใช้ฟังชั่นนี้จากภายใน an interrupt service routine.

Items ถูกจัดคิวโดยการคัดลอกไม่ใช่โดยการอ้างอิงดังนั้นมันจะดีกว่าที่จะจัดคิวเฉพาะ items เล็กๆ, โดยเฉพาะอย่างยิ่งเมื่อถูกเรียกจาก an ISR.

Parameters:

     xQueue                                        The handle to the queue ที่ the item จะถูกโพสต์.

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

     pxHigherPriorityTaskWoken   xQueueSendToFrontFromISR() จะเซ็ต *pxHigherPriorityTaskWoken เป็น pdTRUE ถ้า
                                                          การส่งไปยัง the queue เป็นเหตุให้ a task ปลดบล็อก, และ the unblocked task มี a
                                                          priority สูงกว่า the currently running task. ถ้า
                                                          xQueueSendToFrontFromISR() เซ็ตค่านี้เป็น pdTRUE ดังนั้น a context switch
                                                          ควรถูกร้องขอก่อน the interrupt จะถูกออก.

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

Returns:

     pdTRUE ถ้า the data ถูกส่งไปยัง the queue สำเร็จแล้ว, ถ้าเป็นอย่างอื่น errQUEUE_FULL.

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