From 2e59c25ecbfaae96133ae626ae1023bc09a48266 Mon Sep 17 00:00:00 2001 From: hebinglin Date: Thu, 5 Feb 2026 19:41:21 +0800 Subject: [PATCH] docs(pm): add flash sleep strategy recommendations --- docs/en/api-reference/system/sleep_modes.rst | 74 +++++++++++++++--- .../api-reference/system/sleep_modes.rst | 78 +++++++++++++++---- 2 files changed, 126 insertions(+), 26 deletions(-) diff --git a/docs/en/api-reference/system/sleep_modes.rst b/docs/en/api-reference/system/sleep_modes.rst index 861842e2cbb..6a53c149468 100644 --- a/docs/en/api-reference/system/sleep_modes.rst +++ b/docs/en/api-reference/system/sleep_modes.rst @@ -491,47 +491,97 @@ By default, :cpp:func:`esp_deep_sleep_start` and :cpp:func:`esp_light_sleep_star In {IDF_TARGET_NAME}, there is only RTC FAST memory, so if some variables in the program are marked by ``RTC_DATA_ATTR``, ``RTC_SLOW_ATTR`` or ``RTC_FAST_ATTR`` attributes, all of them go to RTC FAST memory. It will be kept powered on by default. This can be overridden using :cpp:func:`esp_sleep_pd_config` function, if desired. +.. _spi_flash_power_down: + Power-down of Flash ^^^^^^^^^^^^^^^^^^^ -By default, to avoid potential issues, :cpp:func:`esp_light_sleep_start` function does **not** power down flash. To be more specific, it takes time to power down the flash and during this period the system may be woken up, which then actually powers up the flash before this flash could be powered down completely. As a result, there is a chance that the flash may not work properly. +By default, to avoid potential issues, :cpp:func:`esp_light_sleep_start` function does **not** power down SPI Flash. To be more specific, it takes time to power down the SPI Flash and during this period the system may be woken up, which then actually powers up the SPI Flash before this SPI Flash could be powered down completely. As a result, there is a chance that the SPI Flash may not work properly. -So, in theory, it is ok if you only wake up the system after the flash is completely powered down. However, in reality, the flash power-down period can be hard to predict (for example, this period can be much longer when you add filter capacitors to the flash's power supply circuit) and uncontrollable (for example, the asynchronous wake-up signals make the actual sleep time uncontrollable). +So, in theory, it is ok if you only wake up the system after the SPI Flash is completely powered down. However, in reality, the SPI Flash power-down period can be hard to predict (for example, this period can be much longer when you add filter capacitors to the SPI Flash's power supply circuit) and uncontrollable (for example, the asynchronous wake-up signals make the actual sleep time uncontrollable). .. warning:: - If a filter capacitor is added to your flash power supply circuit, please do everything possible to avoid powering down flash. + If a filter capacitor is added to your SPI Flash power supply circuit, please do everything possible to avoid powering down SPI Flash. -Therefore, it is recommended not to power down flash when using ESP-IDF. For power-sensitive applications, it is recommended to use Kconfig option :ref:`CONFIG_ESP_SLEEP_FLASH_LEAKAGE_WORKAROUND` to reduce the power consumption of the flash during Light-sleep, instead of powering down the flash. +Therefore, it is recommended not to power down SPI Flash when using ESP-IDF. For power-sensitive applications, it is recommended to use Kconfig option :ref:`CONFIG_ESP_SLEEP_FLASH_LEAKAGE_WORKAROUND` to reduce the power consumption of the SPI Flash during Light-sleep, instead of powering down the SPI Flash. .. only:: SOC_SPIRAM_SUPPORTED It is worth mentioning that PSRAM has a similar Kconfig option :ref:`CONFIG_ESP_SLEEP_PSRAM_LEAKAGE_WORKAROUND`. -However, for those who have fully understood the risk and are still willing to power down the flash to further reduce the power consumption, please check the following mechanisms: +However, for those who have fully understood the risk and are still willing to power down the SPI Flash to further reduce the power consumption, please check the following mechanisms: .. list:: - - Setting Kconfig option :ref:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH` only powers down the flash when the RTC timer is the only wake-up source **and** the sleep time is longer than the flash power-down period. - - Calling ``esp_sleep_pd_config(ESP_PD_DOMAIN_VDDSDIO, ESP_PD_OPTION_OFF)`` powers down flash when the RTC timer is not enabled as a wakeup source **or** the sleep time is longer than the flash power-down period. + - Setting Kconfig option :ref:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH` only powers down the SPI Flash when the RTC timer is the only wake-up source **and** the sleep time is longer than the SPI Flash power-down period. + - Calling ``esp_sleep_pd_config(ESP_PD_DOMAIN_VDDSDIO, ESP_PD_OPTION_OFF)`` powers down SPI Flash when the RTC timer is not enabled as a wakeup source **or** the sleep time is longer than the SPI Flash power-down period. .. note:: .. list:: - - ESP-IDF does not provide any mechanism that can power down the flash in all conditions when Light-sleep. - - :cpp:func:`esp_deep_sleep_start` function forces power down flash regardless of user configuration. + - ESP-IDF does not provide any mechanism that can power down the SPI Flash in all conditions when Light-sleep. + - :cpp:func:`esp_deep_sleep_start` function forces power down SPI Flash regardless of user configuration. + +.. _spi_flash_power_down_dpd: Flash Entering Deep Power-Down Mode ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -In addition to reducing power consumption by completely powering off the flash, you can further lower flash power usage during sleep by enabling the Kconfig option :ref:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`. Compared with fully cutting off the flash power, this feature avoids the extra delay caused by re-powering the flash when the chip wakes up from sleep, while still achieving extremely low power consumption. Most flashes draw less than 1 µA when entering Deep Power-Down (DPD) mode. +In addition to reducing power consumption by completely powering off the SPI Flash, you can further lower SPI Flash power usage during sleep by enabling the Kconfig option :ref:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`. Compared with fully cutting off the SPI Flash power, this feature avoids the extra delay caused by re-powering the SPI Flash when the chip wakes up from sleep, while still achieving extremely low power consumption. Most SPI Flash draw less than 1 µA when entering Deep Power-Down (DPD) mode. -In almost all use cases, using DPD mode provides better overall benefits than fully powering off the flash, offering both improved safety and lower power consumption. +In almost all use cases, using DPD mode provides better overall benefits than fully powering off the SPI Flash, offering both improved safety and lower power consumption. .. warning:: - Before using this feature, check the datasheet of the flash device used on your chip to ensure it supports the Deep Power-Down mode. + Before using this feature, check the datasheet of the SPI Flash device used on your chip to ensure it supports the Deep Power-Down mode. + +Flash Sleep Strategy Recommendations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In sleep scenarios, the SPI Flash handling method directly affects system safety, and power consumption. Different application scenarios prioritize these factors differently, so it is important to choose an appropriate SPI Flash sleep strategy. + +Keep Flash Powered On +""""""""""""""""""""" + +The standby power consumption of different SPI Flash varies. In ESP series chips, the standby power consumption of SPI Flash is typically below 30 µA. In the following scenarios, it is recommended to keep the SPI Flash powered on: + +1. The system has extremely high stability requirements and cannot accept any potential risks from SPI Flash power-off. + +2. Sleep duration is short or unpredictable, for example, when asynchronous wake-up sources exist (GPIO, UART, etc.). + +3. Large filter capacitors exist in the SPI Flash power supply circuit, making it difficult to estimate the actual SPI Flash power-down time. + +In the above cases, keeping the SPI Flash powered on is the most conservative and safest choice, but note that its standby power consumption is relatively high (about 10-30 µA). + +Power Down Flash +"""""""""""""""" + +You can refer to :ref:`spi_flash_power_down` to power down the SPI Flash during sleep. After the following conditions are met or after thorough evaluation, you may consider this strategy: + +1. The application has strict requirements for extremely low power consumption. + +2. Wake-up sources are controllable, typically only RTC timer wake-up sources are enabled. + +3. It can be ensured that the actual sleep time is greater than the time required for the SPI Flash to completely power down. For ESP series chips other than ESP32-C5 and ESP32-C61, the time required for the SPI Flash to completely power down may be greater than 300ms; while for ESP32-C5 and ESP32-C61, due to the fast discharge feature, the time required is greater than 5ms. If parallel capacitors exist in the SPI Flash power supply circuit, longer sleep time may be required. + +4. If the sleep time is too short, the power consumption during the SPI Flash power-on and power-down processes may exceed the power consumption when keeping it powered on. + +5. There is sufficient control over SPI Flash power supply and IO states to avoid SPI Flash leakage due to pin pull-up during sleep. + +Since the SPI Flash power-down process is greatly affected by hardware design, IO impedance characteristics, power supply, and environmental factors, ESP-IDF cannot guarantee that the SPI Flash will be safely powered down in Light-sleep mode. Therefore, this method is only suitable for scenarios with controllable risks and thorough verification. + +Flash Entering Deep Power-Down (DPD) Mode +"""""""""""""""""""""""""""""""""""""""""" + +In the vast majority of application scenarios, it is recommended to prioritize using the Deep Power-Down (DPD) mode of the SPI Flash to reduce sleep power consumption. For power figures, timings, and how to enable this feature, see :ref:`spi_flash_power_down_dpd` above instead of duplicating them here. DPD mode is suitable for the following scenarios: + +1. Significant reduction in SPI Flash power consumption during sleep is needed, but the risk of SPI Flash re-powering should be avoided. + +2. Sleep duration is short or unpredictable, for example, when asynchronous wake-up sources exist (GPIO, UART, etc.). + +3. SPI Flash chip used explicitly supports Deep Power-Down mode. Configuring IOs (Deep-sleep Only) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/zh_CN/api-reference/system/sleep_modes.rst b/docs/zh_CN/api-reference/system/sleep_modes.rst index fb0bc941944..2cfa5e4151f 100644 --- a/docs/zh_CN/api-reference/system/sleep_modes.rst +++ b/docs/zh_CN/api-reference/system/sleep_modes.rst @@ -491,47 +491,97 @@ RTC 外设和内存断电 {IDF_TARGET_NAME} 中只有 RTC 高速内存，因此，如果程序中的某些值被标记为 ``RTC_DATA_ATTR``、``RTC_SLOW_ATTR`` 或 ``RTC_FAST_ATTR`` 属性，那么所有这些值都将被存入 RTC 高速内存，默认情况下保持供电。如有需要，也可以使用函数 :cpp:func:`esp_sleep_pd_config` 对其进行修改。 -flash 断电 +.. _spi_flash_power_down: + +SPI Flash 断电 ^^^^^^^^^^ -默认情况下，调用函数 :cpp:func:`esp_light_sleep_start` 后，flash **不会** 断电，因为在 sleep 过程中断电 flash 存在风险。具体而言，flash 断电需要时间，但是在此期间，系统有可能被唤醒，导致 flash 重新被上电。此时，断电尚未完成又重新上电的硬件行为有可能导致 flash 无法正常工作。 +默认情况下，调用函数 :cpp:func:`esp_light_sleep_start` 后，SPI Flash **不会** 断电，因为在 sleep 过程中断电 SPI Flash 存在风险。具体而言，SPI Flash 断电需要时间，但是在此期间，系统有可能被唤醒，导致 SPI Flash 重新被上电。此时，断电尚未完成又重新上电的硬件行为有可能导致 SPI Flash 无法正常工作。 -理论上讲，在 flash 完全断电后可以仅唤醒系统，然而现实情况是 flash 断电所需的时间很难预测。如果用户为 flash 供电电路添加了滤波电容，断电所需时间可能会更长。此外，即使可以预知 flash 彻底断电所需的时间，有时也不能通过设置足够长的睡眠时间来确保 flash 断电的安全（比如，突发的异步唤醒源会使得实际的睡眠时间不可控）。 +理论上讲，在 SPI Flash 完全断电后可以仅唤醒系统，然而现实情况是 SPI Flash 断电所需的时间很难预测。如果用户为 SPI Flash 供电电路添加了滤波电容，断电所需时间可能会更长。此外，即使可以预知 SPI Flash 彻底断电所需的时间，有时也不能通过设置足够长的睡眠时间来确保 SPI Flash 断电的安全（比如，突发的异步唤醒源会使得实际的睡眠时间不可控）。 .. warning:: - 如果在 flash 的供电电路上添加了滤波电容，那么应当尽一切可能避免 flash 断电。 + 如果在 SPI Flash 的供电电路上添加了滤波电容，那么应当尽一切可能避免 SPI Flash 断电。 -因为这些不可控的因素，ESP-IDF 很难保证 flash 断电的绝对安全。因此 ESP-IDF 不推荐用户断电 flash。对于一些功耗敏感型应用，可以通过设置 Kconfig 配置项 :ref:`CONFIG_ESP_SLEEP_FLASH_LEAKAGE_WORKAROUND` 来减少 Light-sleep 期间 flash 的功耗。这种方式在几乎所有场景下都要比断电 flash 更好，兼顾了安全性和功耗。 +因为这些不可控的因素，ESP-IDF 很难保证 SPI Flash 断电的绝对安全。因此 ESP-IDF 不推荐用户断电 SPI Flash。对于一些功耗敏感型应用，可以通过设置 Kconfig 配置项 :ref:`CONFIG_ESP_SLEEP_FLASH_LEAKAGE_WORKAROUND` 来减少 Light-sleep 期间 SPI Flash 的功耗。这种方式在几乎所有场景下都要比断电 SPI Flash 更好，兼顾了安全性和功耗。 .. only:: SOC_SPIRAM_SUPPORTED 值得一提的是，PSRAM 也有一个类似的 Kconfig 配置项 :ref:`CONFIG_ESP_SLEEP_PSRAM_LEAKAGE_WORKAROUND`。 -考虑到有些用户能够充分评估断电 flash 的风险，并希望通过断电 flash 来获得更低的功耗，因此 ESP-IDF 提供了两种断电 flash 的机制： +考虑到有些用户能够充分评估断电 SPI Flash 的风险，并希望通过断电 SPI Flash 来获得更低的功耗，因此 ESP-IDF 提供了两种断电 SPI Flash 的机制： .. list:: - - 设置 Kconfig 配置项 :ref:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH` 将使 ESP-IDF 以一个严格的条件来断电 flash。严格的条件具体指的是，RTC timer 是唯一的唤醒源 **且** 睡眠时间比 flash 彻底断电所需时间更长。 - - 调用函数 ``esp_sleep_pd_config(ESP_PD_DOMAIN_VDDSDIO, ESP_PD_OPTION_OFF)`` 将使 ESP-IDF 以一个宽松的条件来断电 flash。宽松的条件具体指的是 RTC timer 唤醒源未被使能 **或** 睡眠时间比 flash 彻底断电所需时间更长。 + - 设置 Kconfig 配置项 :ref:`CONFIG_ESP_SLEEP_POWER_DOWN_FLASH` 将使 ESP-IDF 以一个严格的条件来断电 SPI Flash。严格的条件具体指的是，RTC timer 是唯一的唤醒源 **且** 睡眠时间比 SPI Flash 彻底断电所需时间更长。 + - 调用函数 ``esp_sleep_pd_config(ESP_PD_DOMAIN_VDDSDIO, ESP_PD_OPTION_OFF)`` 将使 ESP-IDF 以一个宽松的条件来断电 SPI Flash。宽松的条件具体指的是 RTC timer 唤醒源未被使能 **或** 睡眠时间比 SPI Flash 彻底断电所需时间更长。 .. note:: .. list:: - - Light-sleep 模式下，ESP-IDF 没有提供保证 flash 一定会被断电的机制。 - - 不管用户的配置如何，函数 :cpp:func:`esp_deep_sleep_start` 都会强制断电 flash。 + - Light-sleep 模式下，ESP-IDF 没有提供保证 SPI Flash 一定会被断电的机制。 + - 不管用户的配置如何，函数 :cpp:func:`esp_deep_sleep_start` 都会强制断电 SPI Flash -flash 进入 deep power-down 模式 +.. _spi_flash_power_down_dpd: + +SPI Flash 进入 deep power-down 模式 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -除了通过让 flash 完全断电来降低芯片功耗之外，还可以通过启用 Kconfig 配置项 :ref:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`，进一步减少休眠期间 flash 的功耗。与直接对 flash 断电相比，该功能能够避免芯片从休眠唤醒时 flash 重新上电所带来的额外延迟，同时也能保持极低的功耗。大多数 flash 在进入 Deep Power-Down（DPD）模式后电流消耗低于 1 µA。 +除了通过让 SPI Flash 完全断电来降低芯片功耗之外，还可以通过启用 Kconfig 配置项 :ref:`CONFIG_ESP_SLEEP_SET_FLASH_DPD`，进一步减少休眠期间 SPI Flash 的功耗。与直接对 SPI Flash 断电相比，该功能能够避免芯片从休眠唤醒时 SPI Flash 重新上电所带来的额外延迟，同时也能保持极低的功耗。大多数 SPI Flash 在进入 Deep Power-Down（DPD）模式后电流消耗低于 1 µA。 -在几乎所有应用场景中，使用 DPD 模式都比直接断电 flash 更具优势，兼顾了安全性与低功耗表现。 +在几乎所有应用场景中，使用 DPD 模式都比直接断电 SPI Flash 更具优势，兼顾了安全性与低功耗表现。 .. warning:: - 使用该功能前需要查阅使用芯片所搭载的 flash 的技术手册是否支持 deep power-down 模式。 + 使用该功能前需要查阅使用芯片所搭载的 SPI Flash 的技术手册是否支持 deep power-down 模式。 + +SPI Flash 休眠策略选择建议 +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +在休眠场景下，SPI Flash 的处理方式直接影响系统的安全性、功耗。不同应用场景对这些因素的侧重不同，因此需要选择合适的 SPI Flash 休眠策略。 + +SPI Flash 不掉电 +""""""""""""" + +不同 SPI Flash 的待机功耗不一致，在 ESP 系列芯片中，SPI Flash 的待机功耗通常低于 30 µA，在以下场景中，建议保持 SPI Flash 不掉电： + +1. 系统对稳定性要求极高，无法接受 SPI Flash 掉电带来的任何潜在风险。 + +2. 休眠时间较短或不可预测，例如存在异步唤醒源（GPIO、UART 等）。 + +3. SPI Flash 供电电路中存在较大的滤波电容，导致 SPI Flash 实际断电时间难以估计。 + +在上述情况下，保持 SPI Flash 供电是最保守、也是最安全的选择，但需要注意其待机功耗相对较高 (约 10-30 µA)。 + +SPI Flash 掉电 +""""""""""" + +可以参考 :ref:`spi_flash_power_down` 实现在休眠中掉电 SPI Flash。在以下条件满足或经过充分评估后，可以考虑该策略： + +1. 应用对极低功耗有严格要求。 + +2. 唤醒源可控，通常仅启用 RTC timer 唤醒源。 + +3. 能够确保实际睡眠时间大于 SPI Flash 彻底断电所需时间。对于除 ESP32-C5 和 ESP32-C61 之外的 ESP 系列芯片，SPI Flash 彻底断电所需时间可能大于 300ms；而对于 ESP32-C5 和 ESP32-C61，由于支持快速放电功能，彻底断电所需时间大于 5ms。如果 SPI Flash 供电电路中存在并联电容，可能需要更长的睡眠时间。 + +4. 如果休眠时间过短，SPI Flash 上电和下电过程所消耗的功耗可能会超过保持供电时的功耗。 + +5. 对 SPI Flash 供电及 IO 状态有充分控制，休眠时避免因为管脚上拉导致 SPI Flash 漏电。 + +由于 SPI Flash 的断电过程受硬件设计、IO 阻抗特性、供电以及环境因素影响较大，ESP-IDF 无法保证在 Light-sleep 模式下 SPI Flash 一定能够安全断电，因此该方式仅适用于风险可控且经过充分验证的场景。 + +SPI Flash 进入 deep power-down（DPD）模式 +"""""""""""""""""""""""""""""""""""""""""" + +在绝大多数应用场景中，推荐优先使用 SPI Flash 的 Deep Power-Down（DPD）模式来降低休眠功耗。功耗数据、时序及如何启用该功能请直接参见上文 :ref:`spi_flash_power_down_dpd`，此处不再重复。DPD 模式适用于以下场景： + +1. 需要显著降低休眠期间 SPI Flash 的功耗，但又希望避免 SPI Flash 重新上电的风险。 + +2. 休眠时间较短或不可预测，例如存在异步唤醒源（GPIO、UART 等）。 + +3. 使用的 SPI Flash 芯片明确支持 Deep Power-Down 模式。 配置 IO（仅适用于 Deep-sleep） ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^