Power Architecture

SoC has an advanced Power Management Controller (PMC), which can flexibly power up different power domains of the chip, to achieve the best balance between chip performance and power consumption.

There are generally three main power domains in the digital system of the SoC: AON, SYSON, and SOC.

Functions in different power domains will be turned off differently in different power-saving modes.

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

Power-Saving Mode

Ameba SoC supports two low power modes:

• Sleep mode

  • Clock Gating (CG): Shuts off the clock to the SOC domain while retaining its power supply.

  • Power Gating (PG): Shuts off the power supply to the SOC domain.

• Deep-Sleep mode

  • Shuts off the power supply to both the SYSON domain and SOC domain. Compared to sleep mode, deep-sleep mode turns off more power domains, resulting in lower power consumption.

Tickless is a low power feature of FreeRTOS. When the system is idle, the CPU will be paused (without disabling clock and power). Both sleep mode and deep sleep mode workflows are based on Tickless.

The following table explains power-saving related terms.

Mode	AON domain	SYSON domain	SOC domain	Description
Tickless	ON	ON	ON	FreeRTOS low power feature CPU periodically enters WFI, and exits WFI when interrupts happen. Radio status can be configured off/periodically on/always on, which depends on the application.
Sleep	ON	ON	CG:ON PG:OFF	A power saving mode on chip level, including clock-gating mode and power-gating mode. CPU can restore stack status when the system exits from sleep mode. The system RAM will be retained, and the data in system RAM will not be lost.
Deep-Sleep	ON	OFF	OFF	A more power-saving mode on chip-level. CPU cannot restore stack status. When the system exits from deep-sleep mode, the CPU follows the reboot process. The system RAM will not be retained. The retention SRAM will not be power off.

Tickless for FreeRTOS

The FreeRTOS supports a low-power feature called Tickless. It is implemented in an idle task which has the lowest priority. That is, it is invoked when there is no other task under running.

Note

• configUSE_TICKLESS_IDLE must be enabled for power-saving application because sleep mode flow is based on Tickless.

• Unlike the original FreeRTOS, We don’t wake up based on the xEpectedIdleTime.

FreeRTOS Tickless in an idle task

The figure above shows idle task code flow. In idle task, it will check sleep conditions (wakelock, sysactive_time, details in Section Wakelock APIs and pmu_set_sysactive_time) to determine whether needs to enter sleep mode or not.

• If not, the CPU will execute an ARM instruction WFI (wait for interrupt) which makes the CPU suspend until the interrupt happens. Normally systick interrupt resumes it. This is the software Tickless.

• If yes, it will execute the function freertos_pre_sleep_processing() to enter sleep mode or deep-sleep mode.

Note

• Even FreeRTOS time control like software timer or vTaskDelay is set, it still enters the sleep mode if meeting the requirement as long as the idle task is executed.

Wi-Fi Power Saving

The WiFi STA power saving modes defined in the IEEE 802.11 specification include the following key features:

• Enter doze state when no data is being sent or received.

• enter awake state for receiving AP beacon frame

• Utilizes beacon TIM (Traffic Indication Map) for data management

During the station’s sleep period, it cannot receive any data frames. Therefore, the AP must buffer any pending frames, and the STA must periodically wake up to check for beacon frames.

Power Saving Mode Timeline

Based on the above standard IEEE 802.11 power saving mechanism, the Ameba IC provides three WiFi power saving modes:

Mode	Full Name	Description
LPS	Legacy Power Save	Switches between awake and doze states under WiFi connection, periodically turns the transceiver on or off for power saving.
WoWLAN	Wake on Wireless LAN	Allows the SoC system to enter sleep mode while maintaining WiFi connectivity. The system can be woken up by unicast packets, broadcast/multicast packets (optional), or AP disconnect event.
IPS	Inactive Power Save	Implements a complete power-down state when not connected.

Entry and exit conditions for WiFi power saving modes:

Mode	User Configuration	Entry and Exit Conditions
LPS	wifi_user_config.lps_enable	Under wifi connection state, automatically enter or exit LPS mode by traffic falling below or exceeding a defined threshold
WoWLAN	Default support	Under WiFi connection, automatically enters or exits WoWLAN mode along with AP core sleep or active mode.
IPS	wifi_user_config.ips_enable	Enters or exits when WiFi connects or disconnects.

Wakeup Source

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

The following table lists the wakeup sources that can be used to wake up the system under different power modes.

