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/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