From cfd8c6fb94fe5bf21cdb75e0777e811008f5fefd Mon Sep 17 00:00:00 2001
From: wuzhenghui <wuzhenghui@espressif.com>
Date: Mon, 19 Feb 2024 11:33:35 +0800
Subject: [PATCH] docs(esp_pm): Adding notes on configuring GPIOs when using
 PD_TOP sleep

Closes https://github.com/espressif/esp-idf/issues/13143
---
 components/esp_driver_gpio/include/driver/gpio.h    | 13 +++++++------
 docs/en/api-reference/system/power_management.rst   |  4 ++++
 .../zh_CN/api-reference/system/power_management.rst |  3 +++
 3 files changed, 14 insertions(+), 6 deletions(-)

diff --git a/components/esp_driver_gpio/include/driver/gpio.h b/components/esp_driver_gpio/include/driver/gpio.h
index 8abe78b709..d5c0e7563c 100644
--- a/components/esp_driver_gpio/include/driver/gpio.h
+++ b/components/esp_driver_gpio/include/driver/gpio.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -367,8 +367,9 @@ esp_err_t gpio_get_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t *stren
   *
   * When a GPIO is set to hold, its state is latched at that moment and will not change when the internal
   * signal or the IO MUX/GPIO configuration is modified (including input enable, output enable, output value,
-  * function, and drive strength values). This function can be used to retain the state of GPIOs when the chip
-  * or system is reset, for example, when watchdog time-out or Deep-sleep events are triggered.
+  * function, and drive strength values). This function can be used to retain the state of GPIOs when the power
+  * domain of where GPIO/IOMUX belongs to becomes off. For example, chip or system is reset (e.g. watchdog
+  * time-out, deep-sleep events are triggered), or peripheral power-down in light-sleep.
   *
   * This function works in both input and output modes, and only applicable to output-capable GPIOs.
   * If this function is enabled:
@@ -392,9 +393,9 @@ esp_err_t gpio_hold_en(gpio_num_t gpio_num);
 /**
   * @brief Disable gpio pad hold function.
   *
-  * When the chip is woken up from Deep-sleep, the gpio will be set to the default mode, so, the gpio will output
-  * the default level if this function is called. If you don't want the level changes, the gpio should be configured to
-  * a known state before this function is called.
+  * When the chip is woken up from peripheral power-down sleep, the gpio will be set to the default mode,
+  * so, the gpio will output the default level if this function is called. If you don't want the level changes, the
+  * gpio should be configured to a known state before this function is called.
   *  e.g.
   *     If you hold gpio18 high during Deep-sleep, after the chip is woken up and `gpio_hold_dis` is called,
   *     gpio18 will output low level(because gpio18 is input mode by default). If you don't want this behavior,
diff --git a/docs/en/api-reference/system/power_management.rst b/docs/en/api-reference/system/power_management.rst
index 6d55422ea8..70f500ced8 100644
--- a/docs/en/api-reference/system/power_management.rst
+++ b/docs/en/api-reference/system/power_management.rst
@@ -169,6 +169,10 @@ Light-sleep Peripheral Power Down
 
     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.
 
+    .. note::
+
+        When the peripheral power domain is powered down during sleep, both the IO_MUX and GPIO modules are inactive, meaning the chip pins' state is not maintained by these modules. To preserve the state of an IO during sleep, it's essential to call :cpp:func:`gpio_hold_dis` and :cpp:func:`gpio_hold_en` before and after configuring the GPIO state. This action ensures that the IO configuration is latched and prevents the IO from becoming floating while in sleep mode.
+
 
 API Reference
 -------------
diff --git a/docs/zh_CN/api-reference/system/power_management.rst b/docs/zh_CN/api-reference/system/power_management.rst
index 56fe1b04c4..e0d3802a40 100644
--- a/docs/zh_CN/api-reference/system/power_management.rst
+++ b/docs/zh_CN/api-reference/system/power_management.rst
@@ -169,6 +169,9 @@ Light-sleep 外设下电
 
     对于未支持 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 参考
 -------------