FreeRTOS API Event Groups

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

Previous topic - Next topic

tha

Returns:

     ค่าของ the event group เมื่ออย่างใดอย่างหนึ่ง the event bits ที่กำลังรออยู่กลายมาเป็นเซ็ต, หรือ the block time หมดเวลาลง.
     ค่าปัจจุบันของ the event bits ใน an event group จะแตกต่างกับ the returned value ถ้า a higher priority task หรือ
     interrupt เปลี่ยนค่าของ an event bit ระหว่าง the calling task ที่ออกจาก the Blocked state และออกจาก the
     xEventGroupWaitBits() function.

     ทดสอบ the return value เพื่อให้รู้ว่า bits ไหนถูกเซ็ต. ถ้า xEventGroupWaitBits() ส่งคืนกลับเนื่องจาก timeout ของมันหมด
     เวลาลงดังนั้นไม่ the bits ทั้งหมดที่กำลังรออยู่จะถูกเซ็ต. ถ้า xEventGroupWaitBits() ส่งคืนกลับเนื่องจาก the bits ที่มันกำลังรออยู่
     ถูกเซ็ตดังนั้น the returned value คือ the event group value ก่อนที่ bits ใดๆจะถูกเคลียร์โดยอัตโนมัติเนื่องจาก the
     xClearOnExit parameter ถูกเซ็ตเป็น pdTRUE.

Example usage:
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)
https://www.freertos.org/xEventGroupWaitBits.html

tha

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

xEventGroupSetBits()
[Event Group API]

event_groups.h

EventBits_t xEventGroupSetBits( EventGroupHandle_t xEventGroup,
                                 const EventBits_t uxBitsToSet );


เซ็ต bits (flags) ภายใน an RTOS event group. ฟังชั่นนี้ไม่สามารถถูกเรียกจาก an interrupt. xEventGroupSetBitsFromISR() เป็น a version ที่สามารถถูกเรียกจาก an interrupt.

การเซ็ต bits ใน an event group จะปลดบล็อก tasks ที่ถูกบล็อกรอสำหรับ the bits โดยอัตโนมัติ.

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

tha

Parameters:

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

     uxBitsToSet       A bitwise value ที่แสดง the bit เดียวหรือหลาย bits เซ็ตภายใน the event group. ตัวอย่างเช่น, เซ็ต
                                  uxBitsToSet เป็น 0x08 เพื่อเซ็ตเฉพาะ bit 3. เซ็ต uxBitsToSet เป็น 0x09 เพื่อเซ็ต bit 3 และ bit 0.


tha

Returns:

     ค่าของ the event group ณ เวลาที่เรียกถึง xEventGroupSetBits() ส่งคืนกลับ.

     มีสองเหตุผลว่าทำใม the returned value อาจมี the bits ที่ระบุโดย the uxBitsToSet parameter ถูกเคลียร์:

          1. ถ้าการเซ็ต a bit เป็นผลให้ a task ที่กำลังรอสำหรับ the bit นั้นอยู่ออกจาก the blocked state ดังนั้นจึงเป็นไปได้ว่า the bit
              จะถูกเคลียร์โดยอัตโนมัติ (ดู the xClearBitOnExit parameter of xEventGroupWaitBits()).

          2. unblocked (หรือมิฉะนั้น Ready state) task ใดๆที่มี a priority สูงกว่า the task นั้นที่เรียก xEventGroupSetBits() จะ
              ปฏิบัติและอาจเปลี่ยน the event group value ก่อนการเรียกถึง xEventGroupSetBits() จะส่งคืนกลับ.

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

tha

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

xEventGroupSetBitsFromISR()
[Event Group API]

event_groups.h

BaseType_t xEventGroupSetBitsFromISR(
                          EventGroupHandle_t xEventGroup,
                          const EventBits_t uxBitsToSet,
                          BaseType_t *pxHigherPriorityTaskWoken );


เซ็ต bits (flags) ภายใน an RTOS event group. เวอร์ชั่นของ xEventGroupSetBits() ที่สามารถถูกเรียกจาก an interrupt service routine (ISR).

การเซ็ต bits ใน an event group จะปลดบล็อกโดยอัตโนมัติ tasks ที่ถูกบล็อกรอสำหรับ the bits อยู่.

