FreeRTOS API Software Timers

Started by tha, January 18, 2022, 05:28:34 PM

Previous topic - Next topic

tha

xTimerGetTimerDaemonTaskHandle

timers.h

TaskHandle_t xTimerGetTimerDaemonTaskHandle( void );
      
Returns:

     ส่งคืนกลับ the task handle ที่เเกี่ยวข้องกับ the software timer daemon (or service) task. ถ้า configUSE_TIMERS ถูก
     เซ็ตเป็น 1 ใน FreeRTOSConfig.h, ดังนั้น the timer daemon task ถูกสร้างโดยอัตโนมัติเมื่อ the RTOS scheduler ถูกสตาร์ท.

tha

pcTimerGetName

timers.h

const char * pcTimerGetName( TimerHandle_t xTimer )
      
Parameters:

     ส่งคืนกลับ the human readable name ที่กำหนดให้ a timer เมื่อตอน the timer ถูกสร้าง.

     xTimer          The handle of the timer ที่กำลังถูกสอบถาม.

Returns:

    A pointer ไปยัง the timer's name, ซึ่งเป็น a standard NULL terminated C string.


tha

https://www.freertos.org/FreeRTOS-timers-xTimerCreate.html

xTimerCreate
[Timer API]

timers.h

TimerHandle_t xTimerCreate
                 ( const char * const pcTimerName,
                   const TickType_t xTimerPeriod,
                   const UBaseType_t uxAutoReload,
                   void * const pvTimerID,
                   TimerCallbackFunction_t pxCallbackFunction );


สร้าง a new software timer instance และส่งคืนกลับ a handle ซึ่ง the timer สามารถถูกอ้างอิง.

สำหรับ RTOS API function นี้มีให้ใช้เป็นประโยชน์:

     1. configUSE_TIMERS and configSUPPORT_DYNAMIC_ALLOCATION ทั้งคู่ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h
         (configSUPPORT_DYNAMIC_ALLOCATION สามารถถูกทิ้งไว้ไม่กำหนดได้อีกด้วย, ซึ่งในกรณีนี้มันจะมีค่าเริ่มต้นเป็น 1).
     2. The FreeRTOS/Source/timers.c C source file ต้องถูก included ใน the build.

แต่ละ software timer ต้องการจำนวนน้อยๆของ RAM ที่ถูกใช้เพื่อเก็บ the timer's state. ถ้า a timer ถูกสร้างโดยใช้ xTimerCreate() ดังนั้น RAM นี้จะถูกจัดสรรโดยอัตโนมัติจาก the FreeRTOS heap. ถ้า a software timer  ถูกสร้างโดยใช้ xTimerCreateStatic() ดังนั้น the RAM ถูกจัดให้มีโดย the application writer, ซึ่งต้องการ parameter เพิ่มเติม, แต่ยอมให้ the RAM ถูกจัดสรรแบบคงที่ที่เวลา compile. ดู the Static Vs Dynamic allocation page สำหรับข้อมูลเพิ่มเติม.

Timers ถูกสร้างใน the dormant state. The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and xTimerChangePeriodFromISR() API functions ทั้งหมดสามารถถูกใช้เพื่อเปลี่ยนผ่าน a timer ลงใน the active state.

tha

