FreeRTOS API Direct To Task Notifications

Started by tha, December 18, 2021, 06:11:43 AM

Previous topic - Next topic

tha

Note: แต่ละ notification ภายใน the array ทำงานโดยอิสระ – a task สามารถบล็อกเฉพาะกับ notification หนึ่งรายการภายใน the array ในแต่ละครั้งเท่านั้นและจะไม่ถูกปลดบล็อกโดย a notification ที่ส่งไปยัง array index อื่นใดๆ.

โดยที่ xTaskNotifyWait() จะส่งคืนกลับเมื่อ a notification กำลังค้างอยู่, ulTaskNotifyTake() จะส่งคืนกลับเมื่อ the task's notification value ไม่เป็นศูนย์, ซึ่งจะลด the task's notification value ก่อนมันจะส่งคืนกลับ.

configUSE_TASK_NOTIFICATIONS ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h (หรือทิ้งไว้ไม่กำหนด) สำหรับมาโครเหล่านี้มีให้ใช้ประโยชน์. The constant configTASK_NOTIFICATION_ARRAY_ENTRIES เซ็ตจำนวนของ indexes ในแต่ละ task's array ของ task notifications.

tha

Backward compatibility information: (ข้อมูลความเข้ากันได้ย้อนหลัง)

ก่อนถึง FreeRTOS V10.4.0 แต่ละ task มี a single "notification value", และทุก task notification API functions ทำงานกับค่านั้น. การแทนที่ the single notification value ด้วย an array of notification values ทำให้จำเป็นต้องมีชุดใหม่ของ API functions ที่สามารถระบุที่อยู่ notifications ภายใน the array. ulTaskNotifyTake() เป็น the original API function, และยังคงเข้ากันได้ย้อนหลังโดยทำงานกับ the notification value ที่ index 0 ใน the array เสมอ. การเรียก ulTaskNotifyTake() เทียบเท่ากับการเรียก ulTaskNotifyTakeIndexed() ที่มี the uxIndexToWaitOn parameter เซ็ตเป็น 0.

tha

Parameters:

     uxIndexToWaitOn        The index ภายใน the calling task's array of notification values ซึ่ง the calling task จะรอสำหรับ a notification ไม่เป็น
                                             ศูนย์.

                                             uxIndexToWaitOn ต้องน้อยกว่า configTASK_NOTIFICATION_ARRAY_ENTRIES.

                                             xTaskNotifyTake() ไม่มี parameter นี้และจะรอสำหรับ notifications ที่ index 0.

     xClearCountOnExit      ถ้า an RTOS task notification ถูกรับและ xClearCountOnExit ถูกเซ็ตเป็น pdFALSE ดังนั้น the RTOS task's notification
                                            value จะถูกลดก่อน ulTaskNotifyTake() ออก. นี้เทียบเท่ากับค่าของ a counting semaphore ที่กำลังถูกลดโดยการเรียกถึง
                                            xSemaphoreTake() สำเร็จ.

                                            ถ้า an RTOS task notification ถูกรับและ xClearCountOnExit ถูกเซ็ตเป็น pdTRUE ดังนั้น the RTOS task's notification
                                            value จะถูกรีเซ็ตเป็น 0 ก่อน ulTaskNotifyTake() ออก. นี้เทียบเท่ากับค่าของ a binary semaphore ที่กำลังถูกทิ้งเป็นศูนย์ (or
                                            empty, or 'not available') หลังจากการเรียกถึง xSemaphoreTake() สำเร็จ.

     xTicksToWait               The maximum time ที่รอใน the Blocked state เพื่อ a notification ถูกรับถ้า a notification ไม่ค้างอยู่แล้วเมื่อ
                                            ulTaskNotifyTake() ถูกเรียก.

                                           The RTOS task ไม่ใช้ CPU time ใดๆเมื่อมันอยู่ใน the Blocked state.

                                           The time ถูกระบุใน RTOS tick periods. The pdMS_TO_TICKS() macro สามารถถูกใช้เพื่อแปลง a time ที่ระบุใน
                                           milliseconds ลงใน a time ที่ระบุใน ticks.

Returns:

     ค่าของ the task's notification value ก่อนมันจะถูกลดหรือเคลียร์ (ดูคำอธิบายของ xClearCountOnExit).

