Clock Tree
==========

{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