Merge branch 'doc/update_esp32p4_pm_programming_guide_docs_v5.3' into 'release/v5.3'

docs(pm): update power management related docs for esp32p4 (v5.3) See merge request espressif/esp-idf!32629
2026-10-02 03:00:34 +03:00 · 2024-09-04 17:58:13 +08:00
parent 2d850169c0 5e403bb7c6
commit 0d1227c06f
17 changed files with 148 additions and 111 deletions
@@ -16,7 +16,7 @@ API 指南
   cplusplus
   core_dump
   current-consumption-measurement-modules
-   :SOC_RTC_MEM_SUPPORTED: deep-sleep-stub
+   :ESP_ROM_SUPPORT_DEEP_SLEEP_WAKEUP_STUB: deep-sleep-stub
   :SOC_USB_OTG_SUPPORTED and not esp32p4: dfu
   error-handling
   :SOC_BLE_MESH_SUPPORTED: esp-ble-mesh/ble-mesh-index
@@ -14,7 +14,7 @@

    * 将关键代码存放到 RAM 中以提高性能；
    * 将可执行代码存放到 IRAM 中，以便在缓存被禁用时运行这些代码；
-    :SOC_RTC_MEM_SUPPORTED: * 将代码存放到 RTC 存储器中，以便在 wake stub 中使用；
+    :ESP_ROM_SUPPORT_DEEP_SLEEP_WAKEUP_STUB: * 将代码存放到 RTC 存储器中，以便在 wake stub 中使用；
    :SOC_ULP_SUPPORTED: * 将代码存放到 RTC 内存中，以便 ULP 协处理器使用。

 链接器脚本生成机制可以让用户指定代码和数据在 ESP-IDF 组件中的存放区域。组件包含如何存放符号、目标或完整库的信息。在构建应用程序时，组件中的这些信息会被收集、解析并处理；生成的存放规则用于链接应用程序。
@@ -150,7 +150,9 @@ DROM（数据存储在 flash 中）
    RTC Slow memory（RTC 慢速存储器）
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-    从 RTC 存储器运行的代码中使用的全局和静态变量必须放入 RTC Slow memory 中。例如 :doc:`深度睡眠 <deep-sleep-stub>` 变量可以放在 RTC Slow memory 中，而不是 RTC FAST memory，或者也可以放入由 :doc:`/api-reference/system/ulp` 访问的代码和变量。
+    .. only:: ESP_ROM_SUPPORT_DEEP_SLEEP_WAKEUP_STUB
+
+        从 RTC 存储器运行的代码中使用的全局和静态变量必须放入 RTC Slow memory 中。例如 :doc:`深度睡眠 <deep-sleep-stub>` 变量可以放在 RTC Slow memory 中，而不是 RTC FAST memory，或者也可以放入由 :doc:`/api-reference/system/ulp` 访问的代码和变量。

    ``RTC_NOINIT_ATTR`` 属性宏可以用来将数据放入 RTC Slow memory。放入此类型存储器的值从深度睡眠模式中醒来后会保持值不变。

@@ -170,8 +172,9 @@ DROM（数据存储在 flash 中）

            对于 {IDF_TARGET_NAME}，RTC 存储器已被重新重命名为 LP（低功耗）存储器。在与 {IDF_TARGET_NAME} 相关的 IDF 代码、文档以及技术参考手册中，可能会出现这两个术语混用的情况。

+    .. only:: ESP_ROM_SUPPORT_DEEP_SLEEP_WAKEUP_STUB

-    RTC FAST memory 的同一区域既可以作为指令存储器也可以作为数据存储器进行访问。从深度睡眠模式唤醒后必须要运行的代码要放在 RTC 存储器中，更多信息请查阅文档 :doc:`深度睡眠 <deep-sleep-stub>`。
+        RTC FAST memory 的同一区域既可以作为指令存储器也可以作为数据存储器进行访问。从深度睡眠模式唤醒后必须要运行的代码要放在 RTC 存储器中，更多信息请查阅文档 :doc:`深度睡眠 <deep-sleep-stub>`。

    .. only:: esp32

