Documentation update on tickless mode porting guide #1337

rajkan01 · 2020-06-03T14:57:23Z

Updated tickless mode porting guide with missing information and done some cleanup.

This PR depends on ARMmbed/mbed-os#12988

kjbracey · 2020-06-03T16:27:41Z

docs/porting/target/tickless/tickless.md

+
+When the tickless mode is enabled, the device suspends the kernel effectively disabling the systick and sets up the [low power ticker] through [mbed::internal::OsTimer].
+
+If the target does not feature a low power ticker or has an excessively long wake-up time, you must also set the `tickless-from-us-ticker` to true in the target's section in the `targets.json` file. In such the device will only enter sleep rather than deepsleep.


Didn't we just merge a PR that meant you didn't have to set this if you don't have a low power ticker at all? It's bright enough to realise that it has to use us-ticker now. So I think you only have to set this if you have it and it doesn't work well.

If that PR has been merged, the "if the target does not feature a low power ticker" condition is no longer true.

How about "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."

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

Just checked, and the PR is still pending, but ready for merge:

ARMmbed/mbed-os#12988

kjbracey

The "tickless" diagram isn't quite right, because it shows "SysTick" being used as the timer. All the ticks are and wakeup from idle are actually coming from "lpticker" (or "usticker").

(In principle the ticks could be SysTick and the wake from idle lpticker, so it could be hybrid, but for now it's all lpticker).

kjbracey · 2020-06-04T11:13:29Z

docs/porting/target/tickless/tickless.md

+
+When the tickless mode is enabled, the device suspends the kernel effectively disabling the systick and sets up the [low power ticker] through [mbed::internal::OsTimer].
+
+If the target does not feature a low power ticker or has an excessively long wake-up time, you must also set the `tickless-from-us-ticker` to true in the target's section in the `targets.json` file. In such the device will only enter sleep rather than deepsleep.


If that PR has been merged, the "if the target does not feature a low power ticker" condition is no longer true.

How about "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."

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

kjbracey

Repeating my earlier comment:

All the ticks [...] and wakeup from idle are actually coming from "lpticker" (or "usticker")

Your diagram is still showing SysTick in use for tickless.

Another minor detail - don't think it's worth putting in the diagram, but for your benefit - it can actually use two lpticker interrupts to wake from a sleep. First one brings it out of deep sleep, and it's scheduled early enough to guarantee it's not late, then it goes back to shallow sleep scheduling wakeup for the exact requested time.

kjbracey · 2020-06-04T12:51:13Z

docs/porting/target/tickless/tickless.md

+
+If tickless mode uses the microsecond ticker, the device will only enter sleep rather than deep sleep, but will still avoid unnecessary tick calls.
+
+*Note that using the tickless mode prevents the user from using the associated timer.*


Oh, never spotted this sentence. Where did it come from?

It's not true in any meaningful sense for users. There is one HAL lpticker and one HAL usticker, yes, but they are always shared by the "ticker_api" framework. The OS timing uses that same sharing mechanism along with Ticker, LowPowerTimeout etc, and doesn't interfere with their use.

You couldn't use LowPowerTicker or MBED_TICKLESS at the same time as directly calling the HAL lpticker interrupt APIs yourself, but no-one would ever attempt that, I hope.

kjbracey · 2020-06-04T12:56:48Z

docs/porting/target/tickless/tickless.md

+
+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.
+
+When the tickless mode is enabled, the device suspends the kernel effectively disabling the systick and sets up 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) through [mbed::internal::OsTimer](../mbed-os-api-doxy/structos__timer__def.html) based on target configuration.


Bit wary about mentioning mbed::internal:: anything in documentation, but I guess it's a potentially useful detail for anyone debugging/maintaining the code.

docs/porting/target/tickless/tickless.md

evedon

The tickless diagram is difficult to read. Please update it.

Co-authored-by: Irit Arkin <[email protected]>

evedon · 2020-06-09T16:33:36Z

It would be useful if the digrams show SysTick (and "lpticker" or "usticker") in (equal) periods of 1ms.

docs/porting/target/tickless/tickless.md

iriark01 · 2020-06-10T10:54:31Z

docs/porting/target/tickless/tickless.md

