FreeRTOS API Stream Buffers

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

Previous topic - Next topic

tha

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

xStreamBufferCreate()
[RTOS Stream Buffer API]

stream_buffer.h

StreamBufferHandle_t xStreamBufferCreate( size_t xBufferSizeBytes,
                                           size_t xTriggerLevelBytes );


สร้าง a new stream buffer โดยใช้การจัดสรร memory แบบไดนามิค. ดู xStreamBufferCreateStatic() สำหรับ a version ที่ใช้การจัดสรร memory แบบสแตติค (memory ที่ถูกจัดสรรที่ compile time).

configSUPPORT_DYNAMIC_ALLOCATION ต้องถูกเซ็ตเป็น 1 หรือทิ้งไว้ไม่กำหนดใน FreeRTOSConfig.h สำหรับ xStreamBufferCreate() มีให้ใช้เป็นประโยชน์.

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

Parameters:

     xBufferSizeBytes         จำนวนทั้งหมดของ bytes ที่ the stream buffer จะสามารถเก็บได้ ณ เวลาใดเวลาหนึ่ง.

     xTriggerLevelBytes     จำนวนของ bytes ที่ต้องอยู่ใน the stream buffer ก่อนที่ a task ที่ถูกบล็อกบน the stream buffer
                                           เพื่อรอสำหรับ data ถูกย้ายออกจาก the blocked state. ตัวอย่างเช่น, ถ้า a task ถูกบล็อกบนการ
                                           อ่านของ an empty stream buffer ที่มี a trigger level เท่ากับ 1 ดังนั้น the task จะถูกปลด
                                           บล็อกเมื่อ a single byte ถูกเขียนไปยัง the buffer หรือ the task's block time หมดเวลาลง. อีก
                                           ตัวอย่างหนึ่ง, ถ้า a task ถูกบล็อกบนการอ่านของ an empty stream buffer ที่มี a trigger level
                                           เท่ากับ 10 ดังนั้น the task จะไม่ถูกปลดบล็อกจนกระทั่ง the stream buffer บรรจุอย่างน้อย 10
                                           bytes หรือ the task's block time หมดเวลาลง. ถ้า a reading task's block time หมดเวลาลง
                                           ก่อนที่ the trigger level จะถูกถึงดังนั้น the task จะยังคงรับตามจำนวน bytes ที่มีให้ใช้เป็นประ   
                                           โยชน์จริงๆ. การเซ็ต a trigger level เท่ากับ 0 จะส่งผลให้ a trigger level เท่ากับ 1 กำลังถูกใช้.
                                           มันไม่ถูกต้องในการระบุ a trigger level ที่ใหญ่กว่า the buffer size.

Returns:

     ถ้า NULL ถูกส่งคืนกลับ, ดังนั้น the stream buffer ไม่สามารถถูกสร้างเนื่องจากมี heap memory ไม่เพียงพอให้ใช้เป็นประโยชน์
     สำหรับ FreeRTOS เพื่อจัดสรร the stream buffer data structures และ storage area. A non-NULL value กำลังถูกส่งคืน
     กลับแสดงให้เห็นว่า the stream buffer ถูกสร้างสำเร็จ - the returned value ควรถูกเก็บเป็น the handle to the created
     stream buffer


tha

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

xStreamBufferCreateStatic()
[RTOS Stream Buffer API]

stream_buffer.h

StreamBufferHandle_t xStreamBufferCreateStatic(
                                    size_t xBufferSizeBytes,
                                    size_t xTriggerLevelBytes,
                                    uint8_t *pucStreamBufferStorageArea,
                                    StaticStreamBuffer_t *pxStaticStreamBuffer );


สร้าง a new stream buffer โดยใช้การจัดสรร memory แบบคงที่. ดู  xStreamBufferCreate() สำหรับ a version ที่ใช้การจัดสรร memory แบบไดนามิค.

configSUPPORT_STATIC_ALLOCATION  ต้องถูกเซ็ตเป็น 1ใน FreeRTOSConfig.h สำหรับ xStreamBufferCreateStatic() มีให้ใช้เป็นประโยชน์.

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


tha

