FreeRTOS API Event Groups

Started by tha, January 28, 2022, 08:18:14 AM

Previous topic - Next topic

tha

https://www.freertos.org/event-groups-API.html

Event Groups
[API]

     เคล็ดลับ: 'Task Notifications' สามารถเป็นทางเลือกที่มีน้ำหนักเบาให้กับ event groups ได้ในหลายสถานการณ์


tha

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

Event Groups
[API]

     เคล็ดลับ: 'Task Notifications' สามารถเป็นทางเลือกที่มีน้ำหนักเบาให้กับ event groups ได้ในหลายสถานการณ์

event_groups.h

EventGroupHandle_t xEventGroupCreate( void );

สร้าง a new RTOS event group, และส่งคืนกลับ a handle ซึ่ง the newly created event group สามารถถูกอ้างอิง.

สำหรับ this RTOS API function มีให้ใช้ประโยชน์:

     1. configSUPPORT_DYNAMIC_ALLOCATION ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h, หรือทิ้งไว้ไม่กำหนด (ซึ่งในกรณีนี้มัน
         จะมีค่าเริ่มต้นเป็น 1).
     2. The RTOS source file FreeRTOS/source/event_groups.c ต้องถูก included ใน the build.

แต่ละ event group ต้องการจำนวนน้อย[มากๆ]ของ RAM ที่ถูกใช้เพื่อเก็บ the event group's state. ถ้า an event group ถูกสร้างโดยใช้ xEventGroupCreate() ดังนั้น RAM ที่ต้องการจะถูกจัดสรรโดยอัตโนมัติจาก the FreeRTOS heap. ถ้า an event group ถูกสร้างโดยใช้ xEventGroupCreateStatic() ดังนั้น the RAM ถูกจัดให้มีโดย the application writer, ซึ่งต้องการ parameter เพิ่มเติม, แต่ยอมให้ the RAM ถูกจัดสรรแบบคงที่ที่เวลา compile. ดู the Static Vs Dynamic allocation page สำหรับข้อมูลเพิ่มเติม.

Event groups ถูกเก็บในตัวแปรของชนิด EventBits_t. จำนวนของ bits (หรือ flags) ที่จัดให้มีใช้ภายใน an event group เป็น 8 ถ้า configUSE_16_BIT_TICKS ถูกเซ็ตเป็น 1, หรือ 24 ถ้า configUSE_16_BIT_TICKS ถูกเซ็ตเป็น 0. การขึ้นอยู่กับ configUSE_16_BIT_TICKS เป็นผลมาจาก the data type ที่ใช้สำหรับ thread local storage ใน the internal implementation of RTOS tasks.

Parameters:

     None
   
Returns:

     ถ้า the event group ถูกสร้างแล้วดังนั้น a handle to the event group จะถูกส่งคืนกลับ. ถ้ามี FreeRTOS heap ไม่เพียงพอให้ใช้
     ประโยชน์เพื่อสร้างง the event group ดังนั้น NULL จะถูกส่งคืนกลับ.


tha

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

xEventGroupCreateStatic
[Event Group API]

     เคล็ดลับ: 'Task Notifications' สามารถเป็นทางเลือกที่มีน้ำหนักเบาให้กับ event groups ได้ในหลายสถานการณ์

event_groups.h

EventGroupHandle_t xEventGroupCreateStatic(
                              StaticEventGroup_t *pxEventGroupBuffer );


สร้าง a new RTOS event group, และส่งคืนกลับ a handle ซึ่ง the newly created event group สามารถถูกอ้างอิง.  configSUPPORT_STATIC_ALLOCATION  ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h and the RTOS source file FreeRTOS/source/event_groups.c ต้องถูก included ใน the build สำหรับ the xEventGroupCreateStatic() function มีให้ใช้ประโยชน์.

แต่ละ event group ต้องการจำนวนน้อย[มากๆ]ของ RAM ที่ถูกใช้เพื่อเก็บ the event group's state. ถ้า an event group ถูกสร้างโดยใช้ xEventGroupCreate() ดังนั้น RAM ที่ต้องการจะถูกจัดสรรโดยอัตโนมัติจาก the FreeRTOS heap. ถ้า an event group ถูกสร้างโดยใช้ xEventGroupCreateStatic() ดังนั้น the RAM ถูกจัดให้มีโดย the application writer, ซึ่งต้องการ parameter เพิ่มเติม, แต่ยอมให้ the RAM ถูกจัดสรรแบบคงที่ที่เวลา compile. ดู the Static Vs Dynamic allocation page สำหรับข้อมูลเพิ่มเติม.

Event groups ถูกเก็บในตัวแปรของชนิด EventBits_t. จำนวนของ bits (หรือ flags) ที่จัดให้มีใช้ภายใน an event group เป็น 8 ถ้า configUSE_16_BIT_TICKS ถูกเซ็ตเป็น 1, หรือ 24 ถ้า configUSE_16_BIT_TICKS ถูกเซ็ตเป็น 0. การขึ้นอยู่กับ configUSE_16_BIT_TICKS เป็นผลมาจาก the data type ที่ใช้สำหรับ thread local storage ใน the internal implementation of RTOS tasks.

Parameters:
     
     pxEventGroupBuffer     ต้องชี้ไปยังตัวแปรชนิด StaticEventGroup_t, ซึ่ง the event group data structure จะถูกเก็บ.

