fix(esp_driver_gpio): manage lp_io module clock by driver

Closes https://github.com/espressif/esp-idf/issues/13683

components/driver/gpio/gpio.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -23,6 +23,7 @@
 #include "hal/gpio_hal.h"
 #include "esp_rom_gpio.h"
 #include "esp_private/esp_gpio_reserve.h"
+#include "esp_private/io_mux.h"
 
 #if (SOC_RTCIO_PIN_COUNT > 0)
 #include "hal/rtc_io_hal.h"
@@ -632,6 +633,11 @@ esp_err_t gpio_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type)
     if ((intr_type == GPIO_INTR_LOW_LEVEL) || (intr_type == GPIO_INTR_HIGH_LEVEL)) {
 #if SOC_RTCIO_WAKE_SUPPORTED
         if (rtc_gpio_is_valid_gpio(gpio_num)) {
+#if SOC_LP_IO_CLOCK_IS_INDEPENDENT
+            // LP_IO Wake-up function does not depend on LP_IO Matrix, but uses its clock to
+            // sample the wake-up signal, we need to enable the LP_IO clock here.
+            io_mux_enable_lp_io_clock(gpio_num, true);
+#endif
             ret = rtc_gpio_wakeup_enable(gpio_num, intr_type);
         }
 #endif
@@ -657,6 +663,9 @@ esp_err_t gpio_wakeup_disable(gpio_num_t gpio_num)
 #if SOC_RTCIO_WAKE_SUPPORTED
     if (rtc_gpio_is_valid_gpio(gpio_num)) {
         ret = rtc_gpio_wakeup_disable(gpio_num);
+#if SOC_LP_IO_CLOCK_IS_INDEPENDENT
+        io_mux_enable_lp_io_clock(gpio_num, false);
+#endif
     }
 #endif
     portENTER_CRITICAL(&gpio_context.gpio_spinlock);
@@ -984,6 +993,9 @@ esp_err_t gpio_deep_sleep_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t int
         return ESP_ERR_INVALID_ARG;
     }
     portENTER_CRITICAL(&gpio_context.gpio_spinlock);
+#if SOC_LP_IO_CLOCK_IS_INDEPENDENT
+    io_mux_enable_lp_io_clock(gpio_num, true);
+#endif
     gpio_hal_deepsleep_wakeup_enable(gpio_context.gpio_hal, gpio_num, intr_type);
 #if CONFIG_ESP_SLEEP_GPIO_RESET_WORKAROUND || CONFIG_PM_SLP_DISABLE_GPIO
     gpio_hal_sleep_sel_dis(gpio_context.gpio_hal, gpio_num);
@@ -1002,6 +1014,9 @@ esp_err_t gpio_deep_sleep_wakeup_disable(gpio_num_t gpio_num)
     gpio_hal_deepsleep_wakeup_disable(gpio_context.gpio_hal, gpio_num);
 #if CONFIG_ESP_SLEEP_GPIO_RESET_WORKAROUND || CONFIG_PM_SLP_DISABLE_GPIO
     gpio_hal_sleep_sel_en(gpio_context.gpio_hal, gpio_num);
+#endif
+#if SOC_LP_IO_CLOCK_IS_INDEPENDENT
+    io_mux_enable_lp_io_clock(gpio_num, false);
 #endif
     portEXIT_CRITICAL(&gpio_context.gpio_spinlock);
     return ESP_OK;

components/driver/gpio/rtc_io.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2019-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2019-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -8,6 +8,8 @@
 #include "esp_log.h"
 #include "esp_err.h"
 #include "esp_check.h"
+#include "esp_private/periph_ctrl.h"
+#include "esp_private/io_mux.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/semphr.h"
 #include "freertos/timers.h"
