Merge branch 'feature/esp32h21_clock_support' into 'master'

feat(clk): Add basic clock support for esp32h21

Closes IDF-11521, IDF-11906, and IDF-12114

See merge request espressif/esp-idf!39066

Author: songruo

Kconfig

@@ -141,7 +141,6 @@ mainmenu "Espressif IoT Development Framework Configuration"
         default "y" if IDF_TARGET="esp32h21"
         select FREERTOS_UNICORE
         select IDF_TARGET_ARCH_RISCV
-        select IDF_ENV_FPGA
         select IDF_ENV_BRINGUP
 
     config IDF_TARGET_ESP32H4

components/bootloader_support/bootloader_flash/src/bootloader_flash_config_esp32h21.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -18,6 +18,7 @@
 #include "hal/cache_hal.h"
 #include "hal/cache_ll.h"
 #include "hal/mspi_ll.h"
+#include "hal/clk_tree_ll.h"
 #include "soc/pcr_reg.h"
 
 static const char *TAG = "boot.esp32h21";
@@ -80,7 +81,9 @@ void IRAM_ATTR bootloader_configure_spi_pins(int drv)
 
 static void IRAM_ATTR bootloader_flash_clock_init(void)
 {
-    // At this moment, BBPLL should be enabled, safe to switch MSPI clock source to PLL_F64M (default clock src) to raise speed
+    // To raise the MSPI clock to 64MHz, needs to enable the 64MHz clock source, which is XTAL_X2_CLK
+    // (FPGA image fixed MSPI0/1 clock to 64MHz)
+    clk_ll_xtal_x2_enable();
     _mspi_timing_ll_set_flash_clk_src(0, FLASH_CLK_SRC_PLL_F64M);
 }
 

components/bootloader_support/src/bootloader_clock_init.c

@@ -18,7 +18,7 @@
 #include "soc/pmu_reg.h"
 #endif
 
-#if CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32C5
+#if CONFIG_IDF_TARGET_ESP32
 #include "hal/clk_tree_ll.h"
 #endif
 #include "esp_rom_sys.h"

components/bootloader_support/src/esp32h21/bootloader_esp32h21.c

@@ -90,7 +90,6 @@ static inline void bootloader_hardware_init(void)
     SET_PERI_REG_MASK(PMU_RF_PWC_REG, PMU_XPD_FORCE_RFPLL);
 
     _regi2c_ctrl_ll_master_enable_clock(true); // keep ana i2c mst clock always enabled in bootloader
-    regi2c_ctrl_ll_master_force_enable_clock(true); // TODO: IDF-11548 Remove this?
     regi2c_ctrl_ll_master_configure_clock();
 }
 

components/esp_hw_support/esp_clk.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -85,10 +85,10 @@ int IRAM_ATTR esp_clk_cpu_freq(void)
 int IRAM_ATTR esp_clk_apb_freq(void)
 {
     // TODO: IDF-5173 Require cleanup, implementation should be unified
-#if CONFIG_IDF_TARGET_ESP32C6 || CONFIG_IDF_TARGET_ESP32H2 || CONFIG_IDF_TARGET_ESP32P4 || CONFIG_IDF_TARGET_ESP32C5 || CONFIG_IDF_TARGET_ESP32C61
-    return rtc_clk_apb_freq_get();
-#else
+#if CONFIG_IDF_TARGET_ESP32 || CONFIG_IDF_TARGET_ESP32S2 || CONFIG_IDF_TARGET_ESP32S3 || CONFIG_IDF_TARGET_ESP32C3 || CONFIG_IDF_TARGET_ESP32C2
     return MIN(s_get_cpu_freq_mhz() * MHZ, APB_CLK_FREQ);
+#else // for all later targets
+    return rtc_clk_apb_freq_get();
 #endif
 }
 

components/esp_hw_support/include/esp_private/esp_clk_tree_common.h

@@ -90,12 +90,33 @@ uint32_t esp_clk_tree_lp_fast_get_freq_hz(esp_clk_tree_src_freq_precision_t prec
  */
 esp_err_t esp_clk_tree_enable_src(soc_module_clk_t clk_src, bool enable);
 
-#if SOC_CLOCK_TREE_MANAGEMENT_SUPPORTED
 /**
- * @brief Set the clock source not in use  on the clock tree to the gated state.
+ * @brief Initialize clock circuit power and clock gating
+ *
+ * Set the clock source not in uses on the clock tree to the gated state,
+ * and initialize reference counters for clock circuit power and clock gating.
  */
 void esp_clk_tree_initialize(void);
-#endif
+
+/**
+ * @brief Enable / Disable the power of the clock circuit
+ *
+ * @param[in] clk_circuit Clock circuits, in soc_root_clk_circuit_t
+ * @param[in] enable  Enable / Disable the power of the clock circuit
+ *
+ * @return
+ *      - ESP_OK               Success
+ */
+esp_err_t esp_clk_tree_enable_power(soc_root_clk_circuit_t clk_circuit, bool enable);
+
+/**
+ * @brief Get the power status of the clock circuit
+ *
+ * @param[in] clk_circuit Clock circuits, in soc_root_clk_circuit_t
+ *
+ * @return True if the clock circuit power is on, false otherwise
+ */
+bool esp_clk_tree_is_power_on(soc_root_clk_circuit_t clk_circuit);
 
 #ifdef __cplusplus
 }

