Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 0 additions & 20 deletions docs/porting/target/tickless.md

This file was deleted.

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/porting/target/tickless/resources/Tick.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
37 changes: 37 additions & 0 deletions docs/porting/target/tickless/tickless.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
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.

# Reminder on scheduling & sleep modes in Mbed OS

Mbed OS uses the SysTick timer at period of 1ms to process threads' scheduling.
For instance, a system running two threads would see its timing diagram look like :

![](./resources/Normal_Tick.png)

Note how the device never enters deepsleep and wastes cycles in Systick while all thread 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 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Enable support is not the same as enable the mode. Which did we want?


When the tickless mode is enabled, the device default SysTick mechanism overrides by the [OsTimer](../mbed-os-api-doxy/structos__timer__def.html) implementation based on either the [low power ticker](../mbed-os-api-doxy/group__hal__lp__ticker.html) or [microsecond ticker](../mbed-os-api-doxy/group__hal__us__ticker.html).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When the tickless mode is enabled, the device default SysTick mechanism overrides by the [OsTimer](../mbed-os-api-doxy/structos__timer__def.html) implementation based on either the [low power ticker](../mbed-os-api-doxy/group__hal__lp__ticker.html) or [microsecond ticker](../mbed-os-api-doxy/group__hal__us__ticker.html).
When the tickless mode is enabled, the device's default SysTick mechanism overrides the [OsTimer](../mbed-os-api-doxy/structos__timer__def.html) implementation, based on either the [low power ticker](../mbed-os-api-doxy/group__hal__lp__ticker.html) or [microsecond ticker](../mbed-os-api-doxy/group__hal__us__ticker.html).


By default, tickless mode uses the low-power ticker if available. If a target's low-power ticker has an excessively long wake-up time or other performance issues, you must set `tickless-from-us-ticker` to `true` in the target's section in the `targets.json` file to make it use the microsecond ticker instead.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Low-power ticker, low power ticker or LowPowerTicker?


If tickless mode uses the microsecond ticker, the device will only enter sleep rather than deep sleep, but will still avoid unnecessary tick calls.

The expected scheduling for the same use-case as previously described should look like :

![](./resources/Tickless.png)

# Testing

There are no dedicated tests validating tickless mode. Running all Mbed OS tests 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 in the section : [Mbed OS power management sleep](../../../apis/power-management-sleep.html)