Wakeup source	Sleep CG	Sleep PG	Deep-Sleep	Restriction
WLAN	√	√	X
BT	√	√	X
IPC	√	√	X	Only KM0 can use the IPC to wake up KM4.
Basic Timer4~7	√	√	X
PMC Timer	√	√	X	For internal usage
UART0~2	√	√	X	When using UART as a wakeup source, the Rx clock source can only be OSC2M, and do not turn off OSC4M during sleep. When the baudrate is larger than 115200, it is not recommended to use UART as a wakeup source. The portion of the command used to wake up that exceeds the FIFO depth (64B) will be lost.
LOGUART	√	√	X	When using LOGUART as a wakeup source: If the Rx clock source is XTAL40M, do not turn off XTAL or OSC4M during sleep. If the Rx clock source is OSC2M, do not turn off OSC4M during sleep. The portion of the command used to wake up that exceeds the FIFO depth (16B) will be lost.
GPIO	√	√	X
I2C	√	√	X
CAP_TOUCH	√	√	X
ADC	√	√	X
SDIO	√	√	X
Key-Scan	√	√	X
BOR	√	√	√
PWR_DOWN	√	√	√
AON_TIMER	√	√	√
AON_WAKEPIN	√	√	√
RTC	√	√	√

Entering Sleep Mode

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

1. Initialize the specific peripheral.

2. Enable and register the peripheral’s interrupt.

3. Set sleep_wevent_config[] in ambea_sleepcfg.c, and the interrupt should be registered on the same CPU selected by sleep_wevent_config[].

4. For peripherals that need special clock settings, set ps_config[] in ameba_sleepcfg.c if needed.

5. Register sleep/wakeup callback if needed.

6. 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).

7. Clear the peripheral’s interrupt when wakeup.

Entering Deep-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:

1. Initialize the related peripheral and enable its interrupt.

2. Set sleep_wakepin_config[] in ameba_sleepcfg.c when using AON wakepin as a wakeup source.

3. Enter deep-sleep mode by releasing the deepwakelock and wakelock in AP.

Power-Saving Configuration

Please reference User Config chapter for detail information.

Power-Saving Related APIs

Wakelock APIs

Wakelock is a 32-bit bitmap. If a module holds a wakelock, the system will not be able to enter sleep mode. Each module has its corresponding bit in the wakelock bitmap (refer to the PMU_DEVICE enumeration). Users can also add custom wakelocks in the enumeration, but the existing defined wakelocks must not be modified.

Ameba SoC defines two types of wakelocks, each supporting up to 32 different modules:

• wakelock: Used for sleep mode. When wakelock is 0, the system can enter sleep mode; otherwise, sleep mode is not allowed.

• deepwakelock: Used for deep sleep mode. When deepwakelock is 0, the system can enter deep sleep mode; otherwise, deep sleep mode is not allowed.

The following shows the system-defined wakelock bitmaps:

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

enum PMU_DEVICE {
   PMU_OS        = 0,
   PMU_WLAN_DEVICE,
   PMU_KM4_RUN,
   PMU_WLAN_FW_DEVICE,
   PMU_BT_DEVICE,
   PMU_DEV_USER_BASE,
   PMU_MAX
};

1. Sleep Mode: The function :func:freertos_ready_to_sleep() determines whether wakelock is 0.

   1. wakelock: When the system boots, the application core (AP) holds the wakelock PMU_OS, while the network core (NP) holds wakelock PMU_OS as well as PMU_KM4_RUN.

   2. Sleep condition: Only when all wakelocks are released, AP or NP is allowed to enter sleep mode.

   3. Sleep procedure: When AP’s wakelock PMU_OS is released, AP will enter sleep mode in the idle task and send IPC to NP. NP will power-gate or clock-gate AP, then release PMU_OS and PMU_KM4_RUN.

2. Deep Sleep Mode: The function :func:freertos_ready_to_dsleep() determines whether deepwakelock is 0.

   1. deepwakelock: When the system boots, the application core holds deepwakelock PMU_OS.

   2. Sleep condition: Only when all deepwakelocks of AP are released, both AP and NP are allowed to enter deep-sleep mode.

   3. Sleep procedure: When all deepwakelocks of AP are released, AP sends IPC to NP in the idle task. NP will send a deep-sleep request, finally allowing the chip to enter deep-sleep mode.

After the system wakes up, unless wakelock/deepwakelock is acquired again, it will quickly re-enter sleep mode.

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

pmu_set_sysactive_time

In some situations, the system needs to keep awake for a period of time to complete a certain process while the system is active.

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

Sleep/Wake Callback APIs

These APIs are used to register suspend/resume callback function for <nDeviceId>. The suspend callback function will be called in idle task before the system enters sleep mode, and the resume callback function will be called after the system resumes.

It is a good way to use the suspend and resume function if there is something to do before the chip sleeps or after the chip wakes. A typical application of the resume function is to acquire the wakelock to prevent the chip from sleeping again. Also, if the CPU chooses PG, some peripherals will lose power so they need to be reinitialized. This can be implemented in the resume function.

Note

• Yield OS is not permitted in the suspend/resume callback functions, thus RTOS APIs which may cause OS yield such as rtos_task_yield, rtos_time_delay_ms, or mutex, semaphore related APIs are not recommended to use.

• pmu_set_sysactive_time is not permitted in the suspend callback function, but permitted in the resume callback function.

