diff --git a/docs/porting/target/tickless.md b/docs/porting/target/tickless.md deleted file mode 100644 index fe69f02ee2..0000000000 --- a/docs/porting/target/tickless.md +++ /dev/null @@ -1,20 +0,0 @@ -# Tickless - -## Tickless mode - -Tickless mode is an optimization mechanism available in RTOS for suspending the SysTick. You can use it in situations when RTOS is idle for multiple ticks, so you can achieve power savings by entering uninterrupted sleep. Target implementing tickless mode disables the SysTick, sets up wake-up timers and enters sleep mode when idle. It then exits sleep mode and re-enables the SysTick when the timer expires or some event occurs (like external interrupt). - -### Enabling tickless mode - -To support tickless mode in Mbed OS, your target needs to meet two requirements: - -- Support for Sleep HAL API -- Support for Low Power Ticker HAL API - -To enable tickless mode support in Mbed OS, you need to add the `MBED_TICKLESS` macro in the `macros` option of the target's section in the `targets.json` file. - -Targets supporting tickless mode override the default SysTick mechanism and use the [OsTimer](../mbed-os-api-doxy/structos__timer__def.html) implementation based on the [low power ticker](../mbed-os-api-doxy/group__hal__lp__ticker.html). This change is necessary to avoid drift connected with using two different timers to measure time. Users must not change the low power ticker interrupt handler when tickless mode is in use. - -### Testing - -There are no dedicated tests validating tickless mode. Running all Mbed OS tests suits, with particular focus on HAL sleep and HAL low power ticker tests, provides sufficient coverage. diff --git a/docs/porting/target/tickless/resources/Normal_Tick.png b/docs/porting/target/tickless/resources/Normal_Tick.png new file mode 100644 index 0000000000..98d70972fc Binary files /dev/null and b/docs/porting/target/tickless/resources/Normal_Tick.png differ diff --git a/docs/porting/target/tickless/resources/Tick.png b/docs/porting/target/tickless/resources/Tick.png new file mode 100644 index 0000000000..0e38b915a9 Binary files /dev/null and b/docs/porting/target/tickless/resources/Tick.png differ diff --git a/docs/porting/target/tickless/resources/Tickless.png b/docs/porting/target/tickless/resources/Tickless.png new file mode 100644 index 0000000000..6a868b65e9 Binary files /dev/null and b/docs/porting/target/tickless/resources/Tickless.png differ diff --git a/docs/porting/target/tickless/tickless.md b/docs/porting/target/tickless/tickless.md new file mode 100644 index 0000000000..aab875ade1 --- /dev/null +++ b/docs/porting/target/tickless/tickless.md @@ -0,0 +1,50 @@ +# Tickless mode + +Tickless mode is an optimization mechanism available in RTOS for suspending the SysTick. You can use it in situations when RTOS is idle for multiple ticks, so you can save power by entering uninterrupted sleep. + +## Scheduling and sleep modes in Mbed OS + +Mbed OS uses the SysTick timer in periods of 1ms to process threads' scheduling. + +For instance, a system running two threads would see this timing: + +![](resources/Normal_Tick.png) + +Note that the device never enters deep sleep and wastes cycles in SysTick while all threads are asleep. + +## Tickless mode + +To support tickless mode in Mbed OS, your target needs to meet two requirements: + +- Support for Sleep HAL API. +- Support for either Low Power or Microsecond Ticker HAL API. + +To enable tickless mode for your target, add the `MBED_TICKLESS` macro in `target.json` (in your target's section): + +```json +"macros_add": [ + "MBED_TICKLESS" +] +``` + +When tickless mode is enabled, Mbed OS's default [OsTimer](../mbed-os-api-doxy/structos__timer__def.html), based on the [low power ticker](../mbed-os-api-doxy/group__hal__lp__ticker.html), replaces SysTick. If a target's low power ticker has an excessively long wake-up time or other performance issues, make it use the [microsecond ticker](../mbed-os-api-doxy/group__hal__us__ticker.html) instead, by adding the `tickless-from-us-ticker` configuration in 'target.json' (in your target's section). This configuration is not required for a target that does not have low power ticker, because it will default to the microsecond ticker. + +```json +"overrides": { + "tickless-from-us-ticker": true +} +``` + +If tickless mode uses the microsecond ticker, the device will enter sleep rather than deep sleep, but will still avoid unnecessary tick calls. + +The expected scheduling for the previous use case should look like: + +![](resources/Tickless.png) + +## Testing + +There are no dedicated tests validating tickless mode. Running all Mbed OS test suites, with particular focus on HAL sleep and HAL low power ticker tests, provides sufficient coverage. + +## References + +You can find more details on sleep modes in Mbed OS in the section [Mbed OS power management (sleep)](../apis/power-management-sleep.html)