การเซ็ต bits ใน an event group ไม่ใช่การทำงานที่กำหนดเนื่องจากมีจำนวนที่ไม่ทราบของ tasks ที่อาจกำลังรอสำหรับ the bit เดียวหรือหลาย bits ถูกเซ็ตอยู่. FreeRTOS ไม่ยอมให้การทำงานที่ไม่ได้กำหนดถูกดำเนินการใน interrupts หรือจาก critical sections. ดังนั้น xEventGroupSetBitFromISR() ส่ง a message ไปยัง the RTOS daemon task เพื่อให้ the set operation ถูกดำเนินการใน the context of the daemon task - โดยที่ a scheduler lock ถูกใช้แทนที่ a critical section.

tha

หมายเหตุ: ตามที่กล่าวไว้ในย่อหน้าข้างต้น, การเซ็ต bits จาก an ISR จะเลื่อน the set operation ไปยัง the RTOS daemon task (รู้อีกอย่างว่า the timer service task). The RTOS daemon task ถูกวางกำหนดการสอดคล้องกันกับ priority ของมัน, เช่นเดียวกับ RTOS task อื่นใดๆ. ดังนั้น, ถ้าจำเป็นต้องให้ the set operation เสร็จสิ้นทันที (ก่อน a task ที่สร้างโดย the application ปฏิบัติ) ดังนั้น the priority of the RTOS daemon task ต้องสูงกว่า the priority of any application task ที่ใช้ the event group. The priority of the RTOS daemon task ถูกเซ็ตโดย the configTIMER_TASK_PRIORITY definition ใน FreeRTOSConfig.h.

INCLUDE_xEventGroupSetBitFromISR, configUSE_TIMERS and INCLUDE_xTimerPendFunctionCall ทั้งหมดต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h เพื่อให้ the xEventGroupSetBitsFromISR() function มีให้ใช้ประโยชน์.

The RTOS source file FreeRTOS/source/event_groups.c ต้องถูก included ใน the build เพื่อให้ the xEventGroupSetBitsFromISR() function มีให้ใช้ประโยชน์.

tha

Parameters:

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

     uxBitsToSet                          A bitwise value ที่แสดง the bit เดียวหรือหลาย bits เซ็ต. ตัวอย่างเช่น, เซ็ต uxBitsToSet
                                                     เป็น 0x08 เพื่อเซ็ตเฉพาะ bit 3. เซ็ต uxBitsToSet เป็น 0x09 เพื่อเซ็ต bit 3 และ bit 0.

   pxHigherPriorityTaskWoken   ตามที่กล่าวไว้ข้างต้น, การเรียกฟังชั่นนี้จะส่งผลให้ a message ถูกส่งไปยัง the RTOS daemon
                                                       task. ถ้า the priority of the daemon task สูงกว่า the priority of the currently
                                                       running task (the task ที่ the interrupt อินเตอร์รัพท์) ดังนั้น
                                                       *pxHigherPriorityTaskWoken จะถูกเซ็ตเป็น pdTRUE โดย
                                                       xEventGroupSetBitsFromISR(), แสดงให้เห็นว่า a context switch ควรถูกร้องขอก่อน
                                                       the interrupt จะออก. ด้วยเหตุผลนั้น *pxHigherPriorityTaskWoken ต้องถูกเริ่มต้นเป็น
                                                       pdFALSE. ดูตัวอย่างโค้ดข้างล่าง.

Returns:

     ถ้า the message ถูกส่งไปยัง the RTOS daemon task แล้วดังนั้น pdPASS จะถูกส่งคืนกลับ, ถ้าเป็นอย่างอื่น pdFAIL จะถูกส่งคืน
     กลับ. pdFAIL จะถูกส่งคืนกลับถ้า the timer service queue เต็มอยู่.

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

tha

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

xEventGroupClearBits()
[Event Group API]

event_groups.h

EventBits_t xEventGroupClearBits(
                                 EventGroupHandle_t xEventGroup,
                                 const EventBits_t uxBitsToClear );


เคลียร์ bits (flags) ภายใน an RTOS event group. ฟังชั่นนี้ไม่สามารถถูกเรียกจาก an interrupt. ดู xEventGroupClearBitsFromISR() สำหรับเวอร์ชั่นที่สามารถถูกเรียกจาก an interrupt.

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

Parameters:

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

     uxBitsToClear             A bitwise value ที่แสดง the bit เดียวหรือหลาย bits เคลียร์ใน the event group. ตัวอย่างเช่น, เซ็ต
                                           uxBitsToClear เป็น 0x08 เพื่อเคลียร์เฉพาะ bit 3. เซ็ต uxBitsToClear เป็น 0x09 เพื่อเคลียร์ bit
                                           3 และ bit 0.

Returns:

     ค่าของ the event group ก่อนที่ the specified bits ถูกเคลียร์.

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