@@ -32,7 +32,7 @@

 .. list::

-   :SOC_RTC_MEM_SUPPORTED: #. 从深度睡眠模式复位：如果 ``RTC_CNTL_STORE6_REG`` 寄存器的值非零，且 ``RTC_CNTL_STORE7_REG`` 寄存器中的 RTC 内存的 CRC 校验值有效，那么程序会使用 ``RTC_CNTL_STORE6_REG`` 寄存器的值作为入口地址，并立即跳转到该地址运行。如果  ``RTC_CNTL_STORE6_REG`` 的值为零，或 ``RTC_CNTL_STORE7_REG`` 中的 CRC 校验值无效，又或通过 ``RTC_CNTL_STORE6_REG`` 调用的代码返回，那么则像上电复位一样继续启动。 **注意**：如果想在这里运行自定义的代码，可以参考 :doc:`深度睡眠 <deep-sleep-stub>` 文档里面介绍的深度睡眠存根机制方法。
+   :ESP_ROM_SUPPORT_DEEP_SLEEP_WAKEUP_STUB: #. 从深度睡眠模式复位：如果 ``RTC_CNTL_STORE6_REG`` 寄存器的值非零，且 ``RTC_CNTL_STORE7_REG`` 寄存器中的 RTC 内存的 CRC 校验值有效，那么程序会使用 ``RTC_CNTL_STORE6_REG`` 寄存器的值作为入口地址，并立即跳转到该地址运行。如果  ``RTC_CNTL_STORE6_REG`` 的值为零，或 ``RTC_CNTL_STORE7_REG`` 中的 CRC 校验值无效，又或通过 ``RTC_CNTL_STORE6_REG`` 调用的代码返回，那么则像上电复位一样继续启动。 **注意**：如果想在这里运行自定义的代码，可以参考 :doc:`深度睡眠 <deep-sleep-stub>` 文档里面介绍的深度睡眠存根机制方法。

   #. 上电复位、软件 SoC 复位、看门狗 SoC 复位：检查 ``GPIO_STRAP_REG`` 寄存器，判断是否请求自定义启动模式，如 UART 下载模式。如果是，ROM 会执行此自定义加载模式，否则会像软件 CPU 复位一样继续启动。请参考 {IDF_TARGET_NAME} 技术规格书了解 SoC 启动模式以及具体执行过程。

@@ -1 +1,13 @@
-TO BE UPDATED IDF-7672
+---------------+---------------------------------------+-------------------------------------+
+| CPU 最高频率  |            电源管理锁获取情况         | APB 频率和 CPU 频率                 |
+|               |                                       |                                     |
+---------------+---------------------------------------+-------------------------------------+
+|      360      | 获取 ``ESP_PM_CPU_FREQ_MAX``          | | CPU: 360 MHz                      |
+|               |                                       | | APB: 90 Mhz                       |
+               +---------------------------------------+-------------------------------------+
+|               | | 获取 ``ESP_PM_APB_FREQ_MAX``,       | | CPU: 90 MHz                       |
+|               | | 未获得 ``ESP_PM_CPU_FREQ_MAX``      | | APB: 90 Mhz                       |
+               +---------------------------------------+-------------------------------------+
+|               |                  无                   | 使用 :cpp:func:`esp_pm_configure`   |
+|               |                                       | 为二者设置最小值                    |
+---------------+---------------------------------------+-------------------------------------+
@@ -55,7 +55,7 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求，

 电源管理锁
 ----------------------
