FreeRTOS API Stream Buffers

Started by tha, December 29, 2021, 05:06:38 PM

Previous topic - Next topic

tha

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

xStreamBufferReceive()
[RTOS Stream Buffer API]

stream_buffer.h

size_t xStreamBufferReceive( StreamBufferHandle_t xStreamBuffer,
                             void *pvRxData,
                             size_t xBufferLengthBytes,
                             TickType_t xTicksToWait );


รับ bytes จาก a stream buffer.

NOTE: อย่างเป็นหนึ่งเดียวท่ามกลาง FreeRTOS objects, the stream buffer implementation (เช่นกัน the message buffer implementation, เนื่องจาก message buffers ถูกสร้างบนส่วนบนของ stream buffers) ทึกทักเอาว่ามีเพียงหนึ่ง task หรือ interrupt ที่จะเขียนไปยัง the buffer (the writer), และเพียงหนึ่ง task หรือ interrupt ที่จะอ่านจาก the buffer (the reader). มันจะปลอดภัยสำหรับ the writer and reader หากเป็น tasks หรือ interrupts ที่แตกต่างกัน, แต่, ไม่เหมือน FreeRTOS objects อื่นๆ, มันจะไม่ปลอดภัยหากมี writers ที่แตกต่างหลายคนหรือ readers ที่แตกต่างหลายคน.  ถ้ามี writers ที่แตกต่างหลายคนดังนั้น the application writer ต้องวางแต่ละการเรียกไปยัง a writing API function (อย่างเช่น xStreamBufferSend()) ภายใน a critical section และใช้ a send block time เท่ากับ 0. ในทำนองเดียวกัน, ถ้ามี readers ที่แตกต่างหลายคนดังนั้น the application writer ต้องวางแต่ละการเรียกไปยัง a reading API function (อย่างเช่น xStreamBufferReceive()) ภายใน a critical section และใช้ a receive block time เท่ากับ 0.

ใช้ xStreamBufferReceive() เพื่ออ่านจาก a stream buffer จาก a task. ใช้ xStreamBufferReceiveFromISR() เพื่ออ่านจาก a stream buffer จาก an interrupt service routine (ISR).

Stream buffer functionality ถูกเปิดการใช้งานโดยการ include ไฟล์ the FreeRTOS/source/stream_buffer.c source file ใน the build.

tha

Parameters:

     xStreamBuffer              The handle of the stream buffer ซึ่ง bytes ถูกรับจาก.

     pvRxData                      A pointer ไปยัง the buffer ซึ่ง the received bytes จะถูกก๊อปปี้ลงใน.

     xBufferLengthBytes    ความยาวของ the buffer ที่ชี้ถึงโดย the pvRxData parameter. นี้ตั้งค่าจำนวนสูงสุดของ bytes ที่รับ
                                            ในการเรียกหนึ่งครั้ง. xStreamBufferReceive จะสิงคืนกลับ bytes ให้มากที่สุดเท่าที่จะเป็นไปได้
                                            จนถึงค่าสูงสุดที่ตั้งค่าโดย xBufferLengthBytes.

     xTicksToWait              จำนวนสูงสุดของเวลาที่ the task ควรยังคงอยู่ใน the Blocked state เพื่อรอสำหรับ data กลายมาเป็นมี
                                           ให้ใช้ประโยชน์ถ้า the stream buffer ว่างเปล่า. xStreamBufferReceive() จะส่งคืนกลับทันทีถ้า
                                           xTicksToWait เป็นศูนย์. The block time ถูกระบุเป็น tick periods, ดังนั้น the absolute time ที่
                                           มันแสดงจะขึ้นอยู่กับ the tick frequency. The macro pdMS_TO_TICKS() สามารถถูกใช้เพื่อ
                                           แปลง a time ที่ระบุเป็น milliseconds ลงใน a time ที่ระบุเป็น ticks. การเซ็ต xTicksToWait เป็น
                                           portMAX_DELAY จะเป็นเหตุให้ the task รอโดยไม่มีกำหนด (โดยไม่มี timing out), โดยที่
                                           INCLUDE_vTaskSuspend ถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h. A task ไม่ใช้ CPU time ใดๆ
                                           เมื่อมันอยู่ใน the blocked state.

