Merge branch 'bugfix/lp_io_clock_control_v5.5' into 'release/v5.5'

fix(rtcio): RTC GPIO configuration should be written if LP IO clock exists (v5.5)

See merge request espressif/esp-idf!46601

components/esp_driver_gpio/src/gpio.c

@@ -454,9 +454,6 @@ esp_err_t gpio_config_as_analog(gpio_num_t gpio_num)
 #if SOC_RTCIO_INPUT_OUTPUT_SUPPORTED
     if (rtc_gpio_is_valid_gpio(gpio_num)) {
         rtc_gpio_deinit(gpio_num);
-        rtc_gpio_set_direction(gpio_num, RTC_GPIO_MODE_DISABLED);
-        rtc_gpio_pullup_dis(gpio_num);
-        rtc_gpio_pulldown_dis(gpio_num);
     }
 #endif
     return ESP_OK;

components/esp_driver_gpio/src/rtc_io.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2019-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2019-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -61,12 +61,19 @@ esp_err_t rtc_gpio_deinit(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();
-    // Select Gpio as Digital Gpio
+    if (io_mux_is_lp_io_in_use(gpio_num)) {
-    rtcio_hal_function_select(rtc_io_number_get(gpio_num), RTCIO_LL_FUNC_DIGITAL);
+        // 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
+#if SOC_RTCIO_INPUT_OUTPUT_SUPPORTED
-    io_mux_force_disable_lp_io_clock(gpio_num);
+        // Disable any configuration of the RTC IO that may affect the GPIO behavior
+        rtc_gpio_set_direction(gpio_num, RTC_GPIO_MODE_DISABLED);
+        rtc_gpio_pullup_dis(gpio_num);
+        rtc_gpio_pulldown_dis(gpio_num);
 #endif
+#if SOC_LP_IO_CLOCK_IS_INDEPENDENT
+        io_mux_force_disable_lp_io_clock(gpio_num);
+#endif
+    }
     RTCIO_EXIT_CRITICAL();
 
     return ESP_OK;

components/esp_hw_support/include/esp_private/io_mux.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -11,7 +11,6 @@
 #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" {
@@ -32,8 +31,8 @@ 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 + 1];
+    uint8_t rtc_io_enabled_cnt[SOC_RTCIO_PIN_COUNT];
-    uint32_t rtc_io_using_mask;
+    uint32_t rtc_io_using_mask : SOC_RTCIO_PIN_COUNT;
 } rtc_io_status_t;
 
 /**
@@ -45,12 +44,24 @@ typedef struct {
 void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable);
 
 /**
- * Force disable one LP_IO to clock dependency
+ * @brief Force disable one LP_IO to clock dependency
+ *
  * @param gpio_num GPIO number
  */
 void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num);
 #endif
 
+#if SOC_RTCIO_PIN_COUNT > 0
+/**
+ * @brief Check if the LP_IO is in use
+ *
+ * @param gpio_num GPIO number
+ *
+ * @return true if the LP_IO is in use, false otherwise
+ */
+bool io_mux_is_lp_io_in_use(gpio_num_t gpio_num);
+#endif
+
 #ifdef __cplusplus
 }
 #endif

components/esp_hw_support/port/esp32/io_mux.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -11,3 +11,11 @@ esp_err_t io_mux_set_clock_source(soc_module_clk_t clk_src)
     // IO MUX clock source is not selectable
     return ESP_OK;
 }
+
+bool io_mux_is_lp_io_in_use(gpio_num_t gpio_num)
+{
+    // ESP32 does not have SOC_LP_IO_CLOCK_IS_INDEPENDENT
+    // which means we don't need LP_IO clock management
+    // So we just always return true here
+    return true;
+}

components/esp_hw_support/port/esp32c5/io_mux.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -49,17 +49,18 @@ esp_err_t io_mux_set_clock_source(soc_module_clk_t clk_src)
 
 void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 {
-    assert(gpio_num != GPIO_NUM_NC);
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
     if (enable) {
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask |= (1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask |= (1ULL << rtc_io_num);
         }
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]++;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]++;
-    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] > 0)) {
+    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0)) {
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]--;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]--;
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
         }
     }
     RTCIO_RCC_ATOMIC() {
@@ -74,10 +75,11 @@ void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 
 void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
 {
-    assert(gpio_num != GPIO_NUM_NC);
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
-    s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] = 0;
+    s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] = 0;
-    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
     if (s_rtc_io_status.rtc_io_using_mask == 0) {
         RTCIO_RCC_ATOMIC() {
             rtcio_ll_enable_io_clock(false);
@@ -85,3 +87,10 @@ void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
     }
     portEXIT_CRITICAL(&s_io_mux_spinlock);
 }