-{IDF_TARGET_MAX_CPU_FREQ: default="Not updated yet", esp32="80 MHz, 160 MHz, or 240 MHz", esp32s2="80 MHz, 160 MHz, 或 240 MHz", esp32s3="80 MHz, 160 MHz, 或 240 MHz", esp32c2="80 MHz 或 120 MHz", esp32c3="80 MHz 或 160 MHz", esp32c6="80 MHz 或 160 MHz"}
+{IDF_TARGET_MAX_CPU_FREQ: default="Not updated yet", esp32="80 MHz, 160 MHz, or 240 MHz", esp32s2="80 MHz, 160 MHz, 或 240 MHz", esp32s3="80 MHz, 160 MHz, 或 240 MHz", esp32c2="80 MHz 或 120 MHz", esp32c3="80 MHz 或 160 MHz", esp32c6="80 MHz 或 160 MHz", esp32p4="360 MHz"}

 应用程序可以通过获取或释放管理锁来控制电源管理算法。应用程序获取电源管理锁后，电源管理算法的操作将受到下面的限制。释放电源管理锁后，限制解除。

@@ -114,7 +114,7 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求，
    - **SPI slave**：从调用 :cpp:func:`spi_slave_initialize` 至 :cpp:func:`spi_slave_free` 期间。
    - **GPTimer**：从调用 :cpp:func:`gptimer_enable` 至 :cpp:func:`gptimer_disable` 期间。
    - **Ethernet**：从调用 :cpp:func:`esp_eth_driver_install` 至 :cpp:func:`esp_eth_driver_uninstall` 期间。
