Power Saving API

Sleep Mode APIs

pmu_set_sleep_type

Items	Description
Introduction	The default system sleep mode is PG. If you need to change the sleep mode, application must call this API before entering sleep.
Parameter	type: PG or CG
Return	None

pmu_get_sleep_type

Items	Description
Introduction	Get the current CPU sleep mode.
Parameter	None
Return	type: PG or CG

Wakelock APIs

The wakelock is a 32-bit variable, where each bit represents a lock for a specific module. If a module holds a lock, the system cannot enter Sleep mode. Only when all modules have released their lock (wakelock=0) can the system potentially enter sleep mode.

Wakelock can be used to protect certain program segments from accidentally entering sleep mode midway (due to waiting).
Users can also add custom locks in PMU_DEVICE, but must not modify the pre-defined locks.

The following is an example of a sleep lock definition. Please note that different chips may have different definitions:

typedef enum {
   PMU_OS                                     = 0,
   PMU_WLAN_DEVICE            = 1,
   PMU_KM4_RUN                           = 2,
   PMU_AP_RUN          = 3,
   PMU_BT_DEVICE            = 4,
   PMU_VAD_DEVICE           = 5,
   PMU_DEV_USER_BASE     = 6, /*number 6 ~ 31 is reserved for customer use*/
   PMU_MAX,
} PMU_DEVICE;

The SDK defines two types of locks: wakelock and deepwakelock:

wakelock: Used for Sleep mode

When the system starts, AP holds the wakelock PMU_OS, and NP holds wakelocks PMU_OS and PMU_AP_RUN,
When all wakelocks on AP are released, AP sends an IPC to NP and enters WFI,
After receiving the IPC, NP will power-gate or clock-gate the AP,
Then NP releases PMU_OS and PMU_AP_RUN, allowing itself to enter Sleep mode as well.

deepwakelock: Used for Deep-Sleep mode:

When the system starts, AP holds the deepwakelock PMU_OS,
When all deeplocks on AP are released, AP sends an IPC to NP and enters WFI,
After receiving the IPC, NP sets the entire system to enter deep-sleep mode based on the current conditions.

Note

When the system wakes up, it will quickly re-enter power-saving mode unless wakelocks are acquired again
Please remember to use pmu_acquire_wakelock or pmu_set_sysactive_time to protect important operations

APIs in the following sections are provided to control the wakelock or deepwakelock.

pmu_acquire_wakelock

Items	Description
Introduction	Acquire the wakelock for one module
Parameter	nDeviceId: Device ID of the corresponding module
Return	None

pmu_release_wakelock

Items	Description
Introduction	Release the wakelock for one module
Parameter	nDeviceId: Device ID of the corresponding module
Return	None

pmu_acquire_deepwakelock

Items	Description
Introduction	Acquire the deepwakelock for one module
Parameter	nDeviceId: Device ID of the corresponding module
Return	None

pmu_release_deepwakelock

Items	Description
Introduction	Release the deepwakelock for one module
Parameter	nDeviceId: Device ID of the corresponding module
Return	None

Active Time API

pmu_set_sysactive_time

In certain scenarios, the system needs to remain awake in the Active state for a period of time to complete specific actions. For example, in cases where a particular behavior has multiple end points or branches, it can be challenging to protect such behavior using wakelock.

Items	Description
Introduction	Set a period of time that the system will keep active
Parameter	timeout: time value, unit is ms. The system will keep active for this time value from now on.
Return	0

Max. Sleep Time API

pmu_set_max_sleep_time

Items	Description
Introduction	Set the maximum sleep time, The system will be woken up after the timeout.
Parameter	timer_ms: system maximum sleep timeout, unit is ms.
Return	None

Note

The system may be woken up by other wake events before the timeout.
This setting only works once. The timer will be cleared after the system wakes up.

Sleep Hook/Wakeup Hook Register

These APIs are used to register Sleep Hook/Wakeup Hook for <nDeviceId>.

Sleep Hook function: Called before the system enters Sleep mode
Wakeup Hook function: Called after system wake-up, before entering system threads

A typical application of the Wakeup Hook function is to acquire locks to prevent the chip from re-entering sleep mode.

Note

If CPU chooses PG (Power Gating), some peripherals will lose power. After the system wakes up, these peripherals need to be re-initialized to function. The re-initialization of peripherals can be implemented in the Wakeup Hook function.

Note

It is forbidden to use APIs that may trigger OS scheduling (such as rtos_task_yield, rtos_time_delay_ms, semaphore/mutex related operations) in Sleep Hook/Wakeup Hook functions
It is forbidden to call pmu_set_sysactive_time in the Sleep Hook function (it is allowed in the Wakeup Hook function)

pmu_register_sleep_callback

Items	Description
Introduction	Register the Sleep Hook/Wakeup Hook for one module
Parameter	- nDeviceId: Device ID needs Sleep Hook/Wakeup Hook - sleep_hook_fun: Sleep Hook function - sleep_param_ptr: Sleep Hook function parameter - wakeup_hook_fun: Wakeup Hook function - wakeup_param_ptr: Wakeup Hook function parameter
Return	None

pmu_unregister_sleep_callback

Items	Description
Introduction	Register the Sleep Hook/Wakeup Hook for one module
Parameter	- nDeviceId: Device ID needs Sleep Hook/Wakeup Hook - sleep_hook_fun: Sleep Hook function - sleep_param_ptr: Sleep Hook function parameter - wakeup_hook_fun: Wakeup Hook function - wakeup_param_ptr: Wakeup Hook function parameter
Return	None

Entering Deep-Sleep Mode

Sleep mode is based on FreeRTOS Tickless, thus it is recommended to enter sleep mode by releasing the wakelock.

Initialize the specific peripheral.
Enable and register the peripheral’s interrupt.
Set sleep_wevent_config[] in ambea_sleepcfg.c, and the interrupt should be registered on the same CPU selected by sleep_wevent_config[].
For peripherals that need special clock settings, set ps_config[] in ameba_sleepcfg.c if needed.
Register sleep/wakeup callback if needed.
Enter sleep mode by releasing the wakelock in application core (AP) (PMU_OS needs to be released since it is acquired by default when boot).
Clear the peripheral’s interrupt when wakeup.

Entering Sleep Mode

Deep-Sleep can also be entered from FreeRTOS Tickless flow.

When the system boots, AP holds the deepwakelock PMU_OS, thus freertos_ready_to_dsleep() will be checked fail and the system does not enter deep-sleep mode in idle task by default. Since freertos_ready_to_dsleep() will be checked only after freertos_ready_to_sleep() is checked pass, both the wakelock and deepwakelock need to be released for entering deep-sleep mode.

Configuration:

Initialize the related peripheral and enable its interrupt.
Set sleep_wakepin_config[] in ameba_sleepcfg.c when using AON wakepin as a wakeup source.
Enter deep-sleep mode by releasing the deepwakelock and wakelock in AP.