Merge branch 'docs/add_description_for_pd_top_gpio_configuration' into 'master'

docs(esp_pm): Adding notes on configuring GPIOs when using PD_TOP sleep

Closes IDFGH-12085 and IDFGH-13186

See merge request espressif/esp-idf!29097

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,
@@ -454,14 +455,20 @@ void gpio_iomux_out(uint8_t gpio_num, int func, bool oen_inv);
   * This function will immediately cause all pads to latch the current values of input enable, output enable,
   * output value, function, and drive strength values.
   *
-  * @warning This function will hold flash and UART pins as well. Therefore, this function, and all code run afterwards
-  * (till calling `gpio_force_unhold_all` to disable this feature), MUST be placed in internal RAM as holding the flash
-  * pins will halt SPI flash operation, and holding the UART pins will halt any UART logging.
+  * @warning
+  *   1. This function will hold flash and UART pins as well. Therefore, this function, and all code run afterwards
+  *      (till calling `gpio_force_unhold_all` to disable this feature), MUST be placed in internal RAM as holding the flash
+  *      pins will halt SPI flash operation, and holding the UART pins will halt any UART logging.
+  *   2. The hold state of all pads will be cancelled during ROM boot, so it is not recommended to use this API to hold
+  *      the pads state during deepsleep and reset.
   * */
 esp_err_t gpio_force_hold_all(void);
 
 /**
-  * @brief Force unhold all digital and rtc gpio pads.
+  * @brief Unhold all digital and rtc gpio pads.
+  *
+  * @note  The global hold signal and the hold signal of each IO act on the PAD through 'or' logic, so if a pad has already
+  *        been configured to hold by `gpio_hold_en`, this API can't release its hold state.
   * */
 esp_err_t gpio_force_unhold_all(void);
 #endif

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
 -------------

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 参考
 -------------