+]
+```
+
+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 below configuration in 'target.json' (in your target's section). And this configuration is not required for the target which does not have low power ticker as the default OsTimer based on the microsecond ticker.


Suggested change

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 below configuration in 'target.json' (in your target's section). And this configuration is not required for the target which does not have low power ticker as the default OsTimer based on the microsecond ticker.

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.

iriark01 · 2020-06-10T11:50:06Z

I'm happy to merge; just need to know if it's 6.1 only, or can join 6.0 as well

evedon

Thanks for the nice update on the diagrams.

iriark01 · 2020-06-10T15:00:14Z

To be honest, the next release is so close that it may as well go into development; it will be published in less than two weeks anyway

iriark01 · 2020-06-10T15:00:41Z

Anyway, need to do more work on the development branch, as this will not be visible - it's not in the JSON

rajkan01 requested review from iriark01, gpsimenos, evedon, ithinuel and kjbracey June 3, 2020 14:58

kjbracey reviewed Jun 3, 2020

View reviewed changes

rajkan01 force-pushed the tickless_docs_update branch 2 times, most recently from 6a9ab05 to 0aea8cd Compare June 4, 2020 11:05

kjbracey suggested changes Jun 4, 2020

View reviewed changes

ithinuel approved these changes Jun 4, 2020

View reviewed changes

rajkan01 force-pushed the tickless_docs_update branch from 0aea8cd to 1554e16 Compare June 4, 2020 12:03

kjbracey suggested changes Jun 4, 2020

View reviewed changes

rajkan01 force-pushed the tickless_docs_update branch from 1554e16 to 8917702 Compare June 5, 2020 10:56

Documentation update on tickless mode porting guide

3a9ec86

rajkan01 force-pushed the tickless_docs_update branch from 8917702 to 3a9ec86 Compare June 5, 2020 11:02

rajkan01 requested a review from kjbracey June 5, 2020 13:13

kjbracey approved these changes Jun 5, 2020

View reviewed changes

iriark01 self-assigned this Jun 8, 2020

First thing: fixing header levels

5ed260a

iriark01 suggested changes Jun 8, 2020

View reviewed changes

evedon requested changes Jun 8, 2020

View reviewed changes

Apply suggestions from code review

127cd3a

Co-authored-by: Irit Arkin <[email protected]>

rajkan01 force-pushed the tickless_docs_update branch 2 times, most recently from 1e84cfd to a970fa0 Compare June 9, 2020 16:02

iriark01 reviewed Jun 10, 2020

View reviewed changes

docs/porting/target/tickless/tickless.md Outdated Show resolved Hide resolved

rajkan01 force-pushed the tickless_docs_update branch 4 times, most recently from e0057e8 to 42c3b4a Compare June 10, 2020 10:43

Incorporated the review comments

9d09e3c

rajkan01 force-pushed the tickless_docs_update branch from 42c3b4a to 9d09e3c Compare June 10, 2020 10:51

iriark01 reviewed Jun 10, 2020

View reviewed changes

Commit the suggestion

363298c

evedon approved these changes Jun 10, 2020

View reviewed changes

iriark01 merged commit b4c7caa into ARMmbed:development Jun 10, 2020


		When the tickless mode is enabled, the device suspends the kernel effectively disabling the systick and sets up the [low power ticker] through [mbed::internal::OsTimer].

		If the target does not feature a low power ticker or has an excessively long wake-up time, you must also set the `tickless-from-us-ticker` to true in the target's section in the `targets.json` file. In such the device will only enter sleep rather than deepsleep.


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

		Note that using the tickless mode prevents the user from using the associated timer.


		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.

		When the tickless mode is enabled, the device suspends the kernel effectively disabling the systick and sets up 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) through [mbed::internal::OsTimer](../mbed-os-api-doxy/structos__timer__def.html) based on target configuration.

Documentation update on tickless mode porting guide #1337

Documentation update on tickless mode porting guide #1337

Uh oh!

Conversation

rajkan01 commented Jun 3, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kjbracey Jun 3, 2020

Choose a reason for hiding this comment

Uh oh!

kjbracey Jun 4, 2020

Choose a reason for hiding this comment

Uh oh!

kjbracey Jun 4, 2020

Choose a reason for hiding this comment

Uh oh!

kjbracey left a comment

Choose a reason for hiding this comment

Uh oh!

kjbracey Jun 4, 2020

Choose a reason for hiding this comment

Uh oh!

kjbracey left a comment

Choose a reason for hiding this comment

Uh oh!

kjbracey Jun 4, 2020

Choose a reason for hiding this comment

Uh oh!

kjbracey Jun 4, 2020

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

evedon left a comment

Choose a reason for hiding this comment

Uh oh!

evedon commented Jun 9, 2020

Uh oh!

Uh oh!

iriark01 Jun 10, 2020

Choose a reason for hiding this comment

Uh oh!

iriark01 commented Jun 10, 2020

Uh oh!

evedon left a comment

Choose a reason for hiding this comment

Uh oh!

iriark01 commented Jun 10, 2020

Uh oh!

iriark01 commented Jun 10, 2020

Uh oh!

Uh oh!

rajkan01 commented Jun 3, 2020 •

edited

Loading