refactor(esp_hw_support): add hal layer for clock output feature

components/esp_hw_support/esp_clock_output.c

@@ -11,8 +11,9 @@
 #include "esp_clock_output.h"
 #include "esp_check.h"
 #include "esp_rom_gpio.h"
-#include "clkout_channel.h"
+#include "soc/clkout_channel.h"
 #include "hal/gpio_hal.h"
+#include "hal/clk_tree_hal.h"
 #include "hal/clk_tree_ll.h"
 #include "soc/soc_caps.h"
 #include "soc/io_mux_reg.h"
@@ -93,7 +94,7 @@ static clkout_channel_handle_t* clkout_channel_alloc(soc_clkout_sig_id_t clk_sig
 #if SOC_CLOCKOUT_HAS_SOURCE_GATE
             clk_ll_enable_clkout_source(clk_sig, true);
 #endif
-            gpio_ll_set_pin_ctrl(clk_sig, CLKOUT_CHANNEL_MASK(allocated_channel->channel_id), CLKOUT_CHANNEL_SHIFT(allocated_channel->channel_id));
+            clk_hal_clock_output_setup(clk_sig, allocated_channel->channel_id);
             portEXIT_CRITICAL(&s_clkout_lock);
         }
         portEXIT_CRITICAL(&allocated_channel->clkout_channel_lock);
@@ -150,7 +151,7 @@ static void clkout_channel_free(clkout_channel_handle_t *channel_hdl)
 #if SOC_CLOCKOUT_HAS_SOURCE_GATE
         clk_ll_enable_clkout_source(channel_hdl->mapped_clock, false);
 #endif
-        gpio_ll_set_pin_ctrl(0, CLKOUT_CHANNEL_MASK(channel_hdl->channel_id), CLKOUT_CHANNEL_SHIFT(channel_hdl->channel_id));
+        clk_hal_clock_output_teardown(channel_hdl->channel_id);
         portEXIT_CRITICAL(&s_clkout_lock);
         channel_hdl->mapped_clock = CLKOUT_SIG_INVALID;
         channel_hdl->is_mapped = false;
