IC: RTL8721Dx RTL8720E RTL8726E RTL8730E

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. AON, SYSON, SOC are three main power domains in digital system. Functions in different power domains will be turned off differently in different power-saving modes.

RTL8721DxRTL8726ERTL8720ERTL8730E

Power domains and wakeup sources

Power-Saving Mode

We supports two low-power modes, which are sleep mode and deep-sleep mode. The deep-sleep mode turns off more power domains than the sleep mode, so it has lower power consumption.

Tickless is a FreeRTOS low power feature, which just gates the CPU (no clock or power be turned off) when it has nothing to do. Sleep mode flow and deep-sleep mode flow are based on Tickless. The following table explains power-saving related terms.

Power-saving mode

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	Clock-gated or power-gated	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 that 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.

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

Wi-Fi Power Saving

IEEE 802.11 power save management allows the station to enter its own sleep state. It defines that the station needs to keep awake at a certain timestamp and enter a sleep state otherwise.

WLAN driver acquires the wakelock to avoid the system entering sleep mode when WLAN needs to keep awake. And it releases the wakelock when it is permitted to enter the sleep state.

IEEE 802.11 power management allows the station to enter power-saving mode. The station cannot receive any frame during power saving. Thus AP needs to buffer these frames and requires the station to periodically wake up to check the beacon which has the information of buffered frames.

Timeline of power saving

In SDK IEEE 802.11 power management is called LPS, and if NP enters sleep mode when Wi-Fi is in LPS mode, we call it WoWLAN mode.

In WoWLAN mode, a timer with a period of about 102ms will be set in the suspend function. And LP will wake up every 102ms to receive the beacon to maintain the connection.

Except for LPS and WoWLAN, we also have IPS, which can be used when Wi-Fi is not connected. The following tables list all three power-saving modes for Wi-Fi and the relationship between the system power mode and Wi-Fi power mode.

WiFi power saving mode

Mode	Wi-Fi status	Description	SDK
IPS	Not associated: RF/BB/MAC OFF	Wi-Fi driver automatically turns Wi-Fi off to save power.	IPS mode is enabled in SDK by default and is not recommended to be disabled.
LPS	Associated: RF periodically ON/OFF MAC/BB always ON	LPS mode is used to implement IEEE 802.11 power management. NP will control RF ON/OFF based on TSF and TIM IE in the beacon.	LPS mode is enabled in SDK by default but can be disabled through API wifi_set_lps_enable().
WoWLAN	Associated: RF and BB periodically ON/OFF MAC periodically enters/ exits CG/PG	NP is waked up at each beacon early interrupt to receive a beacon from the associated AP. NP will wake up AP when receiving a data packet.	WoWLAN mode is enabled in SDK by default.

Relationship between system and Wi-Fi power mode

System power mode	Wi-Fi power mode	Description
Active	IPS	Wi-Fi is on, but not connected
Active	LPS	Wi-Fi is connected and enters IEEE 802.11 power management mechanism
Sleep	Wi-Fi OFF/IPS
Sleep	WoWLAN	Wi-Fi keeps associating.
Deep-sleep	Wi-Fi OFF	Deep-sleep is not recommended if Wi-Fi needs to keep on or associated.

API to enable/disable LPS

API	Parameters
int wifi_set_lps_enable(u8 enable)	Parameter: enable TRUE: enable LPS FALSE: disable LPS

When Wi-Fi is connected and the system enters sleep mode, WoWLAN mode will be entered automatically. And KM0 will periodically wake up to receive the beacon to maintain the connection, this will consume some power. If you are more concerned about the system power consumption during sleep mode, and Wi-Fi is not a necessary function in your application, it is recommended to set Wi-Fi off or choose Wi-Fi IPS mode.

Wakeup Source

RTL8721DxRTL8726ERTL8720ERTL8730E

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

Wakeup sources

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

In some situations, the system needs to keep awake to receive certain events; otherwise, events may be missed when the system is in sleep mode. An idea of wakelock is introduced in that the system cannot enter sleep mode if some module is holding the wakelock.

