FreeRTOS API Direct To Task Notifications

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

Previous topic - Next topic

tha

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

xTaskNotifyAndQuery / xTaskNotifyAndQueryIndexed
[RTOS Task Notification API]

task.h

BaseType_t xTaskNotifyAndQuery( TaskHandle_t xTaskToNotify,
                                 uint32_t ulValue,
                                 eNotifyAction eAction,
                                 uint32_t *pulPreviousNotifyValue );

BaseType_t xTaskNotifyAndQueryIndexed( TaskHandle_t xTaskToNotify,
                                        UBaseType_t uxIndexToNotify,
                                        uint32_t ulValue,
                                        eNotifyAction eAction,
                                        uint32_t *pulPreviousNotifyValue );


ดู RTOS Task Notifications สำหรับรายละเอียดเพิ่มเติม.

xTaskNotifyAndQueryIndexed() ดำเนินการการทำงานเช่นเดียวกับ xTaskNotifyIndexed() โดยเพิ่มที่มันส่งคืนกลับ the target task's prior notification value ด้วย (the notification value ที่เวลาที่ the function ถูกเรียกแทนที่จะเป็นเมื่อ the function ส่งคืนกลับ) ใน pulPreviousNotifyValue parameter ที่เพิ่มมา.

xTaskNotifyAndQuery() ดำเนินการการทำงานเช่นเดียวกับ xTaskNotify() โดยเพิ่มที่มันส่งคืนกลับ the target task's prior notification value ด้วย (the notification value ตามที่เป็นอยู่ในขณะที่ the function ถูกเรียก, แทนที่จะเป็นเมื่อ the function ส่งคืนกลับ) ใน pulPreviousNotifyValue parameter ที่เพิ่มมา.

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

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 ที่สามารถรับค่าใดค่าหนึ่งที่บันทึกไว้ในตารางด้านล่างเพื่อดำเนินการกระทำที่เกี่ยวข้อง.

     pulPreviousNotifyValue   สามารถถูกใช้เพื่อส่งออก the target task's notification value ก่อน bits ใดๆจะถูกแก้ไขโดย the action of
                                                  xTaskNotifyAndQuery().

                                                   pulPreviousNotifyValue เป็น an optional parameter, และสามารถถูกเซ็ตเป็น NULL ถ้ามันไม่ถูกต้องการ. ถ้า
                                                   pulPreviousNotifyValue ไม่ถูกใช้ดังนั้นให้พิจารณาโดยใช้ xTaskNotify() แทน xTaskNotifyAndQuery().

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() จะเทียบเท่ากับ
                                                         การเรียกไปยัง 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:

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


tha

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

xTaskNotifyAndQueryFromISR /
xTaskNotifyAndQueryIndexedFromISR

[RTOS Task Notification API]

task.h

BaseType_t xTaskNotifyAndQueryFromISR(
                      TaskHandle_t xTaskToNotify,
                      uint32_t ulValue,
                      eNotifyAction eAction,
                      uint32_t *pulPreviousNotifyValue,
                      BaseType_t *pxHigherPriorityTaskWoken );

BaseType_t xTaskNotifyAndQueryIndexedFromISR(
                      TaskHandle_t xTaskToNotify,
                      UBaseType_t uxIndexToNotify
                      uint32_t ulValue,
                      eNotifyAction eAction,
                      uint32_t *pulPreviousNotifyValue,
                      BaseType_t *pxHigherPriorityTaskWoken );


ดู RTOS Task Notifications สำหรับรายละเอียดที่มากขึ้น.

xTaskNotifyAndQueryIndexedFromISR() ดำเนินการการทำงานเช่นเดียวกับ xTaskNotifyIndexedFromISR() โดยเพิ่มที่มันส่งคืนกลับ the target task's prior notification value ด้วย (the notification value ที่เวลาที่ the function ถูกเรียกแทนที่จะเป็นที่เวลา the function ส่งคืนกลับ) ใน pulPreviousNotifyValue parameter ที่เพิ่มมา.

