FreeRTOS API Direct To Task Notifications

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

Previous topic - Next topic

tha



     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() จะเทียบเท่ากับ
                                                         การเรียกไปยัง vTaskNotifyGiveFromISR(). ในกรณีนี้ 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]
ตัวอย่างนี้สาธิตวิธีการใช้ xTaskNotifyFromISR() ที่มี the eSetBits action. ดู the xTaskNotify() API documentation page สำหรับตัวอย่างการแสดงวิธีการใช้ the eNoAction, eSetValueWithOverwrite and eSetValueWithoutOverwrite actions.
(ตัวอย่างโค้ดดูในลิ้งค์เอานะครับ)
https://www.freertos.org/xTaskNotifyFromISR.html

tha

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

xTaskNotifyWait / xTaskNotifyWaitIndexed
[RTOS Task Notification API]

task.h

BaseType_t xTaskNotifyWait( uint32_t ulBitsToClearOnEntry,
                             uint32_t ulBitsToClearOnExit,
                             uint32_t *pulNotificationValue,
                             TickType_t xTicksToWait );


BaseType_t xTaskNotifyWaitIndexed( UBaseType_t uxIndexToWaitOn,
                                    uint32_t ulBitsToClearOnEntry,
                                    uint32_t ulBitsToClearOnExit,
                                    uint32_t *pulNotificationValue,
                                    TickType_t xTicksToWait );


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

แต่ละ 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.

xTaskNotifyWait() รอ, ที่มีตัวเลือก timeout, สำหรับ the calling task เพื่อรับ a notification. ถ้า the receiving RTOS task ถูกบล็อกแล้วกำลังรอสำหรับ a notification เมื่อ the notification ที่มันกำลังรอมาถึง the receiving RTOS task จะถูกเอาออกจาก the Blocked state และ the notification ถูกเคลียร์.

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

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

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

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

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. xTaskNotifyWait() เป็น the original API function, และยังคงเข้ากันได้ย้อนหลังโดยทำงานกับ the notification value ที่ index 0 ใน the array เสมอ. การเรียก xTaskNotifyWait() เทียบเท่ากับการเรียก xTaskNotifyWaitIndexed() ที่มี 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.

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

     ulBitsToClearOnEntry       บิตใดๆที่เซ็ตใน ulBitsToClearOnEntry จะถูกเคลียร์ใน the calling RTOS task's notification value เมื่อเข้าสู่ the
                                                  xTaskNotifyWait() function (ก่อน the task รอสำหรับ a new notification) จัดให้มี a notification ไม่รอดำเนินการอยู่
                                                  เมื่อ xTaskNotifyWait() ถูกเรียก.

                                                  ตัวอย่างเช่น, ถ้า ulBitsToClearOnEntry เป็น 0x01, ดังนั้น bit 0 of the task's notification value จะถูกเคลียร์เมื่อเข้าสู่
                                                  the function.

                                                  การเซ็ต ulBitsToClearOnEntry เป็น 0xffffffff (ULONG_MAX) จะเคลียร์ทุก the bits ใน the task's notification
                                                  value, เป็นการเคลียร์ค่าเป็น 0 อย่างมีประสิทธิภาพ.

     ulBitsToClearOnExit         บิตใดๆที่เซ็ตใน ulBitsToClearOnExit จะถูกเคลียร์ใน the calling RTOS task's notification value ก่อนที่
                                                 xTaskNotifyWait() function จะออกถ้า a notification ถูกรับแล้ว.
       
                                                 The bits ถูกเคลียร์หลังจาก the RTOS task's notification value ถูกบันทึกใน *pulNotificationValue (ดูคำอธิบายของ
                                                 pulNotificationValue ข้างล่าง).

                                                 ตัวอย่างเช่น, ถ้า ulBitsToClearOnExit เป็น 0x03, ดังนั้น bit 0 and bit 1 of the task's notification value จะถูกเคลียร์
                                                 ก่อน the function exits.

                                                 การเซ็ต ulBitsToClearOnExit เป็น 0xffffffff (ULONG_MAX) จะเคลียร์ทุก the bits ใน the task's notification value,
                                                 เป็นการเคลียร์ค่าเป็น 0 อย่างมีประสิทธิภาพ.

     pulNotificationValue        ใช้เพื่อส่งออก the RTOS task's notification value. The value ที่คัดลอกไปยัง *pulNotificationValue เป็น the RTOS
                                                 task's notification value ตามที่มันเป็นก่อน bits ใดๆจะถูกเคลียร์เนื่องจาก the ulBitsToClearOnExit setting.

    xTicksToWait                   The maximum time ที่รอใน the Blocked state เพื่อ a notification ถูกรับถ้า a notification ไม่รอดำเนินการอยู่เมื่อ
                                               xTaskNotifyWait() ถูกเรียก.

                                               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:

     pdTRUE ถ้า a notification ถูกรับแล้ว, หรือ a notification มีรอดำเนินการอยู่เมื่อ xTaskNotifyWait() ถูกเรียกwas called.

     pdFALSE ถ้าการเรียกถึง xTaskNotifyWait() หมดเวลาลงก่อน a notification ถูกรับ.