tha

Returns:

     จำนวนของ bytes ที่อ่านจาก the stream buffer. นี้จะเป็นจำนวนของ bytes ที่มีให้ใช้ประโยชน์สูงถึงค่าสูงสุดของ
     xBufferLengthBytes. ตัวอย่างเช่น:

          •  ถ้า the trigger level เป็น 1 (the trigger level ถูกเซ็ตเมื่อ the stream buffer ถูกสร้าง) -
               •  ถ้า xBufferLengthBytes เป็น 10 และ the stream buffer บรรจุ 5 bytes เมื่อ xStreamBufferReceive() ถูกเรียก -
                   ดังนั้น xStreamBufferReceive() จะไม่บล็อก, อ่าน 5 bytes จาก the buffer, และส่งคืนกลับ 5.
               •  ถ้า xBufferLengthBytes เป็น 10 และ the stream buffer บรรจุ 50 bytes เมื่อ xStreamBufferReceive() ถูกเรียก
                   - ดังนั้น xStreamBufferReceive() จะไม่บล็อก, อ่าน 10 bytes จาก the buffer, และส่งคืนกลับ 10.
               •  ถ้า xBufferLengthBytes เป็น 10, the stream buffer บรรจุ 0 bytes เมื่อ xStreamBufferReceive() ถูกเรียก,
                   xTicksToWait เป็น 100, และ 5 bytes ถูกรับลงใน the buffer หลังจาก 50 ticks - ดังนั้น
                   xStreamBufferReceive() จะเข้าสู่ the blocked state เป็นเวลา 50 ticks (ซึ่งคือจนกระทั่ง data มาถึงใน the
                   buffer), ซึ่งหลังจากนั้นมันจะอ่าน 5 bytes จาก the buffer, และส่งคืนกลับ 5.
               •  ถ้า xBufferLengthBytes เป็น 10, the stream buffer บรรจุ 0 bytes เมื่อ xStreamBufferReceive() ถูกเรียก,
                   xTicksToWait เป็น 100, และไม่มี bytes ถูกรับลงใน the buffer ภายใน 100 ticks - ดังนั้น
                   xStreamBufferReceive() จะเข้าสู่ the blocked state เป็นเวลา the full block time เท่ากับ 100 ticks, ซึ่ง
                   หลังจากนั้นมันจะส่งคืนกลับ 0.

          •  ถ้า the trigger level เป็น 6 -
               •  ถ้า xBufferLengthBytes เป็น 10, the stream buffer บรรจุ 0 bytes เมื่อ xStreamBufferReceive() ถูกเรียก,
                   xTicksToWait เป็น 100, และ 10 bytes ถูกรับลงใน the buffer หลังจาก 50 ticks - ดังนั้น
                   xStreamBufferReceive() จะเข้าสู่ the blocked state เป็นเวลา 50 ticks (ซึ่งคือจนกระทั่งอย่างน้อย the
                   trigger level number of bytes มาถึงใน the buffer), ซึ่งหลังจากนั้นมันจะอ่าน 10 bytes จาก the buffer, และ
                   ส่งคืนกลับ 10.
              •  ถ้า xBufferLengthBytes เป็น 10, the stream buffer บรรจุ 0 bytes เมื่อ xStreamBufferReceive() ถูกเรียก,
                  xTicksToWait เป็น 100, และ 5 bytes ถูกรับลงใน the buffer หลังจาก 50 ticks  - ดังนั้น
                  xStreamBufferReceive() จะยังคงบล็อกเป็นเวลาทั้งหมด 100 tick block period (เนื่องจากจำนวนของ data ใน
                  the buffer ไม่ถึง the trigger level), ซึ่งหลังจากนั้นมันจะอ่าน 5 bytes จาก the buffer, และส่งคืนกลับ 5.