components/esp_hw_support/linker.lf

@@ -17,6 +17,8 @@ entries:
         rtc_clk (noflash)
         rtc_time (noflash_text)
         esp_clk_tree: esp_clk_tree_enable_src (noflash)
+        esp_clk_tree: esp_clk_tree_enable_power (noflash)
+        esp_clk_tree: esp_clk_tree_is_power_on (noflash)
     if IDF_TARGET_ESP32 = y:
         rtc_clk:rtc_clk_cpu_freq_to_pll_mhz (noflash)
         rtc_clk:rtc_clk_cpu_freq_to_xtal (noflash)

components/esp_hw_support/port/esp32/esp_clk_tree.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -70,6 +70,22 @@ uint32_t *freq_value)
     return ESP_OK;
 }
 
+void esp_clk_tree_initialize(void)
+{
+}
+
+bool esp_clk_tree_is_power_on(soc_root_clk_circuit_t clk_circuit)
+{
+    (void)clk_circuit;
+    return false;
+}
+
+esp_err_t esp_clk_tree_enable_power(soc_root_clk_circuit_t clk_circuit, bool enable)
+{
+    (void)clk_circuit; (void)enable;
+    return ESP_OK; // TODO: PM-354
+}
+
 esp_err_t esp_clk_tree_enable_src(soc_module_clk_t clk_src, bool enable)
 {
     (void)clk_src; (void)enable;

components/esp_hw_support/port/esp32/rtc_clk.c

@@ -34,7 +34,7 @@
 
 #define XTAL_32K_BOOTSTRAP_TIME_US      7
 
-static void rtc_clk_cpu_freq_to_8m(void);
+static void rtc_clk_cpu_freq_to_rc_fast(void);
 static void rtc_clk_cpu_freq_to_pll_mhz(int cpu_freq_mhz);
 
 // Current PLL frequency, in MHZ (320 or 480). Zero if PLL is not enabled.
@@ -387,7 +387,7 @@ void rtc_clk_cpu_freq_to_xtal(int cpu_freq, int div)
     REG_SET_FIELD(RTC_CNTL_REG, RTC_CNTL_DIG_DBIAS_WAK, dbias);
 }
 
-static void rtc_clk_cpu_freq_to_8m(void)
+static void rtc_clk_cpu_freq_to_rc_fast(void)
 {
     esp_rom_set_cpu_ticks_per_us(8);
     REG_SET_FIELD(RTC_CNTL_REG, RTC_CNTL_DIG_DBIAS_WAK, DIG_DBIAS_XTAL);
@@ -542,7 +542,7 @@ void rtc_clk_cpu_freq_set_config(const rtc_cpu_freq_config_t* config)
         rtc_clk_bbpll_configure(rtc_clk_xtal_freq_get(), config->source_freq_mhz);
         rtc_clk_cpu_freq_to_pll_mhz(config->freq_mhz);
     } else if (config->source == SOC_CPU_CLK_SRC_RC_FAST) {
-        rtc_clk_cpu_freq_to_8m();
+        rtc_clk_cpu_freq_to_rc_fast();
     }
 }
 

components/esp_hw_support/port/esp32c2/esp_clk_tree.c

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -64,6 +64,22 @@ uint32_t *freq_value)
     return ESP_OK;
 }
 
+void esp_clk_tree_initialize(void)
+{
+}
+
+bool esp_clk_tree_is_power_on(soc_root_clk_circuit_t clk_circuit)
+{
+    (void)clk_circuit;
+    return false;
+}
+
+esp_err_t esp_clk_tree_enable_power(soc_root_clk_circuit_t clk_circuit, bool enable)
+{
+    (void)clk_circuit; (void)enable;
+    return ESP_OK; // TODO: PM-354
+}
+
 esp_err_t esp_clk_tree_enable_src(soc_module_clk_t clk_src, bool enable)
 {
     (void)clk_src; (void)enable;