@@ -187,7 +188,11 @@ static void clkout_mapping_free(esp_clock_output_mapping_t *mapping_hdl)
 esp_err_t esp_clock_output_start(soc_clkout_sig_id_t clk_sig, gpio_num_t gpio_num, esp_clock_output_mapping_handle_t *clkout_mapping_ret_hdl)
 {
     ESP_RETURN_ON_FALSE((clkout_mapping_ret_hdl != NULL), ESP_ERR_INVALID_ARG, TAG, "Clock out mapping handle passed in is invalid");
+#if SOC_GPIO_CLOCKOUT_BY_GPIO_MATRIX
+    ESP_RETURN_ON_FALSE(GPIO_IS_VALID_GPIO(gpio_num), ESP_ERR_INVALID_ARG, TAG, "%s", "Output GPIO number error");
+#else
     ESP_RETURN_ON_FALSE(IS_VALID_CLKOUT_IO(gpio_num), ESP_ERR_INVALID_ARG, TAG, "%s", "Output GPIO number error");
+#endif
 
     esp_clock_output_mapping_t *hdl;
     SLIST_FOREACH(hdl, &s_mapping_list, next) {

components/hal/esp32/clk_tree_hal.c

@@ -4,9 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+#include "soc/clkout_channel.h"
+#include "hal/assert.h"
 #include "hal/clk_tree_hal.h"
 #include "hal/clk_tree_ll.h"
-#include "hal/assert.h"
+#include "hal/gpio_ll.h"
 #include "hal/log.h"
 
 static const char *CLK_HAL_TAG = "clk_hal";
@@ -106,3 +108,13 @@ uint32_t clk_hal_apll_get_freq_hz(void)
     uint32_t apll_freq_hz = (uint32_t)((xtal_freq_hz * numerator) / denominator);
     return apll_freq_hz;
 }
+
+void clk_hal_clock_output_setup(soc_clkout_sig_id_t clk_sig, uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(clk_sig, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}
+
+void clk_hal_clock_output_teardown(uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(0, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}

components/hal/esp32c2/clk_tree_hal.c

@@ -4,10 +4,12 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+#include "sdkconfig.h"
+#include "soc/clkout_channel.h"
+#include "hal/assert.h"
 #include "hal/clk_tree_hal.h"
 #include "hal/clk_tree_ll.h"
-#include "sdkconfig.h"
-#include "hal/assert.h"
+#include "hal/gpio_ll.h"
 #include "hal/log.h"
 
 static const char *CLK_HAL_TAG = "clk_hal";
@@ -81,3 +83,13 @@ uint32_t clk_hal_xtal_get_freq_mhz(void)
     }
     return freq;
 }
+
+void clk_hal_clock_output_setup(soc_clkout_sig_id_t clk_sig, uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(clk_sig, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}
+
+void clk_hal_clock_output_teardown(uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(0, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}

components/hal/esp32c3/clk_tree_hal.c

@@ -4,9 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+#include "soc/clkout_channel.h"
+#include "hal/assert.h"
 #include "hal/clk_tree_hal.h"
 #include "hal/clk_tree_ll.h"
-#include "hal/assert.h"
+#include "hal/gpio_ll.h"
 #include "hal/log.h"
 
 static const char *CLK_HAL_TAG = "clk_hal";
@@ -80,3 +82,13 @@ uint32_t clk_hal_xtal_get_freq_mhz(void)
     }
     return freq;
 }
+
+void clk_hal_clock_output_setup(soc_clkout_sig_id_t clk_sig, uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(clk_sig, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}
+
+void clk_hal_clock_output_teardown(uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(0, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}

components/hal/esp32c5/clk_tree_hal.c

@@ -4,10 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-#include "sdkconfig.h"  // TODO: IDF-9197
+#include "soc/clkout_channel.h"
+#include "hal/assert.h"
 #include "hal/clk_tree_hal.h"
 #include "hal/clk_tree_ll.h"
-#include "hal/assert.h"
+#include "hal/gpio_ll.h"
 #include "hal/log.h"
 
 static const char *CLK_HAL_TAG = "clk_hal";
@@ -91,3 +92,13 @@ uint32_t clk_hal_xtal_get_freq_mhz(void)
     }
     return freq;
 }
+
+void clk_hal_clock_output_setup(soc_clkout_sig_id_t clk_sig, uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(clk_sig, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}
+
+void clk_hal_clock_output_teardown(uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(0, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}

components/hal/esp32c6/clk_tree_hal.c

@@ -4,9 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+#include "soc/clkout_channel.h"
+#include "hal/assert.h"
 #include "hal/clk_tree_hal.h"
 #include "hal/clk_tree_ll.h"
-#include "hal/assert.h"
+#include "hal/gpio_ll.h"
 #include "hal/log.h"
 
 static const char *CLK_HAL_TAG = "clk_hal";
@@ -73,3 +75,13 @@ uint32_t clk_hal_xtal_get_freq_mhz(void)
     }
     return freq;
 }
+
+void clk_hal_clock_output_setup(soc_clkout_sig_id_t clk_sig, uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(clk_sig, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}
+
+void clk_hal_clock_output_teardown(uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(0, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}

components/hal/esp32h2/clk_tree_hal.c

@@ -4,9 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+#include "soc/clkout_channel.h"
+#include "hal/assert.h"
 #include "hal/clk_tree_hal.h"
 #include "hal/clk_tree_ll.h"
-#include "hal/assert.h"
+#include "hal/gpio_ll.h"
 #include "hal/log.h"
 
 static const char *CLK_HAL_TAG = "clk_hal";
@@ -73,3 +75,13 @@ uint32_t clk_hal_xtal_get_freq_mhz(void)
     }
     return freq;
 }
+
+void clk_hal_clock_output_setup(soc_clkout_sig_id_t clk_sig, uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(clk_sig, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}
+
+void clk_hal_clock_output_teardown(uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(0, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}

components/hal/esp32s2/clk_tree_hal.c

@@ -4,9 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+#include "soc/clkout_channel.h"
+#include "hal/assert.h"
 #include "hal/clk_tree_hal.h"
 #include "hal/clk_tree_ll.h"
-#include "hal/assert.h"
+#include "hal/gpio_ll.h"
 #include "hal/log.h"
 
 static const char *CLK_HAL_TAG = "clk_hal";
@@ -111,3 +113,13 @@ uint32_t clk_hal_apll_get_freq_hz(void)
     uint32_t apll_freq_hz = (uint32_t)((xtal_freq_hz * numerator) / denominator);
     return apll_freq_hz;
 }
+
+void clk_hal_clock_output_setup(soc_clkout_sig_id_t clk_sig, uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(clk_sig, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}
+
+void clk_hal_clock_output_teardown(uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(0, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}

components/hal/esp32s3/clk_tree_hal.c

@@ -4,9 +4,11 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+#include "soc/clkout_channel.h"
+#include "hal/assert.h"
 #include "hal/clk_tree_hal.h"
 #include "hal/clk_tree_ll.h"
-#include "hal/assert.h"
+#include "hal/gpio_ll.h"
 #include "hal/log.h"
 
 static const char *CLK_HAL_TAG = "clk_hal";
@@ -88,3 +90,13 @@ uint32_t clk_hal_xtal_get_freq_mhz(void)
     }
     return freq;
 }
+
+void clk_hal_clock_output_setup(soc_clkout_sig_id_t clk_sig, uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(clk_sig, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}
+
+void clk_hal_clock_output_teardown(uint8_t channel_id)
+{
+    gpio_ll_set_pin_ctrl(0, CLKOUT_CHANNEL_MASK(channel_id), CLKOUT_CHANNEL_SHIFT(channel_id));
+}

components/hal/include/hal/clk_tree_hal.h

@@ -60,6 +60,19 @@ uint32_t clk_hal_xtal_get_freq_mhz(void);
 uint32_t clk_hal_apll_get_freq_hz(void);
 #endif //SOC_CLK_APLL_SUPPORTED
 
+/**
+ * @brief Set up clock output channel
+ * @param clk_sig    The clock signal source to be mapped to GPIOs
+ * @param channel_id The clock output channel to setup
+ */
+void clk_hal_clock_output_setup(soc_clkout_sig_id_t clk_sig, uint8_t channel_id);
+
+/**
+ * @brief Teardown clock output channel configuration
+ * @param channel_id The clock output channel to teardown
+ */
+void clk_hal_clock_output_teardown(uint8_t channel_id);
+
 #ifdef __cplusplus
 }
 #endif

components/soc/esp32/include/soc/clkout_channel.h

@@ -0,0 +1,52 @@
+/*
+ * SPDX-FileCopyrightText: 2010-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_assert.h"
+#include "soc/soc_caps.h"
+#include "soc/io_mux_reg.h"
+#include "soc/gpio_sig_map.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum clock_out_channel {
+    CLKOUT_CHANNEL_1,
+    CLKOUT_CHANNEL_2,
+    CLKOUT_CHANNEL_3,
+    CLKOUT_CHANNEL_MAX,
+} clock_out_channel_t;
+
+#define CLKOUT_CHANNEL1_GPIO    GPIO_NUM_0
+#define CLKOUT_CHANNEL2_GPIO    GPIO_NUM_3
+#define CLKOUT_CHANNEL3_GPIO    GPIO_NUM_1
+#define FUNC_CLK_OUT1           FUNC_GPIO0_CLK_OUT1
+#define FUNC_CLK_OUT2           FUNC_U0RXD_CLK_OUT2
+#define FUNC_CLK_OUT3           FUNC_U0TXD_CLK_OUT3
+#define IONUM_TO_CLKOUT_CHANNEL(gpio_num)   ((gpio_num == CLKOUT_CHANNEL1_GPIO) ? CLKOUT_CHANNEL_1 : \
+                                             (gpio_num == CLKOUT_CHANNEL2_GPIO) ? CLKOUT_CHANNEL_2 : \
+                                             (gpio_num == CLKOUT_CHANNEL3_GPIO) ? CLKOUT_CHANNEL_3 : -1)
+#define CLKOUT_CHANNEL_TO_IOMUX_FUNC(channel)   ((channel == CLKOUT_CHANNEL_1) ? FUNC_CLK_OUT1 : \
+                                                 (channel == CLKOUT_CHANNEL_2) ? FUNC_CLK_OUT2 : \
+                                                 (channel == CLKOUT_CHANNEL_3) ? FUNC_CLK_OUT3 : -1)
+#define IS_VALID_CLKOUT_IO(gpio_num)    ((gpio_num == CLKOUT_CHANNEL1_GPIO) || (gpio_num == CLKOUT_CHANNEL2_GPIO) || (gpio_num == CLKOUT_CHANNEL3_GPIO))
+
+
+#define CLKOUT_CHANNEL_MASK(channel)    ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1 : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2 : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3 : 0)
+
+#define CLKOUT_CHANNEL_SHIFT(channel)   ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1_S : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2_S : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3_S : 0)
+
+ESP_STATIC_ASSERT(CLKOUT_CHANNEL_MAX == SOC_GPIO_CLOCKOUT_CHANNEL_NUM, "clock_out_channel enumeration mismatch");
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32c2/include/soc/clkout_channel.h

@@ -0,0 +1,42 @@
+/*
+ * SPDX-FileCopyrightText: 2010-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_assert.h"
+#include "soc/soc_caps.h"
+#include "soc/io_mux_reg.h"
+#include "soc/gpio_sig_map.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum clock_out_channel {
+    CLKOUT_CHANNEL_1,
+    CLKOUT_CHANNEL_2,
+    CLKOUT_CHANNEL_3,
+    CLKOUT_CHANNEL_MAX,
+} clock_out_channel_t;
+
+#define CLKOUT_CHANNEL_TO_GPIO_SIG_ID(channel)  ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT_OUT1_IDX : \
+                                                 (channel == CLKOUT_CHANNEL_2) ? CLK_OUT_OUT2_IDX : \
+                                                 (channel == CLKOUT_CHANNEL_3) ? CLK_OUT_OUT3_IDX : SIG_GPIO_OUT_IDX)
+
+
+#define CLKOUT_CHANNEL_MASK(channel)    ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1 : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2 : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3 : 0)
+
+#define CLKOUT_CHANNEL_SHIFT(channel)   ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1_S : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2_S : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3_S : 0)
+
+ESP_STATIC_ASSERT(CLKOUT_CHANNEL_MAX == SOC_GPIO_CLOCKOUT_CHANNEL_NUM, "clock_out_channel enumeration mismatch");
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32c3/include/soc/clkout_channel.h

@@ -0,0 +1,42 @@
+/*
+ * SPDX-FileCopyrightText: 2010-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_assert.h"
+#include "soc/soc_caps.h"
+#include "soc/io_mux_reg.h"
+#include "soc/gpio_sig_map.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum clock_out_channel {
+    CLKOUT_CHANNEL_1,
+    CLKOUT_CHANNEL_2,
+    CLKOUT_CHANNEL_3,
+    CLKOUT_CHANNEL_MAX,
+} clock_out_channel_t;
+
+#define CLKOUT_CHANNEL_TO_GPIO_SIG_ID(channel)  ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT_OUT1_IDX : \
+                                                 (channel == CLKOUT_CHANNEL_2) ? CLK_OUT_OUT2_IDX : \
+                                                 (channel == CLKOUT_CHANNEL_3) ? CLK_OUT_OUT3_IDX : SIG_GPIO_OUT_IDX)
+
+
+#define CLKOUT_CHANNEL_MASK(channel)    ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1 : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2 : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3 : 0)
+
+#define CLKOUT_CHANNEL_SHIFT(channel)   ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1_S : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2_S : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3_S : 0)
+
+ESP_STATIC_ASSERT(CLKOUT_CHANNEL_MAX == SOC_GPIO_CLOCKOUT_CHANNEL_NUM, "clock_out_channel enumeration mismatch");
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32c5/beta3/include/soc/clkout_channel.h

@@ -0,0 +1,42 @@
+/*
+ * SPDX-FileCopyrightText: 2010-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_assert.h"
+#include "soc/soc_caps.h"
+#include "soc/io_mux_reg.h"
+#include "soc/gpio_sig_map.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum clock_out_channel {
+    CLKOUT_CHANNEL_1,
+    CLKOUT_CHANNEL_2,
+    CLKOUT_CHANNEL_3,
+    CLKOUT_CHANNEL_MAX,
+} clock_out_channel_t;
+
+#define CLKOUT_CHANNEL_TO_GPIO_SIG_ID(channel)  ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT_OUT1_IDX : \
+                                                 (channel == CLKOUT_CHANNEL_2) ? CLK_OUT_OUT2_IDX : \
+                                                 (channel == CLKOUT_CHANNEL_3) ? CLK_OUT_OUT3_IDX : SIG_GPIO_OUT_IDX)
+
+
+#define CLKOUT_CHANNEL_MASK(channel)    ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1 : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2 : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3 : 0)
+
+#define CLKOUT_CHANNEL_SHIFT(channel)   ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1_S : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2_S : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3_S : 0)
+
+ESP_STATIC_ASSERT(CLKOUT_CHANNEL_MAX == SOC_GPIO_CLOCKOUT_CHANNEL_NUM, "clock_out_channel enumeration mismatch");
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32c5/mp/include/soc/clkout_channel.h

@@ -0,0 +1,42 @@
+/*
+ * SPDX-FileCopyrightText: 2010-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_assert.h"
+#include "soc/soc_caps.h"
+#include "soc/io_mux_reg.h"
+#include "soc/gpio_sig_map.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum clock_out_channel {
+    CLKOUT_CHANNEL_1,
+    CLKOUT_CHANNEL_2,
+    CLKOUT_CHANNEL_3,
+    CLKOUT_CHANNEL_MAX,
+} clock_out_channel_t;
+
+#define CLKOUT_CHANNEL_TO_GPIO_SIG_ID(channel)  ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT_OUT1_IDX : \
+                                                 (channel == CLKOUT_CHANNEL_2) ? CLK_OUT_OUT2_IDX : \
+                                                 (channel == CLKOUT_CHANNEL_3) ? CLK_OUT_OUT3_IDX : SIG_GPIO_OUT_IDX)
+
+
+#define CLKOUT_CHANNEL_MASK(channel)    ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1 : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2 : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3 : 0)
+
+#define CLKOUT_CHANNEL_SHIFT(channel)   ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1_S : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2_S : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3_S : 0)
+
+ESP_STATIC_ASSERT(CLKOUT_CHANNEL_MAX == SOC_GPIO_CLOCKOUT_CHANNEL_NUM, "clock_out_channel enumeration mismatch");
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32c6/include/soc/clkout_channel.h

@@ -0,0 +1,42 @@
+/*
+ * SPDX-FileCopyrightText: 2010-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_assert.h"
+#include "soc/soc_caps.h"
+#include "soc/io_mux_reg.h"
+#include "soc/gpio_sig_map.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum clock_out_channel {
+    CLKOUT_CHANNEL_1,
+    CLKOUT_CHANNEL_2,
+    CLKOUT_CHANNEL_3,
+    CLKOUT_CHANNEL_MAX,
+} clock_out_channel_t;
+
+#define CLKOUT_CHANNEL_TO_GPIO_SIG_ID(channel)  ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT_OUT1_IDX : \
+                                                 (channel == CLKOUT_CHANNEL_2) ? CLK_OUT_OUT2_IDX : \
+                                                 (channel == CLKOUT_CHANNEL_3) ? CLK_OUT_OUT3_IDX : SIG_GPIO_OUT_IDX)
+
+
+#define CLKOUT_CHANNEL_MASK(channel)    ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1 : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2 : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3 : 0)
+
+#define CLKOUT_CHANNEL_SHIFT(channel)   ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1_S : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2_S : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3_S : 0)
+
+ESP_STATIC_ASSERT(CLKOUT_CHANNEL_MAX == SOC_GPIO_CLOCKOUT_CHANNEL_NUM, "clock_out_channel enumeration mismatch");
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32c61/include/soc/clkout_channel.h

@@ -0,0 +1,42 @@
+/*
+ * SPDX-FileCopyrightText: 2010-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_assert.h"
+#include "soc/soc_caps.h"
+#include "soc/io_mux_reg.h"
+#include "soc/gpio_sig_map.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum clock_out_channel {
+    CLKOUT_CHANNEL_1,
+    CLKOUT_CHANNEL_2,
+    CLKOUT_CHANNEL_3,
+    CLKOUT_CHANNEL_MAX,
+} clock_out_channel_t;
+
+#define CLKOUT_CHANNEL_TO_GPIO_SIG_ID(channel)  ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT_OUT1_IDX : \
+                                                 (channel == CLKOUT_CHANNEL_2) ? CLK_OUT_OUT2_IDX : \
+                                                 (channel == CLKOUT_CHANNEL_3) ? CLK_OUT_OUT3_IDX : SIG_GPIO_OUT_IDX)
+
+
+#define CLKOUT_CHANNEL_MASK(channel)    ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1 : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2 : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3 : 0)
+
+#define CLKOUT_CHANNEL_SHIFT(channel)   ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1_S : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2_S : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3_S : 0)
+
+ESP_STATIC_ASSERT(CLKOUT_CHANNEL_MAX == SOC_GPIO_CLOCKOUT_CHANNEL_NUM, "clock_out_channel enumeration mismatch");
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32h2/include/soc/clkout_channel.h

@@ -0,0 +1,42 @@
+/*
+ * SPDX-FileCopyrightText: 2010-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_assert.h"
+#include "soc/soc_caps.h"
+#include "soc/io_mux_reg.h"
+#include "soc/gpio_sig_map.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum clock_out_channel {
+    CLKOUT_CHANNEL_1,
+    CLKOUT_CHANNEL_2,
+    CLKOUT_CHANNEL_3,
+    CLKOUT_CHANNEL_MAX,
+} clock_out_channel_t;
+
+#define CLKOUT_CHANNEL_TO_GPIO_SIG_ID(channel)  ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT_OUT1_IDX : \
+                                                 (channel == CLKOUT_CHANNEL_2) ? CLK_OUT_OUT2_IDX : \
+                                                 (channel == CLKOUT_CHANNEL_3) ? CLK_OUT_OUT3_IDX : SIG_GPIO_OUT_IDX)
+
+
+#define CLKOUT_CHANNEL_MASK(channel)    ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1 : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2 : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3 : 0)
+
+#define CLKOUT_CHANNEL_SHIFT(channel)   ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1_S : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2_S : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3_S : 0)
+
+ESP_STATIC_ASSERT(CLKOUT_CHANNEL_MAX == SOC_GPIO_CLOCKOUT_CHANNEL_NUM, "clock_out_channel enumeration mismatch");
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32p4/include/soc/clkout_channel.h

@@ -0,0 +1,32 @@
+/*
+ * SPDX-FileCopyrightText: 2010-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_assert.h"
+#include "soc/soc_caps.h"
+#include "soc/io_mux_reg.h"
+#include "soc/gpio_sig_map.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum clock_out_channel {
+    CLKOUT_CHANNEL_1,
+    CLKOUT_CHANNEL_2,
+    CLKOUT_CHANNEL_MAX,
+} clock_out_channel_t;
+
+
+#define CLKOUT_CHANNEL_TO_GPIO_SIG_ID(channel)  ((channel == CLKOUT_CHANNEL_1) ? DBG_CH0_CLK_IDX : \
+                                                 (channel == CLKOUT_CHANNEL_2) ? DBG_CH1_CLK_IDX : SIG_GPIO_OUT_IDX)
+
+ESP_STATIC_ASSERT(CLKOUT_CHANNEL_MAX == SOC_GPIO_CLOCKOUT_CHANNEL_NUM, "clock_out_channel enumeration mismatch");
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32s2/include/soc/clkout_channel.h

@@ -6,8 +6,10 @@
 
 #pragma once
 
-#include "sdkconfig.h"
+#include "esp_assert.h"
 #include "soc/soc_caps.h"
+#include "soc/io_mux_reg.h"
+#include "soc/gpio_sig_map.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -20,35 +22,20 @@ typedef enum clock_out_channel {
     CLKOUT_CHANNEL_MAX,
 } clock_out_channel_t;
 
-#if SOC_GPIO_CLOCKOUT_BY_IO_MUX
-#if CONFIG_IDF_TARGET_ESP32
-#define CLKOUT_CHANNEL1_GPIO    GPIO_NUM_0
-#define CLKOUT_CHANNEL2_GPIO    GPIO_NUM_3
-#define CLKOUT_CHANNEL3_GPIO    GPIO_NUM_1
-#define FUNC_CLK_OUT1           FUNC_GPIO0_CLK_OUT1
-#define FUNC_CLK_OUT2           FUNC_U0RXD_CLK_OUT2
-#define FUNC_CLK_OUT3           FUNC_U0TXD_CLK_OUT3
-#elif CONFIG_IDF_TARGET_ESP32S2 || CONFIG_IDF_TARGET_ESP32S3
 #define CLKOUT_CHANNEL1_GPIO    GPIO_NUM_20
 #define CLKOUT_CHANNEL2_GPIO    GPIO_NUM_19
 #define CLKOUT_CHANNEL3_GPIO    GPIO_NUM_18
 #define FUNC_CLK_OUT1           FUNC_GPIO20_CLK_OUT1
 #define FUNC_CLK_OUT2           FUNC_GPIO19_CLK_OUT2
 #define FUNC_CLK_OUT3           FUNC_DAC_2_CLK_OUT3
-#endif
+
 #define IONUM_TO_CLKOUT_CHANNEL(gpio_num)   ((gpio_num == CLKOUT_CHANNEL1_GPIO) ? CLKOUT_CHANNEL_1 : \
                                              (gpio_num == CLKOUT_CHANNEL2_GPIO) ? CLKOUT_CHANNEL_2 : \
-                                             (gpio_num == CLKOUT_CHANNEL3_GPIO) ? CLKOUT_CHANNEL_3 : 0)
+                                             (gpio_num == CLKOUT_CHANNEL3_GPIO) ? CLKOUT_CHANNEL_3 : -1)
 #define CLKOUT_CHANNEL_TO_IOMUX_FUNC(channel)   ((channel == CLKOUT_CHANNEL_1) ? FUNC_CLK_OUT1 : \
                                                  (channel == CLKOUT_CHANNEL_2) ? FUNC_CLK_OUT2 : \
-                                                 (channel == CLKOUT_CHANNEL_3) ? FUNC_CLK_OUT3 : 0)
+                                                 (channel == CLKOUT_CHANNEL_3) ? FUNC_CLK_OUT3 : -1)
 #define IS_VALID_CLKOUT_IO(gpio_num)    ((gpio_num == CLKOUT_CHANNEL1_GPIO) || (gpio_num == CLKOUT_CHANNEL2_GPIO) || (gpio_num == CLKOUT_CHANNEL3_GPIO))
-#elif SOC_GPIO_CLOCKOUT_BY_GPIO_MATRIX
-#define CLKOUT_CHANNEL_TO_GPIO_SIG_ID(channel)  ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT_OUT1_IDX : \
-                                                 (channel == CLKOUT_CHANNEL_2) ? CLK_OUT_OUT2_IDX : \
-                                                 (channel == CLKOUT_CHANNEL_3) ? CLK_OUT_OUT3_IDX : SIG_GPIO_OUT_IDX)
-#define IS_VALID_CLKOUT_IO(gpio_num)    GPIO_IS_VALID_GPIO(gpio_num)
-#endif
 
 #define CLKOUT_CHANNEL_MASK(channel)    ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1 : \
                                          (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2 : \
@@ -58,6 +45,8 @@ typedef enum clock_out_channel {
                                          (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2_S : \
                                          (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3_S : 0)
 
+ESP_STATIC_ASSERT(CLKOUT_CHANNEL_MAX == SOC_GPIO_CLOCKOUT_CHANNEL_NUM, "clock_out_channel enumeration mismatch");
+
 #ifdef __cplusplus
 }
 #endif

components/soc/esp32s3/include/soc/clkout_channel.h

@@ -0,0 +1,52 @@
+/*
+ * SPDX-FileCopyrightText: 2010-2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_assert.h"
+#include "soc/soc_caps.h"
+#include "soc/io_mux_reg.h"
+#include "soc/gpio_sig_map.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum clock_out_channel {
+    CLKOUT_CHANNEL_1,
+    CLKOUT_CHANNEL_2,
+    CLKOUT_CHANNEL_3,
+    CLKOUT_CHANNEL_MAX,
+} clock_out_channel_t;
+
+#define CLKOUT_CHANNEL1_GPIO    GPIO_NUM_20
+#define CLKOUT_CHANNEL2_GPIO    GPIO_NUM_19
+#define CLKOUT_CHANNEL3_GPIO    GPIO_NUM_18
+#define FUNC_CLK_OUT1           FUNC_GPIO20_CLK_OUT1
+#define FUNC_CLK_OUT2           FUNC_GPIO19_CLK_OUT2
+#define FUNC_CLK_OUT3           FUNC_DAC_2_CLK_OUT3
+
+#define IONUM_TO_CLKOUT_CHANNEL(gpio_num)   ((gpio_num == CLKOUT_CHANNEL1_GPIO) ? CLKOUT_CHANNEL_1 : \
+                                             (gpio_num == CLKOUT_CHANNEL2_GPIO) ? CLKOUT_CHANNEL_2 : \
+                                             (gpio_num == CLKOUT_CHANNEL3_GPIO) ? CLKOUT_CHANNEL_3 : -1)
+#define CLKOUT_CHANNEL_TO_IOMUX_FUNC(channel)   ((channel == CLKOUT_CHANNEL_1) ? FUNC_CLK_OUT1 : \
+                                                 (channel == CLKOUT_CHANNEL_2) ? FUNC_CLK_OUT2 : \
+                                                 (channel == CLKOUT_CHANNEL_3) ? FUNC_CLK_OUT3 : -1)
+#define IS_VALID_CLKOUT_IO(gpio_num)    ((gpio_num == CLKOUT_CHANNEL1_GPIO) || (gpio_num == CLKOUT_CHANNEL2_GPIO) || (gpio_num == CLKOUT_CHANNEL3_GPIO))
+
+#define CLKOUT_CHANNEL_MASK(channel)    ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1 : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2 : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3 : 0)
+
+#define CLKOUT_CHANNEL_SHIFT(channel)   ((channel == CLKOUT_CHANNEL_1) ? CLK_OUT1_S : \
+                                         (channel == CLKOUT_CHANNEL_2) ? CLK_OUT2_S : \
+                                         (channel == CLKOUT_CHANNEL_3) ? CLK_OUT3_S : 0)
+
+ESP_STATIC_ASSERT(CLKOUT_CHANNEL_MAX == SOC_GPIO_CLOCKOUT_CHANNEL_NUM, "clock_out_channel enumeration mismatch");
+
+#ifdef __cplusplus
+}
+#endif