@@ -45,6 +47,9 @@ esp_err_t rtc_gpio_init(gpio_num_t gpio_num)
 {
     ESP_RETURN_ON_FALSE(rtc_gpio_is_valid_gpio(gpio_num), ESP_ERR_INVALID_ARG, RTCIO_TAG, "RTCIO number error");
     RTCIO_ENTER_CRITICAL();
+#if SOC_LP_IO_CLOCK_IS_INDEPENDENT
+    io_mux_enable_lp_io_clock(gpio_num, true);
+#endif
     rtcio_hal_function_select(rtc_io_number_get(gpio_num), RTCIO_LL_FUNC_RTC);
     RTCIO_EXIT_CRITICAL();
 
@@ -57,6 +62,10 @@ esp_err_t rtc_gpio_deinit(gpio_num_t gpio_num)
     RTCIO_ENTER_CRITICAL();
     // Select Gpio as Digital Gpio
     rtcio_hal_function_select(rtc_io_number_get(gpio_num), RTCIO_LL_FUNC_DIGITAL);
+
+#if SOC_LP_IO_CLOCK_IS_INDEPENDENT
+    io_mux_enable_lp_io_clock(gpio_num, false);
+#endif
     RTCIO_EXIT_CRITICAL();
 
     return ESP_OK;

components/esp_hw_support/include/esp_private/io_mux.h

@@ -1,13 +1,17 @@
 /*
- * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 
 #pragma once
 
+#include <stdbool.h>
 #include "esp_err.h"
 #include "soc/clk_tree_defs.h"
+#include "soc/gpio_num.h"
+#include "soc/soc_caps.h"
+#include "soc/io_mux_reg.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -26,6 +30,20 @@ extern "C" {
  */
 esp_err_t io_mux_set_clock_source(soc_module_clk_t clk_src);
 
+#if SOC_LP_IO_CLOCK_IS_INDEPENDENT
+typedef struct {
+    uint8_t rtc_io_enabled_cnt[MAX_RTC_GPIO_NUM];
+    uint32_t rtc_io_using_mask;
+} rtc_io_status_t;
+
+/**
+ * Enable/Disable LP_IO peripheral clock.
+ * @param gpio_num GPIO number
+ * @param enable   true to enable the clock / false to disable the clock
+ */
+void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable);
+#endif
+
 #ifdef __cplusplus
 }
 #endif

components/esp_hw_support/sleep_modes.c

@@ -14,8 +14,10 @@
 #include "esp_sleep.h"
 #include "esp_private/esp_sleep_internal.h"
 #include "esp_private/esp_timer_private.h"
+#include "esp_private/rtc_clk.h"
 #include "esp_private/sleep_event.h"
 #include "esp_private/system_internal.h"
+#include "esp_private/io_mux.h"
 #include "esp_log.h"
 #include "esp_newlib.h"
 #include "esp_timer.h"
@@ -1606,6 +1608,9 @@ esp_err_t esp_sleep_enable_ext0_wakeup(gpio_num_t gpio_num, int level)
 static void ext0_wakeup_prepare(void)
 {
     int rtc_gpio_num = s_config.ext0_rtc_gpio_num;
+#if SOC_LP_IO_CLOCK_IS_INDEPENDENT
+    io_mux_enable_lp_io_clock(rtc_gpio_num, true);
+#endif
     rtcio_hal_ext0_set_wakeup_pin(rtc_gpio_num, s_config.ext0_trigger_level);
     rtcio_hal_function_select(rtc_gpio_num, RTCIO_LL_FUNC_RTC);
     rtcio_hal_input_enable(rtc_gpio_num);
@@ -1735,6 +1740,9 @@ static void ext1_wakeup_prepare(void)
         if ((rtc_gpio_mask & BIT(rtc_pin)) == 0) {
             continue;
         }
+#if SOC_LP_IO_CLOCK_IS_INDEPENDENT
+        io_mux_enable_lp_io_clock(rtc_pin, true);
+#endif
 #if SOC_RTCIO_INPUT_OUTPUT_SUPPORTED
         // Route pad to RTC
         rtcio_hal_function_select(rtc_pin, RTCIO_LL_FUNC_RTC);

components/ulp/lp_core/lp_core/include/ulp_lp_core_gpio.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -29,11 +29,16 @@ typedef enum {
 
 /**
  * @brief Initialize a rtcio pin
+ * @note If IO is used in LP application, `rtc_gpio_init` must be called at least once
+ *       for the using IO before loading LP core firmware in HP Code.
  *
  * @param lp_io_num The rtc io pin to initialize
  */
 static inline void ulp_lp_core_gpio_init(lp_io_num_t lp_io_num)
 {
+#if SOC_LP_IO_CLOCK_IS_INDEPENDENT
+    _rtcio_ll_enable_io_clock(true);
+#endif
     rtcio_ll_function_select(lp_io_num, RTCIO_LL_FUNC_RTC);
 }
 

components/ulp/test_apps/lp_core/main/test_lp_core.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -7,6 +7,9 @@
 #include <stdio.h>
 #include <inttypes.h>
 #include <sys/time.h>
+#include "soc/soc_caps.h"
+#include "soc/gpio_num.h"
+#include "esp_rom_caps.h"
 #include "lp_core_test_app.h"
 #include "lp_core_test_app_counter.h"
 #include "lp_core_test_app_set_timer_wakeup.h"
@@ -17,6 +20,7 @@
 #include "unity.h"
 #include "esp_sleep.h"
 #include "esp_timer.h"
+#include "driver/rtc_io.h"
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
 
@@ -301,6 +305,7 @@ TEST_CASE("LP core gpio tests", "[ulp]")
         .lp_timer_sleep_duration_us = LP_TIMER_TEST_SLEEP_DURATION_US,
     };
 
+    rtc_gpio_init(GPIO_NUM_0);
     load_and_start_lp_core_firmware(&cfg, lp_core_main_gpio_bin_start, lp_core_main_gpio_bin_end);
 
     while(!ulp_gpio_test_finished) {