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
2026-04-27 19:13:21 +00:00 · 2026-01-19 21:55:41 +08:00
parent e80eb6c5c8
commit 4c996ca231
8 changed files with 170 additions and 28 deletions
@@ -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

@@ -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`` 时）。
+
 引导加载程序
 ------------