Parameters:

     pcTimerName          A human readable text name ที่ถูกกำหนดให้กับ the timer. นี้ถูกทำอย่างหมดจดเพื่อช่วยการดีบัก. The
                                         RTOS kernel เองจะอ้างอิง a timer โดย handle ของมันเท่านั้น, และไม่โดยชื่อของมัน.

     xTimerPeriod            คาบเวลาของ the timer. คาบเวลาถูกระบุเป็น ticks, และ the macro pdMS_TO_TICKS() สามารถถูกใช้
                                         พื่อแปลง a time ที่ระบุเป็น milliseconds ไปเป็น a time ที่ระบุเป็น ticks. ตัวอย่างเช่น, ถ้า the
                                         timer ต้องหมดเวลาลงหลังจาก 100 ticks, ดังนั้นเซ็ตอย่างง่ายๆ xTimerPeriod เป็น 100. อีกทาง
                                         เลือกหนึ่ง, ถ้า the timer ต้องหมดเวลาลงหลังจาก 500ms, ดังนั้นเซ็ต xTimerPeriod เป็น
                                         pdMS_TO_TICKS( 500 ). pdMS_TO_TICKS() สามารถถูกใช้ได้เฉพาะถ้า
                                         configTICK_RATE_HZ น้อยกว่าหรือเท่ากับ 1000. The timer period ต้องใหญ่กว่า 0.

tha

     uxAutoReload          ถ้า uxAutoReload ถูกเซ็ตเป็น pdTRUE, ดังนั้น the timer จะหมดเวลาลงซ้ำๆด้วย a frequency ที่เซ็ต
                                        the xTimerPeriod parameter. ถ้า uxAutoReload ถูกเซ็ตเป็น pdFALSE, ดังนั้น the timer จะเป็น
                                        ช็อตเดียวและเข้าสู่ the dormant state หลังจากมันหมดเวลาลง.

     pvTimerID                An identifier ที่ถูกกำหนดให้กับ the timer ที่กำลังถูกสร้าง. โดยทั่วไปจะถูกใช้ใน the timer callback
                                        function เพื่อระบุว่า timer ใดหมดเวลาลงเมื่อ the same callback function ถูกกำหนดให้กับมากกว่า
                                        หนึ่ง timer, หรือร่วมกันกับ the vTimerSetTimerID() and pvTimerGetTimerID() API
                                        functions เพื่อบันทึกค่าระหว่างการเรียกถึง the timer's callback function.

   pxCallbackFunction  The function ที่เรียกเมื่อ the timer หมดเวลาลง. Callback functions ต้องมี the prototype ที่กำหนด
                                        โดย TimerCallbackFunction_t, ซึ่งก็คือ:
                                     
                                        void vCallbackFunction( TimerHandle_t xTimer );

tha

Returns:

     ถ้า the timer ถูกสร้างสเร็จดังนั้น a handle to the newly created timer ถูกส่งคืนกลับ. ถ้า the timer ไม่สามารถถูกสร้างเนื่องจากมี
     FreeRTOS heap ไม่เพียงพอเหลืออยู่ให้จัดสรร the timer structures ดังนั้น NULL ถูกส่งคืนกลับ.

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

tha

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

xTimerCreateStatic
[Timer API]

timers.h

TimerHandle_t xTimerCreateStatic
                 ( const char * const pcTimerName,
                   const TickType_t xTimerPeriod,
                   const UBaseType_t uxAutoReload,
                   void * const pvTimerID,
                   TimerCallbackFunction_t pxCallbackFunction
                   StaticTimer_t *pxTimerBuffer );


สร้าง a new software timer instance และส่งคืนกลับ a handle ซึ่ง the timer สามารถถูกอ้างอิง.

สำหรับ RTOS API function นี้มีให้ใช้เป็นประโยชน์:

     1. configUSE_TIMERS and configSUPPORT_STATIC_ALLOCATION ทั้งคู่ต้องถูกเซ็ตเป็น 1 ใน FreeRTOSConfig.h
     2. The FreeRTOS/Source/timers.c C source file ต้องถูก included ใน the build.

แต่ละ software timer ต้องการจำนวนน้อยๆของ RAM ที่ถูกใช้เพื่อเก็บ the timer's state. ถ้า a timer ถูกสร้างโดยใช้ xTimerCreate() ดังนั้น RAM นี้จะถูกจัดสรรโดยอัตโนมัติจาก the FreeRTOS heap. ถ้า a software timer  ถูกสร้างโดยใช้ xTimerCreateStatic() ดังนั้น the RAM ถูกจัดให้มีโดย the application writer, ซึ่งต้องการ parameter เพิ่มเติม, แต่ยอมให้ the RAM ถูกจัดสรรแบบคงที่ที่เวลา compile. ดู the Static Vs Dynamic allocation page สำหรับข้อมูลเพิ่มเติม.