pmu_register_sleep_callback

Items	Description
Introduction	Register the suspend/resume callback function for one module
Parameter	nDeviceId: Device ID needs suspend/resume callback sleep_hook_fun: Suspend callback function sleep_param_ptr: Suspend callback function parameter wakeup_hook_fun: Resume callback function wakeup_param_ptr: Resume callback function parameter
Return	None

pmu_unregister_sleep_callback

Items	Description
Introduction	Register the suspend/resume callback function for one module
Parameter	nDeviceId: Device ID needs suspend/resume callback sleep_hook_fun: Suspend callback function sleep_param_ptr: Suspend callback function parameter wakeup_hook_fun: Resume callback function wakeup_param_ptr: Resume callback function parameter
Return	None

pmu_set_max_sleep_time

Items	Description
Introduction	Set the maximum sleep time
Parameter	timer_ms: system maximum sleep timeout, unit is ms.
Return	None

Note

• The system will be woken up after the timeout.

• 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.

Wakeup Reason APIs

Note

when wakeup, the corresponding peripheral interrupt will be raised; when clearing the interrupt, the corresponding bit in wakeup reason will also be cleared. Thus it is not possible to get the wakeup reason after the interrupt is cleared.

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

SOCPS_AONWakeReason

Items	Description
Introduction	Get the deep-sleep wakeup reason
Parameter	None
Return	Bit[0]: CHIP_EN short press Bit[1]: CHIP_EN long press Bit[2]: BOR Bit[3]: AON Timer Bit[5:4]: AON GPIO Bit[8]: RTC

WAK_STATUS0

The following register can be used to get the sleep wakeup reason.

Register	Parameters
WAK_STATUS0	Bit[1:0]: WLAN Bit[2]: KM4_WAKE Bit[3]: BT_WAKE_HOST Bit[4]: IPC_KM4 Bit[9:6]: BASIC TIMER4~7 Bit[11:10]: PMC TIMER0~1 Bit[14:12]: UART0~2 Bit[15]: UART_LOG Bit[16]: GPIOA Bit[17]: GPIOB Bit[19:18]:I2C0~1 Bit[20]: Cap-Touch Bit[21]: RTC Bit[22]: ADC Bit[24]: BOR Bit[25]: PWR_DOWN Bit[26]: Key-Scan Bit[27]: AON_Timer Bit[28]: AON_Wakepin Bit[29]: SDIO

UART and LOGUART

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730ERTL8721F

For peripherals that require specific clock settings, such as UART and LOGUART, the configuration procedures are described in the following sections.

1. Initialize UART/LOGUART and enable their interrupts.

2. Set the wake-up source: In sleep_wevent_config[], configure the wake-up source (WAKE_SRC_UART0/WAKE_SRC_UART1/WAKE_SRC_UART2_BT/WAKE_SRC_UART_LOG) and specify the CPU to be woken up (WAKEUP_KM4 or WAKEUP_KM0). Ensure the interrupt is registered on the CPU to be woken up.

3. Select the clock source:

   1. XTAL: In ps_config[], set xtal_mode_in_sleep to XTAL_Normal and set keep_OSC4M_on to TRUE.

   2. OSC2M: In ps_config[], set keep_OSC4M_on to TRUE.

4. Set the operating voltage: In ps_config[], set sleep_to_08V to TRUE.

5. Enter sleep mode by releasing the wake lock on KM4 (PMU_OS needs to be released because it is acquired by default at system startup).

6. Clear the UART/LOGUART interrupt after waking up.

Note

• When using UART as a wake-up source, the following limitations apply:

• The Rx clock source can only be OSC2M, and OSC4M must not be turned off during sleep. It is not recommended to use UART as a wake-up source when the baud rate is greater than 115200.

  • Before sleep, you need to call the API RCC_PeriphClockSource_UART(UARTx_DEV, UART_RX_CLK_OSC_LP) to switch the clock to OSC2M.

  • If higher baud rate is required after waking up, you can use the API RCC_PeriphClockSource_UART(UARTx_DEV, UART_RX_CLK_XTAL_40M) to switch to XTAL40M Rx clock.

• Any part of commands used for wake-up that exceed the FIFO depth (64 bytes) will be lost.

• When using LOGUART as a wake-up source, the following limitations apply:

• If the Rx clock source is OSC2M, OSC4M must not be turned off during sleep.

  • Before sleep, you need to call the API RCC_PeriphClockSource_LOGUART(LOGUART_CLK_OSC_LP) to switch the clock to OSC2M.

  • If higher baud rate is required after waking up, you can use the API RCC_PeriphClockSource_LOGUART(LOGUART_CLK_XTAL_40M) to switch to XTAL40M Rx clock.

• If the Rx clock source is XTAL40M, XTAL must not be turned off during sleep.

• Any part of commands used for wake-up that exceed the FIFO depth (16 bytes) will be lost.