change(esp_hw_support): deprecate esp_deep_sleep_enable_gpio_wakeup API

rename esp_deep_sleep_enable_gpio_wakeup to esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown
rename esp_deepsleep_gpio_wake_up_mode_t to esp_sleep_gpio_wake_up_mode_t

components/esp_hw_support/include/esp_sleep.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -45,7 +45,7 @@ typedef enum {
 typedef enum {
     ESP_GPIO_WAKEUP_GPIO_LOW = 0,
     ESP_GPIO_WAKEUP_GPIO_HIGH = 1
-} esp_deepsleep_gpio_wake_up_mode_t;
+} esp_sleep_gpio_wake_up_mode_t;
 #endif
 
 /**
@@ -456,10 +456,11 @@ __attribute__((deprecated("please use 'esp_sleep_enable_ext1_wakeup_io' and 'esp
 /**
  * @brief Enable wakeup using specific gpio pins
  *
- * This function enables an IO pin to wake up the chip from deep sleep.
+ * This function enables an IO pin to wake up the chip from peripheral powerdowned sleep.
+ * (including deepsleep and peripheral powerdowned lightsleep).
  *
  * @note 1.This function does not modify pin configuration. The pins are configured
- *          inside `esp_deep_sleep_start`, immediately before entering sleep mode.
+ *          inside `esp_sleep_start`, immediately before entering sleep mode.
  *       2.This function is also applicable to waking up the lightsleep when the peripheral
  *         power domain is powered off, see PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP in menuconfig.
  *
@@ -479,9 +480,9 @@ __attribute__((deprecated("please use 'esp_sleep_enable_ext1_wakeup_io' and 'esp
  *            - ESP_GPIO_WAKEUP_GPIO_HIGH: wake up when the gpio turn to high.
  * @return
  *      - ESP_OK on success
- *      - ESP_ERR_INVALID_ARG if the mask contains any invalid deep sleep wakeup pin or wakeup mode is invalid
+ *      - ESP_ERR_INVALID_ARG if the mask contains any invalid wakeup pin or wakeup mode is invalid
  */
-esp_err_t esp_deep_sleep_enable_gpio_wakeup(uint64_t gpio_pin_mask, esp_deepsleep_gpio_wake_up_mode_t mode);
+esp_err_t esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown(uint64_t gpio_pin_mask, esp_sleep_gpio_wake_up_mode_t mode);
 #endif
 
 /**
@@ -499,7 +500,7 @@ esp_err_t esp_deep_sleep_enable_gpio_wakeup(uint64_t gpio_pin_mask, esp_deepslee
  * @note 1. On ESP32, GPIO wakeup source can not be used together with touch or ULP wakeup sources.
  *       2. If PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP is enabled (if target supported),
  *          this API is unavailable since the GPIO module is powered down during sleep.
- *          You can use `esp_deep_sleep_enable_gpio_wakeup` instead, or use EXT1 wakeup source
+ *          You can use `esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown` instead, or use EXT1 wakeup source
  *          by `esp_sleep_enable_ext1_wakeup_io` to achieve the same function.
  *          (Only GPIOs which have RTC functionality can be used)
  *

components/esp_hw_support/sleep_modes.c

@@ -1893,7 +1893,7 @@ bool esp_sleep_is_valid_wakeup_gpio(gpio_num_t gpio_num)
 #if SOC_RTCIO_PIN_COUNT > 0
     return RTC_GPIO_IS_VALID_GPIO(gpio_num);
 #elif SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP
-    return GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO(gpio_num);
+    return GPIO_IS_HP_PERIPH_PD_WAKEUP_VALID_IO(gpio_num);
 #else
     return false;
 #endif
@@ -2156,7 +2156,7 @@ static void esp_sleep_gpio_wakeup_prepare_on_hp_periph_powerdown(void)
     rtc_hal_gpio_clear_wakeup_status();
 }
 
-esp_err_t esp_deep_sleep_enable_gpio_wakeup(uint64_t gpio_pin_mask, esp_deepsleep_gpio_wake_up_mode_t mode)
+esp_err_t esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown(uint64_t gpio_pin_mask, esp_sleep_gpio_wake_up_mode_t mode)
 {
     if (mode > ESP_GPIO_WAKEUP_GPIO_HIGH) {
         ESP_LOGE(TAG, "invalid mode");
@@ -2169,7 +2169,7 @@ esp_err_t esp_deep_sleep_enable_gpio_wakeup(uint64_t gpio_pin_mask, esp_deepslee
     if (invalid_io_mask != 0) {
         for (gpio_num_t gpio_idx = __builtin_ctzll(invalid_io_mask); invalid_io_mask >> gpio_idx; gpio_idx++) {
             if (invalid_io_mask & BIT64(gpio_idx)) {
-                ESP_LOGE(TAG, "gpio %d is an invalid deep sleep wakeup IO", gpio_idx);
+                ESP_LOGE(TAG, "GPIO %d does not support wakeup on peripheral powerdown sleep", gpio_idx);
                 return ESP_ERR_INVALID_ARG;
             }
         }
@@ -2191,8 +2191,7 @@ esp_err_t esp_deep_sleep_enable_gpio_wakeup(uint64_t gpio_pin_mask, esp_deepslee
     s_config.wakeup_triggers |= RTC_GPIO_TRIG_EN;
     return err;
 }
-
+#endif //SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP
-#endif //SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP && SOC_DEEP_SLEEP_SUPPORTED
 
 esp_err_t esp_sleep_enable_gpio_wakeup(void)
 {

components/esp_hw_support/test_apps/wakeup_tests/main/src/io_wakeup_cmd.c

@@ -189,7 +189,7 @@ static int process_rtcio_wakeup(int argc, char **argv)
         ESP_ERROR_CHECK(gpio_config(&config));
 
         /* Enable wake up from GPIO */
