Ewout van Bekkum | 660ebba | 2020-11-11 13:40:10 -0800 | [diff] [blame] | 1 | .. _module-pw_chrono_freertos: |
| 2 | |
| 3 | ------------------ |
| 4 | pw_chrono_freertos |
| 5 | ------------------ |
| 6 | ``pw_chrono_freertos`` is a collection of ``pw_chrono`` backends that are |
| 7 | implemented using FreeRTOS. |
| 8 | |
| 9 | .. warning:: |
Ewout van Bekkum | 4f97fdd | 2021-06-24 10:37:37 -0700 | [diff] [blame] | 10 | This module is still under construction, the API is not yet stable. |
Ewout van Bekkum | 660ebba | 2020-11-11 13:40:10 -0800 | [diff] [blame] | 11 | |
| 12 | SystemClock backend |
| 13 | ------------------- |
| 14 | The FreeRTOS based ``system_clock`` backend implements the |
| 15 | ``pw_chrono:system_clock`` facade by using ``xTaskGetTickCountFromISR()`` and |
Ewout van Bekkum | da2a62d | 2021-03-12 11:34:47 -0800 | [diff] [blame] | 16 | ``xTaskGetTickCount()`` based on the current context. An InterruptSpinLock is |
| 17 | used to manage overflows in a thread and interrupt safe manner to produce a |
Ewout van Bekkum | 660ebba | 2020-11-11 13:40:10 -0800 | [diff] [blame] | 18 | signed 64 bit timestamp. |
| 19 | |
| 20 | The ``SystemClock::now()`` must be used more than once per overflow of the |
| 21 | native FreeRTOS ``xTaskGetTickCount*()`` overflow. Note that this duration may |
| 22 | vary if ``portSUPPRESS_TICKS_AND_SLEEP()``, ``vTaskStepTick()``, and/or |
| 23 | ``xTaskCatchUpTicks()`` are used. |
| 24 | |
Ewout van Bekkum | 4f97fdd | 2021-06-24 10:37:37 -0700 | [diff] [blame] | 25 | SystemTimer backend |
| 26 | ------------------- |
| 27 | The FreeRTOS based ``system_timer`` backend implements the |
| 28 | ``pw_chrono:system_timer`` facade by using FreeRTOS's Software Timers API. |
| 29 | ``pw::chrono::SystemTimer`` instances use ``StaticTimer_t`` & |
| 30 | ``xTimerCreateStatic``, dynamic memory allocation is never used. This means |
| 31 | that both ``#define configUSE_TIMERS 1`` and |
| 32 | ``#define configSUPPORT_STATIC_ALLOCATION 1`` must be set in the FreeRTOS |
| 33 | configuration. |
| 34 | |
| 35 | This also means that FreeRTOS's ``Timer Service Daemon Task`` is used and must |
| 36 | be configured appropriately by the user through ``configTIMER_TASK_PRIORITY``, |
| 37 | ``configTIMER_QUEUE_LENGTH``, and ``configTIMER_TASK_STACK_DEPTH``. |
| 38 | |
Ewout van Bekkum | 660ebba | 2020-11-11 13:40:10 -0800 | [diff] [blame] | 39 | Build targets |
| 40 | ------------- |
| 41 | The GN build for ``pw_chrono_freertos`` has one target: ``system_clock``. |
| 42 | The ``system_clock`` target provides the |
| 43 | ``pw_chrono_backend/system_clock_config.h`` and ``pw_chrono_freertos/config.h`` |
| 44 | headers and the backend for the ``pw_chrono:system_clock``. |