Timers ถูกสร้างใน the dormant state. The xTimerStart(), xTimerReset(), xTimerStartFromISR(), xTimerResetFromISR(), xTimerChangePeriod() and xTimerChangePeriodFromISR() API functions ทั้งหมดสามารถถูกใช้เพื่อเปลี่ยนผ่าน a timer ลงใน the active state.

Parameters:

     pcTimerName          A human readable text name ที่ถูกกำหนดให้กับ the timer. นี้ถูกทำอย่างหมดจดเพื่อช่วยการดีบัก. The
                                         RTOS kernel เองจะอ้างอิง a timer โดย handle ของมันเท่านั้น, และไม่โดยชื่อของมัน.

     xTimerPeriod            คาบเวลาของ the timer. คาบเวลาถูกระบุเป็น ticks, และ the macro pdMS_TO_TICKS() สามารถถูกใช้
                                         พื่อแปลง a time ที่ระบุเป็น milliseconds ไปเป็น a time ที่ระบุเป็น ticks. ตัวอย่างเช่น, ถ้า the
                                         timer ต้องหมดเวลาลงหลังจาก 100 ticks, ดังนั้นเซ็ตอย่างง่ายๆ xTimerPeriod เป็น 100. อีกทาง
                                         เลือกหนึ่ง, ถ้า the timer ต้องหมดเวลาลงหลังจาก 500ms, ดังนั้นเซ็ต xTimerPeriod เป็น
                                         pdMS_TO_TICKS( 500 ). pdMS_TO_TICKS() สามารถถูกใช้ได้เฉพาะถ้า
                                         configTICK_RATE_HZ น้อยกว่าหรือเท่ากับ 1000. The timer period ต้องใหญ่กว่า 0.

     uxAutoReload          ถ้า uxAutoReload ถูกเซ็ตเป็น pdTRUE, ดังนั้น the timer จะหมดเวลาลงซ้ำๆด้วย a frequency ที่เซ็ต
                                        the xTimerPeriod parameter. ถ้า uxAutoReload ถูกเซ็ตเป็น pdFALSE, ดังนั้น the timer จะเป็น
                                        ช็อตเดียวและเข้าสู่ the dormant state หลังจากมันหมดเวลาลง.

     pvTimerID                An identifier ที่ถูกกำหนดให้กับ the timer ที่กำลังถูกสร้าง. โดยทั่วไปจะถูกใช้ใน the timer callback
                                        function เพื่อระบุว่า timer ใดหมดเวลาลงเมื่อ the same callback function ถูกกำหนดให้กับมากกว่า
                                        หนึ่ง timer, หรือร่วมกันกับ the vTimerSetTimerID() and pvTimerGetTimerID() API
                                        functions เพื่อบันทึกค่าระหว่างการเรียกถึง the timer's callback function.

   pxCallbackFunction  The function ที่เรียกเมื่อ the timer หมดเวลาลง. Callback functions ต้องมี the prototype ที่กำหนด
                                        โดย TimerCallbackFunction_t, ซึ่งก็คือ:
                                     
                                        void vCallbackFunction( TimerHandle_t xTimer );

     pxTimerBuffer         ต้องชี้ไปยังตัวแปรของชนิด StaticTimer_t, ซึ่งดังนั้นถูกใช้เพื่อเก็บ the timer's state.

Returns:

     ถ้า the timer ถูกสร้างสเร็จดังนั้น a handle to the newly created timer ถูกส่งคืนกลับ. ถ้า pxTimerBuffer เป็น NULL ดัง
     นั้น the timer จะไม่ถูกสร้างและ NULL จะถูกส่งคืนกลับ.

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