-        ESP_ERROR_CHECK(esp_deep_sleep_enable_gpio_wakeup(BIT64(io_wakeup_num), io_wakeup_level));
+        ESP_ERROR_CHECK(esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown(BIT64(io_wakeup_num), io_wakeup_level));
     }
 
     return 0;

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

@@ -313,7 +313,7 @@ RTC peripherals or RTC memories do not need to be powered on during sleep in thi
 
                 In Light-sleep mode, if you set Kconfig option :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`， to continue using :cpp:func:`gpio_wakeup_enable` for GPIO wakeup, you need to first call :cpp:func:`rtc_gpio_init` and :cpp:func:`rtc_gpio_set_direction`, setting the RTCIO to input mode.
 
-                Alternatively，you can use :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` directly in that condition for GPIO wakeup, because the digital IO power domain is being powered off, where the situation is the same as entering Deep-sleep.
+                Alternatively，you can use :cpp:func:`esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown` directly in that condition for GPIO wakeup, because the digital IO power domain is being powered off.
 
             .. only::  not SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP
 
@@ -328,7 +328,10 @@ RTC peripherals or RTC memories do not need to be powered on during sleep in thi
 
         In addition to the GPIO wakeup mechanism available in Light-sleep mode, {IDF_TARGET_NAME} also supports waking up from Deep-sleep using GPIOs.
 
-        This wakeup source is implemented by :cpp:func:`esp_deep_sleep_enable_gpio_wakeup`, which allows selecting one or more GPIOs and the wakeup level (high or low). Only GPIOs powered by the {IDF_TARGET_RTC_POWER_DOMAIN} power domain can be used as Deep-sleep GPIO wakeup sources. The exact set of supported pins can be checked in the `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__ > Section IO Pins.
+        This wakeup source is implemented by :cpp:func:`esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown`, which allows selecting one or more GPIOs and the wakeup level (high or low). Only GPIOs powered by the {IDF_TARGET_RTC_POWER_DOMAIN} power domain can be used as Deep-sleep GPIO wakeup sources. The exact set of supported pins can be checked in the `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__ > Section IO Pins.
+
+        .. note::
+            This API also works for Light-sleep mode when the peripheral power domain is powered down (see :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`). In this case, it should be used instead of :cpp:func:`esp_sleep_enable_gpio_wakeup` because the GPIO module is powered down during sleep.
 
         For a complete example of using GPIO to wake up from Deep-sleep, see :example:`system/deep_sleep`.
 
@@ -337,17 +340,24 @@ RTC peripherals or RTC memories do not need to be powered on during sleep in thi
     GPIO Wakeup
     ^^^^^^^^^^^
 
-    Any IO can be used as the external input to wake up the chip from Light-sleep. Each pin can be individually configured to trigger wakeup on high or low level using the :cpp:func:`gpio_wakeup_enable` function. Then the :cpp:func:`esp_sleep_enable_gpio_wakeup` function should be called to enable this wakeup source.
+    There are two GPIO wakeup APIs available, each designed for different sleep scenarios:
 
-    Additionally, IOs that are powered by the VDD3P3_RTC power domain can be used to wake up the chip from Deep-sleep. The wakeup pin and wakeup trigger level can be configured by calling :cpp:func:`esp_deep_sleep_enable_gpio_wakeup`. The function will enable the Deep-sleep wakeup for the selected pin.
+    **1. :cpp:func:`esp_sleep_enable_gpio_wakeup` - For Light-sleep (GPIO module powered on)**
 
-    .. only:: SOC_PM_SUPPORT_TOP_PD
+        Any IO can be used as the external input to wake up the chip from Light-sleep when the GPIO module remains powered on. Each pin can be individually configured to trigger wakeup on high or low level using the :cpp:func:`gpio_wakeup_enable` function. Then the :cpp:func:`esp_sleep_enable_gpio_wakeup` function should be called to enable this wakeup source.
 
         .. note::
+            This API is **not available** when :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP` is enabled, because the GPIO module is powered down during sleep in this case. Use :cpp:func:`esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown` instead.
 
-            .. only::  SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP
+    **2. :cpp:func:`esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown` - For Deep-sleep and Light-sleep (peripheral powerdown)**
 
-                In Light-sleep mode, if you set Kconfig option :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`， you can use :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` directly for GPIO wakeup, because the digital IO power domain is being powered off, where the situation is the same as entering Deep-sleep.
+        IOs that are powered by the VDD3P3_RTC power domain can be used to wake up the chip from Deep-sleep or Light-sleep when the peripheral power domain is powered down. The wakeup pin and wakeup trigger level can be configured by calling :cpp:func:`esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown`. This function works for:
+
+        - Deep-sleep mode (always)
+        - Light-sleep mode when :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP` is enabled
+
+        .. note::
+            Only GPIOs powered by the VDD3P3_RTC power domain (RTC IOs) can be used with this API. The exact set of supported pins can be checked in the `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__ > Section IO Pins.
 
 .. only:: esp32h2
 

docs/en/migration-guides/release-6.x/6.0/system.rst

@@ -107,6 +107,67 @@ Update to:
         handle_timer_wakeup();
     }
 