+
+bool io_mux_is_lp_io_in_use(gpio_num_t gpio_num)
+{
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
+    return s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0;
+}

components/esp_hw_support/port/esp32c6/io_mux.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -48,17 +48,18 @@ esp_err_t io_mux_set_clock_source(soc_module_clk_t clk_src)
 
 void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 {
-    assert(gpio_num != GPIO_NUM_NC);
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
     if (enable) {
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask |= (1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask |= (1ULL << rtc_io_num);
         }
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]++;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]++;
-    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] > 0)) {
+    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0)) {
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]--;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]--;
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
         }
     }
     RTCIO_RCC_ATOMIC() {
@@ -73,10 +74,11 @@ void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 
 void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
 {
-    assert(gpio_num != GPIO_NUM_NC);
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
-    s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] = 0;
+    s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] = 0;
-    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
     if (s_rtc_io_status.rtc_io_using_mask == 0) {
         RTCIO_RCC_ATOMIC() {
             rtcio_ll_enable_io_clock(false);
@@ -84,3 +86,10 @@ void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
     }
     portEXIT_CRITICAL(&s_io_mux_spinlock);
 }
+
+bool io_mux_is_lp_io_in_use(gpio_num_t gpio_num)
+{
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
+    return s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0;
+}

components/esp_hw_support/port/esp32c61/io_mux.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -46,17 +46,18 @@ esp_err_t io_mux_set_clock_source(soc_module_clk_t clk_src)
 
 void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 {
-    assert(gpio_num != GPIO_NUM_NC);
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
     if (enable) {
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask |= (1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask |= (1ULL << rtc_io_num);
         }
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]++;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]++;
-    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] > 0)) {
+    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0)) {
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]--;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]--;
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
         }
     }
     RTCIO_RCC_ATOMIC() {
@@ -71,10 +72,11 @@ void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 
 void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
 {
-    assert(gpio_num != GPIO_NUM_NC);
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
-    s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] = 0;
+    s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] = 0;
-    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
     if (s_rtc_io_status.rtc_io_using_mask == 0) {
         RTCIO_RCC_ATOMIC() {
             rtcio_ll_enable_io_clock(false);
@@ -82,3 +84,10 @@ void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
     }
     portEXIT_CRITICAL(&s_io_mux_spinlock);
 }
+
+bool io_mux_is_lp_io_in_use(gpio_num_t gpio_num)
+{
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
+    return s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0;
+}

components/esp_hw_support/port/esp32h2/io_mux.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -43,17 +43,18 @@ esp_err_t io_mux_set_clock_source(soc_module_clk_t clk_src)
 
 void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 {
-    assert(gpio_num != GPIO_NUM_NC);
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
     if (enable) {
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask |= (1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask |= (1ULL << rtc_io_num);
         }
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]++;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]++;
-    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] > 0)) {
+    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0)) {
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]--;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]--;
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
         }
     }
     RTCIO_RCC_ATOMIC() {
@@ -68,10 +69,11 @@ void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 
 void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
 {
-    assert(gpio_num != GPIO_NUM_NC);
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
-    s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] = 0;
+    s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] = 0;
-    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
     if (s_rtc_io_status.rtc_io_using_mask == 0) {
         RTCIO_RCC_ATOMIC() {
             rtcio_ll_enable_io_clock(false);
@@ -79,3 +81,10 @@ void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
     }
     portEXIT_CRITICAL(&s_io_mux_spinlock);
 }
+
+bool io_mux_is_lp_io_in_use(gpio_num_t gpio_num)
+{
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
+    return s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0;
+}

components/esp_hw_support/port/esp32h21/io_mux.c

@@ -1,6 +1,6 @@
 
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -44,17 +44,18 @@ esp_err_t io_mux_set_clock_source(soc_module_clk_t clk_src)
 
 void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 {
-    assert(gpio_num != GPIO_NUM_NC);
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
     if (enable) {
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask |= (1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask |= (1ULL << rtc_io_num);
         }
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]++;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]++;
-    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] > 0)) {
+    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0)) {
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]--;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]--;
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
         }
     }
     RTCIO_RCC_ATOMIC() {
@@ -69,10 +70,11 @@ void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 
 void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
 {
-    assert(gpio_num != GPIO_NUM_NC);
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
-    s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] = 0;
+    s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] = 0;
-    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
     if (s_rtc_io_status.rtc_io_using_mask == 0) {
         RTCIO_RCC_ATOMIC() {
             rtcio_ll_enable_io_clock(false);
@@ -80,3 +82,10 @@ void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
     }
     portEXIT_CRITICAL(&s_io_mux_spinlock);
 }
