Problem Statement:
Zephyr needs to provide an architecture independent method for power
management application to invoke the SOC Deep Sleep functionality.

Why this is a problem:
-----------------------------
- Entry and Exit of Deep Sleep paths are non-trivial and has
dependencies on kernel
cold boot path
- Resume from deep sleep happens with interrupt stack and needs special
handling
- Different architectures have different ways of handling reset/cold
boot which is the path taken by Deep Sleep resume.
- Method to identify Deep Sleep exit requires understanding of SoC
details.

What should be done:
-----------------------------
- Provide api to save thread context and enter Deep Sleep in
architecture and SoC specific regions
- Provide api to restore thread context and resume at location Deep
Sleep was entered
- Api will safely switch away from interrupt stack
- Provide means to identify Deep Sleep exit which are SoC specific

Key
----
PMA: Power Manager Application
ISR: Interrupt Service Routine

Proposed PMA Deep Sleep Entry Flow:
+-----+ +---------+ +-----+
| ISR | | Kernel | | PMA |
+-----+ +---------+ +-----+
| | ----------\ |
| |-| Compute | |
| | | idle | |
| | | ticks | |
| | |---------| |
| | -----------\ |
| |-| Schedule | |
| | | next | |
| | | event | |
| | |----------| |
| | |
| | _sys_soc_suspend(ticks) |
| |--------------------------->|
| | -----------\ |
| | | Select |-|
| | | policy | |
| | | based on | |
| | | ticks | |
| | |----------| |
| | -----------\ |
| | | Execute |-|
| | | Deep | |
| | | Sleep | |
| | | entry | |
| | | policies | |
| | |----------| |
| | |
| | _sys_soc_push_DS() |
| |<---------------------------|
| | |
| | Deep Sleep |
| |----------- |
| | | |
| |<---------- |
| | |



Proposed PMA Deep Sleep Exit Flow:
+-----+ +---------+ +-----+
| ISR | | Kernel | | PMA |
+-----+ +---------+ +-----+
| --------\ | |
| | AON |-| |
| | event | | |
| |-------| | |
| ---------\ | |
| | start |-| |
| | Kernel | | |
| |--------| | |
| | |
| | _sys_soc_resume() |
| |---------------------->|
| | ----------\ |
| | | detects |-|
| | | DS exit | |
| | |---------| |
| | |
| | _sys_soc_pop_DS() |
| |<----------------------|
| | ----------------\ |
| |-| switch thread | |
| | | context | |
| | |---------------| |
| | |
| | prior call to |
| | _sys_soc_push_DS() |
| | returns |
| |---------------------->|
| | -----------\ |
| | | Execute |-|
| | | Deep | |
| | | Sleep | |
| | | exit | |
| | | policies | |
| | |----------| |
| | -------------\ |
| | | enable |-|
| | | interrupts | |
| | |------------| |
| -------------\ | |
|-| re-compute | | |
| | Tickless | | |
| | timeouts | | |
| |------------| | |
| -----------\ | |
|-| schedule | | |
| | next | | |
| | task | | |
| |----------| | |
| | --------------\ |
| |-| next kernel | |
| | | idle | |
| | |-------------| |
| | |
| | prior call to |
| | _sys_soc_suspend() |
| | returns PM_SOC_DS |
| |<----------------------|
| | |


Proposed Cold Boot flow:
+---------+ +-----+
| Kernel | | PMA |
+---------+ +-----+
| -------\ |
|-| cold | |
| | boot | |
| |------| |
| ---------\ |
|-| start | |
| | Kernel | |
| |--------| |
| |
| _sys_soc_resume() |
|---------------------->|
| ----------\ |
| | detects |-|
| | cold | |
| | boot | |
| |---------| |
| |
| returns immediately |
|<----------------------|
| ------------\ |
|-| kernel | |
| | startup | |
| | continues | |
| |-----------| |
| |