+.. _gpio_wakeup_api_changes:
+
+GPIO Wakeup API Changes
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following APIs and types have been removed and replaced with new ones that support both Deep Sleep and Light Sleep (when peripheral power domain is powered down):
+
+**Removed APIs:**
+
+- :func:`esp_deep_sleep_enable_gpio_wakeup` - Use :func:`esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown` instead
+- :func:`gpio_deep_sleep_wakeup_enable` - Use :func:`gpio_wakeup_enable_on_hp_periph_powerdown_sleep` instead
+- :func:`gpio_deep_sleep_wakeup_disable` - Use :func:`gpio_wakeup_disable_on_hp_periph_powerdown_sleep` instead
+
+**Removed Types:**
+
+- :cpp:type:`esp_deepsleep_gpio_wake_up_mode_t` - Use :cpp:type:`esp_sleep_gpio_wake_up_mode_t` instead
+
+**Removed Macros:**
+
+- ``GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO()`` - Use ``GPIO_IS_HP_PERIPH_PD_WAKEUP_VALID_IO()`` instead
+
+**Migration Example:**
+
+Old code:
+
+.. code-block:: c
+
+    #include "esp_sleep.h"
+    #include "driver/gpio.h"
+
+    // Enable GPIO wakeup for deep sleep
+    esp_deep_sleep_enable_gpio_wakeup(BIT(GPIO_NUM_0), ESP_GPIO_WAKEUP_GPIO_LOW);
+
+    // Or using GPIO driver API
+    gpio_deep_sleep_wakeup_enable(GPIO_NUM_0, GPIO_INTR_LOW_LEVEL);
+
+    // Check if GPIO is valid for deep sleep wakeup
+    if (GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO(GPIO_NUM_0)) {
+        // ...
+    }
+
+New code:
+
+.. code-block:: c
+
+    #include "esp_sleep.h"
+    #include "driver/gpio.h"
+
+    // Enable GPIO wakeup for deep sleep or light sleep (when peripheral power domain is powered down)
+    esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown(BIT(GPIO_NUM_0), ESP_GPIO_WAKEUP_GPIO_LOW);
+
+    // Or using GPIO driver API
+    gpio_wakeup_enable_on_hp_periph_powerdown_sleep(GPIO_NUM_0, GPIO_INTR_LOW_LEVEL);
+
+    // Check if GPIO is valid for wakeup on peripheral powerdown sleep
+    if (GPIO_IS_HP_PERIPH_PD_WAKEUP_VALID_IO(GPIO_NUM_0)) {
+        // ...
+    }
+
+**Note:** The new APIs work for both Deep Sleep and Light Sleep modes when the peripheral power domain is powered down (``PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`` enabled in menuconfig).
+
 Bootloader
 ----------
 

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

