FreeRTOS API message Buffers

Started by tha, January 06, 2022, 09:02:46 AM

Previous topic - Next topic

tha

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

xMessageBufferCreate()
[RTOS Message Buffer API]

message_buffer.h

MessageBufferHandle_t xMessageBufferCreate( size_t xBufferSizeBytes );

สร้าง a new message buffer โดยใช้ dynamically allocated memory. ดู xMessageBufferCreateStatic() สำหรับ a version ที่ใช้ statically allocated memory (memory ที่ถูกจัดสรรที่ compile time).

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

Message buffer functionality ถูกเปิดการใช้งานโดยการ include ไฟล์ the FreeRTOS/source/stream_buffer.c source file ใน the build (เนื่องจาก message buffers ใช้ stream buffers).

tha

Parameters:

     xBufferSizeBytes        จำนวนทั้งหมดของ bytes (ไม่ใช่ messages) ที่ the message buffer จะสามารถเก็บได้ ณ เวลาใดเวลา
                                           หนึ่ง. เมื่อ a message ถูกเขียนไปยัง the message buffer an additional sizeof( size_t ) bytes
                                           จะถูกเขียนด้วยเพื่อเก็บ the message's length. sizeof( size_t ) โดยปกติมี 4 bytes บน a 32-bit
                                           architecture, ดังนั้นบน 32-bit architectures ส่วนใหญ่ a 10 byte message จะใช้ 14 bytes of
                                           message buffer space.


tha

Returns:

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


tha

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

xMessageBufferCreateStatic()
[RTOS Message Buffer API]

message_buffer.h

MessageBufferHandle_t xMessageBufferCreateStatic(
                                          size_t xBufferSizeBytes,
                                          uint8_t *pucMessageBufferStorageArea,
                                          StaticMessageBuffer_t *pxStaticMessageBuffer );


สร้าง a new message buffer โดยใช้ statically allocated memory. ดู xMessageBufferCreate() สำหรับ a version ที่ใช้ dynamically allocated memory.

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

Message buffer functionality ถูกเปิดการใช้งานโดยการ include ไฟล์ the FreeRTOS/source/stream_buffer.c source file ใน the build (เนื่องจาก message buffers ใช้ stream buffers).

tha

Parameters:

     xBufferSizeBytes                         ขนาด, เป็น bytes, ของ the buffer ที่ชี้ถึงโดย the pucMessageBufferStorageArea
                                                            parameter. เมื่อ a message ถูกเขียนไปยัง the message buffer an additional
                                                            sizeof( size_t ) bytes จะถูกเขียนด้วยเพื่อเก็บ the message's length. sizeof( s
                                                            ize_t ) โดยปกติมี 4 bytes บน a 32-bit architecture, ดังนั้นบน 32-bit
                                                            architectures ส่วนใหญ่ a 10 byte message จะใช้ 14 bytes of message
                                                            buffer space. จำนวนสูงสุดของ bytes ที่สามารถถูกเก็บใน the message buffer
                                                            จริงๆคือ (xBufferSizeBytes - 1).

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

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

Returns:

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



tha

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

xMessageBufferSend()
[RTOS Message Buffer API]

message_buffer.h

size_t xMessageBufferSend( MessageBufferHandle_t xMessageBuffer,
                           const void *pvTxData,
                           size_t xDataLengthBytes,
                           TickType_t xTicksToWait );


ส่ง a discrete message ไปยัง a message buffer. The message สามารถมีความยาวเท่าใดก็ได้ที่พอดีกับ the buffer's free space, และถูกก๊อปปี้ลงใน the 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 (อย่างเช่น xMessageBufferSend()) ภายใน a critical section และใช้ a send block time เท่ากับ 0. ในทำนองเดียวกัน, ถ้ามี readers ที่แตกต่างหลายคนดังนั้น the application writer ต้องวางแต่ละการเรียกไปยัง a reading API function (อย่างเช่น xMessageBufferReceive()) ภายใน a critical section และใช้ a receive block time เท่ากับ 0.

ใช้ xMessageBufferSend() เพื่อเขียนไปยัง a message buffer จาก a task. ใช้ xMessageBufferSendFromISR() เพื่อเขียนไปยัง a message buffer จาก an interrupt service routine (ISR)

Message buffer functionality ถูกเปิดการใช้งานโดยการ include ไฟล์ the FreeRTOS/source/stream_buffer.c source file ใน the build. (เนื่องจาก message buffers ใช้ stream buffers).

tha

Parameters:

     xMessageBuffer          The handle of the message buffer ซึ่ง a message กำลังถูกส่งถึง.

     pvTxData                     A pointer ไปยัง the message ที่ถูกก๊อปปี้ลงใน the message buffer.

     xDataLengthBytes      ความยาวของ the message. นั่นคือ, จำนวนของ bytes ที่ก๊อปปี้จาก pvTxData ลงใน the message
                                           buffer.  เมื่อ a message ถูกเขียนไปยัง the message buffer an additional sizeof( size_t )
                                           bytes จะถูกเขียนด้วยเพื่อเก็บ the message's length. sizeof( size_t ) โดยปกติมี 4 bytes บน
                                           a 32 bit architecture, ดังนั้นบน 32-bit architectures ส่วนใหญ่ การเซ็ต xDataLengthBytes
                                           เป็น 20 จะลด the free space ใน the message buffer ลง 24 bytes (20 bytes of message
                                           data และ 4 bytes เพื่อเก็บ the message length).

         xTicksToWait          จำนวนสูงสุดของเวลาที่ the task ควรยังคงอยู่ใน the Blocked state เพื่อรอสำหรับ space ที่เพียงพอ
                                           กลายมาเป็นมีให้ใช้ประโยชน์ใน the message buffer, หาก the message buffer มีพื้นที่ไม่เพียง
                                           พอเมื่อ xMessageBufferSend() ถูกเรียก.  The calling task จะไม่บล็อกถ้า xTicksToWait เป็น
                                           ศูนย์. TheThe 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 message buffer. ถ้าการเรียกถึง xMessageBufferSend() หมดเวลาลงก่อนมีพื้นที่ว่างเพียง
     พอที่จะเขียน the message ลงใน the message buffer ดังนั้นศูนย์จะถูกส่งคืนกลับ. ถ้าการเรียกไม่ time out ดังนั้น
     xDataLengthBytes จะถูกส่งคืนกลับ.