xTaskNotifyAndQueryFromISR() ดำเนินการการทำงานเช่นเดียวกับ xTaskNotifyFromISR() โดยเพิ่มที่มันส่งคืนกลับ the target task's prior notification value ด้วย (the notification value ที่เวลาที่ the function ถูกเรียก, แทนที่จะเป็นที่เวลา  the function ส่งคืนกลับ) ใน pulPreviousNotifyValue parameter ที่เพิ่มมา.

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 ที่สามารถรับค่าใดค่าหนึ่งที่บันทึกไว้ในตารางด้านล่างเพื่อดำเนินการกระทำที่เกี่ยวข้อง.

     pulPreviousNotifyValue   สามารถถูกใช้เพื่อส่งออก the target task's notification value ก่อน bits ใดๆจะถูกแก้ไขโดย the action of
                                                  xTaskNotifyAndQueryFromISR().

                                                   pulPreviousNotifyValue เป็น an optional parameter, และสามารถถูกเซ็ตเป็น NULL ถ้ามันไม่ถูกต้องการ. ถ้า
                                                   pulPreviousNotifyValue ไม่ถูกใช้ดังนั้นให้พิจารณาโดยใช้ xTaskNotify() แทน xTaskNotifyAndQueryFromISR().

pxHigherPriorityTaskWoken  *pxHigherPriorityTaskWoken ต้องถูกเริ่มต้นเป็น pdFALSE (0).

                                                   xTaskNotifyAndQueryFromISR() จะเซ็ต *pxHigherPriorityTaskWoken เป็น pdTRUE ถ้าการส่ง the notification
                                                   เป็นเหตุให้ a task ปลดบล็อก, และ the unblocked task มี a priority สูงกว่า the currently running task.

                                                   ถ้า xTaskNotifyAndQueryFromISR() เซ็ตค่านี้เป็น pdTRUE ดังนั้น a context switch ควรถูกร้องขอก่อน the
                                                   interrupt จะถูกออก. ดูตัวอย่างข้างล่าง.

                                                   pxHigherPriorityTaskWoken เป็น an optional parameter และสามารถถูกเซ็ตเป็น NULL.

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() จะเทียบเท่ากับ
                                                         การเรียกไปยัง 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:

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

tha

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

xTaskNotifyFromISR / xTaskNotifyIndexedFromISR
[RTOS Task Notification API]

task.h

BaseType_t xTaskNotifyFromISR( TaskHandle_t xTaskToNotify,
                                uint32_t ulValue,
                                eNotifyAction eAction,
                                BaseType_t *pxHigherPriorityTaskWoken );

BaseType_t xTaskNotifyIndexedFromISR( TaskHandle_t xTaskToNotify,
                                       UBaseType_t uxIndexToNotify,
                                       uint32_t ulValue,
                                       eNotifyAction eAction,
                                       BaseType_t *pxHigherPriorityTaskWoken );


Versions of xTaskNotify() and xTaskNotifyIndexed() ที่สามารถถูกใช้จาก an interrupt service routine (ISR). ดู the documentation page สำหรับ the xTaskNotify() API function สำหรับคำอธิบายการทำงานของมันและ the necessary configuration parameters, ตลอดจน backward compatibility information.

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 ที่สามารถรับค่าใดค่าหนึ่งที่บันทึกไว้ในตารางด้านล่างเพื่อดำเนินการกระทำที่เกี่ยวข้อง.

pxHigherPriorityTaskWoken  *pxHigherPriorityTaskWoken ต้องถูกเริ่มต้นเป็น pdFALSE (0).

                                                   xTaskNotifyFromISR() จะเซ็ต *pxHigherPriorityTaskWoken เป็น pdTRUE ถ้าการส่ง the notification
                                                   เป็นเหตุให้ a task ปลดบล็อก, และ the unblocked task มี a priority สูงกว่า the currently running task.

                                                   ถ้า xTaskNotifyFromISR() เซ็ตค่านี้เป็น pdTRUE ดังนั้น a context switch ควรถูกร้องขอก่อน the
                                                   interrupt จะถูกออก. ดูตัวอย่างข้างล่าง.

                                                   pxHigherPriorityTaskWoken เป็น an optional parameter และสามารถถูกเซ็ตเป็น NULL.