esp_pm: update doc for PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP

components/esp_pm/Kconfig

@@ -105,13 +105,23 @@ menu "Power Management"
             cache configuration, if this option is enabled, it will consume up to 9 KB of internal RAM.
 
     config PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP
-        bool "Power down Digital Peripheral in light sleep"
+        bool "Power down Digital Peripheral in light sleep (EXPERIMENTAL)"
         depends on SOC_PAU_SUPPORTED
         default n #TODO: enable by default if periph init/deinit management supported (WIFI-5252)
         help
-            If enabled, the minimum digital peripheral register context to keep the system running is saved
-            and will reduce sleep current consumption by about 100 uA. enabling this option will consume
-            at least 4.55 KB of internal RAM.
+            If enabled, digital peripherals will be powered down in light sleep, it will reduce sleep
+            current consumption by about 100 uA. Chip will save/restore register context at sleep/wake
+            time to keep the system running. Enabling this option will increase static RAM and heap usage,
+            the actual cost depends on the peripherals you have initialized. In order to save/restore the
+            context of the necessary hardware for FreeRTOS to run, it will need at least 4.55 KB free heap
+            at sleep time. Otherwise sleep will not power down the peripherals.
+
+            Note: Please use this option with caution, the current IDF does not support the retention of
+            all peripherals. When the digital peripherals are powered off and a sleep and wake-up is completed,
+            the peripherals that have not saved the running context are equivalent to performing a reset.
+            !!! Please confirm the peripherals used in your application and their sleep retention support status
+            before enabling this option, peripherals sleep retention driver support status is tracked in
+            power_management.rst
 
     config PM_UPDATE_CCOMPARE_HLI_WORKAROUND
         bool

docs/en/api-reference/system/power_management.rst

@@ -133,6 +133,49 @@ The following peripheral drivers are not aware of DFS yet. Applications need to
     - The legacy timer group driver
     :SOC_MCPWM_SUPPORTED: - MCPWM
 
+
+Light-sleep Peripheral Power Down
+---------------------------------
+
+.. only:: esp32c6 or esp32h2
+
+    {IDF_TARGET_NAME} supports power-down peripherals during Light-sleep.
+
+    If :ref:`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
 -------------
 

docs/zh_CN/api-reference/system/power_management.rst

@@ -133,6 +133,50 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求，
     - 旧版定时器驱动（Timer Group)
     :SOC_MCPWM_SUPPORTED: - MCPWM
 
+
+
+Light-sleep 外设下电
+-------------------------
+
+.. only:: esp32c6 or esp32h2
+
+    {IDF_TARGET_NAME} 支持在 Light-sleep 时掉电外设的电源域.
+
+    如果在 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
+    - TIMG0
+    - SPI0/1
+    - SYSTIMER
+
+    以下外设尚未支持：
+    - 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
+
+    对于未支持 Light-sleep 上下文备份的外设，若启用了电源管理功能，应在外设工作时持有 `ESP_PM_NO_LIGHT_SLEEP` 锁以避免进入休眠导致外设工作上下文丢失。
+
 API 参考
 -------------