From 78b3fca2b48b7df54344447972365c0cd3a67f50 Mon Sep 17 00:00:00 2001 From: wuzhenghui Date: Thu, 15 May 2025 17:05:45 +0800 Subject: [PATCH] change(esp_driver_gpio): deprecate gpio_deep_sleep_wakeup_enable/disable API rename gpio_deep_sleep_wakeup_enable to gpio_wakeup_enable_on_hp_periph_powerdown_sleep rename gpio_deep_sleep_wakeup_disable to gpio_wakeup_disable_on_hp_periph_powerdown_sleep rename GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO to GPIO_IS_HP_PERIPH_PD_WAKEUP_VALID_IO --- .../esp_driver_gpio/include/driver/gpio.h | 12 +++--- components/esp_driver_gpio/src/gpio.c | 10 ++--- components/esp_hw_support/sleep_modes.c | 8 ++-- .../wakeup_tests/main/src/io_wakeup_cmd.c | 2 +- .../release-6.x/6.0/peripherals.rst | 42 +++++++++++++++++++ .../release-6.x/6.0/peripherals.rst | 42 +++++++++++++++++++ 6 files changed, 100 insertions(+), 16 deletions(-) diff --git a/components/esp_driver_gpio/include/driver/gpio.h b/components/esp_driver_gpio/include/driver/gpio.h index 35c5f6843d3..13fbe124079 100644 --- a/components/esp_driver_gpio/include/driver/gpio.h +++ b/components/esp_driver_gpio/include/driver/gpio.h @@ -567,11 +567,11 @@ esp_err_t gpio_sleep_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull); #if SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP -#define GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO(gpio_num) ((gpio_num >= 0) && \ - (((1ULL << (gpio_num)) & SOC_GPIO_DEEP_SLEEP_WAKE_VALID_GPIO_MASK) != 0)) +#define GPIO_IS_HP_PERIPH_PD_WAKEUP_VALID_IO(gpio_num) ((gpio_num >= 0) && \ + (((1ULL << (gpio_num)) & SOC_GPIO_HP_PERIPH_PD_SLEEP_WAKEABLE_MASK) != 0)) /** - * @brief Enable GPIO deep-sleep wake-up function. + * @brief Enable GPIO wake-up function on peripheral powerdowned sleep (including deepsleep and peripheral powerdowned lightsleep). * * @param gpio_num GPIO number. * @@ -583,10 +583,10 @@ esp_err_t gpio_sleep_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull); * - ESP_OK Success * - ESP_ERR_INVALID_ARG Parameter error */ -esp_err_t gpio_deep_sleep_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type); +esp_err_t gpio_wakeup_enable_on_hp_periph_powerdown_sleep(gpio_num_t gpio_num, gpio_int_type_t intr_type); /** - * @brief Disable GPIO deep-sleep wake-up function. + * @brief Disable GPIO peripheral powerdowned sleep (including deepsleep and peripheral powerdowned lightsleep) wake-up function. * * @param gpio_num GPIO number * @@ -594,7 +594,7 @@ esp_err_t gpio_deep_sleep_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t int * - ESP_OK Success * - ESP_ERR_INVALID_ARG Parameter error */ -esp_err_t gpio_deep_sleep_wakeup_disable(gpio_num_t gpio_num); +esp_err_t gpio_wakeup_disable_on_hp_periph_powerdown_sleep(gpio_num_t gpio_num); #endif //SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP diff --git a/components/esp_driver_gpio/src/gpio.c b/components/esp_driver_gpio/src/gpio.c index 3c7f4558721..c1ced24ac9d 100644 --- a/components/esp_driver_gpio/src/gpio.c +++ b/components/esp_driver_gpio/src/gpio.c @@ -1018,9 +1018,9 @@ esp_err_t gpio_sleep_sel_dis(gpio_num_t gpio_num) } #if SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP && SOC_DEEP_SLEEP_SUPPORTED -esp_err_t gpio_deep_sleep_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type) +esp_err_t gpio_wakeup_enable_on_hp_periph_powerdown_sleep(gpio_num_t gpio_num, gpio_int_type_t intr_type) { - if (!GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO(gpio_num)) { + if (!GPIO_IS_HP_PERIPH_PD_WAKEUP_VALID_IO(gpio_num)) { ESP_LOGE(GPIO_TAG, "GPIO %d does not support deep sleep wakeup", gpio_num); return ESP_ERR_INVALID_ARG; } @@ -1040,9 +1040,9 @@ esp_err_t gpio_deep_sleep_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t int return ESP_OK; } -esp_err_t gpio_deep_sleep_wakeup_disable(gpio_num_t gpio_num) +esp_err_t gpio_wakeup_disable_on_hp_periph_powerdown_sleep(gpio_num_t gpio_num) { - if (!GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO(gpio_num)) { + if (!GPIO_IS_HP_PERIPH_PD_WAKEUP_VALID_IO(gpio_num)) { ESP_LOGE(GPIO_TAG, "GPIO %d does not support deep sleep wakeup", gpio_num); return ESP_ERR_INVALID_ARG; } @@ -1057,7 +1057,7 @@ esp_err_t gpio_deep_sleep_wakeup_disable(gpio_num_t gpio_num) portEXIT_CRITICAL(&gpio_context.gpio_spinlock); return ESP_OK; } -#endif // SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP && SOC_DEEP_SLEEP_SUPPORTED +#endif // SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP esp_err_t gpio_get_io_config(gpio_num_t gpio_num, gpio_io_config_t *out_io_config) { diff --git a/components/esp_hw_support/sleep_modes.c b/components/esp_hw_support/sleep_modes.c index 233d6f1c7b0..9699ec022be 100644 --- a/components/esp_hw_support/sleep_modes.c +++ b/components/esp_hw_support/sleep_modes.c @@ -362,7 +362,7 @@ static void touch_wakeup_prepare(void); static void vbat_under_volt_wakeup_prepare(void); #endif #if SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP && SOC_DEEP_SLEEP_SUPPORTED -static void gpio_deep_sleep_wakeup_prepare(void); +static void esp_sleep_gpio_wakeup_prepare_on_hp_periph_powerdown(void); #endif #if ESP_ROM_SUPPORT_DEEP_SLEEP_WAKEUP_STUB && SOC_DEEP_SLEEP_SUPPORTED @@ -995,7 +995,7 @@ static esp_err_t SLEEP_FN_ATTR esp_sleep_start(uint32_t sleep_flags, uint32_t cl #if SOC_GPIO_SUPPORT_HP_PERIPH_PD_SLEEP_WAKEUP && SOC_DEEP_SLEEP_SUPPORTED if (deep_sleep && (s_config.wakeup_triggers & RTC_GPIO_TRIG_EN)) { - gpio_deep_sleep_wakeup_prepare(); + esp_sleep_gpio_wakeup_prepare_on_hp_periph_powerdown(); } #endif @@ -2129,7 +2129,7 @@ uint64_t esp_sleep_get_gpio_wakeup_status(void) return rtc_hal_gpio_get_wakeup_status(); } -static void gpio_deep_sleep_wakeup_prepare(void) +static void esp_sleep_gpio_wakeup_prepare_on_hp_periph_powerdown(void) { uint32_t valid_wake_io_mask = SOC_GPIO_HP_PERIPH_PD_SLEEP_WAKEABLE_MASK; for (gpio_num_t gpio_idx = __builtin_ctz(valid_wake_io_mask); valid_wake_io_mask >> gpio_idx; gpio_idx++) { @@ -2179,7 +2179,7 @@ esp_err_t esp_deep_sleep_enable_gpio_wakeup(uint64_t gpio_pin_mask, esp_deepslee if ((gpio_pin_mask & BIT64(gpio_idx)) == 0) { continue; } - err = gpio_deep_sleep_wakeup_enable(gpio_idx, intr_type); + err = gpio_wakeup_enable_on_hp_periph_powerdown_sleep(gpio_idx, intr_type); s_config.gpio_wakeup_mask |= BIT(gpio_idx); if (mode == ESP_GPIO_WAKEUP_GPIO_HIGH) { diff --git a/components/esp_hw_support/test_apps/wakeup_tests/main/src/io_wakeup_cmd.c b/components/esp_hw_support/test_apps/wakeup_tests/main/src/io_wakeup_cmd.c index b453c8e0205..2b7d0a4a89a 100644 --- a/components/esp_hw_support/test_apps/wakeup_tests/main/src/io_wakeup_cmd.c +++ b/components/esp_hw_support/test_apps/wakeup_tests/main/src/io_wakeup_cmd.c @@ -177,7 +177,7 @@ static int process_rtcio_wakeup(int argc, char **argv) ESP_LOGI(TAG, "io_wakeup_level = %d\n", io_wakeup_level); if (rtcio_wakeup_args.disable->count) { - ESP_ERROR_CHECK(gpio_deep_sleep_wakeup_disable(io_wakeup_num)); + ESP_ERROR_CHECK(gpio_wakeup_disable_on_hp_periph_powerdown_sleep(io_wakeup_num)); } else { gpio_config_t config = { .pin_bit_mask = BIT64(io_wakeup_num), diff --git a/docs/en/migration-guides/release-6.x/6.0/peripherals.rst b/docs/en/migration-guides/release-6.x/6.0/peripherals.rst index a79972d8d1c..4b1a2932229 100644 --- a/docs/en/migration-guides/release-6.x/6.0/peripherals.rst +++ b/docs/en/migration-guides/release-6.x/6.0/peripherals.rst @@ -124,6 +124,48 @@ GPIO - Added the :cpp:type:`esp_err_t` return type to :func:`gpio_uninstall_isr_service`. +GPIO Deep Sleep Wakeup APIs Removed +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following GPIO driver APIs have been removed: + +- :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 + +The deprecated macro ``GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO()`` has been removed. Use ``GPIO_IS_HP_PERIPH_PD_WAKEUP_VALID_IO()`` instead. + +**Migration Example:** + +Old code: + +.. code-block:: c + + #include "driver/gpio.h" + + // Enable GPIO wakeup + gpio_deep_sleep_wakeup_enable(GPIO_NUM_0, GPIO_INTR_LOW_LEVEL); + + // Check validity + if (GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO(GPIO_NUM_0)) { + // ... + } + +New code: + +.. code-block:: c + + #include "driver/gpio.h" + + // Enable GPIO wakeup (works for both deep sleep and light sleep with peripheral powerdown) + gpio_wakeup_enable_on_hp_periph_powerdown_sleep(GPIO_NUM_0, GPIO_INTR_LOW_LEVEL); + + // Check validity + if (GPIO_IS_HP_PERIPH_PD_WAKEUP_VALID_IO(GPIO_NUM_0)) { + // ... + } + +For more details, see the :ref:`GPIO Wakeup API Changes ` section in the System migration guide. + LEDC ---- diff --git a/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst b/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst index c3f0c846719..9bd0b538fc8 100644 --- a/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst +++ b/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst @@ -124,6 +124,48 @@ GPIO - 为 :func:`gpio_uninstall_isr_service` 添加了 :cpp:type:`esp_err_t` 返回类型。 +GPIO 深度睡眠唤醒 API 已移除 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +以下 GPIO 驱动 API 已被移除： + +- :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` 替代 + +已弃用的宏 ``GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO()`` 已被移除。请使用 ``GPIO_IS_HP_PERIPH_PD_WAKEUP_VALID_IO()`` 替代。 + +**迁移示例：** + +旧代码： + +.. code-block:: c + + #include "driver/gpio.h" + + // 启用 GPIO 唤醒 + gpio_deep_sleep_wakeup_enable(GPIO_NUM_0, GPIO_INTR_LOW_LEVEL); + + // 检查有效性 + if (GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO(GPIO_NUM_0)) { + // ... + } + +新代码： + +.. code-block:: c + + #include "driver/gpio.h" + + // 启用 GPIO 唤醒（同时支持深度睡眠和外设电源域掉电时的 Light Sleep） + 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)) { + // ... + } + +更多详细信息，请参阅系统迁移指南中的 :ref:`GPIO 唤醒 API 变更 ` 部分。 + LEDC ----