Example usage:

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


tha

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

xTaskNotifyStateClear / xTaskNotifyStateClearIndexed
[RTOS Task Notification API]

task.h

BaseType_t xTaskNotifyStateClear( TaskHandle_t xTask );

BaseType_t xTaskNotifyStateClearIndexed( TaskHandle_t xTask,
                                          UBaseType_t uxIndexToClear );


แต่ละ RTOS task มี an array of task notifications. แต่ละ task notification มี a notification state ที่สามารถเป็นอย่างใดอย่างหนึ่ง 'pending' หรือ 'not pending', และ a 32-bit notification value.

ถ้า a notification ถูกส่งไปยัง an index ภายใน the array of notifications ดังนั้น the notification ที่ๆ index ถูกพูดได้ว่าเป็น 'pending' จนกระทั่ง the task อ่าน notification value ของมันหรือเคลียร์อย่างชัดแจ้ง the notification state เป็น 'not pending' โดยการเรียก xTaskNotifyStateClear().

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

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

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. xTaskNotifyStateClear() เป็น the original API function, และยังคงเข้ากันได้ย้อนหลังโดยทำงานกับ the notification value ที่ index 0 ภายใน the array เสมอ. การเรียก xTaskNotifyStateClear() เทียบเท่ากับการเรียก xTaskNotifyStateClearIndexed() ที่มี the uxIndexToNotify parameter เซ็ตเป็น 0.

Parameters:

   xTask                           The handle of the RTOS task ที่จะมี notification state ของมันถูกเคลียร์. เซ็ต xTask เป็น NULL เพื่อเคลียร์ the notification
                                        state of the calling task.

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

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

     uxIndexToClear      The index ภายใน the target task's array of notification values ที่จะดำเนินการ. ตัวอย่างเช่น, การเซ็ต uxIndexToClear เป็น 1
                                       จะเคลียร์สถานะของ the notification ที่ index 1 ภายใน the array.

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

                                       ulTaskNotifyStateClear() ไม่มี parameter นี้และจะกระทำบน the notification ที่ index 0 เสมอ.

Returns:

     ถ้า the task ที่อ้างอิงโดย xTask มี a notification pending, และ the notification ถูกเคลียร์, ดังนั้น pdTRUE ถูกส่งคืนกลับ. ถ้า the task ที่อ้างอิงโดย
     xTask ไม่มี a notification pending ดังนั้น pdFALSE ถูกส่งคืนกลับ.

Example usage:

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

tha

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

ulTaskNotifyValueClear / ulTaskNotifyValueClearIndexed
[RTOS Task Notification API]

task.h 

uint32_t ulTaskNotifyValueClear( TaskHandle_t xTask,
                                 uint32_t ulBitsToClear );

uint32_t ulTaskNotifyValueClearIndexed( TaskHandle_t xTask,
                                        UBaseType_t uxIndexToClear,
                                        uint32_t ulBitsToClear );


แต่ละ RTOS task มี an array of task notifications. แต่ละ task notification มี a notification state ที่สามารถเป็นอย่างใดอย่างหนึ่ง 'pending' หรือ 'not pending', และ a 32-bit notification value.

ulTaskNotifyValueClearIndexed() เคลียร์ the bits ที่ระบุโดย the ulBitsToClear bit บังใน the notification value ที่ array index uxIndexToClear of the task ที่อ้างอิงโดย xTask.

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

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

tha

Parameters:

     xTask                        The handle of the RTOS task ที่จะมี bits ใน notification value ของมันถูกเคลียร์. เซ็ต xTask เป็น NULL เพื่อเคลียร์ bits ใน
                                       the notification value of the calling task.

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

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

     uxIndexToClear      The index ภายใน the target task's array of notification values ที่จะเคลียร์ the bits. uxIndexToClear ต้องน้อยกว่า
                                       configTASK_NOTIFICATION_ARRAY_ENTRIES. ulTaskNotifyValueClear() ไม่มี parameter นี้และจะเคลียร์ bits ใน the
                                       notification value ที่ index 0 เสมอ.

     ulBitsToClear          Bit mask ของ the bits ที่จะเคลียร์ใน the notification value of xTask. เซ็ต a bit เป็น 1 เพื่อเคลียร์บิตที่ตรงกันใน the task's
                                       notification value. เซ็ต ulBitsToClear เป็น 0xffffffff (UINT_MAX on 32-bit architectures) เพื่อเคลียร์ the notification
                                       value เป็น 0. เซ็ต ulBitsToClear เป็น 0 เพื่อสอบถาม the task's notification value โดยไม่มีการเคลียร์บิตใดๆ.

Returns:

     ค่าของ the target task's notification value ก่อนที่ the bits ที่ระบุโดย ulBitsToClear ถูกเคลียร์.

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