+
+bool io_mux_is_lp_io_in_use(gpio_num_t gpio_num)
+{
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
+    return s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0;
+}

components/esp_hw_support/port/esp32p4/io_mux.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -53,17 +53,18 @@ esp_err_t io_mux_set_clock_source(soc_module_clk_t clk_src)
 
 void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 {
-    assert((gpio_num != GPIO_NUM_NC) && (gpio_num <= MAX_RTC_GPIO_NUM) && "RTCIO number error");
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
     if (enable) {
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask |= (1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask |= (1ULL << rtc_io_num);
         }
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]++;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]++;
-    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] > 0)) {
+    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0)) {
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]--;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]--;
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
         }
     }
     RTCIO_RCC_ATOMIC() {
@@ -78,10 +79,11 @@ void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 
 void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
 {
-    assert((gpio_num != GPIO_NUM_NC) && (gpio_num <= MAX_RTC_GPIO_NUM) && "RTCIO number error");
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
-    s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] = 0;
+    s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] = 0;
-    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
     if (s_rtc_io_status.rtc_io_using_mask == 0) {
         RTCIO_RCC_ATOMIC() {
             rtcio_ll_enable_io_clock(false);
@@ -89,3 +91,10 @@ void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
     }
     portEXIT_CRITICAL(&s_io_mux_spinlock);
 }
+
+bool io_mux_is_lp_io_in_use(gpio_num_t gpio_num)
+{
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
+    return s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0;
+}

components/esp_hw_support/port/esp32s2/io_mux.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -31,17 +31,18 @@ static rtc_io_status_t s_rtc_io_status = {
 
 void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 {
-    assert(gpio_num != GPIO_NUM_NC);
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
     if (enable) {
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask |= (1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask |= (1ULL << rtc_io_num);
         }
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]++;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]++;
-    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] > 0)) {
+    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0)) {
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]--;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]--;
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
         }
     }
     RTCIO_RCC_ATOMIC() {
@@ -56,10 +57,11 @@ void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 
 void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
 {
-    assert(gpio_num != GPIO_NUM_NC);
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
-    s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] = 0;
+    s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] = 0;
-    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
     if (s_rtc_io_status.rtc_io_using_mask == 0) {
         RTCIO_RCC_ATOMIC() {
             rtcio_ll_enable_io_clock(false);
@@ -67,3 +69,10 @@ void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
     }
     portEXIT_CRITICAL(&s_io_mux_spinlock);
 }
+
+bool io_mux_is_lp_io_in_use(gpio_num_t gpio_num)
+{
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
+    return s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0;
+}

components/esp_hw_support/port/esp32s3/io_mux.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2022-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2022-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -31,17 +31,18 @@ static rtc_io_status_t s_rtc_io_status = {
 
 void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 {
-    assert(gpio_num != GPIO_NUM_NC);
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
     if (enable) {
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask |= (1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask |= (1ULL << rtc_io_num);
         }
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]++;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]++;
-    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] > 0)) {
+    } else if (!enable && (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0)) {
-        s_rtc_io_status.rtc_io_enabled_cnt[gpio_num]--;
+        s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num]--;
-        if (s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] == 0) {
+        if (s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] == 0) {
-            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+            s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
         }
     }
     RTCIO_RCC_ATOMIC() {
@@ -56,10 +57,11 @@ void io_mux_enable_lp_io_clock(gpio_num_t gpio_num, bool enable)
 
 void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
 {
-    assert(gpio_num != GPIO_NUM_NC);
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
     portENTER_CRITICAL(&s_io_mux_spinlock);
-    s_rtc_io_status.rtc_io_enabled_cnt[gpio_num] = 0;
+    s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] = 0;
-    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << gpio_num);
+    s_rtc_io_status.rtc_io_using_mask &= ~(1ULL << rtc_io_num);
     if (s_rtc_io_status.rtc_io_using_mask == 0) {
         RTCIO_RCC_ATOMIC() {
             rtcio_ll_enable_io_clock(false);
@@ -67,3 +69,10 @@ void io_mux_force_disable_lp_io_clock(gpio_num_t gpio_num)
     }
     portEXIT_CRITICAL(&s_io_mux_spinlock);
 }