Example usage:

[ตัวอย่างเพิ่มเติมถูกอ้างอิงจาก the main RTOS task notifications page]
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)
https://www.freertos.org/ulTaskNotifyTake.html


tha

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

xTaskNotify / xTaskNotifyIndexed
[RTOS Task Notification API]

task.h

BaseType_t xTaskNotify( TaskHandle_t xTaskToNotify,
                         uint32_t ulValue,
                         eNotifyAction eAction );

BaseType_t xTaskNotifyIndexed( TaskHandle_t xTaskToNotify,
                                UBaseType_t uxIndexToNotify,
                                uint32_t ulValue,
                                eNotifyAction eAction );


[ถ้าคุณกำลังใช้ RTOS task notifications เพื่อจัดให้มีใช้ binary or counting semaphore type behaviour ดังนั้นใช้ xTaskNotifyGive() API function ที่ง่ายกว่าแทน xTaskNotify()]

แต่ละ task มี an array of 'task notifications' (หรือเพียงแค่ 'notifications'), แต่ละของมันมี a state และ a 32-bit value. A direct to task notification เป็น an event ที่ส่งโดยตรงไปยัง a task ที่สามารถปลดบล็อก the receiving task, และเลือกที่จะอัปเดตหนึ่งใน the receiving task's notification values ได้หลายวิธี. ตัวอย่างเช่น, a notification อาจเขียนทับหนึ่งใน the receiving task's notification values, หรือเพียงแค่เซ็ตบิตอย่างน้อยหนึ่งบิตในหนึ่งใน the receiving task's notification values.

tha

xTaskNotify() ถูกใช้เพื่อส่ง an event โดยตรงไปยังและมีศักยภาพปลดบล็อก an RTOS task, และเลือกที่จะอัปเดตหนึ่งใน the receiving task's notification values ด้วยวิธีใดวิธีหนึ่งต่อไปนี้:

     •  เขียน a 32-bit number ไปยัง the notification value
     •  บวกหนึ่ง (เพิ่ม) the notification value
     •  เซ็ตอย่างน้อยหนึ่งบิตใน the notification value
     •  ทิ้ง the notification value ไว้ไม่เปลี่ยน

xTaskNotify() and xTaskNotifyIndexed() เป็นมาโครที่เทียบเท่ากัน - ความแตกต่างเพียงอย่างเดียวคือ xTaskNotifyIndexed() สามารถดำเนินการกับ task notification ใดๆภายใน the array และ xTaskNotify() ดำเนินการกับ the task notification ที่ array index 0 เสมอ.

ฟังชั่นนี้ต้องไม่ถูกเรียกจาก an interrupt service routine (ISR). ใช้ xTaskNotifyFromISR() แทน.

configUSE_TASK_NOTIFICATIONS ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h (หรือทิ้งไว้ไม่กำหนด) สำหรับมาโครเหล่านี้มีให้ใช้ประโยชน์. The constant configTASK_NOTIFICATION_ARRAY_ENTRIES เซ็ตจำนวนของ indexes ในแต่ละ task's array ของ task notifications.

tha

Backward compatibility information: (ข้อมูลความเข้ากันได้ย้อนหลัง)

ก่อนถึง FreeRTOS V10.4.0 แต่ละ task มี a single "notification value", และทุก task notification API functions ทำงานกับค่านั้น. การแทนที่ the single notification value ด้วย an array of notification values ทำให้จำเป็นต้องมีชุดใหม่ของ API functions ที่สามารถระบุที่อยู่ notifications ภายใน the array. xTaskNotify() เป็น the original API function, และยังคงเข้ากันได้ย้อนหลังโดยทำงานกับ the notification value ที่ index 0 ใน the array เสมอ. การเรียก xTaskNotify() เทียบเท่ากับการเรียก xTaskNotifyIndexed() ที่มี the uxIndexToNotify parameter เซ็ตเป็น 0.

tha

