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.

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

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

Please reference Wi-Fi Power Saving chapter for detailed information.

Wakeup Source

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

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

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

github source code

• ameba_sleepcfg.c

Wakeup Mask Setup

For sleep mode, only one CPU is required to wake up to execute the program in some situations. The wakeup mask module is designed to implement this function. In general, in addition to configuring the wakeup mask, it is also necessary to register the wakeup source interrupt so that the specific CPU can handle it upon wakeup.

By setting a wakeup mask, you can choose to wake up only one CPU core. If KM4 is chosen, KM0 will be waked up first and then KM0 will resume KM4.

Users can set the wakeup attribute in sleep_wevent_config[] in ameba_sleepcfg.c to choose which CPU you want to wake up. The wakeup attribute of each wakeup source can be set to WAKEUP_KM4 or WAKEUP_KM0 or WAKEUP_NULL, respectively indicating that this wakeup source is only to wake up KM4, or wake up KM0, or not used as a wakeup source.

/* Wakeup entry can be set to WAKEUP_NULL/WAKEUP_KM4/WAKEUP_KM0 */
WakeEvent_TypeDef sleep_wevent_config[] = {
   //   Module                    Wakeup
   {WAKE_SRC_SDIO,                WAKEUP_NULL},
   {WAKE_SRC_AON_WAKEPIN,         WAKEUP_NULL},
   {WAKE_SRC_AON_TIM,             WAKEUP_NULL},
   {WAKE_SRC_Keyscan,             WAKEUP_NULL},
   {WAKE_SRC_PWR_DOWN,            WAKEUP_NULL},
   {WAKE_SRC_BOR,                 WAKEUP_NULL},
   {WAKE_SRC_ADC,                 WAKEUP_NULL},
   {WAKE_SRC_RTC,                 WAKEUP_NULL},
   {WAKE_SRC_CTOUCH,              WAKEUP_NULL},
   {WAKE_SRC_I2C1,                WAKEUP_NULL},
   {WAKE_SRC_I2C0,                WAKEUP_NULL},
   {WAKE_SRC_GPIOB,               WAKEUP_NULL},
   {WAKE_SRC_GPIOA,               WAKEUP_NULL},
   {WAKE_SRC_UART_LOG,            WAKEUP_NULL},
   {WAKE_SRC_UART2_BT,            WAKEUP_NULL},
   {WAKE_SRC_UART1,               WAKEUP_NULL},
   {WAKE_SRC_UART0,               WAKEUP_NULL},
   {WAKE_SRC_pmc_timer1,          WAKEUP_KM0},  /* Internal use, do not change it */
   {WAKE_SRC_pmc_timer0,          WAKEUP_KM4},  /* Internal use, do not change it */
   {WAKE_SRC_Timer7,              WAKEUP_NULL},
   {WAKE_SRC_Timer6,              WAKEUP_NULL},
   {WAKE_SRC_Timer5,              WAKEUP_NULL},
   {WAKE_SRC_Timer4,              WAKEUP_NULL},
   {WAKE_SRC_IPC_KM4,             WAKEUP_KM4},  /* IPC can only wake up KM4, do not change it */
   {WAKE_SRC_BT_WAKE_HOST,        WAKEUP_NULL},
   {WAKE_SRC_KM4_WAKE_IRQ,        WAKEUP_KM0},  /* Internal use, do not change it */
   {WAKE_SRC_WIFI_FTSR_MAILBOX,   WAKEUP_KM0},  /* Wi-Fi wakeup, do not change it */
   {WAKE_SRC_WIFI_FISR_FESR_IRQ,  WAKEUP_KM0},  /* Wi-Fi wakeup, do not change it */
   {0xFFFFFFFF,                   WAKEUP_NULL},
};

AON Wakepin Configuration

AON wakepin is one of the peripherals that can be set as a wakeup source. SoC has two AON wakepins (PB30 and PB31), which can be configured in sleep_wakepin_config[] in ameba_sleepcfg.c. The config attribute can be set to DISABLE_WAKEPIN or HIGH_LEVEL_WAKEUP or LOW_LEVEL_WAKEUP, meaning not wake up, or GPIO level high will wake up, or GPIO level low will wake up respectively.

/* can be used by sleep mode & deep sleep mode */
/* config can be set to DISABLE_WAKEPIN/HIGH_LEVEL_WAKEUP/LOW_LEVEL_WAKEUP */
WAKEPIN_TypeDef sleep_wakepin_config[] = {
   //   wakepin      config
   {WAKEPIN_0,    DISABLE_WAKEPIN},  /* WAKEPIN_0 corresponding to _PB_30 */
   {WAKEPIN_1,    DISABLE_WAKEPIN},  /* WAKEPIN_1 corresponding to _PB_31 */
   {0xFFFFFFFF,  DISABLE_WAKEPIN},
};

Note

• By default, AON_WAKEPIN_IRQ will not be enabled in sleep_wakepin_config[], and users need to enable it by themselves.

• The wakeup mask will not be set in sleep_wakepin_config[]. If wakepin is used for sleep mode, WAKE_SRC_AON_WAKEPIN entry needs to be set in sleep_wevent_config[].

Clock and Voltage Configuration

The XTAL, OSC4M state, and sleep mode voltage are configurable in ps_config[] in ameba_sleepcfg.c. Users can use this configuration for peripherals that need XTAL or OSC4M on in sleep mode.

PSCFG_TypeDef ps_config = {
   .keep_OSC4M_on = FALSE,        /* Keep OSC4M on or off for sleep */
   .xtal_mode_in_sleep = XTAL_OFF,    /* Set XTAL mode during sleep mode, see enum xtal_mode_sleep for details */
   .sleep_to_08V = FALSE,        /* Default sleep to 0.7V, setting this option to TRUE will sleep to 0.8V */
};

Sleep mode Configuration

• Application software can set sleep mode to CG or PG by calling pmu_set_sleep_type(uint32_t type)().

• Users can get CPU’s sleep mode by calling pmu_get_sleep_type().

Note

• KM0 and KM4 are in the same power domain, so they will have the same sleep type, thus pmu_set_sleep_type() should be set to KM4, and KM0 will follow KM4’s sleep mode type.

• Sleep mode is set to PG by default. If users want to change the sleep type, pmu_set_sleep_type() needs to be called before sleep.

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:

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

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

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

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

RTL8721DxRTL8720ERTL8726ERTL8713ERTL8730E

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 (UART0/UART1/UART2_BT/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.