+
+bool io_mux_is_lp_io_in_use(gpio_num_t gpio_num)
+{
+    uint32_t rtc_io_num = gpio_num - RTCIO_LL_GPIO_NUM_OFFSET;
+    assert(rtc_io_num < SOC_RTCIO_PIN_COUNT);
+    return s_rtc_io_status.rtc_io_enabled_cnt[rtc_io_num] > 0;
+}

components/hal/esp32c5/include/hal/rtc_io_ll.h

@@ -31,6 +31,8 @@ extern "C" {
 
 #define RTCIO_LL_PIN_FUNC       1
 
+#define RTCIO_LL_GPIO_NUM_OFFSET    0 // rtcio 0-6 correspond to gpio 0-6
+
 typedef enum {
     RTCIO_LL_FUNC_RTC = 0x0,         /*!< The pin controlled by RTC module. */
     RTCIO_LL_FUNC_DIGITAL = 0x1,     /*!< The pin controlled by DIGITAL module. */

components/hal/esp32c6/include/hal/rtc_io_ll.h

@@ -30,6 +30,8 @@ extern "C" {
 
 #define RTCIO_LL_PIN_FUNC       0
 
+#define RTCIO_LL_GPIO_NUM_OFFSET    0 // rtcio 0-7 correspond to gpio 0-7
+
 typedef enum {
     RTCIO_LL_FUNC_RTC = 0x0,         /*!< The pin controlled by RTC module. */
     RTCIO_LL_FUNC_DIGITAL = 0x1,     /*!< The pin controlled by DIGITAL module. */

components/hal/esp32c61/include/hal/rtc_io_ll.h

@@ -31,6 +31,8 @@ extern "C" {
 
 #define RTCIO_LL_PIN_FUNC       1
 
+#define RTCIO_LL_GPIO_NUM_OFFSET    0 // rtcio 0-6 correspond to gpio 0-6
+
 typedef enum {
     RTCIO_LL_FUNC_RTC = 0x0,         /*!< The pin controlled by RTC module. */
     RTCIO_LL_FUNC_DIGITAL = 0x1,     /*!< The pin controlled by DIGITAL module. */

components/hal/esp32p4/include/hal/rtc_io_ll.h

@@ -31,6 +31,8 @@ extern "C" {
 
 #define RTCIO_LL_PIN_FUNC       1 // LP_GPIO function
 
+#define RTCIO_LL_GPIO_NUM_OFFSET    0 // rtcio 0-15 correspond to gpio 0-15
+
 typedef enum {
     RTCIO_LL_FUNC_RTC = 0x0,         /*!< The pin controlled by RTC module. */
     RTCIO_LL_FUNC_DIGITAL = 0x1,     /*!< The pin controlled by DIGITAL module. */

components/hal/esp32s2/include/hal/rtc_io_ll.h

@@ -21,7 +21,9 @@
 #include "soc/rtc_periph.h"
 #include "soc/sens_struct.h"
 
-#define RTCIO_LL_PIN_FUNC     0
+#define RTCIO_LL_PIN_FUNC           0
+
+#define RTCIO_LL_GPIO_NUM_OFFSET    0 // rtcio 0-21 correspond to gpio 0-21
 
 #ifdef __cplusplus
 extern "C" {

components/hal/esp32s3/include/hal/rtc_io_ll.h

@@ -23,6 +23,7 @@
 #include "soc/usb_serial_jtag_reg.h"
 #include "soc/usb_serial_jtag_struct.h"
 #include "soc/sens_struct.h"
+#include "soc/rtc_cntl_reg.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -30,6 +31,8 @@ extern "C" {
 
 #define RTCIO_LL_PIN_FUNC     0
 
+#define RTCIO_LL_GPIO_NUM_OFFSET    0 // rtcio 0-21 correspond to gpio 0-21
+
 typedef enum {
     RTCIO_LL_FUNC_RTC = 0x0,         /*!< The pin controlled by RTC module. */
     RTCIO_LL_FUNC_DIGITAL = 0x1,     /*!< The pin controlled by DIGITAL module. */

components/soc/esp32c2/register/soc/io_mux_reg.h

@@ -131,7 +131,6 @@
 
 #define EXT_OSC_SLOW_GPIO_NUM        0
 
-#define MAX_RTC_GPIO_NUM              5
 #define MAX_PAD_GPIO_NUM             20
 #define MAX_GPIO_NUM                 24
 #define DIG_IO_HOLD_BIT_SHIFT         0

components/soc/esp32c3/register/soc/io_mux_reg.h

@@ -140,7 +140,6 @@
 #define USB_INT_PHY0_DM_GPIO_NUM   18
 #define USB_INT_PHY0_DP_GPIO_NUM   19
 
-#define MAX_RTC_GPIO_NUM 5
 #define MAX_PAD_GPIO_NUM 21
 #define MAX_GPIO_NUM    25
 

components/soc/esp32c5/register/soc/io_mux_reg.h

@@ -143,7 +143,6 @@ extern "C" {
 
 #define EXT_OSC_SLOW_GPIO_NUM        0
 
-#define MAX_RTC_GPIO_NUM              6
 #define MAX_PAD_GPIO_NUM             28
 #define MAX_GPIO_NUM                 32
 #define DIG_IO_HOLD_BIT_SHIFT        32

components/soc/esp32c6/register/soc/io_mux_reg.h

@@ -148,7 +148,6 @@
 
 #define EXT_OSC_SLOW_GPIO_NUM        0
 
-#define MAX_RTC_GPIO_NUM              7
 #define MAX_PAD_GPIO_NUM             30
 #define MAX_GPIO_NUM                 34
 #define DIG_IO_HOLD_BIT_SHIFT        32

components/soc/esp32c61/register/soc/io_mux_reg.h

@@ -111,7 +111,6 @@ extern "C" {
 
 #define EXT_OSC_SLOW_GPIO_NUM        0
 
-#define MAX_RTC_GPIO_NUM              6
 #define MAX_PAD_GPIO_NUM             29
 #define MAX_GPIO_NUM                 33
 

components/soc/esp32h2/register/soc/io_mux_reg.h

@@ -160,7 +160,6 @@
 
 #define EXT_OSC_SLOW_GPIO_NUM        13
 
-#define MAX_RTC_GPIO_NUM             14            // GPIO7~14 are the pads with LP function
 #define MAX_PAD_GPIO_NUM             27
 #define MAX_GPIO_NUM                 31
 

components/soc/esp32h21/register/soc/io_mux_reg.h

@@ -147,7 +147,6 @@ extern "C" {
 #define EXT_OSC_SLOW_GPIO_NUM        6
 
 
-#define MAX_RTC_GPIO_NUM             11             // GPIO5~11 are the pads with LP function
 #define MAX_PAD_GPIO_NUM             25
 #define MAX_GPIO_NUM                 29
 

components/soc/esp32h4/register/soc/io_mux_reg.h

@@ -154,7 +154,7 @@ extern "C" {
 #define GPIO_PAD_SET_DRV(num, drv) PIN_SET_DRV(IOMUX_REG_GPIO##num, drv)
 
 #define EXT_OSC_SLOW_GPIO_NUM         0
-#define MAX_RTC_GPIO_NUM              5
+
 #define MAX_PAD_GPIO_NUM             39
 #define MAX_GPIO_NUM                 43
 

components/soc/esp32p4/register/hw_ver1/soc/io_mux_reg.h

@@ -194,7 +194,6 @@
 
 #define EXT_OSC_SLOW_GPIO_NUM        0 // XTAL_32K_N
 
-#define MAX_RTC_GPIO_NUM             15
 #define MAX_PAD_GPIO_NUM             54
 #define MAX_GPIO_NUM                 56
 

components/soc/esp32p4/register/hw_ver3/soc/io_mux_reg.h

@@ -192,7 +192,6 @@
 #define USB_OTG_INT_PHY_DM_GPIO_NUM     USB_INT_PHY1_DM_GPIO_NUM
 #define USB_OTG_INT_PHY_DP_GPIO_NUM     USB_INT_PHY1_DP_GPIO_NUM
 
-#define MAX_RTC_GPIO_NUM             15
 #define MAX_PAD_GPIO_NUM             54
 #define MAX_GPIO_NUM                 56
 

components/soc/esp32s2/register/soc/io_mux_reg.h

@@ -156,7 +156,6 @@
 #define SPI_D7_GPIO_NUM  36
 #define SPI_DQS_GPIO_NUM 37
 
-#define MAX_RTC_GPIO_NUM 21
 #define MAX_PAD_GPIO_NUM 46
 #define MAX_GPIO_NUM    53
 

components/soc/esp32s3/register/soc/io_mux_reg.h

@@ -166,7 +166,6 @@
 #define XTAL32K_P_GPIO_NUM 15
 #define XTAL32K_N_GPIO_NUM 16
 
-#define MAX_RTC_GPIO_NUM 21
 #define MAX_PAD_GPIO_NUM 48
 #define MAX_GPIO_NUM    53