tha

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

xStreamBufferReceiveFromISR()
[RTOS Stream Buffer API]

stream_buffer.h

size_t xStreamBufferReceiveFromISR( StreamBufferHandle_t xStreamBuffer,
                                    void *pvRxData,
                                    size_t xBufferLengthBytes,
                                    BaseType_t *pxHigherPriorityTaskWoken );


An interrupt safe version of the API function ที่รับ bytes จาก a stream buffer.

NOTE: อย่างเป็นหนึ่งเดียวท่ามกลาง FreeRTOS objects, the stream buffer implementation (เช่นกัน the message buffer implementation, เนื่องจาก message buffers ถูกสร้างบนส่วนบนของ stream buffers) ทึกทักเอาว่ามีเพียงหนึ่ง task หรือ interrupt ที่จะเขียนไปยัง the buffer (the writer), และเพียงหนึ่ง task หรือ interrupt ที่จะอ่านจาก the buffer (the reader). มันจะปลอดภัยสำหรับ the writer and reader หากเป็น tasks หรือ interrupts ที่แตกต่างกัน, แต่, ไม่เหมือน FreeRTOS objects อื่นๆ, มันจะไม่ปลอดภัยหากมี writers ที่แตกต่างหลายคนหรือ readers ที่แตกต่างหลายคน.  ถ้ามี writers ที่แตกต่างหลายคนดังนั้น the application writer ต้องวางแต่ละการเรียกไปยัง a writing API function (อย่างเช่น xStreamBufferSend()) ภายใน a critical section และใช้ a send block time เท่ากับ 0. ในทำนองเดียวกัน, ถ้ามี readers ที่แตกต่างหลายคนดังนั้น the application writer ต้องวางแต่ละการเรียกไปยัง a reading API function (อย่างเช่น xStreamBufferReceive()) ภายใน a critical section และใช้ a receive block time เท่ากับ 0.

ใช้ xStreamBufferReceive() เพื่ออ่านจาก a stream buffer จาก a task. ใช้ xStreamBufferReceiveFromISR() เพื่ออ่านจาก a stream buffer จาก an interrupt service routine (ISR).

Stream buffer functionality ถูกเปิดการใช้งานโดยการ include ไฟล์ the FreeRTOS/source/stream_buffer.c source file ใน the build.

tha

Parameters:

     xStreamBuffer                           The handle of the stream buffer ซึ่ง bytes ถูกรับจาก.

     pvRxData                                   A pointer ไปยัง the buffer ซึ่ง the received bytes จะถูกก๊อปปี้ลงใน.

     xBufferLengthBytes                  ความยาวของ the buffer ที่ชี้ถึงโดย the pvRxData parameter. นี้ตั้งค่าจำนวนสูงสุดของ
                                                         bytes ที่รับในการเรียกหนึ่งครั้ง. xStreamBufferReceive จะสิงคืนกลับ bytes ให้มาก
                                                         ที่สุดเท่าที่จะเป็นไปได้จนถึงค่าสูงสุดที่ตั้งค่าโดย xBufferLengthBytes.

   pxHigherPriorityTaskWoken   เป็นไปได้ว่า a stream buffer จะมี a task ที่ถูกบล็อกบนมันกำลังรอสำหรับ data. การเรียก
                                                       xStreamBufferReceiveFromISR() สามารถทำให้ data มีให้ใช้ประโยชน์, และเป็นเหตุให้ a
                                                       task ที่กำลังรอสำหรับ data ออกจาก the Blocked state. ถ้าการเรียก
                                                       xStreamBufferReceiveFromISR() เป็นเหตุให้ a task ออกจาก the Blocked state,
                                                        และ the unblocked task นั้นมี a priority สูงกว่า the currently executing task
                                                       (the task ที่ถูกอินเตอร์รัพท์), ดังนั้น, ภายใน, xStreamBufferReceiveFromISR() จะเซ็ต
                                                       *pxHigherPriorityTaskWoken เป็น pdTRUE. ถ้า xStreamBufferReceiveFromISR()
                                                         เซ็ตค่านี้เป็น pdTRUE, ดังนั้น a context switch ตามปกติควรถูกดำเนินการก่อนที่ the
                                                        interrupt จะถูกออก. นี้จะทำให้แน่ใจว่า the interrupt รีเทิร์นโดยตรงไปยัง the highest
                                                        priority Ready state task. *pxHigherPriorityTaskWoken ควรถูกเซ็ตเป็น
                                                        pdFALSE กอนที่มันจะถูกส่งผ่านไปยัง the function. ดู the example code ข้างล่าง
                                                        สำหรับตัวอย่าง.

