Skip to content

Documentation update on tickless mode porting guide #1337

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Jun 10, 2020
Merged
Show file tree
Hide file tree
Changes from all commits
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.
50 changes: 50 additions & 0 deletions docs/porting/target/tickless/tickless.md
Original file line number Diff line number Diff line change
@@ -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)