The Wakelock is a 32-bit map. Each module has its own bit in the wakelock bit map (see enum PMU_DEVICE). Users can also add the wakelock in the enum.

• If the wakelock bit map equals zero, it means that there is no module holding the wakelock.

• If the wakelock bit map is larger than zero, it means that some modules are holding the wakelock, and the system is not allowed to enter sleep mode.

RTL8721DxRTL8720ERTL8726ERTL8730E

Wakelock is a judging condition in the function freertos_ready_to_sleep(). When the system boots, application core(AP) holds the wakelock PMU_OS, and network core(NP) holds the wakelock PMU_OS and PMU_KM4_RUN or PMU_AP_RUN. Only if all wakelocks are released, AP or NP is permitted to enter sleep mode. The function freertos_ready_to_sleep() will judge the value of wakelock.

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
};

It is recommended to enter sleep mode by releasing the wakelock. After the wakelock PMU_OS of AP is released, AP will enter sleep mode in idle task and send IPC to NP. NP will power-gate or clock-gate AP and then release PMU_OS and PMU_KM4_RUN or PMU_AP_RUN.

When the system wakes, it will enter sleep mode again quickly unless it acquires the wakelock.

Similar to the wakelock for sleep mode, there is a 32-bit deepwakelock map for deep-sleep mode. If the deepwakelock bit map is larger than zero, it means that some modules are holding the deepwakelock, and the system is not allowed to enter deep-sleep mode. When the system boots, application core holds the deepwakelock PMU_OS.

Deepwakelock is a judging condition in the function freertos_ready_to_dsleep(). After the deepwakelock PMU_OS of AP is released, and all wakelocks of AP are released, AP will be allowed to enter deep-sleep mode and send IPC to NP in idle task. NP will send a deep-sleep request and let the chip finally enter deep-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

RTL8721DxRTL8720ERTL8726ERTL8730E

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

Note that 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.

Wakeup time

RTL8721DxRTL8720ERTL8726ERTL8730E

UART and LOGUART

RTL8721DxRTL8720ERTL8726ERTL8730E

For peripherals that need specific clock settings, such as UART and LOGUART, their setting flows are described in the following section.

UART

1. Initialize UART and enable its interrupt.

2. Set the related wakeup source (WAKE_SRC_UART0/WAKE_SRC_UART1/WAKE_SRC_UART2_BT) in sleep_wevent_config[] to WAKEUP_KM4 or WAKEUP_KM0 (based on which CPU you want to wake). The interrupt should be registered on the same CPU selected by sleep_wevent_config[].

3. Set keep_OSC4M_on in ps_config[] to TRUE to keep OSC4M enabled during sleep mode.

4. Switch clock to OSC2M with API RCC_PeriphClockSource_UART(UARTx_DEV, UART_RX_CLK_OSC_LP).

5. Enter sleep mode by releasing the wakelock in KM4 (PMU_OS needs to be released since it is acquired by default when boot).

6. Clear the UART interrupt when wakeup.

7. If a higher baudrate is required after waking up, it is recommended to switch to XTAL40M Rx clock by API RCC_PeriphClockSource_UART(UART0_DEV, UART_RX_CLK_XTAL_40M).

Note

When using UART as a wakeup source, there are some restrictions:

• 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

1. Initialize LOGUART and enable its interrupt.

2. Set WAKE_SRC_UART_LOG in sleep_wevent_config[] to WAKEUP_KM4 or WAKEUP_KM0 (based on which CPU you want to wake). The interrupt should be registered on the same CPU selected by sleep_wevent_config[].

3. Set xtal_mode_in_sleep to XTAL_Normal in ps_config[].

4. Enter sleep mode by releasing the wakelock in KM4 (PMU_OS needs to be released since it is acquired by default when boot).

5. Clear the LOGUART interrupt when wakeup.

Note

When using LOGUART as a wakeup source, there are some restrictions:

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