@@ -313,7 +313,7 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒
 
                 在 Light-sleep 模式下，如果设置 Kconfig 选项 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`，为了继续使用 :cpp:func:`gpio_wakeup_enable` 用于 GPIO 唤醒， 需要先调用 :cpp:func:`rtc_gpio_init` 和 :cpp:func:`rtc_gpio_set_direction`，用于设置 RTC IO 为输入模式。
 
-                或者， 可以使用直接调用 :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` 用于 GPIO 唤醒，因为此时 digital IO 的电源域已经被关闭，这个情况类似于进入 Deep-sleep。
+                或者， 可以使用直接调用 :cpp:func:`esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown` 用于 GPIO 唤醒，因为此时 digital IO 的电源域已经被关闭。
 
             .. only::  not SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP
 
@@ -328,7 +328,10 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒
 
         除了 Light-sleep 模式下的 GPIO 唤醒之外，{IDF_TARGET_NAME} 还支持 Deep-sleep 模式下的 GPIO 唤醒。
 
-        该唤醒源由 :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` 函数实现，用户可以配置一个或多个 GPIO 管脚以及唤醒电平（高电平或低电平）。只有由 {IDF_TARGET_RTC_POWER_DOMAIN} 电源域供电的 GPIO 管脚才能用作 Deep-sleep GPIO 唤醒源。具体支持的管脚请参考 `datasheet <{IDF_TARGET_DATASHEET_CN_URL}>`__ > IO 管脚。
+        该唤醒源由 :cpp:func:`esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown` 函数实现，用户可以配置一个或多个 GPIO 管脚以及唤醒电平（高电平或低电平）。只有由 {IDF_TARGET_RTC_POWER_DOMAIN} 电源域供电的 GPIO 管脚才能用作 Deep-sleep GPIO 唤醒源。具体支持的管脚请参考 `datasheet <{IDF_TARGET_DATASHEET_CN_URL}>`__ > IO 管脚。
+
+        .. note::
+            该 API 同样适用于外设电源域掉电时的 Light-sleep 模式（参见 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`）。在这种情况下，应使用此 API 而不是 :cpp:func:`esp_sleep_enable_gpio_wakeup`，因为 GPIO 模块在睡眠期间会被断电。
 
         完整示例请参考 :example:`system/deep_sleep`。
 
@@ -337,17 +340,24 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒
     GPIO 唤醒
     ^^^^^^^^^^^
 
-    任何一个 IO 都可以用作外部输入管脚，将芯片从 Light-sleep 状态唤醒。调用 :cpp:func:`gpio_wakeup_enable` 函数可以将任意管脚单独配置为在高电平或低电平触发唤醒。此后，应调用 :cpp:func:`esp_sleep_enable_gpio_wakeup` 函数来启用此唤醒源。
+    有两种 GPIO 唤醒 API 可供使用，分别适用于不同的睡眠场景：
 
-    此外，可将由 VDD3P3_RTC 电源域供电的 IO 用于芯片的 Deep-sleep 唤醒。调用 :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` 函数可以配置相应的唤醒管脚和唤醒触发电平，该函数用于启用相应管脚的 Deep-sleep 唤醒功能。
+    **1. :cpp:func:`esp_sleep_enable_gpio_wakeup` - 适用于 Light-sleep（GPIO 模块保持上电）**
 
-    .. only:: SOC_PM_SUPPORT_TOP_PD
+        当 GPIO 模块在睡眠期间保持上电时，任何 IO 都可以用作外部输入管脚，将芯片从 Light-sleep 状态唤醒。调用 :cpp:func:`gpio_wakeup_enable` 函数可以将任意管脚单独配置为在高电平或低电平触发唤醒。此后，应调用 :cpp:func:`esp_sleep_enable_gpio_wakeup` 函数来启用此唤醒源。
 
         .. note::
+            当启用 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP` 时，此 API **不可用**，因为 GPIO 模块在睡眠期间会被断电。请使用 :cpp:func:`esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown` 替代。
 
-            .. only::  SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP
+    **2. :cpp:func:`esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown` - 适用于 Deep-sleep 和外设掉电的 Light-sleep**
 
