Warning
This document is not updated for ESP32H2 yet, so some of the content may not be correct.
This warning was automatically inserted due to the source file being in the add_warnings_pages list.
Power Management
Overview
Power management algorithm included in ESP-IDF can adjust the advanced peripheral bus (APB) frequency, CPU frequency, and put the chip into light sleep mode to run an application at smallest possible power consumption, given the requirements of application components.
Application components can express their requirements by creating and acquiring power management locks.
For example:
Driver for a peripheral clocked from APB can request the APB frequency to be set to 80 MHz while the peripheral is used.
RTOS can request the CPU to run at the highest configured frequency while there are tasks ready to run.
A peripheral driver may need interrupts to be enabled, which means it will have to request disabling light sleep.
Since requesting higher APB or CPU frequencies or disabling light sleep causes higher current consumption, please keep the usage of power management locks by components to a minimum.
Configuration
Power management can be enabled at compile time, using the option CONFIG_PM_ENABLE.
Enabling power management features comes at the cost of increased interrupt latency. Extra latency depends on a number of factors, such as the CPU frequency, single/dual core mode, whether or not frequency switch needs to be done. Minimum extra latency is 0.2 us (when the CPU frequency is 240 MHz and frequency scaling is not enabled). Maximum extra latency is 40 us (when frequency scaling is enabled, and a switch from 40 MHz to 80 MHz is performed on interrupt entry).
Dynamic frequency scaling (DFS) and automatic light sleep can be enabled in an application by calling the function esp_pm_configure()
. Its argument is a structure defining the frequency scaling settings, esp_pm_config_t
. In this structure, three fields need to be initialized:
max_freq_mhz
: Maximum CPU frequency in MHz, i.e., the frequency used when theESP_PM_CPU_FREQ_MAX
lock is acquired. This field will usually be set to the default CPU frequency.min_freq_mhz
: Minimum CPU frequency in MHz, i.e., the frequency used when only theESP_PM_APB_FREQ_MAX
lock is acquired. This field can be set to the XTAL frequency value, or the XTAL frequency divided by an integer. Note that 10 MHz is the lowest frequency at which the default REF_TICK clock of 1 MHz can be generated.light_sleep_enable
: Whether the system should automatically enter light sleep when no locks are acquired (true
/false
).Alternatively, if you enable the option CONFIG_PM_DFS_INIT_AUTO in menuconfig, the maximum CPU frequency will be determined by the CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ setting, and the minimum CPU frequency will be locked to the XTAL frequency.
Note
Automatic light sleep is based on FreeRTOS Tickless Idle functionality. If automatic light sleep is requested while the option CONFIG_FREERTOS_USE_TICKLESS_IDLE is not enabled in menuconfig, esp_pm_configure()
will return the error ESP_ERR_NOT_SUPPORTED.
Note
In light sleep, peripherals are clock gated, and interrupts (from GPIOs and internal peripherals) will not be generated. A wakeup source described in the Sleep Modes documentation can be used to trigger wakeup from the light sleep state.
Power Management Locks
Applications have the ability to acquire/release locks in order to control the power management algorithm. When an application acquires a lock, the power management algorithm operation is restricted in a way described below. When the lock is released, such restrictions are removed.
Power management locks have acquire/release counters. If the lock has been acquired a number of times, it needs to be released the same number of times to remove associated restrictions.
ESP32-H2 supports three types of locks described in the table below.
Lock |
Description |
---|---|
|
Requests CPU frequency to be at the maximum value set with |
|
Requests the APB frequency to be at the maximum supported value. For ESP32-H2, this is 80 MHz. |
|
Disables automatic switching to light sleep. |
ESP32-H2 Power Management Algorithm
The table below shows how CPU and APB frequencies will be switched if dynamic frequency scaling is enabled. You can specify the maximum CPU frequency with either esp_pm_configure()
or CONFIG_ESP_DEFAULT_CPU_FREQ_MHZ.
Note
To be updated
If none of the locks are acquired, and light sleep is enabled in a call to esp_pm_configure()
, the system will go into light sleep mode. The duration of light sleep will be determined by:
FreeRTOS tasks blocked with finite timeouts
Timers registered with High resolution timer APIs
Light sleep duration will be chosen to wake up the chip before the nearest event (task being unblocked, or timer elapses).
To skip unnecessary wake-up, you can consider initializing an esp_timer with the skip_unhandled_events option as true. Timers with this flag will not wake up the system and it helps to reduce consumption.
Dynamic Frequency Scaling and Peripheral Drivers
When DFS is enabled, the APB frequency can be changed multiple times within a single RTOS tick. The APB frequency change does not affect the operation of some peripherals, while other peripherals may have issues. For example, Timer Group peripheral timers will keep counting, however, the speed at which they count will change proportionally to the APB frequency.
The following peripherals work normally even when the APB frequency is changing:
UART: if REF_TICK or XTAL is used as a clock source. See
uart_config_t::source_clk
.LEDC: if REF_TICK is used as a clock source. See
ledc_timer_config()
function.RMT: if REF_TICK or XTAL is used as a clock source. See
rmt_config_t::flags
and macro RMT_CHANNEL_FLAGS_AWARE_DFS.GPTimer: if APB is used as the clock source. See
gptimer_config_t::clk_src
.TSENS: XTAL or RTC_8M is used as a clock source. So, APB frequency changing will not influence it.
Currently, the following peripheral drivers are aware of DFS and will use the ESP_PM_APB_FREQ_MAX
lock for the duration of the transaction:
SPI master
I2C
I2S (If the APLL clock is used, then it will use the
ESP_PM_NO_LIGHT_SLEEP
lock)SDMMC
The following drivers will hold the ESP_PM_APB_FREQ_MAX
lock while the driver is enabled:
SPI slave: between calls to
spi_slave_initialize()
andspi_slave_free()
.Ethernet: between calls to
esp_eth_driver_install()
andesp_eth_driver_uninstall()
.WiFi: between calls to
esp_wifi_start()
andesp_wifi_stop()
. If modem sleep is enabled, the lock will be released for the periods of time when radio is disabled.TWAI: between calls to
twai_driver_install()
andtwai_driver_uninstall()
(only when the clock source is set toTWAI_CLK_SRC_APB
).Bluetooth: between calls to
esp_bt_controller_enable()
andesp_bt_controller_disable()
. If Bluetooth modem sleep is enabled, theESP_PM_APB_FREQ_MAX
lock will be released for the periods of time when radio is disabled. However theESP_PM_NO_LIGHT_SLEEP
lock will still be held.
The following peripheral drivers are not aware of DFS yet. Applications need to acquire/release locks themselves, when necessary:
PCNT
Sigma-delta
The legacy timer group driver
MCPWM
Light-sleep Peripheral Power Down
ESP32-H2 supports power-down peripherals during Light-sleep.
If CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP is enabled, when the driver initializes the peripheral, the driver will register the working register context of the peripheral to the sleep retention link. Before entering sleep, the REG_DMA peripheral will read the configuration in the sleep retention link, and back up the register context to memory according to the configuration. REG_DMA will also restore context from memory to peripheral registers on wakeup.
Currently IDF supports Light-sleep context retention for the following peripherals: - INT_MTX - TEE/APM - IO_MUX / GPIO - UART0 - TIMG0 - SPI0/1 - SYSTIMER
The following peripherals are not yet supported: - GDMA - ETM - TIMG1 - ASSIST_DEBUG - Trace - Crypto: AES/ECC/HMAC/RSA/SHA/DS/XTA_AES/ECDSA - SPI2 - I2C - I2S - PCNT - USB-Serial-JTAG - TWAI - LEDC - MCPWM - RMT - SARADC - SDIO - PARL_IO - UART1
For peripherals that do not support Light-sleep context retention, if the Power management is enabled, the ESP_PM_NO_LIGHT_SLEEP lock should be held when the peripheral is working to avoid losing the working context of the peripheral when entering sleep.
API Reference
Header File
Functions
-
esp_err_t esp_pm_configure(const void *config)
Set implementation-specific power management configuration.
- Parameters
config – pointer to implementation-specific configuration structure (e.g. esp_pm_config_esp32)
- Returns
ESP_OK on success
ESP_ERR_INVALID_ARG if the configuration values are not correct
ESP_ERR_NOT_SUPPORTED if certain combination of values is not supported, or if CONFIG_PM_ENABLE is not enabled in sdkconfig
-
esp_err_t esp_pm_get_configuration(void *config)
Get implementation-specific power management configuration.
- Parameters
config – pointer to implementation-specific configuration structure (e.g. esp_pm_config_esp32)
- Returns
ESP_OK on success
ESP_ERR_INVALID_ARG if the pointer is null
-
esp_err_t esp_pm_lock_create(esp_pm_lock_type_t lock_type, int arg, const char *name, esp_pm_lock_handle_t *out_handle)
Initialize a lock handle for certain power management parameter.
When lock is created, initially it is not taken. Call esp_pm_lock_acquire to take the lock.
This function must not be called from an ISR.
- Parameters
lock_type – Power management constraint which the lock should control
arg – argument, value depends on lock_type, see esp_pm_lock_type_t
name – arbitrary string identifying the lock (e.g. “wifi” or “spi”). Used by the esp_pm_dump_locks function to list existing locks. May be set to NULL. If not set to NULL, must point to a string which is valid for the lifetime of the lock.
out_handle – [out] handle returned from this function. Use this handle when calling esp_pm_lock_delete, esp_pm_lock_acquire, esp_pm_lock_release. Must not be NULL.
- Returns
ESP_OK on success
ESP_ERR_NO_MEM if the lock structure can not be allocated
ESP_ERR_INVALID_ARG if out_handle is NULL or type argument is not valid
ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
-
esp_err_t esp_pm_lock_acquire(esp_pm_lock_handle_t handle)
Take a power management lock.
Once the lock is taken, power management algorithm will not switch to the mode specified in a call to esp_pm_lock_create, or any of the lower power modes (higher numeric values of ‘mode’).
The lock is recursive, in the sense that if esp_pm_lock_acquire is called a number of times, esp_pm_lock_release has to be called the same number of times in order to release the lock.
This function may be called from an ISR.
This function is not thread-safe w.r.t. calls to other esp_pm_lock_* functions for the same handle.
- Parameters
handle – handle obtained from esp_pm_lock_create function
- Returns
ESP_OK on success
ESP_ERR_INVALID_ARG if the handle is invalid
ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
-
esp_err_t esp_pm_lock_release(esp_pm_lock_handle_t handle)
Release the lock taken using esp_pm_lock_acquire.
Call to this functions removes power management restrictions placed when taking the lock.
Locks are recursive, so if esp_pm_lock_acquire is called a number of times, esp_pm_lock_release has to be called the same number of times in order to actually release the lock.
This function may be called from an ISR.
This function is not thread-safe w.r.t. calls to other esp_pm_lock_* functions for the same handle.
- Parameters
handle – handle obtained from esp_pm_lock_create function
- Returns
ESP_OK on success
ESP_ERR_INVALID_ARG if the handle is invalid
ESP_ERR_INVALID_STATE if lock is not acquired
ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
-
esp_err_t esp_pm_lock_delete(esp_pm_lock_handle_t handle)
Delete a lock created using esp_pm_lock.
The lock must be released before calling this function.
This function must not be called from an ISR.
- Parameters
handle – handle obtained from esp_pm_lock_create function
- Returns
ESP_OK on success
ESP_ERR_INVALID_ARG if the handle argument is NULL
ESP_ERR_INVALID_STATE if the lock is still acquired
ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
-
esp_err_t esp_pm_dump_locks(FILE *stream)
Dump the list of all locks to stderr
This function dumps debugging information about locks created using esp_pm_lock_create to an output stream.
This function must not be called from an ISR. If esp_pm_lock_acquire/release are called while this function is running, inconsistent results may be reported.
- Parameters
stream – stream to print information to; use stdout or stderr to print to the console; use fmemopen/open_memstream to print to a string buffer.
- Returns
ESP_OK on success
ESP_ERR_NOT_SUPPORTED if CONFIG_PM_ENABLE is not enabled in sdkconfig
Structures
-
struct esp_pm_config_t
Power management config.
Pass a pointer to this structure as an argument to esp_pm_configure function.
Type Definitions
-
typedef esp_pm_config_t esp_pm_config_esp32_t
backward compatibility newer chips no longer require this typedef
-
typedef esp_pm_config_t esp_pm_config_esp32s2_t
-
typedef esp_pm_config_t esp_pm_config_esp32s3_t
-
typedef esp_pm_config_t esp_pm_config_esp32c3_t
-
typedef esp_pm_config_t esp_pm_config_esp32c2_t
-
typedef esp_pm_config_t esp_pm_config_esp32c6_t
-
typedef struct esp_pm_lock *esp_pm_lock_handle_t
Opaque handle to the power management lock.
Enumerations
-
enum esp_pm_lock_type_t
Power management constraints.
Values:
-
enumerator ESP_PM_CPU_FREQ_MAX
Require CPU frequency to be at the maximum value set via esp_pm_configure. Argument is unused and should be set to 0.
-
enumerator ESP_PM_APB_FREQ_MAX
Require APB frequency to be at the maximum value supported by the chip. Argument is unused and should be set to 0.
-
enumerator ESP_PM_NO_LIGHT_SLEEP
Prevent the system from going into light sleep. Argument is unused and should be set to 0.
-
enumerator ESP_PM_CPU_FREQ_MAX