FreeRTOS API Reference

Started by tha, December 07, 2021, 06:05:54 AM

Previous topic - Next topic

tha

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

uxTaskGetStackHighWaterMark
uxTaskGetStackHighWaterMark2

[Task Control]

task. h

UBaseType_t uxTaskGetStackHighWaterMark
                                ( TaskHandle_t xTask );

configSTACK_DEPTH_TYPE uxTaskGetStackHighWaterMark2
                                ( TaskHandle_t xTask );


INCLUDE_uxTaskGetStackHighWaterMark ต้องถูกกำหนดเป็น 1 เพื่อฟังชั่นเหล่านี้มีให้ใช้เป็นประโยชน์. ดู the RTOS Configuration documentation สำหรับข้อมูลเพิ่มเติม.

uxTaskGetStackHighWaterMark2() คือ a version of uxTaskGetStackHighWaterMark() ที่ส่งคืนกลับ a user definable type เพื่อเอาออก the data type width restriction ของ UBaseType_t types บน 8-bit architectures.

The stack ที่ใช้โดย a task จะโตขึ้นหรือหดตัวลงเนื่องจาก the task executes และ interrupts ถูกประมวลผล. uxTaskGetStackHighWaterMark() ส่งคืนกลับจำนวนต่ำสุดของ remaining stack space ที่มีให้ใช้ประโยชน์กับ the task ตั้งแต่ the task สตาร์ทการปฏิบัติ -  นั้นคือจำนวนของ stack ที่ยังคงไม่ถูกใช้เมื่อ the task stack อยู่ที่ค่าใหญ่ที่สุด(ลึกที่สุด)ของมัน.  นี่คือสิ่งที่เรียกว่า the stack 'high water mark'.

Parameters:

     xTask     The handle of the task ที่กำลังถูกสอบถาม. A task อาจสอบถาม high water mark ของตัวมันเองโดยส่งผ่าน NULL เป็น the xTask parameter.

Returns:

     ค่าที่ส่งคืนกลับคือ the high water mark เป็น words (ตัวอย่างเช่น, บน a 32 bit machine ค่าที่ส่งคืนกลับเท่ากับ 1 จะแสดงให้เห็นว่า 4 bytes ของ stack ไม่
     ได้ถูกใช้). ถ้า the return value เป็นศูนย์ดังนั้น the task มีทีท่าว่าจะโอเวอร์โฟล์ stack ของมัน. ถ้า the return value เข้าใกล้ศูนย์ดังนั้น the task จะเข้ามาใกล้
     การโอเวอร์โฟล์ stack ของมัน.

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

tha

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

vTaskSetApplicationTaskTag
[Task Control]

task. h

void vTaskSetApplicationTaskTag(
                        TaskHandle_t xTask,
                        TaskHookFunction_t pxTagValue );


configUSE_APPLICATION_TASK_TAG ต้องถูกกำหนดเป็น 1 เพื่อฟังชั่นนี้มีให้ใช้เป็นประโยชน์. ดู the RTOS Configuration documentation สำหรับข้อมูลเพิ่มเติม.

A 'tag' value สามารถถูกกำหนดไปยังแต่ละ task. ค่านี้สำหรับใช้กับ the application เท่านั้น - the RTOS kernel ตัวมันเองไม่ได้ใช้มันในทางใดทางหนึ่ง. The RTOS trace macros documentation page จัดให้มีตัวอย่างที่ดีของวิธีที่ an application ทำการใช้คุณลักษณะนี้.

Parameters:

     xTask            The handle of the task ซึ่ง a tag value กำลังถูกกำหนด. การส่งผ่าน xTask เป็น NULL เป็นเหตุให้ the tag ถูกกำหนดไปยัง the calling
                            task.

     pxTagValue   ค่าที่ถูกกำหนดให้กับ the task tag. นี้เป็นประเภท  TaskHookFunction_t เพื่อยอมให้ a function pointer ถูกกำหนดเป็น the tag, แม้ว่า                     
                              ค่าใดๆสามารถถูกกำหนดตามจริง. ดูตัวอย่างข้างล่าง.

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

tha

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

xTaskCallApplicationTaskHook
[Task Control]

task. h

BaseType_t xTaskCallApplicationTaskHook(
                                   TaskHandle_t xTask,
                                   void *pvParameter );


configUSE_APPLICATION_TASK_TAG ต้องถูกกำหนดเป็น 1 เพื่อฟังชั่นนี้มีให้ใช้เป็นประโยชน์. ดู the RTOS Configuration documentation สำหรับข้อมูลเพิ่มเติม.