Returns:

     ถ้า the event group ถูกสร้างสำเร็จแล้วดังนั้น a handle to the event group จะถูกส่งคืนกลับ. ถ้า pxEventGroupBuffer เป็น
     NULL ดังนั้น NULL จะถูกส่งคืนกลับ.



tha

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

vEventGroupDelete()
[Event Group API]

event_groups.h

void vEventGroupDelete( EventGroupHandle_t xEventGroup );

ลบ an event group ที่ถูกสร้างก่อนหน้านี้โดยใช้การเรียกไปยัง xEventGroupCreate().

Tasks ที่ถูกบล็อกบน the event group ที่กำลังถูกลบจะถูกปลดบล็อก, และรายงาน an event group value เป็น 0.

The RTOS source file FreeRTOS/source/event_groups.c ต้องถูก included ใน the build สำหรับ the vEventGroupDelete() function มีให้ใช้ประโยชน์.

ฟังชั่นนี้ไม่สามารถถูกเรียกจาก an interrupt.

Parameters:

     xEventGroup          The event group ที่กำลังถูกลบ.

Returns:

     None.

tha

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

xEventGroupWaitBits()
[Event Group API]

event_groups.h

EventBits_t xEventGroupWaitBits(
                       const EventGroupHandle_t xEventGroup,
                       const EventBits_t uxBitsToWaitFor,
                       const BaseType_t xClearOnExit,
                       const BaseType_t xWaitForAllBits,
                       TickType_t xTicksToWait );


อ่าน bits ภายใน an RTOS event group, สามารถเลือกเข้าสู่ the Blocked state (ที่มี a timeout) เพื่อรอสำหรับ a bit หรือ group of bits กลายมาเป็น set.

ฟังชั่นนี้ไม่สามารถถูกเรียกจาก an interrupt.

The RTOS source file FreeRTOS/source/event_groups.c ต้องถูก included ใน the build สำหรับ the xEventGroupWaitBits() function มีให้ใช้ประโยชน์.

tha

Parameters:

     xEventGroup          The event group ซึ่ง the bits ในนั้นกำลังถูกทดสอบ. The event group ต้องถูกสร้างก่อนหน้าโดยใช้การ
                                       เรียกถึง xEventGroupCreate().

     uxBitsToWaitFor     A bitwise value ที่แสดง the bit เดียวหรือหลาย bits ทดสอบภายใน the event group. ตัวอย่างเช่น, เพื่อ
                                       รอสำหรับ bit 0 and/or bit 2 เซ็ต uxBitsToWaitFor เป็น 0x05. เพื่อรอสำหรับ bits 0 and/or bit 1
                                       and/or bit 2 เซ็ต uxBitsToWaitFor เป็น 0x07. เป็นต้น.

                                       uxBitsToWaitFor ต้องไม่ถูกเซ็ตเป็น 0.

tha

     xClearOnExit          ถ้า xClearOnExit ถูกเซ็ตเป็น pdTRUE ดังนั้น bits ใดๆที่เซ็ตใน the value ที่ส่งผ่านเป็น the
                                      uxBitsToWaitFor parameter จะถูกเคลียร์ใน the event group ก่อน xEventGroupWaitBits() ส่งคืน
                                      กลับถ้า xEventGroupWaitBits() ส่งคืนกลับด้วยเหตุผลใดก็ตามนอกเหนือจาก a timeout. The timeout
                                      value ถูกเซ็ตโดย the xTicksToWait parameter.

                                      ถ้า xClearOnExit ถูกเซ็ตเป็น pdFALSE ดังนั้น the bits ที่เซ็ตใน the event group ไม่ถูกเปลี่ยนแปลง
                                      เมื่อการเรียกถึง xEventGroupWaitBits() ส่งคืนกลับ.

tha

     xWaitForAllBits      xWaitForAllBits ถูกใช้เพื่อสร้างอย่างใดอย่างหนึ่ง a logical AND test (โดยที่ทุก bits ต้องถูก set) หรือ a
                                       logical OR test (โดยที่อย่างน้อย bits ต้องถูก set) ดังต่อไปนี้:

                                       ถ้า xWaitForAllBits ถูกเซ็ตเป็น pdTRUE ดังนั้น xEventGroupWaitBits() จะส่งคืนกลับเมื่ออย่างใด
                                       อย่างหนึ่ง the bits ทั้งมดที่เซ็ตใน the value ที่ส่งผ่านเป็น the uxBitsToWaitFor parameter ถูกเซ็ต
                                       ใน the event group หรือ the specified block time หมดเวลาลง.

                                       ถ้า xWaitForAllBits ถูกเซ็ตเป็น pdFALSE ดังนั้น xEventGroupWaitBits() จะส่งคืนกลับเมื่อ the
                                       bits ใดๆที่เซ็ตใน the value ที่ส่งผ่านเป็น the uxBitsToWaitFor parameter ถูกเซ็ตใน the event
                                       group หรือ the specified block time หมดเวลาลง.

     xTicksToWait         จำนวนสูงสุดของเวลา (ระบุเป็น 'ticks') เพื่อรอสำหรับหนึ่ง/ทั้งหมด (ขึ้นอยู่กับ the xWaitForAllBits value)
                                       ของ the bits ที่ระบุโดย uxBitsToWaitFor กลายมาเป็น set.