clk_tree: prework of introducing clk subsystem control

1. Clean up clk usage in IDF, replace rtc_clk_xtal/apb_freq_get with
   upper level API esp_clk_xtal/apb_freq
2. Fix small errors and wrong comments related to clock
3. Add clk_tree_defs.h to provide an unified clock id for each chip
   Modify the NGed drivers to adopt new clock ids

components/bt/controller/esp32/bt.c

@@ -1665,7 +1665,7 @@ esp_err_t esp_bt_controller_init(esp_bt_controller_config_t *cfg)
     bool set_div_ret __attribute__((unused));
     if (btdm_lpclk_sel == BTDM_LPCLK_SEL_XTAL) {
         select_src_ret = btdm_lpclk_select_src(BTDM_LPCLK_SEL_XTAL);
-        set_div_ret = btdm_lpclk_set_div(rtc_clk_xtal_freq_get() * 2 - 1);
+        set_div_ret = btdm_lpclk_set_div(esp_clk_xtal_freq() * 2 / MHZ - 1);
         assert(select_src_ret && set_div_ret);
         btdm_lpcycle_us_frac = RTC_CLK_CAL_FRACT;
         btdm_lpcycle_us = 2 << (btdm_lpcycle_us_frac);

components/bt/controller/esp32c3/bt.c

@@ -1073,7 +1073,7 @@ esp_err_t esp_bt_controller_init(esp_bt_controller_config_t *cfg)
         bool set_div_ret __attribute__((unused));
         if (s_lp_cntl.lpclk_sel == BTDM_LPCLK_SEL_XTAL) {
             select_src_ret = btdm_lpclk_select_src(BTDM_LPCLK_SEL_XTAL);
-            set_div_ret = btdm_lpclk_set_div(rtc_clk_xtal_freq_get() * 2);
+            set_div_ret = btdm_lpclk_set_div(esp_clk_xtal_freq() * 2 / MHZ);
             assert(select_src_ret && set_div_ret);
             btdm_lpcycle_us_frac = RTC_CLK_CAL_FRACT;
             btdm_lpcycle_us = 2 << (btdm_lpcycle_us_frac);

components/bt/controller/esp32s3/bt.c

@@ -1041,7 +1041,7 @@ esp_err_t esp_bt_controller_init(esp_bt_controller_config_t *cfg)
         bool set_div_ret __attribute__((unused));
         if (s_lp_cntl.lpclk_sel == BTDM_LPCLK_SEL_XTAL) {
             select_src_ret = btdm_lpclk_select_src(BTDM_LPCLK_SEL_XTAL);
-            set_div_ret = btdm_lpclk_set_div(rtc_clk_xtal_freq_get() * 2);
+            set_div_ret = btdm_lpclk_set_div(esp_clk_xtal_freq() * 2 / MHZ);
             assert(select_src_ret && set_div_ret);
             btdm_lpcycle_us_frac = RTC_CLK_CAL_FRACT;
             btdm_lpcycle_us = 2 << (btdm_lpcycle_us_frac);

components/driver/deprecated/timer_legacy.c

@@ -15,7 +15,7 @@
 #include "hal/timer_ll.h"
 #include "hal/check.h"
 #include "soc/timer_periph.h"
-#include "soc/rtc.h"
+#include "esp_private/esp_clk.h"
 #include "soc/timer_group_reg.h"
 #include "esp_private/periph_ctrl.h"
 
@@ -78,11 +78,11 @@ esp_err_t timer_get_counter_time_sec(timer_group_t group_num, timer_idx_t timer_
     uint32_t div = p_timer_obj[group_num][timer_num]->divider;
     switch (p_timer_obj[group_num][timer_num]->clk_src) {
     case GPTIMER_CLK_SRC_APB:
-        *time = (double)timer_val * div / rtc_clk_apb_freq_get();
+        *time = (double)timer_val * div / esp_clk_apb_freq();
         break;
 #if SOC_TIMER_GROUP_SUPPORT_XTAL
     case GPTIMER_CLK_SRC_XTAL:
-        *time = (double)timer_val * div / ((int)rtc_clk_xtal_freq_get() * MHZ);
+        *time = (double)timer_val * div / esp_clk_xtal_freq();
         break;
 #endif
     default:

components/driver/ledc.c

@@ -11,7 +11,7 @@
 #include "esp_check.h"
 #include "soc/gpio_periph.h"
 #include "soc/ledc_periph.h"
-#include "soc/rtc.h"
+#include "esp_private/esp_clk.h"
 #include "soc/soc_caps.h"
 #include "hal/ledc_hal.h"
 #include "hal/gpio_hal.h"
@@ -120,7 +120,7 @@ static uint32_t ledc_get_src_clk_freq(ledc_clk_cfg_t clk_cfg)
 #endif
 #if SOC_LEDC_SUPPORT_XTAL_CLOCK
     } else if (clk_cfg == LEDC_USE_XTAL_CLK) {
-        src_clk_freq = rtc_clk_xtal_freq_get() * 1000000;
+        src_clk_freq = esp_clk_xtal_freq();
 #endif
     }
     return src_clk_freq;
@@ -140,7 +140,7 @@ static uint32_t ledc_get_glb_clk_freq(ledc_slow_clk_sel_t clk_cfg)
             break;
 #if SOC_LEDC_SUPPORT_XTAL_CLOCK
         case LEDC_SLOW_CLK_XTAL:
-            src_clk_freq = rtc_clk_xtal_freq_get() * 1000000;
+            src_clk_freq = esp_clk_xtal_freq();
             break;
 #endif
     }

components/driver/rmt.c

@@ -21,7 +21,7 @@
 #include "soc/soc_memory_layout.h"
 #include "soc/rmt_periph.h"
 #include "soc/rmt_struct.h"
-#include "soc/rtc.h"
+#include "esp_private/esp_clk.h"
 #include "hal/rmt_hal.h"
 #include "hal/rmt_ll.h"
 #include "hal/gpio_hal.h"
@@ -602,7 +602,7 @@ static esp_err_t rmt_internal_config(rmt_dev_t *dev, const rmt_config_t *rmt_par
     if (rmt_param->flags & RMT_CHANNEL_FLAGS_AWARE_DFS) {
 #if SOC_RMT_SUPPORT_XTAL
         // clock src: XTAL_CLK
-        rmt_source_clk_hz = rtc_clk_xtal_freq_get() * 1000000;
+        rmt_source_clk_hz = esp_clk_xtal_freq();
         rmt_ll_set_group_clock_src(dev, channel, RMT_CLK_SRC_XTAL, 1, 0, 0);
 #elif SOC_RMT_SUPPORT_REF_TICK
         // clock src: REF_CLK

components/driver/spi_master.c

@@ -121,8 +121,8 @@ We have two bits to control the interrupt:
 #include "driver/gpio.h"
 #include "hal/spi_hal.h"
 #include "esp_heap_caps.h"
-//Temporarily include soc/rtc.h, will be replaced by clock tree API
-#include "soc/rtc.h"
+//Temporarily include esp_clk.h, will be replaced by clock tree API
+#include "esp_private/esp_clk.h"
 
 
 typedef struct spi_device_t spi_device_t;
@@ -320,7 +320,7 @@ esp_err_t spi_bus_add_device(spi_host_device_t host_id, const spi_device_interfa
     spi_host_t *host = bus_driver_ctx[host_id];
     const spi_bus_attr_t* bus_attr = host->bus_attr;
     SPI_CHECK(dev_config->spics_io_num < 0 || GPIO_IS_VALID_OUTPUT_GPIO(dev_config->spics_io_num), "spics pin invalid", ESP_ERR_INVALID_ARG);
-    uint32_t apb_clk_freq_hz = rtc_clk_apb_freq_get();
+    uint32_t apb_clk_freq_hz = esp_clk_apb_freq();
     assert((apb_clk_freq_hz == 80 * 1000 * 1000) || (apb_clk_freq_hz == 40 * 1000 * 1000) || (apb_clk_freq_hz == 48 * 1000 * 1000));
     SPI_CHECK((dev_config->clock_speed_hz > 0) && (dev_config->clock_speed_hz <= apb_clk_freq_hz) , "invalid sclk speed", ESP_ERR_INVALID_ARG);
 #ifdef CONFIG_IDF_TARGET_ESP32
@@ -349,7 +349,7 @@ esp_err_t spi_bus_add_device(spi_host_device_t host_id, const spi_device_interfa
     int duty_cycle = (dev_config->duty_cycle_pos==0) ? 128 : dev_config->duty_cycle_pos;
     int use_gpio = !(bus_attr->flags & SPICOMMON_BUSFLAG_IOMUX_PINS);
     spi_hal_timing_param_t timing_param = {
-        .clk_src_hz = rtc_clk_apb_freq_get(),
+        .clk_src_hz = esp_clk_apb_freq(),
         .clk_sel = SPI_CLK_APB,     //Currently, SPI driver only set SPI to APB clock. SPI is not supposed to be used during sleep modes.
         .half_duplex = half_duplex,
         .no_compensate = no_compensate,

components/driver/temperature_sensor.c

@@ -133,7 +133,7 @@ esp_err_t temperature_sensor_start(temperature_sensor_handle_t tsens)
     ESP_RETURN_ON_FALSE((tsens != NULL), ESP_ERR_INVALID_ARG, TAG, "Has not been installed");
     ESP_RETURN_ON_FALSE(tsens->tsens_hw_state == TSENS_HW_STATE_CONFIGURED, ESP_ERR_INVALID_STATE, TAG, "Is already running or has not been configured");
 #if SOC_TEMPERATURE_SENSOR_SUPPORT_FAST_RC
-    if (tsens->clk_src == TEMPERATURE_SENSOR_CLK_SRC_FAST_RC) {
+    if (tsens->clk_src == TEMPERATURE_SENSOR_CLK_SRC_RC_FAST) {
         periph_rtc_dig_clk8m_enable();
     }
 #endif
@@ -149,7 +149,7 @@ esp_err_t temperature_sensor_stop(temperature_sensor_handle_t tsens)
     ESP_RETURN_ON_FALSE(tsens->tsens_hw_state == TSENS_HW_STATE_STARTED, ESP_ERR_INVALID_STATE, TAG, "Has not been started");
     temperature_sensor_ll_enable(false);
 #if SOC_TEMPERATURE_SENSOR_SUPPORT_FAST_RC
-    if (tsens->clk_src == TEMPERATURE_SENSOR_CLK_SRC_FAST_RC) {
+    if (tsens->clk_src == TEMPERATURE_SENSOR_CLK_SRC_RC_FAST) {
         periph_rtc_dig_clk8m_disable();
     }
 #endif

components/driver/test/test_pwm.c

@@ -12,7 +12,7 @@
 #include "soc/soc_caps.h"
 #include "hal/gpio_hal.h"
 #include "esp_rom_gpio.h"
-#include "soc/rtc.h"
+#include "esp_private/esp_clk.h"
 #if SOC_MCPWM_SUPPORTED
 #include "soc/mcpwm_periph.h"
 #include "driver/pulse_cnt.h"
@@ -484,7 +484,7 @@ static void mcpwm_swsync_test(mcpwm_unit_t unit)
 
     vTaskDelay(pdMS_TO_TICKS(100));
 
-    uint32_t delta_timestamp_us = (cap_timestamp[2] - cap_timestamp[1]) * 1000000 / rtc_clk_apb_freq_get();
+    uint32_t delta_timestamp_us = (cap_timestamp[2] - cap_timestamp[1]) * 1000000 / esp_clk_apb_freq();
     uint32_t expected_phase_us = 1000000 / mcpwm_get_frequency(unit, MCPWM_TIMER_0) * test_sync_phase / 1000;
     // accept +-2 error
     TEST_ASSERT_UINT32_WITHIN(2, expected_phase_us, delta_timestamp_us);

components/driver/test/test_spi_master.c

@@ -29,7 +29,7 @@
 #include "../cache_utils.h"
 #include "soc/soc_memory_layout.h"
 #include "driver/spi_common_internal.h"
-#include "soc/rtc.h"
+#include "esp_private/esp_clk.h"
 
 
 const static char TAG[] = "test_spi";
@@ -93,14 +93,14 @@ TEST_CASE("SPI Master clockdiv calculation routines", "[spi]")
     };
     TEST_ESP_OK(spi_bus_initialize(TEST_SPI_HOST, &buscfg, SPI_DMA_CH_AUTO));
 
-    uint32_t apb_freq_hz = rtc_clk_apb_freq_get();
-    if (apb_freq_hz == (80 * MHZ)) {
+    uint32_t apb_freq_hz = esp_clk_apb_freq();
+    if (apb_freq_hz == (80 * 1000 * 1000)) {
         uint32_t clk_param[TEST_CLK_TIMES][3] = TEST_CLK_PARAM_APB_80;
         for (int i = 0; i < TEST_CLK_TIMES; i++) {
             check_spi_pre_n_for(clk_param[i][0], clk_param[i][1], clk_param[i][2]);
         }
     } else {
-        TEST_ASSERT(apb_freq_hz == (40 * MHZ));
+        TEST_ASSERT(apb_freq_hz == (40 * 1000 * 1000));
         uint32_t clk_param[TEST_CLK_TIMES][3] = TEST_CLK_PARAM_APB_40;
         for (int i = 0; i < TEST_CLK_TIMES; i++) {
             check_spi_pre_n_for(clk_param[i][0], clk_param[i][1], clk_param[i][2]);

components/driver/test_apps/legacy_timer_driver/main/test_legacy_timer.c

@@ -10,7 +10,7 @@
 #include "esp_system.h"
 #include "unity.h"
 #include "driver/timer.h"
-#include "soc/rtc.h"
+#include "esp_private/esp_clk.h"
 #include "soc/soc_caps.h"
 #include "esp_rom_sys.h"
 
@@ -857,7 +857,7 @@ TEST_CASE("Timer_clock_source", "[hw_timer]")
     // configure clock source as XTAL clock
     all_timer_pause();
     config.clk_src = TIMER_SRC_CLK_XTAL;
-    config.divider = rtc_clk_xtal_freq_get() * 1000000 / TEST_TIMER_RESOLUTION_HZ;
+    config.divider = esp_clk_xtal_freq() / TEST_TIMER_RESOLUTION_HZ;
     all_timer_init(&config, true);
     all_timer_set_alarm_value(1.2 * TEST_TIMER_RESOLUTION_HZ);
 

components/esp_hw_support/esp_clk.c

@@ -39,7 +39,7 @@
 
 // g_ticks_us defined in ROMs for PRO and APP CPU
 extern uint32_t g_ticks_per_us_pro;
-#if CONFIG_IDF_TARGET_ESP32
+#if SOC_CPU_CORES_NUM > 1
 #ifndef CONFIG_FREERTOS_UNICORE
 extern uint32_t g_ticks_per_us_app;
 #endif
@@ -79,7 +79,7 @@ void IRAM_ATTR ets_update_cpu_frequency(uint32_t ticks_per_us)
 {
     /* Update scale factors used by esp_rom_delay_us */
     g_ticks_per_us_pro = ticks_per_us;
-#if CONFIG_IDF_TARGET_ESP32
+#if SOC_CPU_CORES_NUM > 1
 #ifndef CONFIG_FREERTOS_UNICORE
     g_ticks_per_us_app = ticks_per_us;
 #endif

components/esp_hw_support/port/esp32c2/rtc_clk_init.c

@@ -46,7 +46,7 @@ void rtc_clk_init(rtc_clk_config_t cfg)
 
     /* Enable the internal bus used to configure PLLs */
     SET_PERI_REG_BITS(ANA_CONFIG_REG, ANA_CONFIG_M, ANA_CONFIG_M, ANA_CONFIG_S);
-    CLEAR_PERI_REG_MASK(ANA_CONFIG_REG, ANA_I2C_APLL_M | ANA_I2C_BBPLL_M);
+    CLEAR_PERI_REG_MASK(ANA_CONFIG_REG, ANA_I2C_BBPLL_M);
 
     rtc_xtal_freq_t xtal_freq = cfg.xtal_freq;
     esp_rom_uart_tx_wait_idle(0);

components/esp_hw_support/port/esp32c3/rtc_clk_init.c

@@ -47,7 +47,7 @@ void rtc_clk_init(rtc_clk_config_t cfg)
 
     /* Enable the internal bus used to configure PLLs */
     SET_PERI_REG_BITS(ANA_CONFIG_REG, ANA_CONFIG_M, ANA_CONFIG_M, ANA_CONFIG_S);
-    CLEAR_PERI_REG_MASK(ANA_CONFIG_REG, ANA_I2C_APLL_M | ANA_I2C_BBPLL_M);
+    CLEAR_PERI_REG_MASK(ANA_CONFIG_REG, ANA_I2C_BBPLL_M);
 
     rtc_xtal_freq_t xtal_freq = cfg.xtal_freq;
     esp_rom_uart_tx_wait_idle(0);

components/esp_hw_support/port/esp32s3/rtc_clk_init.c

@@ -43,7 +43,7 @@ void rtc_clk_init(rtc_clk_config_t cfg)
 
     /* Enable the internal bus used to configure PLLs */
     SET_PERI_REG_BITS(ANA_CONFIG_REG, ANA_CONFIG_M, ANA_CONFIG_M, ANA_CONFIG_S);
-    CLEAR_PERI_REG_MASK(ANA_CONFIG_REG, I2C_APLL_M | I2C_BBPLL_M);
+    CLEAR_PERI_REG_MASK(ANA_CONFIG_REG, I2C_BBPLL_M);
 
     rtc_xtal_freq_t xtal_freq = cfg.xtal_freq;
     esp_rom_uart_tx_wait_idle(0);

components/esp_hw_support/test/test_dport.c

@@ -163,7 +163,7 @@ TEST_CASE("access DPORT and APB at same time (Freq CPU and APB = 80 MHz)", "[esp
 
 TEST_CASE("access DPORT and APB at same time (Freq CPU and APB = 40 MHz (XTAL))", "[esp32]")
 {
-    run_tasks_with_change_freq_cpu((int) rtc_clk_xtal_freq_get());
+    run_tasks_with_change_freq_cpu(esp_clk_xtal_freq() / MHZ);
 }
 
 static uint32_t stall_other_cpu_counter;

components/esp_lcd/src/esp_lcd_panel_io_i80.c

@@ -25,7 +25,7 @@
 #include "esp_lcd_panel_io.h"
 #include "esp_rom_gpio.h"
 #include "soc/soc_caps.h"
-#include "soc/rtc.h" // for `rtc_clk_xtal_freq_get()`
+#include "esp_private/esp_clk.h"
 #include "esp_memory_utils.h"
 #include "hal/dma_types.h"
 #include "hal/gpio_hal.h"
@@ -483,7 +483,7 @@ static esp_err_t lcd_i80_select_periph_clock(esp_lcd_i80_bus_handle_t bus, lcd_c
 #endif
         break;
     case LCD_CLK_SRC_XTAL:
-        bus->resolution_hz = rtc_clk_xtal_freq_get() * 1000000 / LCD_PERIPH_CLOCK_PRE_SCALE;
+        bus->resolution_hz = esp_clk_xtal_freq() / LCD_PERIPH_CLOCK_PRE_SCALE;
         break;
     default:
         ESP_RETURN_ON_FALSE(false, ESP_ERR_NOT_SUPPORTED, TAG,  "unsupported clock source: %d", clk_src);

components/esp_lcd/src/esp_lcd_rgb_panel.c

@@ -25,7 +25,7 @@
 #include "esp_lcd_panel_ops.h"
 #include "esp_rom_gpio.h"
 #include "soc/soc_caps.h"
-#include "soc/rtc.h" // for querying XTAL clock
+#include "esp_private/esp_clk.h"
 #include "hal/dma_types.h"
 #include "hal/gpio_hal.h"
 #include "esp_private/gdma.h"
@@ -459,7 +459,7 @@ static esp_err_t lcd_rgb_panel_select_periph_clock(esp_rgb_panel_t *panel, lcd_c
 #endif
         break;
     case LCD_CLK_SRC_XTAL:
-        panel->resolution_hz = rtc_clk_xtal_freq_get() * 1000000 / LCD_PERIPH_CLOCK_PRE_SCALE;
+        panel->resolution_hz = esp_clk_xtal_freq() / LCD_PERIPH_CLOCK_PRE_SCALE;
         break;
     default:
         ESP_RETURN_ON_FALSE(false, ESP_ERR_NOT_SUPPORTED, TAG,  "unsupported clock source: %d", clk_src);

components/esp_lcd/test_apps/i80_lcd/main/test_i80_lcd_panel.c

@@ -30,6 +30,7 @@ TEST_CASE("i80_and_i2s_driver_co-existence", "[lcd][i2s]")
     esp_lcd_i80_bus_config_t bus_config = {
         .dc_gpio_num = TEST_LCD_DC_GPIO,
         .wr_gpio_num = TEST_LCD_PCLK_GPIO,
+        .clk_src = LCD_CLK_SRC_PLL160M,
         .data_gpio_nums = {
             TEST_LCD_DATA0_GPIO,
             TEST_LCD_DATA1_GPIO,
@@ -67,6 +68,7 @@ TEST_CASE("lcd_i80_device_swap_color_bytes", "[lcd]")
     esp_lcd_i80_bus_config_t bus_config = {
         .dc_gpio_num = TEST_LCD_DC_GPIO,
         .wr_gpio_num = TEST_LCD_PCLK_GPIO,
+        .clk_src = LCD_CLK_SRC_PLL160M,
         .data_gpio_nums = {
             TEST_LCD_DATA0_GPIO,
             TEST_LCD_DATA1_GPIO,
@@ -129,6 +131,7 @@ TEST_CASE("lcd_i80_device_clock_mode", "[lcd]")
     esp_lcd_i80_bus_config_t bus_config = {
         .dc_gpio_num = TEST_LCD_DC_GPIO,
         .wr_gpio_num = TEST_LCD_PCLK_GPIO,
+        .clk_src = LCD_CLK_SRC_PLL160M,
         .data_gpio_nums = {
             TEST_LCD_DATA0_GPIO,
             TEST_LCD_DATA1_GPIO,
@@ -188,6 +191,7 @@ TEST_CASE("lcd_i80_bus_and_device_allocation", "[lcd]")
     esp_lcd_i80_bus_config_t bus_config = {
         .dc_gpio_num = TEST_LCD_DC_GPIO,
         .wr_gpio_num = TEST_LCD_PCLK_GPIO,
+        .clk_src = LCD_CLK_SRC_PLL160M,
         .data_gpio_nums = {
             TEST_LCD_DATA0_GPIO,
             TEST_LCD_DATA1_GPIO,
@@ -232,6 +236,7 @@ TEST_CASE("lcd_i80_bus_exclusively_owned_by_one_device", "[lcd]")
     esp_lcd_i80_bus_config_t bus_config = {
         .dc_gpio_num = TEST_LCD_DC_GPIO,
         .wr_gpio_num = TEST_LCD_PCLK_GPIO,
+        .clk_src = LCD_CLK_SRC_PLL160M,
         .data_gpio_nums = {
             TEST_LCD_DATA0_GPIO,
             TEST_LCD_DATA1_GPIO,
@@ -267,6 +272,7 @@ TEST_CASE("lcd_panel_i80_io_test", "[lcd]")
     esp_lcd_i80_bus_config_t bus_config = {
         .dc_gpio_num = TEST_LCD_DC_GPIO,
         .wr_gpio_num = TEST_LCD_PCLK_GPIO,
+        .clk_src = LCD_CLK_SRC_PLL160M,
         .data_gpio_nums = {
             TEST_LCD_DATA0_GPIO,
             TEST_LCD_DATA1_GPIO,
@@ -389,6 +395,7 @@ TEST_CASE("lcd_panel_with_i80_interface_(st7789, 8bits)", "[lcd]")
     esp_lcd_i80_bus_config_t bus_config = {
         .dc_gpio_num = TEST_LCD_DC_GPIO,
         .wr_gpio_num = TEST_LCD_PCLK_GPIO,
+        .clk_src = LCD_CLK_SRC_PLL160M,
         .data_gpio_nums = {
             TEST_LCD_DATA0_GPIO,
             TEST_LCD_DATA1_GPIO,

components/esp_pm/pm_impl.c

@@ -254,7 +254,7 @@ esp_err_t esp_pm_configure(const void* vconfig)
         return ESP_ERR_INVALID_ARG;
     }
 
-    int xtal_freq_mhz = (int) rtc_clk_xtal_freq_get();
+    int xtal_freq_mhz = esp_clk_xtal_freq() / MHZ;
     if (min_freq_mhz < xtal_freq_mhz && min_freq_mhz * MHZ / REF_CLK_FREQ < REF_CLK_DIV_MIN) {
         ESP_LOGW(TAG, "min_freq_mhz should be >= %d", REF_CLK_FREQ * REF_CLK_DIV_MIN / MHZ);
         return ESP_ERR_INVALID_ARG;
@@ -768,7 +768,7 @@ void esp_pm_impl_init(void)
     }
 
 #ifdef CONFIG_PM_DFS_INIT_AUTO
-    int xtal_freq = (int) rtc_clk_xtal_freq_get();
+    int xtal_freq_mhz = esp_clk_xtal_freq() / MHZ;
 #if CONFIG_IDF_TARGET_ESP32
     esp_pm_config_esp32_t cfg = {
 #elif CONFIG_IDF_TARGET_ESP32S2
@@ -783,7 +783,7 @@ void esp_pm_impl_init(void)
     esp_pm_config_esp32c2_t cfg = {
 #endif
         .max_freq_mhz = DEFAULT_CPU_FREQ,
-        .min_freq_mhz = xtal_freq,
+        .min_freq_mhz = xtal_freq_mhz,
     };
 
     esp_pm_configure(&cfg);

components/esp_pm/test/test_pm.c

@@ -39,7 +39,7 @@ TEST_CASE("Can dump power management lock stats", "[pm]")
 
 static void switch_freq(int mhz)
 {
-    int xtal_freq = rtc_clk_xtal_freq_get();
+    int xtal_freq_mhz = esp_clk_xtal_freq() / MHZ;
 #if CONFIG_IDF_TARGET_ESP32
     esp_pm_config_esp32_t pm_config = {
 #elif CONFIG_IDF_TARGET_ESP32S2
@@ -52,7 +52,7 @@ static void switch_freq(int mhz)
     esp_pm_config_esp32h2_t pm_config = {
 #endif
         .max_freq_mhz = mhz,
-        .min_freq_mhz = MIN(mhz, xtal_freq),
+        .min_freq_mhz = MIN(mhz, xtal_freq_mhz),
     };
     ESP_ERROR_CHECK( esp_pm_configure(&pm_config) );
     printf("Waiting for frequency to be set to %d MHz...\n", mhz);
@@ -86,7 +86,7 @@ TEST_CASE("Can switch frequency using esp_pm_configure", "[pm]")
 static void light_sleep_enable(void)
 {
     int cur_freq_mhz = esp_clk_cpu_freq() / MHZ;
-    int xtal_freq = (int) rtc_clk_xtal_freq_get();
+    int xtal_freq = esp_clk_xtal_freq() / MHZ;
 
 #if CONFIG_IDF_TARGET_ESP32
     esp_pm_config_esp32_t pm_config = {

components/esp_system/port/cpu_start.c

@@ -71,7 +71,7 @@
 #include "hal/efuse_ll.h"
 #include "soc/periph_defs.h"
 #include "esp_cpu.h"
-#include "soc/rtc.h"
+#include "esp_private/esp_clk.h"
 
 #if CONFIG_ESP32_TRAX || CONFIG_ESP32S2_TRAX || CONFIG_ESP32S3_TRAX
 #include "esp_private/trax.h"
@@ -544,7 +544,7 @@ void IRAM_ATTR call_start_cpu0(void)
 
 #ifndef CONFIG_IDF_ENV_FPGA // TODO: on FPGA it should be possible to configure this, not currently working with APB_CLK_FREQ changed
 #ifdef CONFIG_ESP_CONSOLE_UART
-    uint32_t clock_hz = rtc_clk_apb_freq_get();
+    uint32_t clock_hz = esp_clk_apb_freq();
 #if CONFIG_IDF_TARGET_ESP32S3 || CONFIG_IDF_TARGET_ESP32C3 || CONFIG_IDF_TARGET_ESP32H2 || CONFIG_IDF_TARGET_ESP32C2
     clock_hz = UART_CLK_FREQ_ROM; // From esp32-s3 on, UART clock source is selected to XTAL in ROM
 #endif

components/esp_timer/src/esp_timer_impl_systimer.c

@@ -14,7 +14,7 @@
 #include "esp_compiler.h"
 #include "soc/periph_defs.h"
 #include "soc/soc_caps.h"
-#include "soc/rtc.h"
+#include "esp_private/esp_clk.h"
 #include "freertos/FreeRTOS.h"
 #include "hal/systimer_ll.h"
 #include "hal/systimer_types.h"
@@ -113,7 +113,8 @@ esp_err_t esp_timer_impl_early_init(void)
     systimer_hal_init(&systimer_hal);
 
 #if !SOC_SYSTIMER_FIXED_TICKS_US
-    assert(rtc_clk_xtal_freq_get() == 40 && "update the step for xtal to support other XTAL:APB frequency ratios");
+    assert(esp_clk_xtal_freq() == (40 * 1000000) &&
+            "update the step for xtal to support other XTAL:APB frequency ratios");
     systimer_hal_set_steps_per_tick(&systimer_hal, 0, 2); // for xtal
     systimer_hal_set_steps_per_tick(&systimer_hal, 1, 1); // for pll
 #endif

components/esp_wifi/src/wifi_init.c

@@ -12,7 +12,7 @@
 #include "esp_pm.h"
 #include "esp_sleep.h"
 #include "esp_private/pm_impl.h"
-#include "soc/rtc.h"
+#include "esp_private/esp_clk.h"
 #include "esp_wpa.h"
 #include "esp_netif.h"
 #include "esp_coexist_internal.h"
@@ -264,8 +264,8 @@ void wifi_apb80m_request(void)
 {
     assert(s_wifi_modem_sleep_lock);
     esp_pm_lock_acquire(s_wifi_modem_sleep_lock);
-    if (rtc_clk_apb_freq_get() != APB_CLK_FREQ) {
-        ESP_LOGE(__func__, "WiFi needs 80MHz APB frequency to work, but got %dHz", rtc_clk_apb_freq_get());
+    if (esp_clk_apb_freq() != APB_CLK_FREQ) {
+        ESP_LOGE(__func__, "WiFi needs 80MHz APB frequency to work, but got %dHz", esp_clk_apb_freq());
     }
 }
 

components/hal/esp32c3/include/hal/rmt_ll.h

@@ -98,7 +98,7 @@ static inline void rmt_ll_set_group_clock_src(rmt_dev_t *dev, uint32_t channel,
     case RMT_CLK_SRC_APB:
         dev->sys_conf.sclk_sel = 1;
         break;
-    case RMT_CLK_SRC_FAST_RC:
+    case RMT_CLK_SRC_RC_FAST:
         dev->sys_conf.sclk_sel = 2;
         break;
     case RMT_CLK_SRC_XTAL:
@@ -707,7 +707,7 @@ static inline rmt_clock_source_t rmt_ll_get_group_clock_src(rmt_dev_t *dev, uint
         clk_src = RMT_CLK_SRC_APB;
         break;
     case 2:
-        clk_src = RMT_CLK_SRC_FAST_RC;
+        clk_src = RMT_CLK_SRC_RC_FAST;
         break;
     case 3:
         clk_src = RMT_CLK_SRC_XTAL;

components/hal/esp32c3/include/hal/temperature_sensor_ll.h

@@ -81,7 +81,7 @@ static inline void temperature_sensor_ll_clk_sel(temperature_sensor_clk_src_t cl
         case TEMPERATURE_SENSOR_CLK_SRC_XTAL:
             clk_sel = 1;
             break;
-        case TEMPERATURE_SENSOR_CLK_SRC_FAST_RC:
+        case TEMPERATURE_SENSOR_CLK_SRC_RC_FAST:
             clk_sel = 0;
             break;
         default:

components/hal/esp32h2/include/hal/rmt_ll.h

@@ -98,7 +98,7 @@ static inline void rmt_ll_set_group_clock_src(rmt_dev_t *dev, uint32_t channel,
     case RMT_CLK_SRC_APB:
         dev->sys_conf.sclk_sel = 1;
         break;
-    case RMT_CLK_SRC_FAST_RC:
+    case RMT_CLK_SRC_RC_FAST:
         dev->sys_conf.sclk_sel = 2;
         break;
     case RMT_CLK_SRC_XTAL:
@@ -707,7 +707,7 @@ static inline rmt_clock_source_t rmt_ll_get_group_clock_src(rmt_dev_t *dev, uint
         clk_src = RMT_CLK_SRC_APB;
         break;
     case 2:
-        clk_src = RMT_CLK_SRC_FAST_RC;
+        clk_src = RMT_CLK_SRC_RC_FAST;
         break;
     case 3:
         clk_src = RMT_CLK_SRC_XTAL;

components/hal/esp32h2/include/hal/temperature_sensor_ll.h

@@ -82,7 +82,7 @@ static inline void temperature_sensor_ll_clk_sel(temperature_sensor_clk_src_t cl
         case TEMPERATURE_SENSOR_CLK_SRC_XTAL:
             clk_sel = 1;
             break;
-        case TEMPERATURE_SENSOR_CLK_SRC_FAST_RC:
+        case TEMPERATURE_SENSOR_CLK_SRC_RC_FAST:
             clk_sel = 0;
             break;
         default:

components/hal/esp32s3/include/hal/rmt_ll.h

@@ -98,7 +98,7 @@ static inline void rmt_ll_set_group_clock_src(rmt_dev_t *dev, uint32_t channel,
     case RMT_CLK_SRC_APB:
         dev->sys_conf.sclk_sel = 1;
         break;
-    case RMT_CLK_SRC_FAST_RC:
+    case RMT_CLK_SRC_RC_FAST:
         dev->sys_conf.sclk_sel = 2;
         break;
     case RMT_CLK_SRC_XTAL:
@@ -744,7 +744,7 @@ static inline rmt_clock_source_t rmt_ll_get_group_clock_src(rmt_dev_t *dev, uint
         clk_src = RMT_CLK_SRC_APB;
         break;
     case 2:
-        clk_src = RMT_CLK_SRC_FAST_RC;
+        clk_src = RMT_CLK_SRC_RC_FAST;
         break;
     case 3:
         clk_src = RMT_CLK_SRC_XTAL;

components/hal/include/hal/lcd_types.h

@@ -6,33 +6,19 @@
 
 #pragma once
 
+#include "soc/soc_caps.h"
+#include "soc/clk_tree_defs.h"
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#if SOC_LCD_I80_SUPPORTED || SOC_LCD_RGB_SUPPORTED
 /**
  * @brief LCD clock source
- * @note User should select the clock source based on the real requirement:
- * @verbatim embed:rst:leading-asterisk
- * +---------------------+-------------------------+----------------------------+
- * | LCD clock source    | Features                | Power Management           |
- * +=====================+=========================+============================+
- * | LCD_CLK_SRC_PLL160M | High resolution         | ESP_PM_APB_FREQ_MAX lock   |
- * +---------------------+-------------------------+----------------------------+
- * | LCD_CLK_SRC_PLL240M | High resolution         | ESP_PM_APB_FREQ_MAX lock   |
- * +---------------------+-------------------------+----------------------------+
- * | LCD_CLK_SRC_APLL    | Configurable resolution | ESP_PM_NO_LIGHT_SLEEP lock |
- * +---------------------+-------------------------+----------------------------+
- * | LCD_CLK_SRC_XTAL    | Medium resolution       | No PM lock                 |
- * +---------------------+-------------------------+----------------------------+
- * @endverbatim
  */
-typedef enum {
-    LCD_CLK_SRC_PLL160M, /*!< Select PLL160M as the source clock */
-    LCD_CLK_SRC_PLL240M, /*!< Select PLL240M as the source clock */
-    LCD_CLK_SRC_APLL,    /*!< Select APLL as the source clock */
-    LCD_CLK_SRC_XTAL,    /*!< Select XTAL as the source clock */
-} lcd_clock_source_t;
+typedef soc_periph_lcd_clk_src_t lcd_clock_source_t;
+#endif
 
 #ifdef __cplusplus
 }

components/hal/include/hal/rmt_types.h

@@ -6,6 +6,8 @@
 
 #pragma once
 
+#include "soc/clk_tree_defs.h"
+
 #ifdef __cplusplus
 extern "C" {
 #endif
@@ -14,13 +16,7 @@ extern "C" {
  * @brief RMT group clock source
  * @note User should select the clock source based on the power and resolution requirement
  */
-typedef enum {
-    RMT_CLK_SRC_NONE,     /*!< No clock source is selected */
-    RMT_CLK_SRC_REFTICK,  /*!< Select REF_TICK as the source clock */
-    RMT_CLK_SRC_APB,      /*!< Select APB as the source clock */
-    RMT_CLK_SRC_FAST_RC,  /*!< Select internal fast RC oscillator as the source clock */
-    RMT_CLK_SRC_XTAL,     /*!< Select XTAL as the source clock */
-} rmt_clock_source_t;
+typedef soc_periph_rmt_clk_src_t rmt_clock_source_t;
 
 /**
  * @brief The layout of RMT symbol stored in memory, which is decided by the hardware design

components/hal/include/hal/temperature_sensor_types.h

@@ -6,32 +6,16 @@
 
 #pragma once
 
+#include "soc/clk_tree_defs.h"
+
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
  * @brief temperature sensor clock source
- * @note User should select the clock source based on the real requirement:
- * @verbatim embed:rst:leading-asterisk
- * +------------------------------------+-------------------------+----------------------------+
- * | temperature sensor clock source    | Features                | Power Management           |
- * +====================================+=========================+============================+
- * | TEMPERATURE_SENSOR_CLK_SRC_XTAL    | external clock source   |          no lock           |
- * +------------------------------------+-------------------------+----------------------------+
- * | TEMPERATURE_SENSOR_CLK_SRC_FAST_RC | On board clock source   |          no lock           |
- * +------------------------------------+-------------------------+----------------------------+
- * @endverbatim
  */
-typedef enum {
-    TEMPERATURE_SENSOR_CLK_SRC_DEFAULT = 0,
-#if SOC_TEMPERATURE_SENSOR_SUPPORT_XTAL
-    TEMPERATURE_SENSOR_CLK_SRC_XTAL = 1,  /*!< Select XTAL as the source clock */
-#endif
-#if SOC_TEMPERATURE_SENSOR_SUPPORT_FAST_RC
-    TEMPERATURE_SENSOR_CLK_SRC_FAST_RC = 2,  /*!< Select FOSC as the source clock */
-#endif
-} temperature_sensor_clk_src_t;
+typedef soc_periph_temperature_sensor_clk_src_t temperature_sensor_clk_src_t;
 
 #ifdef __cplusplus
 }

components/hal/include/hal/timer_types.h

@@ -1,12 +1,12 @@
 /*
- * SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
 
 #pragma once
 
-#include "soc/soc_caps.h"
+#include "soc/clk_tree_defs.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -14,24 +14,8 @@ extern "C" {
 
 /**
  * @brief GPTimer clock source
- * @note The clock source listed here is not supported on all targets
- * @note User should select the clock source based on real requirements:
- * @verbatim embed:rst:leading-asterisk
- * +----------------------+----------------------------------+--------------------------+
- * | GPTimer clock source | Features                         | Power Management         |
- * +======================+==================================+==========================+
- * | GPTIMER_CLK_SRC_APB  | High resolution                  | ESP_PM_APB_FREQ_MAX lock |
- * +----------------------+----------------------------------+--------------------------+
- * | GPTIMER_CLK_SRC_XTAL | Medium resolution, high accuracy | No PM lock               |
- * +----------------------+----------------------------------+--------------------------+
- * @endverbatim
  */
-typedef enum {
-    GPTIMER_CLK_SRC_APB,  /*!< Select APB as the source clock */
-#if SOC_TIMER_GROUP_SUPPORT_XTAL
-    GPTIMER_CLK_SRC_XTAL, /*!< Select XTAL as the source clock */
-#endif
-} gptimer_clock_source_t;
+typedef soc_periph_gptimer_clk_src_t gptimer_clock_source_t;
 
 /**
  * @brief GPTimer count direction

components/soc/esp32/include/soc/clk_tree_defs.h

@@ -0,0 +1,137 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ ************************* ESP32 Root Clock Source ****************************
+ * 1) Internal 8MHz RC Oscillator: RC_FAST (usually referred as FOSC or CK8M/CLK8M in TRM and reg. description)
+ *
+ *    This RC oscillator generates a ~8.5MHz clock signal output as the RC_FAST_CLK.
+ *    The ~8.5MHz signal output is also passed into a configurable divider, which by default divides the input clock
+ *    frequency by 256, to generate a RC_FAST_D256_CLK (usually referred as 8md256 or simply d256 in reg. description).
+ *
+ *    The exact frequency of RC_FAST_CLK can be computed in runtime through calibration on the RC_FAST_D256_CLK.
+ *
+ * 2) External 2~40MHz Crystal Clock: XTAL
+ *
+ * 3) Internal 150kHz RC Oscillator: RC_SLOW (usually referrred as RTC in TRM or reg. description)
+ *
+ *    This RC oscillator generates a ~150kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock
+ *    can be computed in runtime through calibration.
+ *
+ * 4) External 32kHz Crystal Clock (optional): XTAL32K
+ *
+ *    The clock source for this XTAL32K_CLK can be either a 32kHz crystal connecting to the 32K_XP and 32K_XN pins
+ *    or a 32kHz clock signal generated by an external circuit. The external signal must be connected to the 32K_XN pin.
+ *    Additionally, a 1nF capacitor must be placed between the 32K_XP pin and ground. In this case, the 32K_XP pin
+ *    cannot be used as a GPIO pin.
+ *
+ *    XTAL32K_CLK can also be calibrated to get its exact frequency.
+ */
+
+/* With the default value of CK8M_DFREQ = 172, RC_FAST clock frequency is 8.5 MHz +/- 7% */
+#define SOC_CLK_RC_FAST_FREQ_APPROX         8500000
+#define SOC_CLK_RC_SLOW_FREQ_APPROX         150000
+#define SOC_CLK_RC_FAST_D256_FREQ_APPROX    (SOC_CLK_RC_FAST_FREQ_APPROX / 256)
+#define SOC_CLK_XTAL32K_FREQ_APPROX         32768
+
+/**
+ * @brief Root clock
+ * Naming convention: SOC_ROOT_CLK_{loc}_{type}_<attr>
+ * {loc}: EXT, INT
+ * {type}: XTAL, RC
+ * <attr> - optional: <frequency>, FAST, SLOW
+ */
+typedef enum {
+    SOC_ROOT_CLK_INT_RC_FAST,          /*!< Internal 8MHz RC oscillator */
+    SOC_ROOT_CLK_INT_RC_SLOW,          /*!< Internal 150kHz RC oscillator */
+    SOC_ROOT_CLK_EXT_XTAL,             /*!< External 2~40MHz crystal */
+    SOC_ROOT_CLK_EXT_XTAL32K,          /*!< External 32kHz crystal/clock signal */
+} soc_root_clk_t;
+
+/**
+ * @brief CPU_CLK mux inputs, which are the supported clock sources for the CPU_CLK
+ */
+typedef enum {
+    SOC_CPU_CLK_SRC_XTAL,              /*!< Select XTAL_CLK as CPU_CLK source */
+    SOC_CPU_CLK_SRC_PLL,               /*!< Select PLL_CLK as CPU_CLK source (PLL_CLK is the output of 40MHz crystal oscillator frequency multiplier, can be 480MHz or 320MHz) */
+    SOC_CPU_CLK_SRC_RC_FAST,           /*!< Select RC_FAST_CLK as CPU_CLK source */
+    SOC_CPU_CLK_SRC_APLL,              /*!< Select APLL_CLK as CPU_CLK source */
+} soc_cpu_clk_src_t;
+
+/**
+ * @brief RTC_SLOW_CLK mux inputs, which are the supported clock sources for the RTC_SLOW_CLK
+ */
+typedef enum {
+    SOC_RTC_SLOW_CLK_SRC_RC_SLOW,      /*!< Select RC_SLOW_CLK as RTC_SLOW_CLK source */
+    SOC_RTC_SLOW_CLK_SRC_XTAL32K,      /*!< Select XTAL32K_CLK as RTC_SLOW_CLK source */
+    SOC_RTC_SLOW_CLK_SRC_RC_FAST_D256, /*!< Select RC_FAST_D256_CLK (referred as FOSC_DIV or 8m_d256/8md256 in TRM and reg. description) as RTC_SLOW_CLK source */
+} soc_rtc_slow_clk_src_t;
+
+/**
+ * @brief RTC_FAST_CLK mux inputs, which are the supported clock sources for the RTC_FAST_CLK
+ */
+typedef enum {
+    SOC_RTC_FAST_CLK_SRC_XTAL_D4,      /*!< Select XTAL_D4_CLK (may referred as XTAL_CLK_DIV_4) as RTC_FAST_CLK source */
+    SOC_RTC_FAST_CLK_SRC_XTAL_DIV = SOC_RTC_FAST_CLK_SRC_XTAL_D4, /*!< Alias name for `SOC_RTC_FAST_CLK_SRC_XTAL_D4` */
+    SOC_RTC_FAST_CLK_SRC_RC_FAST,      /*!< Select RC_FAST_CLK as RTC_FAST_CLK source */
+} soc_rtc_fast_clk_src_t;
+
+/**
+ * @brief Supported clock sources for modules (CPU, peripherials, RTC, etc.)
+ * Naming convention: SOC_MOD_CLK_{<upstream>clock_name}_<attr>
+ * {<upstream>clock_name}: APB, APLL, (BB)PLL, etc.
+ * <attr> - optional: FAST, SLOW, D<divider>, F<freq>
+ */
+typedef enum {
+    // For CPU domain
+    SOC_MOD_CLK_CPU = 1,                       /*< CPU_CLK can be sourced from XTAL, PLL, RC_FAST, or APLL by configuring soc_cpu_clk_src_t */
+    // For RTC domain
+    SOC_MOD_CLK_RTC_FAST = 2,                  /*< RTC_FAST_CLK can be sourced from XTAL_D4 or RC_FAST by configuring soc_rtc_fast_clk_src_t */
+    SOC_MOD_CLK_RTC_SLOW = 3,                  /*< RTC_SLOW_CLK can be sourced from RC_SLOW, XTAL32K, or RC_FAST_D256 by configuring soc_rtc_slow_clk_src_t */
+    // For digital domain: peripherals, WIFI, BLE
+    SOC_MOD_CLK_APB = 4,                       /*< APB_CLK is highly dependent on the CPU_CLK source */
+    SOC_MOD_CLK_PLL_D2 = 5,                    /*< PLL_D2_CLK is derived from PLL, it has a fixed divider of 2 */
+    SOC_MOD_CLK_XTAL32K = 6,                   /*< XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals */
+    SOC_MOD_CLK_RC_FAST = 7,                   /*< RC_FAST_CLK comes from the internal 8MHz rc oscillator, passing a clock gating to the peripherals */
+    SOC_MOD_CLK_RC_FAST_D256 = 8,              /*< RC_FAST_D256_CLK comes from the internal 8MHz rc oscillator, divided by 256, and passing a clock gating to the peripherals */
+    SOC_MOD_CLK_XTAL = 9,                      /*< XTAL_CLK comes from the external crystal (2~40MHz) */
+    SOC_MOD_CLK_APB_F1M = 10,                  /*< APB_F1M_CLK (referred as REF_TICK in TRM) is derived from APB, it has a fixed frequency of 1MHz even when APB frequency changes */
+    SOC_MOD_CLK_APLL = 11,                     /*< APLL is sourced from PLL, and its frequency is configurable through APLL configuration registers */
+} soc_module_clk_t;
+
+
+// List clock sources available to each peripherial
+// soc_module_clk_src_t enum starts from 1 to save enum = 0 for AUTO selection
+
+typedef enum {
+    GPTIMER_CLK_SRC_APB = SOC_MOD_CLK_APB,                      /*!< Select APB as the source clock */
+} soc_periph_gptimer_clk_src_t;
+
+typedef enum {
+    LCD_CLK_SRC_PLL160M = SOC_MOD_CLK_PLL_D2,                   /*!< Select PLL_D2 (160MHz) as the source clock */
+    LCD_CLK_SRC_APLL = SOC_MOD_CLK_APLL,                        /*!< Select APLL as the source clock */
+    LCD_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,                        /*!< Select XTAL as the source clock */
+} soc_periph_lcd_clk_src_t;
+
+typedef enum {
+    RMT_CLK_SRC_NONE = 0,                                       /*!< No clock source is selected */
+    RMT_CLK_SRC_REFTICK = SOC_MOD_CLK_APB_F1M,                  /*!< Select REF_TICK (1MHz) as the source clock */
+    RMT_CLK_SRC_APB = SOC_MOD_CLK_APB,                          /*!< Select APB as the source clock */
+} soc_periph_rmt_clk_src_t;
+
+// ESP32 does not support temperature sensor, it is only to pass ci check_public_headers
+typedef enum {
+    TEMPERATURE_SENSOR_SRC_NA,
+} soc_periph_temperature_sensor_clk_src_t;
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32c2/include/soc/clk_tree_defs.h

@@ -0,0 +1,124 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ ************************ ESP32C2 Root Clock Source ***************************
+ * 1) Internal 20MHz RC Oscillator: RC_FAST (usually referred as FOSC or CK8M/CLK8M in TRM and reg. description)
+ *
+ *    This RC oscillator generates a ~17.5MHz clock signal output as the RC_FAST_CLK.
+ *    The ~17.5MHz signal output is also passed into a configurable divider, which by default divides the input clock
+ *    frequency by 256, to generate a RC_FAST_D256_CLK (usually referred as 8md256 or simply d256 in reg. description).
+ *
+ *    The exact frequency of RC_FAST_CLK can be computed in runtime through calibration on the RC_FAST_D256_CLK.
+ *
+ * 2) External 40MHz Crystal Clock: XTAL
+ *
+ * 3) Internal 1500kHz RC Oscillator: RC_SLOW (usually referrred as RTC in TRM or reg. description)
+ *
+ *    This RC oscillator generates a ~150kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock
+ *    can be computed in runtime through calibration.
+ *
+ * 4) External Slow Clock (optional): XTAL32K
+ *
+ *    A clock signal generated by an external circuit can be connected to the 32K_XN pin to be the clock source for the
+ *    RTC_SLOW_CLK. In such case, a 1nF capacitor should be placed between the 32K_XN pin and ground, so the 32K_XP pin
+ *    cannot be used as a GPIO pin.
+ *
+ *    XTAL32K_CLK can also be calibrated to get its exact frequency.
+ */
+
+/* With the default value of CK8M_DFREQ = 100, RC_FAST clock frequency is 17.5 MHz +/- 7% */
+#define SOC_CLK_RC_FAST_FREQ_APPROX         17500000
+#define SOC_CLK_RC_SLOW_FREQ_APPROX         150000
+#define SOC_CLK_RC_FAST_D256_FREQ_APPROX    (SOC_CLK_RC_FAST_FREQ_APPROX / 256)
+#define SOC_CLK_XTAL32K_FREQ_APPROX         32768
+
+/**
+ * @brief Root clock
+ * Naming convention: SOC_ROOT_CLK_{loc}_{type}_<attr>
+ * {loc}: EXT, INT
+ * {type}: XTAL, RC
+ * <attr> - optional: <frequency>, FAST, SLOW
+ */
+typedef enum {
+    SOC_ROOT_CLK_INT_RC_FAST,          /*!< Internal 8MHz RC oscillator */
+    SOC_ROOT_CLK_INT_RC_SLOW,          /*!< Internal 150kHz RC oscillator */
+    SOC_ROOT_CLK_EXT_XTAL,             /*!< External 40MHz crystal */
+    SOC_ROOT_CLK_EXT_XTAL32K,          /*!< External ~32kHz clock signal */
+} soc_root_clk_t;
+
+/**
+ * @brief CPU_CLK mux inputs, which are the supported clock sources for the CPU_CLK
+ */
+typedef enum {
+    SOC_CPU_CLK_SRC_XTAL,              /*!< Select XTAL_CLK as CPU_CLK source */
+    SOC_CPU_CLK_SRC_PLL,               /*!< Select PLL_CLK as CPU_CLK source (PLL_CLK is the output of 40MHz crystal oscillator frequency multiplier, 480MHz) */
+    SOC_CPU_CLK_SRC_RC_FAST,           /*!< Select RC_FAST_CLK as CPU_CLK source */
+} soc_cpu_clk_src_t;
+
+/**
+ * @brief RTC_SLOW_CLK mux inputs, which are the supported clock sources for the RTC_SLOW_CLK
+ */
+typedef enum {
+    SOC_RTC_SLOW_CLK_SRC_RC_SLOW,      /*!< Select RC_SLOW_CLK as RTC_SLOW_CLK source */
+    SOC_RTC_SLOW_CLK_SRC_XTAL32K,      /*!< Select XTAL32K_CLK as RTC_SLOW_CLK source */
+    SOC_RTC_SLOW_CLK_SRC_RC_FAST_D256, /*!< Select RC_FAST_D256_CLK (referred as FOSC_DIV or 8m_d256/8md256 in TRM and reg. description) as RTC_SLOW_CLK source */
+} soc_rtc_slow_clk_src_t;
+
+/**
+ * @brief RTC_FAST_CLK mux inputs, which are the supported clock sources for the RTC_FAST_CLK
+ */
+typedef enum {
+    SOC_RTC_FAST_CLK_SRC_XTAL_D2,      /*!< Select XTAL_D2_CLK (may referred as XTAL_CLK_DIV_2) as RTC_FAST_CLK source */
+    SOC_RTC_FAST_CLK_SRC_XTAL_DIV = SOC_RTC_FAST_CLK_SRC_XTAL_D2, /*!< Alias name for `SOC_RTC_FAST_CLK_SRC_XTAL_D2` */
+    SOC_RTC_FAST_CLK_SRC_RC_FAST,      /*!< Select RC_FAST_CLK as RTC_FAST_CLK source */
+} soc_rtc_fast_clk_src_t;
+
+/**
+ * @brief Supported clock sources for modules (CPU, peripherials, RTC, etc.)
+ * Naming convention: SOC_MOD_CLK_{<upstream>clock_name}_<attr>
+ * {<upstream>clock_name}: (BB)PLL etc.
+ * <attr> - optional: FAST, SLOW, D<divider>, F<freq>
+ */
+typedef enum {
+    // For CPU domain
+    SOC_MOD_CLK_CPU = 1,                       /*< CPU_CLK can be sourced from XTAL, PLL, or RC_FAST by configuring soc_cpu_clk_src_t */
+    // For RTC domain
+    SOC_MOD_CLK_RTC_FAST = 2,                  /*< RTC_FAST_CLK can be sourced from XTAL_D2 or RC_FAST by configuring soc_rtc_fast_clk_src_t */
+    SOC_MOD_CLK_RTC_SLOW = 3,                  /*< RTC_SLOW_CLK can be sourced from RC_SLOW, XTAL32K, or RC_FAST_D256 by configuring soc_rtc_slow_clk_src_t */
+    // For digital domain: peripherals, WIFI, BLE
+    SOC_MOD_CLK_PLL_F40M = 4,                  /*< PLL_F40M_CLK is derived from PLL, and has a fixed frequency of 40MHz */
+    SOC_MOD_CLK_PLL_F60M = 5,                  /*< PLL_F60M_CLK is derived from PLL, and has a fixed frequency of 60MHz */
+    SOC_MOD_CLK_PLL_F80M = 6,                  /*< PLL_F80M_CLK is derived from PLL, and has a fixed frequency of 80MHz */
+    SOC_MOD_CLK_XTAL32K = 7,                   /*< XTAL32K_CLK comes from the external 32kHz clock signal, passing a clock gating to the peripherals */
+    SOC_MOD_CLK_RC_FAST = 8,                   /*< RC_FAST_CLK comes from the internal 20MHz rc oscillator, passing a clock gating to the peripherals */
+    SOC_MOD_CLK_RC_FAST_D256 = 9,              /*< RC_FAST_D256_CLK comes from the internal 20MHz rc oscillator, divided by 256, and passing a clock gating to the peripherals */
+    SOC_MOD_CLK_XTAL = 10,                     /*< XTAL_CLK comes from the external 40MHz crystal */
+} soc_module_clk_t;
+
+
+// List clock sources available to each peripherial
+// soc_module_clk_src_t enum starts from 1 to save enum = 0 for AUTO selection
+
+typedef enum {
+    GPTIMER_CLK_SRC_APB = SOC_MOD_CLK_PLL_F40M,                      /*!< Select APB as the source clock */
+    GPTIMER_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,                         /*!< Select XTAL as the source clock */
+} soc_periph_gptimer_clk_src_t;
+
+typedef enum {
+    TEMPERATURE_SENSOR_CLK_SRC_DEFAULT = 0,                          /*!< Use default clock selection */
+    TEMPERATURE_SENSOR_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,              /*!< Select XTAL as the source clock */
+    TEMPERATURE_SENSOR_CLK_SRC_RC_FAST = SOC_MOD_CLK_RC_FAST,        /*!< Select RC_FAST as the source clock */
+} soc_periph_temperature_sensor_clk_src_t;
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32c2/include/soc/regi2c_defs.h

@@ -20,7 +20,6 @@
 
 #define ANA_I2C_SAR_FORCE_PD BIT(18)
 #define ANA_I2C_BBPLL_M      BIT(17) /* Clear to enable BBPLL */
-#define ANA_I2C_APLL_M       BIT(14) /* Clear to enable APLL */
 
 
 #define ANA_CONFIG2_REG  0x6000E048

components/soc/esp32c2/include/soc/rtc_cntl_reg.h

@@ -661,7 +661,7 @@ RO CPU.*/
 #define RTC_CNTL_ANA_CLK_RTC_SEL_V  0x3
 #define RTC_CNTL_ANA_CLK_RTC_SEL_S  30
 /* RTC_CNTL_FAST_CLK_RTC_SEL :  ;bitpos:[29] ;default: 1'b0 ; */
-/*description: fast_clk_rtc sel. 0: XTAL div 4.*/
+/*description: fast_clk_rtc sel. 0: XTAL div 2.*/
 #define RTC_CNTL_FAST_CLK_RTC_SEL    (BIT(29))
 #define RTC_CNTL_FAST_CLK_RTC_SEL_M  (BIT(29))
 #define RTC_CNTL_FAST_CLK_RTC_SEL_V  0x1

components/soc/esp32c2/include/soc/rtc_cntl_struct.h

@@ -273,7 +273,7 @@ typedef volatile struct rtc_cntl_dev_s{
             uint32_t ck8m_force_pu                 :    1;  /*CK8M force power up*/
             uint32_t xtal_global_force_gating      :    1;  /*Need add desc*/
             uint32_t xtal_global_force_nogating    :    1;  /*Need add desc*/
-            uint32_t fast_clk_rtc_sel              :    1;  /*fast_clk_rtc sel. 0: XTAL div 4*/
+            uint32_t fast_clk_rtc_sel              :    1;  /*fast_clk_rtc sel. 0: XTAL div 2*/
             uint32_t ana_clk_rtc_sel               :    2;  /*Need add desc*/
         };
         uint32_t val;

components/soc/esp32c3/include/soc/clk_tree_defs.h

@@ -0,0 +1,133 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ ************************* ESP32C3 Root Clock Source ****************************
+ * 1) Internal 20MHz RC Oscillator: RC_FAST (usually referred as FOSC or CK8M/CLK8M in TRM and reg. description)
+ *
+ *    This RC oscillator generates a ~17.5MHz clock signal output as the RC_FAST_CLK.
+ *    The ~17.5MHz signal output is also passed into a configurable divider, which by default divides the input clock
+ *    frequency by 256, to generate a RC_FAST_D256_CLK (usually referred as 8md256 or simply d256 in reg. description).
+ *
+ *    The exact frequency of RC_FAST_CLK can be computed in runtime through calibration on the RC_FAST_D256_CLK.
+ *
+ * 2) External 40MHz Crystal Clock: XTAL
+ *
+ * 3) Internal 1500kHz RC Oscillator: RC_SLOW (usually referrred as RTC in TRM or reg. description)
+ *
+ *    This RC oscillator generates a ~150kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock
+ *    can be computed in runtime through calibration.
+ *
+ * 4) External 32kHz Crystal Clock (optional): XTAL32K
+ *
+ *    The clock source for this XTAL32K_CLK can be either a 32kHz crystal connecting to the 32K_XP and 32K_XN pins
+ *    or a 32kHz clock signal generated by an external circuit. The external signal must be connected to the 32K_XN pin.
+ *    Additionally, a 1nF capacitor must be placed between the 32K_XP pin and ground. In this case, the 32K_XP pin
+ *    cannot be used as a GPIO pin.
+ *
+ *    XTAL32K_CLK can also be calibrated to get its exact frequency.
+ */
+
+/* With the default value of CK8M_DFREQ = 100, RC_FAST clock frequency is 17.5 MHz +/- 7% */
+#define SOC_CLK_RC_FAST_FREQ_APPROX         17500000
+#define SOC_CLK_RC_SLOW_FREQ_APPROX         150000
+#define SOC_CLK_RC_FAST_D256_FREQ_APPROX    (SOC_CLK_RC_FAST_FREQ_APPROX / 256)
+#define SOC_CLK_XTAL32K_FREQ_APPROX         32768
+
+/**
+ * @brief Root clock
+ * Naming convention: SOC_ROOT_CLK_{loc}_{type}_<attr>
+ * {loc}: EXT, INT
+ * {type}: XTAL, RC
+ * <attr> - optional: <frequency>, FAST, SLOW
+ */
+typedef enum {
+    SOC_ROOT_CLK_INT_RC_FAST,          /*!< Internal 8MHz RC oscillator */
+    SOC_ROOT_CLK_INT_RC_SLOW,          /*!< Internal 150kHz RC oscillator */
+    SOC_ROOT_CLK_EXT_XTAL,             /*!< External 40MHz crystal */
+    SOC_ROOT_CLK_EXT_XTAL32K,          /*!< External 32kHz crystal/clock signal */
+} soc_root_clk_t;
+
+/**
+ * @brief CPU_CLK mux inputs, which are the supported clock sources for the CPU_CLK
+ */
+typedef enum {
+    SOC_CPU_CLK_SRC_XTAL,              /*!< Select XTAL_CLK as CPU_CLK source */
+    SOC_CPU_CLK_SRC_PLL,               /*!< Select PLL_CLK as CPU_CLK source (PLL_CLK is the output of 40MHz crystal oscillator frequency multiplier, can be 480MHz or 320MHz) */
+    SOC_CPU_CLK_SRC_RC_FAST,           /*!< Select RC_FAST_CLK as CPU_CLK source */
+} soc_cpu_clk_src_t;
+
+/**
+ * @brief RTC_SLOW_CLK mux inputs, which are the supported clock sources for the RTC_SLOW_CLK
+ */
+typedef enum {
+    SOC_RTC_SLOW_CLK_SRC_RC_SLOW,      /*!< Select RC_SLOW_CLK as RTC_SLOW_CLK source */
+    SOC_RTC_SLOW_CLK_SRC_XTAL32K,      /*!< Select XTAL32K_CLK as RTC_SLOW_CLK source */
+    SOC_RTC_SLOW_CLK_SRC_RC_FAST_D256, /*!< Select RC_FAST_D256_CLK (referred as FOSC_DIV or 8m_d256/8md256 in TRM and reg. description) as RTC_SLOW_CLK source */
+} soc_rtc_slow_clk_src_t;
+
+/**
+ * @brief RTC_FAST_CLK mux inputs, which are the supported clock sources for the RTC_FAST_CLK
+ */
+typedef enum {
+    SOC_RTC_FAST_CLK_SRC_XTAL_D2,      /*!< Select XTAL_D2_CLK (may referred as XTAL_CLK_DIV_2) as RTC_FAST_CLK source */
+    SOC_RTC_FAST_CLK_SRC_XTAL_DIV = SOC_RTC_FAST_CLK_SRC_XTAL_D2, /*!< Alias name for `SOC_RTC_FAST_CLK_SRC_XTAL_D2` */
+    SOC_RTC_FAST_CLK_SRC_RC_FAST,      /*!< Select RC_FAST_CLK as RTC_FAST_CLK source */
+} soc_rtc_fast_clk_src_t;
+
+/**
+ * @brief Supported clock sources for modules (CPU, peripherials, RTC, etc.)
+ * Naming convention: SOC_MOD_CLK_{<upstream>clock_name}_<attr>
+ * {<upstream>clock_name}: APB, (BB)PLL, etc.
+ * <attr> - optional: FAST, SLOW, D<divider>, F<freq>
+ */
+typedef enum {
+    // For CPU domain
+    SOC_MOD_CLK_CPU = 1,                       /*< CPU_CLK can be sourced from XTAL, PLL, or RC_FAST by configuring soc_cpu_clk_src_t */
+    // For RTC domain
+    SOC_MOD_CLK_RTC_FAST = 2,                  /*< RTC_FAST_CLK can be sourced from XTAL_D2 or RC_FAST by configuring soc_rtc_fast_clk_src_t */
+    SOC_MOD_CLK_RTC_SLOW = 3,                  /*< RTC_SLOW_CLK can be sourced from RC_SLOW, XTAL32K, or RC_FAST_D256 by configuring soc_rtc_slow_clk_src_t */
+    // For digital domain: peripherals, WIFI, BLE
+    SOC_MOD_CLK_APB = 4,                       /*< APB_CLK is highly dependent on the CPU_CLK source */
+    SOC_MOD_CLK_PLL_F80M = 5,                  /*< PLL_F80M_CLK is derived from PLL, and has a fixed frequency of 80MHz */
+    SOC_MOD_CLK_PLL_F160M = 6,                 /*< PLL_F160M_CLK is derived from PLL, and has a fixed frequency of 160MHz */
+    SOC_MOD_CLK_PLL_D2 = 7,                    /*< PLL_D2_CLK is derived from PLL, it has a fixed divider of 2 */
+    SOC_MOD_CLK_XTAL32K = 8,                   /*< XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals */
+    SOC_MOD_CLK_RC_FAST = 9,                   /*< RC_FAST_CLK comes from the internal 20MHz rc oscillator, passing a clock gating to the peripherals */
+    SOC_MOD_CLK_RC_FAST_D256 = 10,             /*< RC_FAST_D256_CLK comes from the internal 20MHz rc oscillator, divided by 256, and passing a clock gating to the peripherals */
+    SOC_MOD_CLK_XTAL = 11,                     /*< XTAL_CLK comes from the external 40MHz crystal */
+} soc_module_clk_t;
+
+
+// List clock sources available to each peripherial
+// soc_module_clk_src_t enum starts from 1 to save enum = 0 for AUTO selection
+
+typedef enum {
+    GPTIMER_CLK_SRC_APB = SOC_MOD_CLK_APB,                      /*!< Select APB as the source clock */
+    GPTIMER_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,                    /*!< Select XTAL as the source clock */
+} soc_periph_gptimer_clk_src_t;
+
+typedef enum {
+    TEMPERATURE_SENSOR_CLK_SRC_DEFAULT = 0,                     /*!< Use default clock selection */
+    TEMPERATURE_SENSOR_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,         /*!< Select XTAL as the source clock */
+    TEMPERATURE_SENSOR_CLK_SRC_RC_FAST = SOC_MOD_CLK_RC_FAST,   /*!< Select RC_FAST as the source clock */
+} soc_periph_temperature_sensor_clk_src_t;
+
+typedef enum {
+    RMT_CLK_SRC_NONE = 0,                                       /*!< No clock source is selected */
+    RMT_CLK_SRC_APB = SOC_MOD_CLK_APB,                          /*!< Select APB as the source clock */
+    RMT_CLK_SRC_RC_FAST = SOC_MOD_CLK_RC_FAST,                  /*!< Select RC_FAST as the source clock */
+    RMT_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,                        /*!< Select XTAL as the source clock */
+} soc_periph_rmt_clk_src_t;
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32c3/include/soc/regi2c_defs.h

@@ -19,7 +19,6 @@
 
 #define ANA_I2C_SAR_FORCE_PD BIT(18)
 #define ANA_I2C_BBPLL_M      BIT(17) /* Clear to enable BBPLL */
-#define ANA_I2C_APLL_M       BIT(14) /* Clear to enable APLL */
 
 
 #define ANA_CONFIG2_REG  0x6000E048

components/soc/esp32c3/include/soc/rtc_cntl_reg.h

@@ -1,16 +1,8 @@
-// Copyright 2020 Espressif Systems (Shanghai) PTE LTD
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
+/*
+ * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
 #ifndef _SOC_RTC_CNTL_REG_H_
 #define _SOC_RTC_CNTL_REG_H_
 
@@ -1001,7 +993,7 @@ extern "C" {
 #define RTC_CNTL_ANA_CLK_RTC_SEL_V  0x3
 #define RTC_CNTL_ANA_CLK_RTC_SEL_S  30
 /* RTC_CNTL_FAST_CLK_RTC_SEL : R/W ;bitpos:[29] ;default: 1'b0 ; */
-/*description: fast_clk_rtc sel. 0: XTAL div 4*/
+/*description: fast_clk_rtc sel. 0: XTAL div 2*/
 #define RTC_CNTL_FAST_CLK_RTC_SEL  (BIT(29))
 #define RTC_CNTL_FAST_CLK_RTC_SEL_M  (BIT(29))
 #define RTC_CNTL_FAST_CLK_RTC_SEL_V  0x1

components/soc/esp32c3/include/soc/rtc_cntl_struct.h

@@ -1,16 +1,8 @@
-// Copyright 2020 Espressif Systems (Shanghai) PTE LTD
-//
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-//     http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
+/*
+ * SPDX-FileCopyrightText: 2020-2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
 #ifndef _SOC_RTC_CNTL_STRUCT_H_
 #define _SOC_RTC_CNTL_STRUCT_H_
 #ifdef __cplusplus
@@ -335,7 +327,7 @@ typedef volatile struct rtc_cntl_dev_s {
             uint32_t ck8m_force_pu:              1;        /*CK8M force power up*/
             uint32_t xtal_global_force_gating:   1;
             uint32_t xtal_global_force_nogating: 1;
-            uint32_t fast_clk_rtc_sel:           1;        /*fast_clk_rtc sel. 0: XTAL div 4*/
+            uint32_t fast_clk_rtc_sel:           1;        /*fast_clk_rtc sel. 0: XTAL div 2*/
             uint32_t ana_clk_rtc_sel:            2;
         };
         uint32_t val;

components/soc/esp32h2/include/rev1/soc/clkrst_reg.h

@@ -27,7 +27,7 @@ extern "C" {
 /* SYSTEM_XTAL_FREQ : RO ;bitpos:[7:0] ;default: 8'h0 ; */
 /*description: */
 #define SYSTEM_CLK_XTAL_FREQ  0x000000FF
-#define SYSTEM_CLK_XTAL_FREQ_M  ((SYSTEM_XTAL_FREQ_V)<<(SYSTEM_XTAL_FREQ_S))
+#define SYSTEM_CLK_XTAL_FREQ_M  ((SYSTEM_CLK_XTAL_FREQ_V)<<(SYSTEM_CLK_XTAL_FREQ_S))
 #define SYSTEM_CLK_XTAL_FREQ_V  0xFF
 #define SYSTEM_CLK_XTAL_FREQ_S  0
 

components/soc/esp32h2/include/rev1/soc/rtc_cntl_reg.h

@@ -1065,7 +1065,7 @@ extern "C" {
 #define RTC_CNTL_ANA_CLK_RTC_SEL_V  0x3
 #define RTC_CNTL_ANA_CLK_RTC_SEL_S  30
 /* RTC_CNTL_FAST_CLK_RTC_SEL : R/W ;bitpos:[29] ;default: 1'b0 ; */
-/*description: fast_clk_rtc sel. 0: XTAL div 4*/
+/*description: fast_clk_rtc sel. 0: XTAL div 2*/
 #define RTC_CNTL_FAST_CLK_RTC_SEL  (BIT(29))
 #define RTC_CNTL_FAST_CLK_RTC_SEL_M  (BIT(29))
 #define RTC_CNTL_FAST_CLK_RTC_SEL_V  0x1

components/soc/esp32h2/include/rev1/soc/rtc_cntl_struct.h

@@ -335,7 +335,7 @@ typedef volatile struct rtc_cntl_dev_s {
             uint32_t ck8m_force_pu:              1;          /*CK8M force power up*/
             uint32_t xtal_global_force_gating:   1;
             uint32_t xtal_global_force_nogating: 1;
-            uint32_t fast_clk_rtc_sel:           1;          /*fast_clk_rtc sel. 0: XTAL div 4*/
+            uint32_t fast_clk_rtc_sel:           1;          /*fast_clk_rtc sel. 0: XTAL div 2*/
             uint32_t ana_clk_rtc_sel:            2;
         };
         uint32_t val;

components/soc/esp32h2/include/rev2/soc/clkrst_reg.h

@@ -49,13 +49,13 @@ extern "C" {
 #define SYSTEM_CPU_DIV_NUM_M  (SYSTEM_CPU_DIV_NUM_V << SYSTEM_CPU_DIV_NUM_S)
 #define SYSTEM_CPU_DIV_NUM_V  0x000000FFU
 #define SYSTEM_CPU_DIV_NUM_S  0
-/** SYSTEM_PRE_DIV_CNT : R/W; bitpos: [13:8]; default: 0;
+/** SYSTEM_CPU_DIV_NUMERATOR : R/W; bitpos: [13:8]; default: 0;
  *  Need add description
  */
-#define SYSTEM_PRE_DIV_CNT    0x0000003FU
-#define SYSTEM_PRE_DIV_CNT_M  (SYSTEM_PRE_DIV_CNT_V << SYSTEM_PRE_DIV_CNT_S)
-#define SYSTEM_PRE_DIV_CNT_V  0x0000003FU
-#define SYSTEM_PRE_DIV_CNT_S  8
+#define SYSTEM_CPU_DIV_NUMERATOR    0x0000003FU
+#define SYSTEM_CPU_DIV_NUMERATOR_M  (SYSTEM_CPU_DIV_NUMERATOR_V << SYSTEM_CPU_DIV_NUMERATOR_S)
+#define SYSTEM_CPU_DIV_NUMERATOR_V  0x0000003FU
+#define SYSTEM_CPU_DIV_NUMERATOR_S  8
 /** SYSTEM_CPU_DIV_DENOMINATOR : R/W; bitpos: [21:16]; default: 0;
  *  Need add description
  */

components/soc/esp32h2/include/rev2/soc/rtc_cntl_reg.h

@@ -1,5 +1,5 @@
 /**
- * SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
  *
  *  SPDX-License-Identifier: Apache-2.0
  */
@@ -1422,7 +1422,7 @@ extern "C" {
 #define RTC_CNTL_XTAL_GLOBAL_FORCE_NOGATING_V  0x00000001U
 #define RTC_CNTL_XTAL_GLOBAL_FORCE_NOGATING_S  28
 /** RTC_CNTL_FAST_CLK_RTC_SEL : R/W; bitpos: [29]; default: 0;
- *  fast_clk_rtc sel. 0: XTAL div 4, 1: CK8M
+ *  fast_clk_rtc sel. 0: XTAL div 2, 1: CK8M
  */
 #define RTC_CNTL_FAST_CLK_RTC_SEL    (BIT(29))
 #define RTC_CNTL_FAST_CLK_RTC_SEL_M  (RTC_CNTL_FAST_CLK_RTC_SEL_V << RTC_CNTL_FAST_CLK_RTC_SEL_S)

components/soc/esp32h2/include/rev2/soc/rtc_cntl_struct.h

@@ -1,5 +1,5 @@
 /**
- * SPDX-FileCopyrightText: 2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
  *
  *  SPDX-License-Identifier: Apache-2.0
  */
@@ -982,7 +982,7 @@ typedef union {
          */
         uint32_t xtal_global_force_nogating:1;
         /** fast_clk_rtc_sel : R/W; bitpos: [29]; default: 0;
-         *  fast_clk_rtc sel. 0: XTAL div 4, 1: CK8M
+         *  fast_clk_rtc sel. 0: XTAL div 2, 1: CK8M
          */
         uint32_t fast_clk_rtc_sel:1;
         /** ana_clk_rtc_sel : R/W; bitpos: [31:30]; default: 0;

components/soc/esp32h2/include/soc/clk_tree_defs.h

@@ -0,0 +1,137 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ ************************ ESP32H2 Root Clock Source ***************************
+ * 1) Internal 8MHz RC Oscillator: RC_FAST (usually referred as FOSC or CK8M/CLK8M in TRM and reg. description)
+ *
+ *    This RC oscillator generates a ~8.5MHz clock signal output as the RC_FAST_CLK.
+ *
+ *    The exact frequency of RC_FAST_CLK cannot be computed in runtime through calibration. You can output the RC_FAST
+ *    clock signal to a gpio pin in order to get the frequency through an oscillscope or a logic analyzer.
+ *
+ * 2) External 32MHz Crystal Clock: XTAL
+ *
+ * 3) Internal 1500kHz RC Oscillator: RC_SLOW (usually referrred as RTC in TRM or reg. description)
+ *
+ *    This RC oscillator generates a ~150kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock
+ *    can be computed in runtime through calibration.
+ *
+ * 4) External 32kHz Crystal Clock (optional): XTAL32K
+ *
+ *    The clock source for this XTAL32K_CLK can be either a 32kHz crystal connecting to the 32K_XP and 32K_XN pins
+ *    or a 32kHz clock signal generated by an external circuit. The external signal must be connected to the 32K_XN pin.
+ *    Additionally, a 1nF capacitor must be placed between the 32K_XP pin and ground. In this case, the 32K_XP pin
+ *    cannot be used as a GPIO pin.
+ *
+ *    XTAL32K_CLK can also be calibrated to get its exact frequency.
+ *
+ * 5) Internal 32kHz RC Oscillator: RC_32K
+ *
+ *    The exact frequency of this clock can be computed in runtime through calibration.
+ */
+
+/* With the default value of CK8M_DFREQ = 600, RC_FAST clock frequency nears 7 MHz +/- 7% */  //<---- DFREQ to be adjusted! */
+#define SOC_CLK_RC_FAST_FREQ_APPROX         7000000
+/* With the default value of DCAP = 128 */                                                    //<---- DCAP to be adjusted!
+#define SOC_CLK_RC_SLOW_FREQ_APPROX         130000
+#define SOC_CLK_RC_FAST_D256_FREQ_APPROX    (SOC_CLK_RC_FAST_FREQ_APPROX / 256)
+/* With the default value of DFREQ = 707  */                                                  //<---- DFREQ to be adjusted!
+#define SOC_CLK_RC_32K_FREQ_APPROX          32768
+#define SOC_CLK_XTAL32K_FREQ_APPROX         32768
+
+/**
+ * @brief Root clock
+ * Naming convention: SOC_ROOT_CLK_{loc}_{type}_<attr>
+ * {loc}: EXT, INT
+ * {type}: XTAL, RC
+ * <attr> - optional: <frequency>, FAST, SLOW
+ */
+typedef enum {
+    SOC_ROOT_CLK_INT_RC_FAST,          /*!< Internal 8MHz RC oscillator */
+    SOC_ROOT_CLK_INT_RC_SLOW,          /*!< Internal 150kHz RC oscillator */
+    SOC_ROOT_CLK_EXT_XTAL,             /*!< External 32MHz crystal */
+    SOC_ROOT_CLK_EXT_XTAL32K,          /*!< External 32kHz crystal/clock signal */
+    SOC_ROOT_CLK_INT_RC_32K            /*!< Internal 32kHz RC oscillator */
+} soc_root_clk_t;
+
+/**
+ * @brief CPU_CLK mux inputs, which are the supported clock sources for the CPU_CLK
+ */
+typedef enum {
+    SOC_CPU_CLK_SRC_XTAL,              /*!< Select XTAL_CLK as CPU_CLK source */
+    SOC_CPU_CLK_SRC_PLL,               /*!< Select PLL_CLK as CPU_CLK source (PLL_CLK is the output of 32MHz crystal oscillator frequency multiplier, 96MHz) */
+    SOC_CPU_CLK_SRC_RC_FAST,           /*!< Select RC_FAST_CLK as CPU_CLK source */
+    SOC_CPU_CLK_SRC_XTAL_DIV,          /*!< Select XTAL_D2_CLK as CPU_CLK source */
+} soc_cpu_clk_src_t;
+
+/**
+ * @brief RTC_SLOW_CLK mux inputs, which are the supported clock sources for the RTC_SLOW_CLK
+ */
+typedef enum {
+    SOC_RTC_SLOW_CLK_SRC_RC_SLOW,      /*!< Select RC_SLOW_CLK as RTC_SLOW_CLK source */
+    SOC_RTC_SLOW_CLK_SRC_XTAL32K,      /*!< Select XTAL32K_CLK as RTC_SLOW_CLK source */
+    SOC_RTC_SLOW_CLK_SRC_RC_32K,       /*!< Select RC_32K_CLK as RTC_SLOW_CLK source */
+} soc_rtc_slow_clk_src_t;
+
+/**
+ * @brief RTC_FAST_CLK mux inputs, which are the supported clock sources for the RTC_FAST_CLK
+ */
+typedef enum {
+    SOC_RTC_FAST_CLK_SRC_XTAL_D2,      /*!< Select XTAL_D2_CLK (may referred as XTAL_CLK_DIV_2) as RTC_FAST_CLK source */
+    SOC_RTC_FAST_CLK_SRC_XTAL_DIV = SOC_RTC_FAST_CLK_SRC_XTAL_D2, /*!< Alias name for `SOC_RTC_FAST_CLK_SRC_XTAL_D2` */
+    SOC_RTC_FAST_CLK_SRC_RC_FAST,      /*!< Select RC_FAST_CLK as RTC_FAST_CLK source */
+} soc_rtc_fast_clk_src_t;
+
+/**
+ * @brief Supported clock sources for modules (CPU, peripherials, RTC, etc.)
+ * Naming convention: SOC_MOD_CLK_{<upstream>clock_name}_<attr>
+ * {<upstream>clock_name}: AHB etc.
+ * <attr> - optional: FAST, SLOW, D<divider>, F<freq>
+ */
+typedef enum {
+    // For CPU domain
+    SOC_MOD_CLK_CPU = 1,                       /*< CPU_CLK can be sourced from XTAL, PLL, RC_FAST, or XTAL_D2 by configuring soc_cpu_clk_src_t */
+    // For RTC domain
+    SOC_MOD_CLK_RTC_FAST = 2,                  /*< RTC_FAST_CLK can be sourced from XTAL_D2 or RC_FAST by configuring soc_rtc_fast_clk_src_t */
+    SOC_MOD_CLK_RTC_SLOW = 3,                  /*< RTC_SLOW_CLK can be sourced from RC_SLOW, XTAL32K, or RC_32K by configuring soc_rtc_slow_clk_src_t */
+    // For digital domain: peripherals, WIFI, BLE
+    SOC_MOD_CLK_AHB = 4,                       /*< AHB_CLK sources from CPU with a configurable divider */
+    SOC_MOD_CLK_XTAL32K = 5,                   /*< XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals */
+    SOC_MOD_CLK_RC_FAST = 6,                   /*< RC_FAST_CLK comes from the internal 8MHz rc oscillator, passing a clock gating to the peripherals */
+    SOC_MOD_CLK_XTAL = 7,                      /*< XTAL_CLK comes from the external 32MHz crystal */
+} soc_module_clk_t;
+
+
+// List clock sources available to each peripherial
+// soc_module_clk_src_t enum starts from 1 to save enum = 0 for AUTO selection
+
+typedef enum {
+    GPTIMER_CLK_SRC_APB = SOC_MOD_CLK_AHB,                      /*!< Select AHB as the source clock */
+    GPTIMER_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,                    /*!< Select XTAL as the source clock */
+} soc_periph_gptimer_clk_src_t;
+
+typedef enum {
+    TEMPERATURE_SENSOR_CLK_SRC_DEFAULT = 0,                     /*!< Use default clock selection */
+    TEMPERATURE_SENSOR_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,         /*!< Select XTAL as the source clock */
+    TEMPERATURE_SENSOR_CLK_SRC_RC_FAST = SOC_MOD_CLK_RC_FAST,   /*!< Select RC_FAST as the source clock */
+} soc_periph_temperature_sensor_clk_src_t;
+
+typedef enum {
+    RMT_CLK_SRC_NONE = 0,                                       /*!< No clock source is selected */
+    RMT_CLK_SRC_APB = SOC_MOD_CLK_AHB,                          /*!< Select AHB as the source clock */
+    RMT_CLK_SRC_RC_FAST = SOC_MOD_CLK_RC_FAST,                  /*!< Select RC_FAST as the source clock */
+    RMT_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,                        /*!< Select XTAL as the source clock */
+} soc_periph_rmt_clk_src_t;
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32h2/include/soc/regi2c_defs.h

@@ -20,7 +20,6 @@
 
 #define ANA_I2C_SAR_FORCE_PD BIT(18)
 #define ANA_I2C_BBPLL_M      BIT(17) /* Clear to enable BBPLL */
-#define ANA_I2C_APLL_M       BIT(14) /* Clear to enable APLL */
 
 
 #define ANA_CONFIG2_REG  0x6000E048

components/soc/esp32s2/include/soc/clk_tree_defs.h

@@ -0,0 +1,139 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ ************************* ESP32S2 Root Clock Source ****************************
+ * 1) Internal 8MHz RC Oscillator: RC_FAST (usually referred as FOSC or CK8M/CLK8M in TRM and reg. description)
+ *
+ *    This RC oscillator generates a ~8.5MHz clock signal output as the RC_FAST_CLK.
+ *    The ~8.5MHz signal output is also passed into a configurable divider, which by default divides the input clock
+ *    frequency by 256, to generate a RC_FAST_D256_CLK (usually referred as 8md256 or simply d256 in reg. description).
+ *
+ *    The exact frequency of RC_FAST_CLK can be computed in runtime through calibration on the RC_FAST_D256_CLK.
+ *
+ * 2) External 40MHz Crystal Clock: XTAL
+ *
+ * 3) Internal 90kHz RC Oscillator: RC_SLOW (usually referrred as RTC in TRM or reg. description)
+ *
+ *    This RC oscillator generates a ~90kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock
+ *    can be computed in runtime through calibration.
+ *
+ * 4) External 32kHz Crystal Clock (optional): XTAL32K
+ *
+ *    The clock source for this XTAL32K_CLK can be either a 32kHz crystal connecting to the 32K_XP and 32K_XN pins
+ *    or a 32kHz clock signal generated by an external circuit. The external signal must be connected to the 32K_XN pin.
+ *    Additionally, a 1nF capacitor must be placed between the 32K_XP pin and ground. In this case, the 32K_XP pin
+ *    cannot be used as a GPIO pin.
+ *
+ *    XTAL32K_CLK can also be calibrated to get its exact frequency.
+ */
+
+/* With the default value of CK8M_DFREQ = 172, RC_FAST clock frequency is 8.5 MHz +/- 7% */
+#define SOC_CLK_RC_FAST_FREQ_APPROX         8500000
+#define SOC_CLK_RC_SLOW_FREQ_APPROX         90000
+#define SOC_CLK_RC_FAST_D256_FREQ_APPROX    (SOC_CLK_RC_FAST_FREQ_APPROX / 256)
+#define SOC_CLK_XTAL32K_FREQ_APPROX         32768
+
+/**
+ * @brief Root clock
+ * Naming convention: SOC_ROOT_CLK_{loc}_{type}_<attr>
+ * {loc}: EXT, INT
+ * {type}: XTAL, RC
+ * <attr> - optional: <frequency>, FAST, SLOW
+ */
+typedef enum {
+    SOC_ROOT_CLK_INT_RC_FAST,          /*!< Internal 8MHz RC oscillator */
+    SOC_ROOT_CLK_INT_RC_SLOW,          /*!< Internal 90kHz RC oscillator */
+    SOC_ROOT_CLK_EXT_XTAL,             /*!< External 40MHz crystal */
+    SOC_ROOT_CLK_EXT_XTAL32K,          /*!< External 32kHz crystal/clock signal */
+} soc_root_clk_t;
+
+/**
+ * @brief CPU_CLK mux inputs, which are the supported clock sources for the CPU_CLK
+ */
+typedef enum {
+    SOC_CPU_CLK_SRC_XTAL,              /*!< Select XTAL_CLK as CPU_CLK source */
+    SOC_CPU_CLK_SRC_PLL,               /*!< Select PLL_CLK as CPU_CLK source (PLL_CLK is the output of 40MHz crystal oscillator frequency multiplier, can be 480MHz or 320MHz) */
+    SOC_CPU_CLK_SRC_RC_FAST,           /*!< Select RC_FAST_CLK as CPU_CLK source */
+    SOC_CPU_CLK_SRC_APLL,              /*!< Select APLL_CLK as CPU_CLK source */
+} soc_cpu_clk_src_t;
+
+/**
+ * @brief RTC_SLOW_CLK mux inputs, which are the supported clock sources for the RTC_SLOW_CLK
+ */
+typedef enum {
+    SOC_RTC_SLOW_CLK_SRC_RC_SLOW,      /*!< Select RC_SLOW_CLK as RTC_SLOW_CLK source */
+    SOC_RTC_SLOW_CLK_SRC_XTAL32K,      /*!< Select XTAL32K_CLK as RTC_SLOW_CLK source */
+    SOC_RTC_SLOW_CLK_SRC_RC_FAST_D256, /*!< Select RC_FAST_D256_CLK (referred as FOSC_DIV or 8m_d256/8md256 in TRM and reg. description) as RTC_SLOW_CLK source */
+} soc_rtc_slow_clk_src_t;
+
+/**
+ * @brief RTC_FAST_CLK mux inputs, which are the supported clock sources for the RTC_FAST_CLK
+ */
+typedef enum {
+    SOC_RTC_FAST_CLK_SRC_XTAL_D4,      /*!< Select XTAL_D4_CLK (may referred as XTAL_CLK_DIV_4) as RTC_FAST_CLK source */
+    SOC_RTC_FAST_CLK_SRC_XTAL_DIV = SOC_RTC_FAST_CLK_SRC_XTAL_D4, /*!< Alias name for `SOC_RTC_FAST_CLK_SRC_XTAL_D4` */
+    SOC_RTC_FAST_CLK_SRC_RC_FAST,      /*!< Select RC_FAST_CLK as RTC_FAST_CLK source */
+} soc_rtc_fast_clk_src_t;
+
+/**
+ * @brief Supported clock sources for modules (CPU, peripherials, RTC, etc.)
+ * Naming convention: SOC_MOD_CLK_{<upstream>clock_name}_<attr>
+ * {<upstream>clock_name}: APB, APLL, (BB)PLL, etc.
+ * <attr> - optional: FAST, SLOW, D<divider>, F<freq>
+ */
+typedef enum {
+    // For CPU domain
+    SOC_MOD_CLK_CPU = 1,                       /*< CPU_CLK can be sourced from XTAL, PLL, RC_FAST, or APLL by configuring soc_cpu_clk_src_t */
+    // For RTC domain
+    SOC_MOD_CLK_RTC_FAST = 2,                  /*< RTC_FAST_CLK can be sourced from XTAL_D4 or RC_FAST by configuring soc_rtc_fast_clk_src_t */
+    SOC_MOD_CLK_RTC_SLOW = 3,                  /*< RTC_SLOW_CLK can be sourced from RC_SLOW, XTAL32K, or RC_FAST_D256 by configuring soc_rtc_slow_clk_src_t */
+    // For digital domain: peripherals, WIFI, BLE
+    SOC_MOD_CLK_APB = 4,                       /*< APB_CLK is highly dependent on the CPU_CLK source */
+    SOC_MOD_CLK_PLL_F160M = 5,                 /*< PLL_F160M_CLK is derived from PLL, and has a fixed frequency of 160MHz */
+    SOC_MOD_CLK_XTAL32K = 6,                   /*< XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals */
+    SOC_MOD_CLK_RC_FAST = 7,                   /*< RC_FAST_CLK comes from the internal 8MHz rc oscillator, passing a clock gating to the peripherals */
+    SOC_MOD_CLK_RC_FAST_D256 = 8,              /*< RC_FAST_D256_CLK is derived from the internal 8MHz rc oscillator, divided by 256, and passing a clock gating to the peripherals */
+    SOC_MOD_CLK_XTAL = 9,                      /*< XTAL_CLK comes from the external 40MHz crystal */
+    SOC_MOD_CLK_APB_F1M = 10,                  /*< APB_F1M_CLK (referred as REF_TICK in TRM) is derived from APB, it has a fixed frequency of 1MHz even when APB frequency changes */
+    SOC_MOD_CLK_APLL = 11,                     /*< APLL is sourced from PLL, and its frequency is configurable through APLL configuration registers */
+    SOC_MOD_CLK_TEMP_SENSOR = 12,              /*< TEMP_SENSOR_CLK comes directly from the internal 8MHz rc oscillator */
+} soc_module_clk_t;
+
+
+// List clock sources available to each peripherial
+// soc_module_clk_src_t enum starts from 1 to save enum = 0 for AUTO selection
+
+typedef enum {
+    GPTIMER_CLK_SRC_APB = SOC_MOD_CLK_APB,                          /*!< Select APB as the source clock */
+    GPTIMER_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,                        /*!< Select XTAL as the source clock */
+} soc_periph_gptimer_clk_src_t;
+
+typedef enum {
+    TEMPERATURE_SENSOR_CLK_SRC_DEFAULT = 0,                         /*!< Use default clock selection */
+    TEMPERATURE_SENSOR_CLK_SRC_RC_FAST = SOC_MOD_CLK_TEMP_SENSOR,   /*!< Select RC_FAST as the source clock */
+} soc_periph_temperature_sensor_clk_src_t;
+
+typedef enum {
+    LCD_CLK_SRC_PLL160M = SOC_MOD_CLK_PLL_F160M,                    /*!< Select PLL_F160M as the source clock */
+    LCD_CLK_SRC_APLL = SOC_MOD_CLK_APLL,                            /*!< Select APLL as the source clock */
+    LCD_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,                            /*!< Select XTAL as the source clock */
+} soc_periph_lcd_clk_src_t;
+
+typedef enum {
+    RMT_CLK_SRC_NONE = 0,                                           /*!< No clock source is selected */
+    RMT_CLK_SRC_REFTICK = SOC_MOD_CLK_APB_F1M,                      /*!< Select REF_TICK (1MHz) as the source clock */
+    RMT_CLK_SRC_APB = SOC_MOD_CLK_APB,                              /*!< Select APB as the source clock */
+} soc_periph_rmt_clk_src_t;
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32s3/include/soc/clk_tree_defs.h

@@ -0,0 +1,139 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ ************************* ESP32S3 Root Clock Source ****************************
+ * 1) Internal 20MHz RC Oscillator: RC_FAST (usually referred as FOSC or CK8M/CLK8M in TRM and reg. description)
+ *
+ *    This RC oscillator generates a ~17.5MHz clock signal output as the RC_FAST_CLK.
+ *    The ~17.5MHz signal output is also passed into a configurable divider, which by default divides the input clock
+ *    frequency by 256, to generate a RC_FAST_D256_CLK (usually referred as 8md256 or simply d256 in reg. description).
+ *
+ *    The exact frequency of RC_FAST_CLK can be computed in runtime through calibration on the RC_FAST_D256_CLK.
+ *
+ * 2) External 40MHz Crystal Clock: XTAL
+ *
+ * 3) Internal 1500kHz RC Oscillator: RC_SLOW (usually referrred as RTC in TRM or reg. description)
+ *
+ *    This RC oscillator generates a ~150kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock
+ *    can be computed in runtime through calibration.
+ *
+ * 4) External 32kHz Crystal Clock (optional): XTAL32K
+ *
+ *    The clock source for this XTAL32K_CLK can be either a 32kHz crystal connecting to the 32K_XP and 32K_XN pins
+ *    or a 32kHz clock signal generated by an external circuit. The external signal must be connected to the 32K_XN pin.
+ *    Additionally, a 1nF capacitor must be placed between the 32K_XP pin and ground. In this case, the 32K_XP pin
+ *    cannot be used as a GPIO pin.
+ *
+ *    XTAL32K_CLK can also be calibrated to get its exact frequency.
+ */
+
+/* With the default value of CK8M_DFREQ = 100, RC_FAST clock frequency is 17.5 MHz +/- 7% */
+#define SOC_CLK_RC_FAST_FREQ_APPROX         17500000
+#define SOC_CLK_RC_SLOW_FREQ_APPROX         150000
+#define SOC_CLK_RC_FAST_D256_FREQ_APPROX    (SOC_CLK_RC_FAST_FREQ_APPROX / 256)
+#define SOC_CLK_XTAL32K_FREQ_APPROX         32768
+
+/**
+ * @brief Root clock
+ * Naming convention: SOC_ROOT_CLK_{loc}_{type}_<attr>
+ * {loc}: EXT, INT
+ * {type}: XTAL, RC
+ * <attr> - optional: <frequency>, FAST, SLOW
+ */
+typedef enum {
+    SOC_ROOT_CLK_INT_RC_FAST,          /*!< Internal 8MHz RC oscillator */
+    SOC_ROOT_CLK_INT_RC_SLOW,          /*!< Internal 150kHz RC oscillator */
+    SOC_ROOT_CLK_EXT_XTAL,             /*!< External 40MHz crystal */
+    SOC_ROOT_CLK_EXT_XTAL32K,          /*!< External 32kHz crystal/clock signal */
+} soc_root_clk_t;
+
+/**
+ * @brief CPU_CLK mux inputs, which are the supported clock sources for the CPU_CLK
+ */
+typedef enum {
+    SOC_CPU_CLK_SRC_XTAL,              /*!< Select XTAL_CLK as CPU_CLK source */
+    SOC_CPU_CLK_SRC_PLL,               /*!< Select PLL_CLK as CPU_CLK source (PLL_CLK is the output of 40MHz crystal oscillator frequency multiplier, can be 480MHz or 320MHz) */
+    SOC_CPU_CLK_SRC_RC_FAST,           /*!< Select RC_FAST_CLK as CPU_CLK source */
+} soc_cpu_clk_src_t;
+
+/**
+ * @brief RTC_SLOW_CLK mux inputs, which are the supported clock sources for the RTC_SLOW_CLK
+ */
+typedef enum {
+    SOC_RTC_SLOW_CLK_SRC_RC_SLOW,      /*!< Select RC_SLOW_CLK as RTC_SLOW_CLK source */
+    SOC_RTC_SLOW_CLK_SRC_XTAL32K,      /*!< Select XTAL32K_CLK as RTC_SLOW_CLK source */
+    SOC_RTC_SLOW_CLK_SRC_RC_FAST_D256, /*!< Select RC_FAST_D256_CLK (referred as FOSC_DIV or 8m_d256/8md256 in TRM and reg. description) as RTC_SLOW_CLK source */
+} soc_rtc_slow_clk_src_t;
+
+/**
+ * @brief RTC_FAST_CLK mux inputs, which are the supported clock sources for the RTC_FAST_CLK
+ */
+typedef enum {
+    SOC_RTC_FAST_CLK_SRC_XTAL_D2,      /*!< Select XTAL_D2_CLK (may referred as XTAL_CLK_DIV_2) as RTC_FAST_CLK source */
+    SOC_RTC_FAST_CLK_SRC_XTAL_DIV = SOC_RTC_FAST_CLK_SRC_XTAL_D2, /*!< Alias name for `SOC_RTC_FAST_CLK_SRC_XTAL_D2` */
+    SOC_RTC_FAST_CLK_SRC_RC_FAST,      /*!< Select RC_FAST_CLK as RTC_FAST_CLK source */
+} soc_rtc_fast_clk_src_t;
+
+/**
+ * @brief Supported clock sources for modules (CPU, peripherials, RTC, etc.)
+ * Naming convention: SOC_MOD_CLK_{<upstream>clock_name}_<attr>
+ * {<upstream>clock_name}: APB, (BB)PLL, etc.
+ * <attr> - optional: FAST, SLOW, D<divider>, F<freq>
+ */
+typedef enum {
+    // For CPU domain
+    SOC_MOD_CLK_CPU = 1,                       /*< CPU_CLK can be sourced from XTAL, PLL, or RC_FAST by configuring soc_cpu_clk_src_t */
+    // For RTC domain
+    SOC_MOD_CLK_RTC_FAST = 2,                  /*< RTC_FAST_CLK can be sourced from XTAL_D2 or RC_FAST by configuring soc_rtc_fast_clk_src_t */
+    SOC_MOD_CLK_RTC_SLOW = 3,                  /*< RTC_SLOW_CLK can be sourced from RC_SLOW, XTAL32K, or RC_FAST_D256 by configuring soc_rtc_slow_clk_src_t */
+    // For digital domain: peripherals, WIFI, BLE
+    SOC_MOD_CLK_APB = 4,                       /*< APB_CLK is highly dependent on the CPU_CLK source */
+    SOC_MOD_CLK_PLL_F80M = 5,                  /*< PLL_F80M_CLK is derived from PLL, and has a fixed frequency of 80MHz */
+    SOC_MOD_CLK_PLL_F160M = 6,                 /*< PLL_F160M_CLK is derived from PLL, and has a fixed frequency of 160MHz */
+    SOC_MOD_CLK_PLL_D2 = 7,                    /*< PLL_D2_CLK is derived from PLL, it has a fixed divider of 2 */
+    SOC_MOD_CLK_XTAL32K = 8,                   /*< XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals */
+    SOC_MOD_CLK_RC_FAST = 9,                   /*< RC_FAST_CLK comes from the internal 20MHz rc oscillator, passing a clock gating to the peripherals */
+    SOC_MOD_CLK_RC_FAST_D256 = 10,             /*< RC_FAST_D256_CLK comes from the internal 20MHz rc oscillator, divided by 256, and passing a clock gating to the peripherals */
+    SOC_MOD_CLK_XTAL = 11,                     /*< XTAL_CLK comes from the external 40MHz crystal */
+    SOC_MOD_CLK_TEMP_SENSOR = 12,              /*< TEMP_SENSOR_CLK comes directly from the internal 20MHz rc oscillator */
+} soc_module_clk_t;
+
+
+// List clock sources available to each peripherial
+// soc_module_clk_src_t enum starts from 1 to save enum = 0 for AUTO selection
+
+typedef enum {
+    GPTIMER_CLK_SRC_APB = SOC_MOD_CLK_APB,                          /*!< Select APB as the source clock */
+    GPTIMER_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,                        /*!< Select XTAL as the source clock */
+} soc_periph_gptimer_clk_src_t;
+
+typedef enum {
+    TEMPERATURE_SENSOR_CLK_SRC_DEFAULT = 0,                         /*!< Use default clock selection */
+    TEMPERATURE_SENSOR_CLK_SRC_RC_FAST = SOC_MOD_CLK_TEMP_SENSOR,   /*!< Select RC_FAST as the source clock */
+} soc_periph_temperature_sensor_clk_src_t;
+
+typedef enum {
+    LCD_CLK_SRC_PLL160M = SOC_MOD_CLK_PLL_F160M,                    /*!< Select PLL_F160M as the source clock */
+    LCD_CLK_SRC_PLL240M = SOC_MOD_CLK_PLL_D2,                       /*!< Select PLL_D2 as the source clock */
+    LCD_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,                            /*!< Select XTAL as the source clock */
+} soc_periph_lcd_clk_src_t;
+
+typedef enum {
+    RMT_CLK_SRC_NONE = 0,                                           /*!< No clock source is selected */
+    RMT_CLK_SRC_APB = SOC_MOD_CLK_APB,                              /*!< Select APB as the source clock */
+    RMT_CLK_SRC_RC_FAST = SOC_MOD_CLK_RC_FAST,                      /*!< Select RC_FAST as the source clock */
+    RMT_CLK_SRC_XTAL = SOC_MOD_CLK_XTAL,                            /*!< Select XTAL as the source clock */
+} soc_periph_rmt_clk_src_t;
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32s3/include/soc/regi2c_defs.h

@@ -16,8 +16,6 @@
 #define ANA_CONFIG_REG  0x6000E044
 #define ANA_CONFIG_S    (8)
 #define ANA_CONFIG_M    (0x3FF)
-/* Clear to enable APLL */
-#define I2C_APLL_M      (BIT(14))
 /* Clear to enable BBPLL */
 #define I2C_BBPLL_M     (BIT(17))
 /* Clear to enable SAR */

components/soc/esp32s3/include/soc/rtc.h

@@ -83,7 +83,7 @@ extern "C" {
 
 /* Core voltage needs to be increased in two cases:
  * 1. running at 240 MHz
- * 2. running with 80MHz Flash frequency
+ * 2. running with 80MHz or 120M Flash frequency
  */
 #if CONFIG_ESPTOOLPY_FLASHFREQ_80M || CONFIG_ESPTOOLPY_FLASHFREQ_120M
 #define DIG_DBIAS_80M_160M  RTC_CNTL_DBIAS_1V25

components/soc/esp32s3/include/soc/rtc_cntl_reg.h

@@ -1301,7 +1301,7 @@ ork.*/
 #define RTC_CNTL_ANA_CLK_RTC_SEL_V  0x3
 #define RTC_CNTL_ANA_CLK_RTC_SEL_S  30
 /* RTC_CNTL_FAST_CLK_RTC_SEL : R/W ;bitpos:[29] ;default: 1'b0 ; */
-/*description: fast_clk_rtc sel. 0: XTAL div 4.*/
+/*description: fast_clk_rtc sel. 0: XTAL div 2.*/
 #define RTC_CNTL_FAST_CLK_RTC_SEL    (BIT(29))
 #define RTC_CNTL_FAST_CLK_RTC_SEL_M  (BIT(29))
 #define RTC_CNTL_FAST_CLK_RTC_SEL_V  0x1

components/soc/esp32s3/include/soc/rtc_cntl_struct.h

@@ -373,7 +373,7 @@ typedef volatile struct rtc_cntl_dev_s {
             uint32_t ck8m_force_pu                 :    1;  /*CK8M force power up*/
             uint32_t xtal_global_force_gating      :    1;
             uint32_t xtal_global_force_nogating    :    1;
-            uint32_t fast_clk_rtc_sel              :    1;  /*fast_clk_rtc sel. 0: XTAL div 4*/
+            uint32_t fast_clk_rtc_sel              :    1;  /*fast_clk_rtc sel. 0: XTAL div 2*/
             uint32_t ana_clk_rtc_sel               :    2;
         };
         uint32_t val;

docs/doxygen/Doxyfile

@@ -203,6 +203,7 @@ INPUT = \
     $(PROJECT_PATH)/components/pthread/include/esp_pthread.h \
     $(PROJECT_PATH)/components/sdmmc/include/sdmmc_cmd.h \
     $(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/adc_channel.h \
+    $(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/clk_tree_defs.h \
     $(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/soc_caps.h \
     $(PROJECT_PATH)/components/soc/$(IDF_TARGET)/include/soc/uart_channel.h \
     $(PROJECT_PATH)/components/spi_flash/include/esp_flash_spi_init.h \

examples/peripherals/mcpwm/mcpwm_capture_hc_sr04/main/mcpwm_capture_hc_sr04.c

@@ -18,7 +18,7 @@
 #include "freertos/queue.h"
 #include "esp_log.h"
 #include "esp_check.h"
-#include "soc/rtc.h"
+#include "esp_private/esp_clk.h"
 #include "driver/mcpwm.h"
 
 const static char *TAG = "hc-sr04";
@@ -121,7 +121,7 @@ void app_main(void) {
         uint32_t pulse_count;
         // block and wait for new measurement
         xQueueReceive(cap_queue, &pulse_count, portMAX_DELAY);
-        uint32_t pulse_width_us = pulse_count * (1000000.0 / rtc_clk_apb_freq_get());
+        uint32_t pulse_width_us = pulse_count * (1000000.0 / esp_clk_apb_freq());
         // following formula is based on: https://www.elecrow.com/download/HC_SR04%20Datasheet.pdf
         if (pulse_width_us > 35000) {
             // out of range

tools/ci/check_copyright_ignore.txt

@@ -1331,8 +1331,6 @@ components/soc/esp32c3/include/soc/interrupt_reg.h
 components/soc/esp32c3/include/soc/ledc_reg.h
 components/soc/esp32c3/include/soc/nrx_reg.h
 components/soc/esp32c3/include/soc/reset_reasons.h
-components/soc/esp32c3/include/soc/rtc_cntl_reg.h
-components/soc/esp32c3/include/soc/rtc_cntl_struct.h
 components/soc/esp32c3/include/soc/rtc_i2c_reg.h
 components/soc/esp32c3/include/soc/rtc_i2c_struct.h
 components/soc/esp32c3/include/soc/sensitive_reg.h

tools/ci/check_soc_headers_leak.py

@@ -17,6 +17,7 @@ allowed_soc_headers = (
     'soc/reset_reasons.h',
     'soc/reg_base.h',
     'soc/efuse_periph.h',  # 'soc/efuse_periph.h' should not be allowed , remove it from the list in IDF-1256
+    'soc/clk_tree_defs.h',
 )
 
 include_header_pattern = re.compile(r'[\s]*#[\s]*include ["<](.*)[">].*')