Returns:

     จำนวนของ bytes ที่อ่านจาก the stream buffer, ถ้ามี.

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

tha

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

vStreamBufferDelete()
[RTOS Stream Buffer API]

stream_buffer.h

void vStreamBufferDelete( StreamBufferHandle_t xStreamBuffer );

ลบ a stream buffer ที่ถูกสร้างก่อนหน้านั้นโดยใช้การเรียกถึง xStreamBufferCreate() หรือ xStreamBufferCreateStatic(). ถ้า the stream buffer ที่ถูกสร้างนั้นใช้ dynamic memory (นั่นคือ, โดย xStreamBufferCreate()), ดังนั้น the allocated memory จะถูกปล่อยฟรี.

A stream buffer handle ต้องไม่ถูกใช้หลังจาก the stream buffer ได้ถูกลบไปแล้ว.

Stream buffer functionality ถูกเปิดการใช้งานโดยการ include ไฟล์ the FreeRTOS/source/stream_buffer.c source file ใน the build.

Parameters:

     xStreamBuffer               The handle of the stream buffer ที่ถูกลบ.

tha

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

xStreamBufferBytesAvailable()
[RTOS Stream Buffer API]

stream_buffer.h

size_t xStreamBufferBytesAvailable( StreamBufferHandle_t xStreamBuffer );

สอบถาม a stream buffer เพื่อดู data จำนวนเท่าไหร่ที่มันบรรจุ, ซึ่งเท่ากันกับจำนวนของ bytes ที่สามารถถูกอ่านได้จาก the stream buffer ก่อนที่ the stream buffer จะว่างเปล่า.

Stream buffer functionality ถูกเปิดการใช้งานโดยการ include ไฟล์ the FreeRTOS/source/stream_buffer.c source file ใน the build.

Parameters:

     xStreamBuffer               The handle of the stream buffer ที่กำลังถูกสอบถาม.

Returns:

     จำนวนของ bytes ที่สามารถถูกอ่านได้จาก the stream buffer ก่อนที่ the stream buffer จะว่างเปล่า.

tha

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

xStreamBufferSpacesAvailable()
[RTOS Stream Buffer API]

stream_buffer.h

size_t xStreamBufferSpacesAvailable( StreamBufferHandle_t xStreamBuffer );

สอบถาม a stream buffer เพื่อดู free space จำนวนเท่าใดที่มันบรรจุ, ซึ่งจะเท่ากับจำนวนของ data ที่สามารถถูกส่งได้ไปยัง the stream buffer ก่อนที่มันจะเต็ม.

Stream buffer functionality ถูกเปิดการใช้งานโดยการ include ไฟล์ the FreeRTOS/source/stream_buffer.c source file ใน the build.

Parameters:

     xStreamBuffer               The handle of the stream buffer ที่กำลังถูกสอบถาม.

Returns:

     จำนวนของ bytes ที่สามารถถูกเขียนได้ไปยัง the stream buffer ก่อนที่ the stream buffer จะเต็ม.