-    - **WiFi**：从调用 :cpp:func:`esp_wifi_start` 至 :cpp:func:`esp_wifi_stop` 期间。如果启用了调制解调器睡眠模式，广播关闭时将释放此管理锁。
+    :SOC_WIFI_SUPPORTED: - **WiFi**：从调用 :cpp:func:`esp_wifi_start` 至 :cpp:func:`esp_wifi_stop` 期间。如果启用了调制解调器睡眠模式，广播关闭时将释放此管理锁。
    :SOC_TWAI_SUPPORTED: - **TWAI**：从调用 :cpp:func:`twai_driver_install` 至 :cpp:func:`twai_driver_uninstall` 期间 (只有在 TWAI 时钟源选择为 :cpp:enumerator:`TWAI_CLK_SRC_APB` 的时候生效)。
    :SOC_BT_SUPPORTED and esp32: - **Bluetooth**：从调用 :cpp:func:`esp_bt_controller_enable` 至 :cpp:func:`esp_bt_controller_disable` 期间。如果启用了蓝牙调制解调器，广播关闭时将释放此管理锁。但依然占用 ``ESP_PM_NO_LIGHT_SLEEP`` 锁，除非将 :ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` 选项设置为 “外部 32 kHz 晶振”。
    :SOC_BT_SUPPORTED and not esp32: - **Bluetooth**：从调用 :cpp:func:`esp_bt_controller_enable` 至 :cpp:func:`esp_bt_controller_disable` 期间。如果启用了蓝牙调制解调器，广播关闭时将释放此管理锁。但依然占用 ``ESP_PM_NO_LIGHT_SLEEP`` 锁。
@@ -129,46 +129,53 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求，
    :SOC_MCPWM_SUPPORTED: - MCPWM


-Light-sleep 外设下电
-------------------------
+.. only:: SOC_PM_SUPPORT_TOP_PD and not esp32c5

-.. only:: esp32c6 or esp32h2
+    Light-sleep 外设下电
+    -------------------------

-    {IDF_TARGET_NAME} 支持在 Light-sleep 时掉电外设的电源域.
+        {IDF_TARGET_NAME} 支持在 Light-sleep 时掉电外设的电源域.

-    如果在 menuconfig 中启用了 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`，在初始化外设时，驱动会将外设工作的寄存器上下文注册到休眠备份链表中，在进入休眠前，``REG_DMA`` 外设会读取休眠备份链表中的配置，根据链表中的配置将外设的寄存器上下文备份至内存，``REG_DMA`` 也会在唤醒时将上下文从内存恢复到外设寄存中。
+        如果在 menuconfig 中启用了 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`，在初始化外设时，驱动会将外设工作的寄存器上下文注册到休眠备份链表中，在进入休眠前，``REG_DMA`` 外设会读取休眠备份链表中的配置，根据链表中的配置将外设的寄存器上下文备份至内存，``REG_DMA`` 也会在唤醒时将上下文从内存恢复到外设寄存中。

-    目前 IDF 支持以下外设的 Light-sleep 上下文备份：
-    - INT_MTX
-    - TEE/APM
-    - IO_MUX / GPIO
-    - UART0/1
-    - GPTimer
-    - SPI0/1
-    - SYSTIMER
+        目前 IDF 支持以下外设的 Light-sleep 上下文备份：

-    以下外设尚未支持：
-    - ETM
-    - ASSIST_DEBUG
-    - Trace
-    - Crypto: AES/ECC/HMAC/RSA/SHA/DS/XTA_AES/ECDSA
-    - SPI2
-    - I2S
-    - PCNT
-    - USB-Serial-JTAG
-    - TWAI
-    - LEDC
-    - MCPWM
-    - RMT
-    - SARADC
-    - SDIO
-    - PARL_IO
+        .. list::

-    对于未支持 Light-sleep 上下文备份的外设，若启用了电源管理功能，应在外设工作时持有 ``ESP_PM_NO_LIGHT_SLEEP`` 锁以避免进入休眠导致外设工作上下文丢失。
+            - INT_MTX
+            - TEE/APM
+            - IO_MUX / GPIO
+            - Timer Group 0 & Timer Group 1
+            - SPI0/1
+            - SYSTIMER
+            :SOC_RMT_SUPPORT_SLEEP_RETENTION: - RMT
+            :SOC_I2C_SUPPORT_SLEEP_RETENTION:- I2C
+            :SOC_UART_SUPPORT_SLEEP_RETENTION: - All UARTs

-    .. note::
+        以下外设尚未支持：

-        当外设电源域在睡眠期间断电时，IO_MUX 和 GPIO 模块都处于下电状态，这意味着芯片引脚的状态不会受这些模块控制。要在休眠期间保持 IO 的状态，需要在配置 GPIO 状态前后调用 :cpp:func:`gpio_hold_dis` 和 :cpp:func:`gpio_hold_en`。此操作可确保 IO 配置被锁存，防止 IO 在睡眠期间浮空。
+        .. list::
+
+            - ETM
+            - ASSIST_DEBUG
+            - Trace
+            - Crypto: AES/ECC/HMAC/RSA/SHA/DS/XTA_AES/ECDSA
+            - SPI2
+            - I2S
+            - PCNT
+            - USB-Serial-JTAG
+            - TWAI
+            - LEDC
+            - MCPWM
+            - SARADC
+            - SDIO
+            - PARL_IO
+
+        对于未支持 Light-sleep 上下文备份的外设，若启用了电源管理功能，应在外设工作时持有 ``ESP_PM_NO_LIGHT_SLEEP`` 锁以避免进入休眠导致外设工作上下文丢失。
+
+        .. note::
+
+            当外设电源域在睡眠期间断电时，IO_MUX 和 GPIO 模块都处于下电状态，这意味着芯片引脚的状态不会受这些模块控制。要在休眠期间保持 IO 的状态，需要在配置 GPIO 状态前后调用 :cpp:func:`gpio_hold_dis` 和 :cpp:func:`gpio_hold_en`。此操作可确保 IO 配置被锁存，防止 IO 在睡眠期间浮空。


 API 参考
@@ -32,7 +32,7 @@
        :SOC_RTC_FAST_MEM_SUPPORTED: - RTC 高速内存
        :SOC_RTC_SLOW_MEM_SUPPORTED: - RTC 低速内存

-.. only:: SOC_BT_SUPPORTED
+.. only:: SOC_WIFI_SUPPORTED and SOC_BT_SUPPORTED

    睡眠模式下的 Wi-Fi 和 Bluetooth 功能
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -41,7 +41,7 @@

    如需保持 Wi-Fi 和 Bluetooth 连接，请启用 Wi-Fi 和 Bluetooth Modem-sleep 模式和自动 Light-sleep 模式（请参阅 :doc:`电源管理 API <power_management>`）。在这两种模式下，Wi-Fi 和 Bluetooth 驱动程序发出请求时，系统将自动从睡眠中被唤醒，从而保持连接。

-.. only:: not SOC_BT_SUPPORTED
+.. only:: SOC_WIFI_SUPPORTED and not SOC_BT_SUPPORTED

    睡眠模式下的 Wi-Fi 功能
    ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -227,7 +227,7 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒
        - 当任意一个所选管脚为高电平时唤醒 (ESP_EXT1_WAKEUP_ANY_HIGH)
        - 当所有所选管脚为低电平时唤醒 (ESP_EXT1_WAKEUP_ALL_LOW)

-    .. only:: esp32s2 or esp32s3 or esp32c6 or esp32h2
+    .. only:: not esp32

        - 当任意一个所选管脚为高电平时唤醒 (ESP_EXT1_WAKEUP_ANY_HIGH)
        - 当任意一个所选管脚为低电平时唤醒 (ESP_EXT1_WAKEUP_ANY_LOW)
@@ -344,7 +344,7 @@ UART 唤醒（仅适用于 Light-sleep 模式）

 使用 UART 唤醒之后，在芯片 Active 模式下需要让 UART 接受一些数据用来清零内部的唤醒指示信号。不然的话，下一次 UART 唤醒的触发将只需要比配置的阈值少两个上升沿的数量。

-    .. only:: esp32c6 or esp32h2
+    .. only:: SOC_PM_SUPPORT_TOP_PD and not esp32c5

       .. note::

@@ -471,13 +471,12 @@ UART 输出处理

 .. list::

-    - :example:`protocols/sntp`：如何实现 Deep-sleep 模式的基本功能，周期性唤醒 ESP 模块，以从 NTP 服务器获取时间。
-    - :example:`wifi/power_save`：如何通过 Wi-Fi Modem-sleep 模式和自动 Light-sleep 模式保持 Wi-Fi 连接。
-    :SOC_BT_SUPPORTED: - :example:`bluetooth/nimble/power_save`：如何通过 Bluetooth Modem-sleep 模式和自动 Light-sleep 模式保持 Bluetooth 连接。
-    :SOC_ULP_SUPPORTED: - :example:`system/deep_sleep`：如何使用 Deep-sleep 唤醒触发器和 ULP 协处理器编程。
-    :not SOC_ULP_SUPPORTED: - :example:`system/deep_sleep`：如何通过多种芯片支持的唤醒源，如 RTC 定时器, GPIO, EXT0, EXT1, 触摸传感器等，触发 Deep-sleep 唤醒。
-    - :example:`system/light_sleep`: 如何使用多种芯片支持的唤醒源，如定时器，GPIO，触摸传感器等，触发 Light-sleep 唤醒。
-
+    - :example:`protocols/sntp` 演示如何实现 Deep-sleep 模式的基本功能，周期性唤醒 ESP 模块，以从 NTP 服务器获取时间。
+    :SOC_WIFI_SUPPORTED: - :example:`wifi/power_save` 演示如何通过 Wi-Fi Modem-sleep 模式和自动 Light-sleep 模式保持 Wi-Fi 连接。
+    :SOC_BT_SUPPORTED: - :example:`bluetooth/nimble/power_save` 演示如何通过 Bluetooth Modem-sleep 模式和自动 Light-sleep 模式保持 Bluetooth 连接。
+    :SOC_ULP_SUPPORTED: - :example:`system/deep_sleep` 演示如何使用 Deep-sleep 唤醒触发器和 ULP 协处理器编程。
+    :not SOC_ULP_SUPPORTED: - :example:`system/deep_sleep` 演示如何通过 {IDF_TARGET_NAME} 的唤醒源，如 RTC 定时器, GPIO, EXT0, EXT1, 触摸传感器等，触发 Deep-sleep 唤醒。
+    - :example:`system/light_sleep` 演示如何使用  {IDF_TARGET_NAME} 的唤醒源，如定时器，GPIO，触摸传感器等，触发 Light-sleep 唤醒。

 API 参考
 -------------