Parameters:

     xTaskToNotify           The handle of the RTOS task ที่กำลังถูกแจ้งเตือน. นี้เป็น the target task

                                         เพื่อได้รับ a task's handle สร้าง the task โดยใช้ xTaskCreate() และทำการใช้ของ the pxCreatedTask parameter, หรือ
                                         สร้าง the task โดยใช้ xTaskCreateStatic() และเก็บ the returned value, หรือใช้ the task's name ในการเรียกไปยัง
                                         xTaskGetHandle().

                                         The handle ของ the currently executing RTOS task ถูกส่งคืนกลับโดย the xTaskGetCurrentTaskHandle() API
                                         function.

     uxIndexToNotify       The index ภายใน the target task's array ของ notification values ที่ the notification จะถูกส่ง.

                                        uxIndexToNotify ต้องน้อยกว่า configTASK_NOTIFICATION_ARRAY_ENTRIES.

                                        xTaskNotify() ไม่มี parameter นี้และส่ง notifications ไปยัง index 0 เสมอ.

     ulValue                      ใช้เพื่ออัปเดต the notification value of the target task. ดูคำอธิบายของ of the eAction parameter ข้างล่าง.

     eAction                     An enumerated type ที่สามารถรับค่าใดค่าหนึ่งที่บันทึกไว้ในตารางด้านล่างเพื่อดำเนินการกระทำที่เกี่ยวข้อง.

tha



     eAction                                        An enumerated type ที่สามารถรับค่าใดค่าหนึ่งที่บันทึกไว้ในตารางด้านล่างเพื่อดำเนินการกระทำที่เกี่ยวข้อง.

     eNoAction                                   The target task รับ the event, แต่ notification value ของมันไม่ถูกอัปเดต. ในกรณีนี้ ulValue จะไม่ถูกใช้.

     eSetBits                                      The notification value of the target task จะเป็น bitwise ORed(ออร์) กับ ulValue. ตัวอย่างเช่น, ถ้า ulValue ถูก
                                                         เซ็ตเป็น 0x01, ดังนั้น bit 0 จะได้รับการเซ็ตภายใน the target task's notification value. ในทำนองเดียวกัน ถ้า
                                                         ulValue เป็น 0x04 ดังนั้น bit 2  จะได้รับการเซ็ตใน the target task's notification value. ด้วยวิธีนี้ the RTOS
                                                         task notification mechanism สามารถถูกใช้เป็นทางเลือกที่มีน้ำหนักเบาแทน an event group.

     eIncrement                             The notification value of the target task จะถูกเพิ่มขึ้นหนึ่ง, การทำการเรียกไปยัง xTaskNotify() จะเทียบเท่ากับ
                                                         การเรียกไปยัง xTaskNotifyGive(). ในกรณีนี้ ulValue จะไม่ถูกใช้.

     eSetValueWithOverwrite        The notification value of the target task ถูกเซ็ตโดยไม่มีเงื่อนไขไปยัง ulValue. ด้วยวิธีนี้ the RTOS task
                                                        notification mechanism กำลังถูกใช้เป็นทางเลือกที่มีน้ำหนักเบาแทน xQueueOverwrite().

     eSetValueWithoutOverwrite  ถ้า the target task ไม่มี a notification pending (รอดำเนินการอยู่)แล้วดังนั้น notification value ของมันจะถูกเซ็ตไปยัง
                                                        ulValue.

                                                        ถ้า the target task มี a notification pending (รอดำเนินการอยู่)แล้วดังนั้น notification value ของมันจะไม่ถูก
                                                        อัปเดตเนื่องจากการทำอย่างนี้จะเขียนทับค่าก่อนหน้าก่อนที่มันจะถูกใช้. ในกรณีนี้การเรียกไปยัง xTaskNotify() จะล้มเหลว
                                                        และ pdFALSE จะถูกส่งคืนกลับ.

                                                        ด้วยวิธีนี้ the RTOS task notification mechanism กำลังถูกใช้เป็นทางเลือกที่มีน้ำหนักเบาแทน xQueueSend() บน
                                                        a queue ที่มีความยาว 1.

Returns:

     pdPASS จะถูกส่งคืนกลับในทุกกรณีนอกเหนือจากเมื่อ eAction ถูกเซ็ตเป้น eSetValueWithoutOverwrite และ the target task's notification value ไม่
     สามารถถูกอัปเดตเพราะว่า the target task มี a notification pending แล้ว.

Example usage:

[ตัวอย่างเพิ่มเติมถูกอ้างอิงจาก the main RTOS task notifications page]
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)
https://www.freertos.org/xTaskNotify.html