Parameters:

     xBufferSizeBytes                       ขนาด, เป็น bytes, ของ the buffer ที่ชี้ถึงโดย the pucStreamBufferStorageArea
                                                         parameter.

     xTriggerLevelBytes                   จำนวนของ bytes ที่ต้องอยู่ใน the stream buffer ก่อนที่ a task ที่ถูกบล็อกบน the
                                                         stream buffer เพื่อรอสำหรับ data ถูกย้ายออกจาก the blocked state. ตัวอย่างเช่น,
                                                         ถ้า a task ถูกบล็อกบนการอ่านของ an empty stream buffer ที่มี a trigger level
                                                         เท่ากับ 1 ดังนั้น the task จะถูกปลดบล็อกเมื่อ a single byte ถูกเขียนไปยัง the buffer
                                                         หรือ the task's block time หมดเวลาลง. อีกตัวอย่างหนึ่ง, ถ้า a task ถูกบล็อกบนการ
                                                         อ่านของ an empty stream buffer ที่มี a trigger level เท่ากับ 10 ดังนั้น the task
                                                         จะไม่ถูกปลดบล็อกจนกระทั่ง the stream buffer บรรจุอย่างน้อย 10 bytes หรือ the
                                                         task's block time หมดเวลาลง. ถ้า a reading task's block time หมดเวลาลงก่อนที่
                                                         the trigger level จะถูกถึงดังนั้น the task จะยังคงรับตามจำนวน bytes ที่มีให้ใช้เป็นประ
                                                         โยชน์จริงๆ. การเซ็ต a trigger level เท่ากับ 0 จะส่งผลให้ a trigger level เท่ากับ 1
                                                         กำลังถูกใช้. มันไม่ถูกต้องในการระบุ a trigger level ที่ใหญ่กว่า the buffer size.

   pucStreamBufferStorageArea    ต้องชี้ไปยัง a uint8_t array ที่ใหญ่อย่างน้อย xBufferSizeBytes + 1. นี้คือ the
                                                            array ซึ่ง streams ถูกคัดลอกถึงเมื่อพวกมันถูกเขียนไปยัง the stream buffer.

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

Returns:

     ถ้า the stream buffer ถูกสร้างสำเร็จดังนั้น a handle to the created stream buffer จะถูกส่งคืนกลับ. ถ้าอย่างใดอย่างหนึ่ง
     pucStreamBufferStorageArea or pxStaticstreamBuffer เป็น NULL ดังนั้น NULL จะถูกส่งคืนกลับ.

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

tha

สวัสดีปีใหม่ 2565 ครับชาว Electoday ทุกท่าน

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

xStreamBufferSend()
[RTOS Stream Buffer API]

stream_buffer.h

size_t xStreamBufferSend( StreamBufferHandle_t xStreamBuffer,
                          const void *pvTxData,
                          size_t xDataLengthBytes,
                          TickType_t xTicksToWait );


ส่ง bytes ไปยัง a stream buffer. The bytes ถูกคัดลอกลงใน the 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.

ใช้ xStreamBufferSend() เพื่อเขียนไปยัง a stream buffer จาก a task. ใช้ xStreamBufferSendFromISR() เพื่อเขียนไปยัง 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 ซึ่ง a stream กำลังถูกส่งถึง.

     pvTxData                    A pointer ไปยัง the buffer ที่เก็บ the bytes ที่จะถูกก๊อปปี้ลงใน the stream buffer.

     xDataLengthBytes    จำนวนสูงสุดของ bytes ที่ก๊อปปี้จาก pvTxData ลงใน the stream buffer.

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

Returns:
     จำนวนของ bytes ที่เขียนไปยัง the stream buffer. ถ้า a task หมดเวลาลงก่อนที่มันสามารถเขียนทุก xDataLengthBytes ลงใน
     the buffer มันจะยังคงเขียน bytes ให้ได้มากที่สุดเท่าที่เป็นได้.

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

tha

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

xStreamBufferSendFromISR()
[RTOS Stream Buffer API]

stream_buffer.h

size_t xStreamBufferSendFromISR( StreamBufferHandle_t xStreamBuffer,
                                 const void *pvTxData,
                                 size_t xDataLengthBytes,
                                 BaseType_t *pxHigherPriorityTaskWoken );


Interrupt safe version of the API function ที่ส่ง a stream of bytes ไปยัง the 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.

ใช้ xStreamBufferSend() เพื่อเขียนไปยัง a stream buffer จาก a task. ใช้ xStreamBufferSendFromISR() เพื่อเขียนไปยัง 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 ซึ่ง a stream กำลังถูกส่งถึง.

     pvTxData                                  A pointer ไปยัง the buffer ที่เก็บ the bytes ที่จะถูกก๊อปปี้ลงใน the stream buffer.

     xDataLengthBytes                   จำนวนสูงสุดของ bytes ที่ก๊อปปี้จาก pvTxData ลงใน the stream buffer.

   pxHigherPriorityTaskWoken   เป็นไปได้ว่า a stream buffer จะมี a task ที่ถูกบล็อกบนมันกำลังรอสำหรับ data. การเรียก
                                                       xStreamBufferSendFromISR() สามารถทำให้ data มีให้ใช้ประโยชน์, และเป็นเหตุให้ a
                                                       task ที่กำลังรอสำหรับ data ออกจาก the Blocked state. ถ้าการเรียก
                                                       xStreamBufferSendFromISR() เป็นเหตุให้ a task ออกจาก the Blocked state,
                                                       และ the unblocked task นั้นมี a priority สูงกว่า the currently executing task
                                                       (the task ที่ถูกอินเตอร์รัพท์), ดังนั้น, ภายใน, xStreamBufferSendFromISR() จะเซ็ต
                                                       *pxHigherPriorityTaskWoken เป็น pdTRUE. ถ้า xStreamBufferSendFromISR()
                                                        เซ็ตค่านี้เป็น 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. ถ้า a task หมดเวลาลงก่อนที่มันสามารถเขียนทุก xDataLengthBytes ลงใน
     the buffer มันจะยังคงเขียน bytes ให้ได้มากที่สุดเท่าที่เป็นได้.

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