Nuvoton / Mbed OS NuMaker-mbed-tickless-example

NuMaker tickless example

README.md@14:83b73695da8f, 2018-04-18 (annotated)

Committer:
ccli8
Date:
Wed Apr 18 15:16:23 2018 +0800
Revision:
14:83b73695da8f
Parent:
8:acff1b7adc39
Child:
16:ed2c228cbc9c
Update README.md



1. Update target link

2. Add comment for choosing idle handler

Who changed what in which revision?

UserRevisionLine numberNew contents of line
ccli8 1:eb1da9d36e12 1 # Example for tickless support on Nuvoton targets
ccli8 1:eb1da9d36e12 2
ccli8 1:eb1da9d36e12 3 This is an example to demonstrate [tickless](https://en.wikipedia.org/wiki/Tickless_kernel) support on
ccli8 1:eb1da9d36e12 4 Nuvoton Mbed-enabled boards.
ccli8 1:eb1da9d36e12 5 With tickless support, user program would enter **Idle** mode (shallow sleep) or **Power-down** mode (deep sleep)
ccli8 1:eb1da9d36e12 6 automatically when CPU is idle.
ccli8 1:eb1da9d36e12 7
ccli8 1:eb1da9d36e12 8 ## Supported platforms
ccli8 14:83b73695da8f 9 - [NuMaker-PFM-NUC472](https://os.mbed.com/platforms/Nuvoton-NUC472/)
ccli8 14:83b73695da8f 10 - [NuMaker-PFM-M453](https://os.mbed.com/platforms/Nuvoton-M453/)
ccli8 14:83b73695da8f 11 - [NuMaker-PFM-M487](https://os.mbed.com/platforms/NuMaker-PFM-M487/)
ccli8 14:83b73695da8f 12 - [NuMaker-PFM-NANO130](https://os.mbed.com/platforms/NuMaker-PFM-NANO130/)
ccli8 1:eb1da9d36e12 13
ccli8 1:eb1da9d36e12 14 ## Supported wake-up source
ccli8 1:eb1da9d36e12 15 - Button(s)
ccli8 1:eb1da9d36e12 16 - lp_ticker (internal with tickless)
ccli8 1:eb1da9d36e12 17 - WDT timeout
ccli8 1:eb1da9d36e12 18 - RTC alarm
ccli8 1:eb1da9d36e12 19 - UART CTS state change (TODO)
ccli8 1:eb1da9d36e12 20 - I2C address match (TODO)
ccli8 1:eb1da9d36e12 21
ccli8 14:83b73695da8f 22 ## Choose idle handler
ccli8 14:83b73695da8f 23 Application user can choose to use Mbed OS internal idle handler or customize its own one.
ccli8 14:83b73695da8f 24 1. To use Mbed OS internal idle handler, ensure the `MBED_TICKLESS` macro is defined in `mbed_app.json`.
ccli8 14:83b73695da8f 25 1. To customize idle handler, ensure the `MBED_TICKLESS` macro is not defined in `mbed_app.json`.
ccli8 14:83b73695da8f 26 This gives flexibility for providing platform-dependent idle handler.
ccli8 14:83b73695da8f 27 The `idle_hdlr` in `main.cpp` is a trivial example.
ccli8 14:83b73695da8f 28
ccli8 14:83b73695da8f 29 <pre>
ccli8 14:83b73695da8f 30 {
ccli8 14:83b73695da8f 31 "target_overrides": {
ccli8 14:83b73695da8f 32 "NUMAKER_PFM_NUC472": {
ccli8 14:83b73695da8f 33 "target.macros_add": ["OS_IDLE_THREAD_STACK_SIZE=512", <b>"MBED_TICKLESS"</b>],
ccli8 14:83b73695da8f 34 "target.gpio-irq-debounce-enable-list": "SW1, SW2",
ccli8 14:83b73695da8f 35 "target.gpio-irq-debounce-clock-source": "GPIO_DBCTL_DBCLKSRC_IRC10K",
ccli8 14:83b73695da8f 36 "target.gpio-irq-debounce-sample-rate": "GPIO_DBCTL_DBCLKSEL_256"
ccli8 14:83b73695da8f 37 },
ccli8 14:83b73695da8f 38 </pre>
ccli8 14:83b73695da8f 39
ccli8 1:eb1da9d36e12 40 ## Execution
ccli8 1:eb1da9d36e12 41 To run this tickless example, target board must run with no ICE connected.
ccli8 1:eb1da9d36e12 42 With ICE connected, system will enter **Idle** mode (shallow sleep) rather than **Power-down** mode (deep sleep)
ccli8 1:eb1da9d36e12 43 even though `deepsleep()` is called.
ccli8 1:eb1da9d36e12 44
ccli8 1:eb1da9d36e12 45 ### Modes
ccli8 1:eb1da9d36e12 46 There are two modes on Nuvoton Mbed-enabled boards:
ccli8 1:eb1da9d36e12 47
ccli8 1:eb1da9d36e12 48 #### MASS mode
ccli8 1:eb1da9d36e12 49 This mode supports drap-n-drop programming and VCOM. For retrieving chip information, ICE is connected and system cannot enter
ccli8 1:eb1da9d36e12 50 **Power-down** mode.
ccli8 1:eb1da9d36e12 51
ccli8 1:eb1da9d36e12 52 #### Debug mode
ccli8 1:eb1da9d36e12 53 This mode supports debugger and VCOM. But without entering debug session for debugging, ICE isn't connected and system can enter
ccli8 1:eb1da9d36e12 54 **Power-down** mode (deep sleep).
ccli8 1:eb1da9d36e12 55
ccli8 1:eb1da9d36e12 56 So to run this tickless example, user must switch to **MASS** mode first for drag-n-drop programming and
ccli8 1:eb1da9d36e12 57 then switch to **Debug** mode without entering debug session for running the code.
ccli8 1:eb1da9d36e12 58
ccli8 1:eb1da9d36e12 59 ### Note for terminal output
ccli8 1:eb1da9d36e12 60 With your terminal program configured with 9600/8-N-1, you would see output with:
ccli8 1:eb1da9d36e12 61 <pre>
ccli8 1:eb1da9d36e12 62 I am going to shallow/deep sleep
ccli8 1:eb1da9d36e12 63 Wake up by WDT timeout from <b>deep sleep</b>
ccli8 1:eb1da9d36e12 64
ccli8 1:eb1da9d36e12 65 I am going to shallow/deep sleep
ccli8 1:eb1da9d36e12 66 Wake up by <b>Unidentified</b> from <b>deep sleep</b>
ccli8 1:eb1da9d36e12 67
ccli8 1:eb1da9d36e12 68 I am going to shallow/deep sleep
ccli8 1:eb1da9d36e12 69 Wake up by Button2 from <b>deep sleep</b>
ccli8 1:eb1da9d36e12 70
ccli8 1:eb1da9d36e12 71 I am going to shallow/deep sleep
ccli8 1:eb1da9d36e12 72 Wake up by RTC alarm from <b>deep sleep</b>
ccli8 1:eb1da9d36e12 73
ccli8 1:eb1da9d36e12 74 I am going to shallow/deep sleep
ccli8 1:eb1da9d36e12 75 Wake up by Button1 from <b>deep sleep</b>
ccli8 1:eb1da9d36e12 76 </pre>
ccli8 1:eb1da9d36e12 77
ccli8 1:eb1da9d36e12 78 1. If you see `shallow sleep` rather than `deep sleep`, you just enter **Idle** mode (shallow sleep) rather than
ccli8 1:eb1da9d36e12 79 **Power-down** mode (deep sleep). And you need to check your environment.
ccli8 1:eb1da9d36e12 80 1. If you see `Unidentified`, it means chip is waken up from **Power-down** mode but its wake-up source is unidentified.
ccli8 1:eb1da9d36e12 81 Usually it is `lp_ticker` which is internal with the tickless mechanism.
ccli8 1:eb1da9d36e12 82
ccli8 1:eb1da9d36e12 83 ## Known issues
ccli8 8:acff1b7adc39 84 1. Since mbed OS **5.6.2**, `Ticker`, `Timeout`, and `Timer` could work correctly with this example.
ccli8 8:acff1b7adc39 85 But use of them would lock deep sleep and cause the system from entering into deep sleep mode.
ccli8 8:acff1b7adc39 86 It is because these timers rely on internal `us_ticker`, which relies on high-res clocks HXT/HIRC,
ccli8 8:acff1b7adc39 87 which are forced to stop in deep sleep mode to save more power.
ccli8 8:acff1b7adc39 88 To ensure these timers work correctly, the system is guarded from entering into deep sleep mode during their use.
ccli8 1:eb1da9d36e12 89
ccli8 8:acff1b7adc39 90 1. Use of interrupt callback and asynchronous transfer in `Serial`, `SPI`, `CAN`, etc. has the same issue as above.
ccli8 8:acff1b7adc39 91
ccli8 8:acff1b7adc39 92 1. Use of wait series functions (`wait`/`wait_ms`/`wait_us`) has the same issue as above.
ccli8 8:acff1b7adc39 93 During the wait time, the system is guarded from entering deep sleep mode.
ccli8 8:acff1b7adc39 94
ccli8 8:acff1b7adc39 95 1. Use of `EventQueue` has the same issue as above because `EventQueue` relies on `Timer`/`Ticker` for its internal counting.
ccli8 8:acff1b7adc39 96
ccli8 8:acff1b7adc39 97 1. Use of `RtosTimer` can work seamlessly with this example because `RtosTimer` relies on system timer rather than `us_ticker`.