-                在 Light-sleep 模式下，如果设置 Kconfig 选项 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`，可以使用直接调用 :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` 用于 GPIO 唤醒，因为此时 digital IO 的电源域会被断电，行为与进入 Deep-sleep 模式时相同。
+        可将由 VDD3P3_RTC 电源域供电的 IO 用于芯片的 Deep-sleep 唤醒，或在外设电源域掉电时的 Light-sleep 唤醒。调用 :cpp:func:`esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown` 函数可以配置相应的唤醒管脚和唤醒触发电平。此函数适用于：
+
+        - Deep-sleep 模式（始终可用）
+        - 启用 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP` 时的 Light-sleep 模式
+
+        .. note::
+            只有由 VDD3P3_RTC 电源域供电的 GPIO（RTC IO）可以与此 API 一起使用。具体支持的管脚请参考 `datasheet <{IDF_TARGET_DATASHEET_CN_URL}>`__ > IO 管脚。
 
 .. only:: esp32h2
 

docs/zh_CN/migration-guides/release-6.x/6.0/system.rst

@@ -107,6 +107,67 @@ Xtensa 特殊寄存器头文件已更新，使用新的命名约定。旧的 ``s
         handle_timer_wakeup();
     }
 
+.. _gpio_wakeup_api_changes:
+
+GPIO 唤醒 API 变更
+^^^^^^^^^^^^^^^^^^
+
+以下 API 和类型已被移除，并替换为支持 Deep Sleep 和 Light Sleep（当外设电源域掉电时）的新 API：
+
+**已移除的 API：**
+
+- :func:`esp_deep_sleep_enable_gpio_wakeup` - 请使用 :func:`esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown` 替代
+- :func:`gpio_deep_sleep_wakeup_enable` - 请使用 :func:`gpio_wakeup_enable_on_hp_periph_powerdown_sleep` 替代
+- :func:`gpio_deep_sleep_wakeup_disable` - 请使用 :func:`gpio_wakeup_disable_on_hp_periph_powerdown_sleep` 替代
+
+**已移除的类型：**
+
+- :cpp:type:`esp_deepsleep_gpio_wake_up_mode_t` - 请使用 :cpp:type:`esp_sleep_gpio_wake_up_mode_t` 替代
+
+**已移除的宏：**
+
+- ``GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO()`` - 请使用 ``GPIO_IS_HP_PERIPH_PD_WAKEUP_VALID_IO()`` 替代
+
+**迁移示例：**
+
+旧代码：
+
+.. code-block:: c
+
+    #include "esp_sleep.h"
+    #include "driver/gpio.h"
+
+    // 为深度睡眠启用 GPIO 唤醒
+    esp_deep_sleep_enable_gpio_wakeup(BIT(GPIO_NUM_0), ESP_GPIO_WAKEUP_GPIO_LOW);
+
+    // 或使用 GPIO 驱动 API
+    gpio_deep_sleep_wakeup_enable(GPIO_NUM_0, GPIO_INTR_LOW_LEVEL);
+
+    // 检查 GPIO 是否可用于深度睡眠唤醒
+    if (GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO(GPIO_NUM_0)) {
+        // ...
+    }
+
+新代码：
+
+.. code-block:: c
+
+    #include "esp_sleep.h"
+    #include "driver/gpio.h"
+
+    // 为深度睡眠或轻量睡眠（当外设电源域掉电时）启用 GPIO 唤醒
+    esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown(BIT(GPIO_NUM_0), ESP_GPIO_WAKEUP_GPIO_LOW);
+
+    // 或使用 GPIO 驱动 API
+    gpio_wakeup_enable_on_hp_periph_powerdown_sleep(GPIO_NUM_0, GPIO_INTR_LOW_LEVEL);
+
+    // 检查 GPIO 是否可用于外设电源域掉电睡眠唤醒
+    if (GPIO_IS_HP_PERIPH_PD_WAKEUP_VALID_IO(GPIO_NUM_0)) {
+        // ...
+    }
+
+**注意：** 新的 API 同时支持 Deep Sleep 和 Light Sleep 模式（当在 menuconfig 中启用 ``PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`` 时）。
+
 引导加载程序
 ------------
 

examples/system/deep_sleep/main/gpio_wakeup.c

@@ -25,7 +25,7 @@ void example_deep_sleep_register_gpio_wakeup(void)
     };
 
     ESP_ERROR_CHECK(gpio_config(&config));
-    ESP_ERROR_CHECK(esp_deep_sleep_enable_gpio_wakeup(BIT(DEFAULT_WAKEUP_PIN), DEFAULT_WAKEUP_LEVEL));
+    ESP_ERROR_CHECK(esp_sleep_enable_gpio_wakeup_on_hp_periph_powerdown(BIT(DEFAULT_WAKEUP_PIN), DEFAULT_WAKEUP_LEVEL));
 
     printf("Enabling GPIO wakeup on pins GPIO%d\n", DEFAULT_WAKEUP_PIN);
 }