A 'tag' value สามารถถูกกำหนดไปยังแต่ละ task. โดยปกติค่านี้สำหรับการใช้ของ the application เท่านั้นและ the RTOS kernel ไม่เข้าถึงมัน. อย่างไรก็ตาม, เป็นไปได้ที่จะใช้ the tag เพื่อกำหนด a hook (หรื callback) function ให้กับ a task - the hook function กำลังถูกปฏิบัติโดยการเรียก xTaskCallApplicationTaskHook(). แต่ละ task สามารถกำหนด callback ของตัวมันเอง, หรือเพียงแค่ไม่กำหนด a callback เลย.

แม้ว่าจะเป็นไปได้ที่จะใช้ the first function parameter เพื่อเรียก the hook function ของ task ใดๆ, การใช้งานทั่วไปส่วนใหญ่ของ task hook function จะใช้กับ the trace hook macros, ตามตัวอย่างที่ให้ไว้ด้านล่าง.

Task hook functions ต้องมีประเภท TaskHookFunction_t, ที่ได้รับ a void * parameter, และส่งคืนกลับค่าของประเภท BaseType_t. The void * parameter สามารถถูกใช้เพื่อส่งผ่านข้อมูลใดๆลงใน the hook function.

Parameters:

     xTask               The handle of the task ซึ่ง hook function กำลังถูกเรียก. การส่งผ่าน NULL เป็น xTask จะเรียกl the hook function ที่เกี่ยวข้องกับ the
                              currently executing task.

     pvParameter    ค่าที่ส่งผ่านไปยัง the hook function. นี้สามารถเป็น a pointer ไปยัง a structure, หรือค่าตัวเลขง่ายๆ.

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


tha

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

vTaskSetThreadLocalStoragePointer
[Task Utilities]

task. h

void vTaskSetThreadLocalStoragePointer( TaskHandle_t xTaskToSet,
                                        BaseType_t xIndex,
                                        void *pvValue )


เซ็ตค่าใน a task's thread local storage array.

ฟังชั่นนี้ถูกมุ่งหมายสำหรับผู้ใช้ขั้นสูงเท่านั้น

Parameters:

     xTaskToSet     The handle of the task ซึ่ง the thread local data กำลังถูกเขียน. A task สามารถเขียนถึง thread local data ของตัวมันเองโดยการใช้
                              NULL เป็น the parameter value.

     xIndex             ดัชนีใน the thread local storage array ซึ่ง data กำลังถูกเขียน.

                              จำนวนของ available array indexes ถูกเซ็ตโดย the configNUM_THREAD_LOCAL_STORAGE_POINTERS compile time
                              configuration constant ใน FreeRTOSConfig.h.

     pvValue           ค่าที่เขียนลงใน the index ที่ระบุโดย the xIndex parameter.

Example usage:

ดูตัวอย่่างที่จัดให้มีบน the thread local storage array documentation page.

tha

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

pvTaskGetThreadLocalStoragePointer
[Task Utilities]

task. h

void *pvTaskGetThreadLocalStoragePointer(
                                 TaskHandle_t xTaskToQuery,
                                 BaseType_t xIndex );


ดึงค่าจาก a task's thread local storage array.

ฟังชั่นนี้ถูกมุ่งหมายสำหรับผู้ใช้ขั้นสูงเท่านั้น

Parameters:

     xTaskToQuery         The handle of the task ซึ่ง the thread local data กำลังถูกอ่าน. A task สามารถอ่าน thread local data ของตัวมันเองโดยการใช้
                                        NULL เป็น the parameter value.

     xIndex                      ดัชนีใน the thread local storage array ซึ่ง data กำลังถูกอ่าน.

                                      จำนวนของ available array indexes ถูกเซ็ตโดย the configNUM_THREAD_LOCAL_STORAGE_POINTERS compile time
                                      configuration constant ใน FreeRTOSConfig.h.

Returns:

     ค่าที่เก็บในตำแหน่งดัชนี xIndex ของ the thread local storage array ของ task xTaskToQuery.

Example usage:

ดูตัวอย่่างที่จัดให้มีบน the thread local storage array documentation page.

tha

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

vTaskSetTimeOutState()
[Task Utilities]

task.h

void vTaskSetTimeOutState( TimeOut_t * const pxTimeOut );

ฟังชั่นนี้ถูกมุ่งหมายสำหรับผู้ใช้ขั้นสูงเท่านั้น

A task สามารถเข้าสู่ the Blocked state เพื่อรอสำหรับ an event. โดยทั่วไป, the task จะไม่รอใน the Blocked state อย่างไม่มีกำหนด, แต่แทนด้วย a timeout period จะถูกระบุ. The task จะถูกเอาออกจาก the Blocked state ถ้า the timeout period หมดเวลาลงก่อน the event ที่ the task กำลังรอจะเกิดขึ้น.

