FreeRTOS API message Buffers

  • 17 Replies
  • 166 Views
*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API message Buffers
« Reply #8 on: January 07, 2022, 04:28:18 pm »
https://www.freertos.org/xMessageBufferSendFromISR.html

xMessageBufferSendFromISR()
[RTOS Message Buffer API]

message_buffer.h

size_t xMessageBufferSendFromISR( MessageBufferHandle_t xMessageBuffer,
                                  const void *pvTxData,
                                  size_t xDataLengthBytes,
                                  BaseType_t *pxHigherPriorityTaskWoken );


Interrupt safe version of the API function ที่ส่ง 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).

*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API message Buffers
« Reply #9 on: January 07, 2022, 04:49:43 pm »
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).

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

Returns:

     จำนวนของ bytes ที่เขียนไปยัง the message buffer. ถ้า the message buffer ไม่มีพื้นที่ว่างเพียงพอสำหรับ the message ที่จะถูกเก็บ ดังนั้น 0 จะถูกส่งคืนกลับ. ถ้าเป็นอย่างอื่น xDataLengthBytes จะถูกส่งคืนกลับ.

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

*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API message Buffers
« Reply #10 on: January 08, 2022, 07:24:56 am »
https://www.freertos.org/xMessageBufferReceive.html

xMessageBufferReceive()
[RTOS Message Buffer API]

message_buffer.h

size_t xMessageBufferReceive( MessageBufferHandle_t xMessageBuffer,
                              void *pvRxData,
                              size_t xBufferLengthBytes,
                              TickType_t xTicksToWait );


รับ a discrete message จาก an RTOS message buffer. Messages สามารถมีความยาวแปรผันได้และถูกก๊อปปี้ออกจาก 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.

ใช้ xMessageBufferReceive() เพื่ออ่านจาก a message buffer จาก a task. ใช้ xMessageBufferReceiveFromISR() เพื่ออ่านจาก 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).

*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API message Buffers
« Reply #11 on: January 08, 2022, 08:07:24 am »
Parameters:

     xMessageBuffer          The handle of the message buffer ซึ่ง a message กำลังถูกรับจาก.

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

    xBufferLengthBytes    ความยาวของ the buffer ที่ชี้ถึงโดย the pvRxData parameter. นี้เซ็ต the maximum length of
                                           the message ที่สามารถถูกรับ. ถ้า xBufferLengthBytes เล็กเกินไปที่จะเก็บ the next message
                                           ดังนั้น the message จะถูกทิ้งใน the message buffer และ 0 จะถูกส่งคืนกลับ.

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

Returns:

     ความยาว, เป็น bytes, ของ the message ที่อ่านจาก the message buffer, ถ้ามี. ถ้า xMessageBufferReceive() หมดเวลาลง
     ก่อนที่ a message กลายมาเป็นมีให้ใช้ประโยชน์ดังนั้นศูนย์จะถูกส่งคืนกลับ. ถ้า the length of the message ใหญ่กว่า
     xBufferLengthBytes ดังนั้น the message จะถูกทิ้งใน the message buffer และศูนย์จะถูกส่งคืนกลับ.


*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API message Buffers
« Reply #12 on: January 08, 2022, 09:25:09 am »
https://www.freertos.org/xMessageBufferReceiveFromISR.html

xMessageBufferReceiveFromISR()
[RTOS Message Buffer API]

message_buffer.h

size_t xMessageBufferReceiveFromISR( MessageBufferHandle_t xMessageBuffer,
                                     void *pvRxData,
                                     size_t xBufferLengthBytes,
                                     BaseType_t *pxHigherPriorityTaskWoken );


An interrupt safe version of the API function ที่รับ a discrete message จาก an RTOS message buffer. Messages สามารถมีความยาวแปรผันได้และถูกก๊อปปี้ออกจาก 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.

ใช้ xMessageBufferReceive() เพื่ออ่านจาก a message buffer จาก a task. ใช้ xMessageBufferReceiveFromISR() เพื่ออ่านจาก 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).

Parameters:

     xMessageBuffer                  The handle of the message buffer ซึ่ง a message กำลังถูกรับจาก.

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

     xBufferLengthBytes           ความยาวของ the buffer ที่ชี้ถึงโดย the pvRxData parameter. นี้เซ็ต the maximum
                                                    length of the message ที่สามารถถูกรับ. ถ้า xBufferLengthBytes เล็กเกินไปที่จะเก็บ
                                                    the next message ดังนั้น the message จะถูกทิ้งใน the message buffer และ 0 จะถูก
                                                    ส่งคืนกลับ.

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

Returns:

     ความยาว, เป็น bytes, ของ the message ที่อ่านจาก the message buffer, ถ้ามี.

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

*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API message Buffers
« Reply #13 on: January 08, 2022, 10:35:17 am »
https://www.freertos.org/vMessageBufferDelete.html

vMessageBufferDelete()
[RTOS Message Buffer API]

message_buffer.h

void vMessageBufferDelete( MessageBufferHandle_t xMessageBuffer );

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

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

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

Parameters:

     xMessageBuffer           The handle of the message buffer ที่จะถูกลบ.

*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API message Buffers
« Reply #14 on: January 08, 2022, 04:40:23 pm »
https://www.freertos.org/xMessageBufferSpacesAvailable.html

xMessageBufferSpacesAvailable()
[RTOS Message Buffer API]

message_buffer.h

size_t xMessageBufferSpacesAvailable( MessageBufferHandle_t xMessageBuffer );

สอบถาม a message buffer เพื่อดู free space จำนวนเท่าไหร่ที่มันบรรจุ, ซึ่งเท่ากันกับจำนวนของ data ที่สามารถถูกส่งไปยัง the message buffer ก่อนที่มันจะเต็ม. The returned value มี 4 bytes ใหญ่กว่า the maximum message size ที่สามารถสามารถถูกส่งไปยัง the message buffer.

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

Parameters:

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

Returns:

     จำนวนของ bytes ที่สามารถถูกเขียนไปยัง the message buffer ก่อนที่ 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, ดังนั้นถ้า xMessageBufferSpacesAvailable() ส่งคืนกลับ 10, ดังนั้น
     ขนาดของ the largest message ที่สามารถถูกเขียนไปยัง the message buffer คือ 6 bytes.

*

Offline tha

  • *****
  • 3177
    • View Profile
Re: FreeRTOS API message Buffers
« Reply #15 on: January 08, 2022, 05:02:08 pm »
https://www.freertos.org/xMessageBufferReset.html

xMessageBufferReset()
[RTOS Message Buffer API]

message_buffer.h

BaseType_t xMessageBufferReset( MessageBufferHandle_t xMessageBuffer );

รีเซ็ต a message buffer ไปเป็นสภาวะเริ่มต้นของมัน, ว่างเปล่า. data ใดๆที่อยู่ใน the message buffer จะถูกละทิ้ง. A message buffer สามารถถูกรีเซ็ตเฉพาะถ้าไม่มี taks ถูกบล็อกรอเพื่ออย่างใดอย่างหนึ่ง ส่งไปยัง หรือ รับจาก the message buffer.

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

Parameters:

     xMessageBuffer          The handle of the message buffer ที่กำลังถูก reset.

Returns:

     ถ้า the message buffer ถูกรีเซ็ตดังนั้น pdPASS จะถูกส่งคืนกลับ. ถ้ามี taks ถูกบล็อกรอเพื่อ ส่งไปยัง หรือ รับจาก the message
     buffer ดังนั้น the message buffer จะไม่ถูกรีเซ็ตและ pdFAIL จะถูกส่งคืนกลับ.