clk_tree: add initial docs for clock tree

docs/en/api-reference/peripherals/clk_tree.rst

@@ -1,9 +1,79 @@
 Clock Tree
 ==========
 
-Clock Source Definitions
-------------------------
+{IDF_TARGET_RC_FAST_VAGUE_FREQ: default="8", esp32="8", esp32s2="8", esp32c3="17.5", esp32s3="17.5", esp32c2="17.5", esp32h2="8"}
+
+{IDF_TARGET_RC_FAST_ADJUSTED_FREQ: default="8.5", esp32="8.5", esp32s2="8.5", esp32c3="17.5", esp32s3="17.5", esp32c2="17.5", esp32h2="8.5"}
+
+{IDF_TARGET_XTAL_FREQ: default="40", esp32="2~40", esp32s2="40", esp32c3="40", esp32s3="40", esp32c2="40", esp32h2="32"}
+
+{IDF_TARGET_RC_SLOW_VAGUE_FREQ: default="136", esp32="150", esp32s2="90"}
 
 This section lists definitions of the {IDF_TARGET_NAME}'s supported root clocks and module clocks. These definitions are commonly used in the driver configuration, to help user select a proper source clock for the peripheral.
 
+Root Clocks
+-----------
+
+Root clocks generate reliable clock signals. These clock signals then pass through various gates, muxes, dividers, or multipliers to become the clock sources for every functional module: the CPU core(s), WIFI, BT, the RTC, and the peripherals.
+
+{IDF_TARGET_NAME}'s root clocks are listed in :cpp:type:`soc_root_clk_t`:
+
+    .. list::
+    
+        - Internal {IDF_TARGET_RC_FAST_VAGUE_FREQ}MHz RC Oscillator (RC_FAST)
+
+            This RC oscillator generates a ~{IDF_TARGET_RC_FAST_ADJUSTED_FREQ}MHz clock signal output as the RC_FAST_CLK. 
+
+            .. only:: not esp32h2
+
+                The ~{IDF_TARGET_RC_FAST_ADJUSTED_FREQ}MHz 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.
+
+                The exact frequency of RC_FAST_CLK can be computed in runtime through calibration on the RC_FAST_D256_CLK.
+
+            .. only:: esp32h2
+
+                The exact frequency of RC_FAST_CLK cannot be computed in runtime through calibration, but it is still possible to get its frequency through an oscillscope or a logic analyzer by routing the clock signal to a GPIO pin.
+        
+        - External {IDF_TARGET_XTAL_FREQ}MHz Crystal (XTAL)
+
+        - Internal {IDF_TARGET_RC_SLOW_VAGUE_FREQ}kHz RC Oscillator (RC_SLOW)
+
+            This RC oscillator generates a ~{IDF_TARGET_RC_SLOW_VAGUE_FREQ}kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock can be computed in runtime through calibration.
+
+        .. only:: not esp32c2
+
+            - External 32kHz Crystal - optional (XTAL32K)
+
+                .. only:: esp32
+
+                    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.
+                
+                .. only:: not esp32
+
+                     The clock source for this XTAL32K_CLK can be either a 32kHz crystal connecting to the XTAL_32K_P and XTAL_32K_N pins or a 32kHz clock signal generated by an external circuit. The external signal must be connected to the XTAL_32K_P pin.
+            
+                XTAL32K_CLK can also be calibrated to get its exact frequency.
+        
+        .. only:: esp32c2
+
+            - External Slow Clock - optional (OSC_SLOW)
+
+                A clock signal generated by an external circuit can be connected to pin0 to be the clock source for the RTC_SLOW_CLK. This clock can also be calibrated to get its exact frequency.
+        
+        .. only:: esp32h2
+
+            - Internal 32kHz RC Oscillator (RC32K)
+
+                The exact frequency of this clock can be computed in runtime through calibration.
+
+Typically, the frequency of the signal generated from a RC oscillator circuit is less accurate and more sensitive to environment comparing to the signal generated from a crystal. {IDF_TARGET_NAME} provides several clock source options for the RTC_SLOW_CLK, and users can make the choice based on the requirements for system time accuracy and power consumption (refer to :ref:`rtc-clock-source-choice` for more details).
+
+Module Clocks
+-------------
+
+{IDF_TARGET_NAME}'s available module clocks are listed in :cpp:type:`soc_module_clk_t`. Each module clock has a unique ID. You can get more information on each clock by checking the documented enum value. 
+
+API Reference
+-------------
+
 .. include-build-file:: inc/clk_tree_defs.inc

docs/en/api-reference/system/system_time.rst

@@ -29,6 +29,8 @@ The possible combinations of hardware timers used to keep system time are listed
 It is recommended that users stick to the default option as it provides the highest accuracy. However, users can also select a different setting via the :ref:`CONFIG_NEWLIB_TIME_SYSCALL` configuration option.
 
 
+.. _rtc-clock-source-choice:
+
 RTC Timer Clock Sources
 ------------------------
 

docs/zh_CN/api-reference/system/system_time.rst

@@ -29,6 +29,8 @@
 默认时钟源的时间精度最高，建议使用该配置。此外，用户也可以通过配置选项 :ref:`CONFIG_NEWLIB_TIME_SYSCALL` 来选择其他时钟源。
 
 
+.. _rtc-clock-source-choice:
+
 RTC 定时器时钟源
 -----------------