ถ้า a task เข้าสู่และออกจาก the Blocked state มากกว่าหนึ่งครั้งในขณะที่มันกำลังรอสำหรับ the event เกิดขึ้นดังนั้น the timeout ที่ใช้แต่ละครั้งที่ the task เข้าสู่ the Blocked state ต้องถูกปรับเพื่อให้แน่ใจว่าทั้งหมดของเวลาที่ใช้ทั้งหมดใน the Blocked state ไม่เกิน the originally specified timeout period. xTaskCheckForTimeOut() ดำเนินการการปรับ,  โดยคำนึงถึงเหตุการณ์ที่เกิดขึ้นเป็นครั้งคราว เช่น tick count โอเวอร์โฟล์, ซึ่งจะทำให้การปรับแบบแมนน้วลมีแนวโน้มที่จะเกิด error.

vTaskSetTimeOutState() ถูกใช้กับ xTaskCheckForTimeOut(). vTaskSetTimeOutState() ถูกเรียกเพื่อเซ็ตเงื่อนไขเริ่มต้น, หลังจากที่ xTaskCheckForTimeOut() สามารถถูกเรียกเพื่อเช็คสำหรับ a timeout condition, และปรับ the remaining block time ถ้า a timeout ยังไม่ได้เกิดขึ้น.

Parameters:

     pxTimeOut          ตัวชี้ไปยัง a structure ที่จะถูกเริ่มต้นเพื่อเก็บข้อมูลที่จำเป็นในการตัดสินใจถ้า a timeout ได้เกิดขึ้น.

Example usage:

ดูตัวอย่่างที่จัดให้มีบน the xTaskCheckForTimeOut() documentation page.

tha

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

xTaskCheckForTimeOut()
[Task Utilities]

task.h

BaseType_t xTaskCheckForTimeOut( TimeOut_t * const pxTimeOut,
                                 TickType_t * const pxTicksToWait );


ฟังชั่นนี้ถูกมุ่งหมายสำหรับผู้ใช้ขั้นสูงเท่านั้น

A task สามารถเข้าสู่ the Blocked state เพื่อรอสำหรับ an event. โดยทั่วไป, the task จะไม่รอใน the Blocked state อย่างไม่มีกำหนด, แต่แทนด้วย a timeout period จะถูกระบุ. The task จะถูกเอาออกจาก the Blocked state ถ้า the timeout period หมดเวลาลงก่อน the event ที่ the task กำลังรอจะเกิดขึ้น.

ถ้า a task เข้าสู่และออกจาก the Blocked state มากกว่าหนึ่งครั้งในขณะที่มันกำลังรอสำหรับ the event เกิดขึ้นดังนั้น the timeout ที่ใช้แต่ละครั้งที่ the task เข้าสู่ the Blocked state ต้องถูกปรับเพื่อให้แน่ใจว่าทั้งหมดของเวลาที่ใช้ทั้งหมดใน the Blocked state ไม่เกิน the originally specified timeout period. xTaskCheckForTimeOut() ดำเนินการการปรับ,  โดยคำนึงถึงเหตุการณ์ที่เกิดขึ้นเป็นครั้งคราว เช่น tick count โอเวอร์โฟล์, ซึ่งจะทำให้การปรับแบบแมนน้วลมีแนวโน้มที่จะเกิด error.

xTaskCheckForTimeOut() ถูกใช้กับ vTaskSetTimeOutState(). vTaskSetTimeOutState() ถูกเรียกเพื่อเซ็ตเงื่อนไขเริ่มต้น, หลังจากที่ xTaskCheckForTimeOut() สามารถถูกเรียกเพื่อเช็คสำหรับ a timeout condition, และปรับ the remaining block time ถ้า a timeout ยังไม่ได้เกิดขึ้น.

Parameters:

     pxTimeOut           ตัวชี้ไปยัง a structure ที่เก็บข้อมูลที่จำเป็นในการตัดสินใจถ้า a timeout ได้เกิดขึ้น. pxTimeOut ถูกเริ่มต้นโดยใช้
                                    vTaskSetTimeOutState().

     pxTicksToWait      ใช้ส่งผ่าน an adjusted block time ออกไป, ซึ่งเป็น the block time ที่เหลืออยู่หลังจากได้คำนึงถึงเวลาที่ใช้ไปแล้วใน the Blocked
                                     state.

Returns:

     ถ้า pdTRUE ถูกส่งคืนกลับดังนั้นไม่มี block time เหลืออยู่, และ a timeout ได้เกิดขึ้นแล้ว.

     ถ้า pdFALSE ถูกส่งคืนกลับดังนั้น block time บางส่วนยังคงเหลืออยู่, และดังนั้น a timeout ไม่ได้เกิดขึ้น.

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