# Clock Tree

[中文]

The clock subsystem of ESP32 is used to source and distribute system/module clocks from a range of root clocks. The clock tree driver maintains the basic functionality of the system clock and the intricate relationship among module clocks.

This document starts with the introduction to root and module clocks. Then it covers the clock tree APIs that can be called to monitor the status of the module clocks at runtime.

## Introduction

This section lists definitions of ESP32's supported root clocks and module clocks. These definitions are commonly used in the driver configuration, to help 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), Wi-Fi, Bluetooth, the RTC, and the peripherals.

ESP32's root clocks are listed in `soc_root_clk_t`:

> - Internal 8 MHz RC Oscillator (RC_FAST)

>   > This RC oscillator generates a about 8.5 MHz clock signal output as the `RC_FAST_CLK`.

>   > The about 8.5 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`.

> - External 2 ~ 40 MHz Crystal (XTAL)

> - Internal 150 kHz RC Oscillator (RC_SLOW)

>   > This RC oscillator generates a about 150kHz clock signal output as the `RC_SLOW_CLK`. The exact frequency of this clock can be computed in runtime through calibration.

> - External 32 kHz Crystal - optional (XTAL32K)

>   > The clock source for this `XTAL32K_CLK` can be either a 32 kHz crystal connecting to the `32K_XP` and `32K_XN` pins or a 32 kHz clock signal generated by an external circuit. The external signal must be connected to the `32K_XN` pin. Additionally, a 1 nF 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.

Typically, the frequency of the signal generated from an RC oscillator circuit is less accurate and more sensitive to the environment compared to the signal generated from a crystal. ESP32 provides several clock source options for the `RTC_SLOW_CLK`, and it is possible to make the choice based on the requirements for system time accuracy and power consumption. For more details, please refer to RTC Timer Clock Sources.

### Module Clocks

ESP32's available module clocks are listed in `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 Usage

The clock tree driver provides an all-in-one API to get the frequency of the module clocks, `esp_clk_tree_src_get_freq_hz()`. This function allows you to obtain the clock frequency at any time by providing the clock name `soc_module_clk_t` and specifying the desired precision level for the returned frequency value `esp_clk_tree_src_freq_precision_t`.

## API Reference

### Header File

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

- This header file can be included with:

  >     #include "soc/clk_tree_defs.h"

### Macros

SOC_CLK_RC_FAST_FREQ_APPROX

  Approximate RC_FAST_CLK frequency in Hz

SOC_CLK_RC_SLOW_FREQ_APPROX

  Approximate RC_SLOW_CLK frequency in Hz

SOC_CLK_RC_FAST_D256_FREQ_APPROX

  Approximate RC_FAST_D256_CLK frequency in Hz

SOC_CLK_XTAL32K_FREQ_APPROX

  Approximate XTAL32K_CLK frequency in Hz

SOC_GPTIMER_CLKS

  Array initializer for all supported clock sources of GPTimer.

  The following code can be used to iterate all possible clocks:

      soc_periph_gptimer_clk_src_t gptimer_clks[] = (soc_periph_gptimer_clk_src_t)SOC_GPTIMER_CLKS;
      for (size_t i = 0; i< sizeof(gptimer_clks) / sizeof(gptimer_clks[0]); i++) {
          soc_periph_gptimer_clk_src_t clk = gptimer_clks[i];
      // Test GPTimer with the clock `clk`
      }

SOC_LCD_CLKS

  Array initializer for all supported clock sources of LCD.

SOC_RMT_CLKS

  Array initializer for all supported clock sources of RMT.

SOC_PCNT_CLKS

  Array initializer for all supported clock sources of PCNT.

SOC_UART_CLKS

  Array initializer for all supported clock sources of UART.

SOC_MCPWM_TIMER_CLKS

  Array initializer for all supported clock sources of MCPWM Timer.

SOC_MCPWM_CAPTURE_CLKS

  Array initializer for all supported clock sources of MCPWM Capture Timer.

SOC_MCPWM_CARRIER_CLKS

  Array initializer for all supported clock sources of MCPWM Carrier.

SOC_I2S_CLKS

  Array initializer for all supported clock sources of I2S.

SOC_I2C_CLKS

  Array initializer for all supported clock sources of I2C.

SOC_SPI_CLKS

  Array initializer for all supported clock sources of SPI.

SOC_SDM_CLKS

  Array initializer for all supported clock sources of SDM.

SOC_DAC_DIGI_CLKS

  Array initializer for all supported clock sources of DAC digital controller.

SOC_DAC_COSINE_CLKS

  Array initializer for all supported clock sources of DAC cosine wave generator.

SOC_TWAI_CLKS

  Array initializer for all supported clock sources of TWAI.

SOC_ADC_DIGI_CLKS

  Array initializer for all supported clock sources of ADC digital controller.

SOC_ADC_RTC_CLKS

  Array initializer for all supported clock sources of ADC RTC controller.

SOC_MWDT_CLKS

  Array initializer for all supported clock sources of MWDT.

SOC_LEDC_CLKS

  Array initializer for all supported clock sources of LEDC.

SOC_LEDC_CLK_STRS

SOC_SDMMC_CLKS

  Array initializer for all supported clock sources of SDMMC.

### Enumerations

enum soc_root_clk_t

  Root clock.

  Values:

  enumerator SOC_ROOT_CLK_INT_RC_FAST

    Internal 8MHz RC oscillator

  enumerator SOC_ROOT_CLK_INT_RC_SLOW

    Internal 150kHz RC oscillator

  enumerator SOC_ROOT_CLK_EXT_XTAL

    External 2~40MHz crystal

  enumerator SOC_ROOT_CLK_EXT_XTAL32K

    External 32kHz crystal/clock signal

enum soc_root_clk_circuit_t

  ROOT clock circuit, which requires explicitly enabling the targeting circuit to use.

  Values:

  enumerator SOC_ROOT_CIRCUIT_CLK_BBPLL

    BBPLL_CLK is the output of the BBPLL generator circuit

  enumerator SOC_ROOT_CIRCUIT_CLK_APLL

    APLL_CLK is the output of the APLL generator circuit

enum soc_cpu_clk_src_t

  CPU_CLK mux inputs, which are the supported clock sources for the CPU_CLK.

  Note

  Enum values are matched with the register field values on purpose

  Values:

  enumerator SOC_CPU_CLK_SRC_XTAL

    Select XTAL_CLK as CPU_CLK source

  enumerator 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)

  enumerator SOC_CPU_CLK_SRC_RC_FAST

    Select RC_FAST_CLK as CPU_CLK source

  enumerator SOC_CPU_CLK_SRC_APLL

    Select APLL_CLK as CPU_CLK source

  enumerator SOC_CPU_CLK_SRC_INVALID

    Invalid CPU_CLK source

enum soc_rtc_slow_clk_src_t

  RTC_SLOW_CLK mux inputs, which are the supported clock sources for the RTC_SLOW_CLK.

  Note

  Enum values are matched with the register field values on purpose

  Values:

  enumerator SOC_RTC_SLOW_CLK_SRC_RC_SLOW

    Select RC_SLOW_CLK as RTC_SLOW_CLK source

  enumerator SOC_RTC_SLOW_CLK_SRC_XTAL32K

    Select XTAL32K_CLK as RTC_SLOW_CLK source

  enumerator 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

  enumerator SOC_RTC_SLOW_CLK_SRC_INVALID

    Invalid RTC_SLOW_CLK source

  enumerator SOC_RTC_SLOW_CLK_SRC_DEFAULT

    RC_SLOW_CLK is the default clock source for RTC_SLOW_CLK

enum soc_rtc_fast_clk_src_t

  RTC_FAST_CLK mux inputs, which are the supported clock sources for the RTC_FAST_CLK.

  Note

  Enum values are matched with the register field values on purpose

  Values:

  enumerator SOC_RTC_FAST_CLK_SRC_XTAL_D4

    Select XTAL_D4_CLK (may referred as XTAL_CLK_DIV_4) as RTC_FAST_CLK source

  enumerator SOC_RTC_FAST_CLK_SRC_RC_FAST

    Select RC_FAST_CLK as RTC_FAST_CLK source

  enumerator SOC_RTC_FAST_CLK_SRC_INVALID

    Invalid RTC_FAST_CLK source

  enumerator SOC_RTC_FAST_CLK_SRC_DEFAULT

    XTAL_D4_CLK is the default clock source for RTC_FAST_CLK

  enumerator SOC_RTC_FAST_CLK_SRC_XTAL_DIV

    Alias name for `SOC_RTC_FAST_CLK_SRC_XTAL_D4`

enum soc_xtal_freq_t

  Possible main XTAL frequency options on the target.

  Note

  Enum values equal to the frequency value in MHz

  Note

  Not all frequency values listed here are supported in IDF. Please check SOC_XTAL_SUPPORT_XXX in soc_caps.h for the supported ones.

  Values:

  enumerator SOC_XTAL_FREQ_AUTO

    Automatic XTAL frequency detention

  enumerator SOC_XTAL_FREQ_24M

    24MHz XTAL

  enumerator SOC_XTAL_FREQ_26M

    26MHz XTAL

  enumerator SOC_XTAL_FREQ_40M

    40MHz XTAL

enum soc_module_clk_t

  Supported clock sources for modules (CPU, peripherals, RTC, etc.)

  Note

  enum starts from 1, to save 0 for special purpose

  Values:

  enumerator SOC_MOD_CLK_CPU

    CPU_CLK can be sourced from XTAL, PLL, RC_FAST, or APLL by configuring soc_cpu_clk_src_t

  enumerator SOC_MOD_CLK_RTC_FAST

    RTC_FAST_CLK can be sourced from XTAL_D4 or RC_FAST by configuring soc_rtc_fast_clk_src_t

  enumerator SOC_MOD_CLK_RTC_SLOW

    RTC_SLOW_CLK can be sourced from RC_SLOW, XTAL32K, or RC_FAST_D256 by configuring soc_rtc_slow_clk_src_t

  enumerator SOC_MOD_CLK_APB

    APB_CLK is highly dependent on the CPU_CLK source

  enumerator SOC_MOD_CLK_PLL_D2

    PLL_D2_CLK is derived from PLL, it has a fixed divider of 2

  enumerator SOC_MOD_CLK_PLL_F160M

    PLL_F160M_CLK is derived from PLL, and has a fixed frequency of 160MHz

  enumerator SOC_MOD_CLK_XTAL32K

    XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals

  enumerator SOC_MOD_CLK_RC_FAST

    RC_FAST_CLK comes from the internal 8MHz rc oscillator, passing a clock gating to the peripherals

  enumerator SOC_MOD_CLK_RC_FAST_D256

    RC_FAST_D256_CLK comes from the internal 8MHz rc oscillator, divided by 256, and passing a clock gating to the peripherals

  enumerator SOC_MOD_CLK_XTAL

    XTAL_CLK comes from the external crystal (2~40MHz)

  enumerator SOC_MOD_CLK_REF_TICK

    REF_TICK is derived from APB, it has a fixed frequency of 1MHz even when APB frequency changes

  enumerator SOC_MOD_CLK_APLL

    APLL is sourced from PLL, and its frequency is configurable through APLL configuration registers

  enumerator SOC_MOD_CLK_INVALID

    Indication of the end of the available module clock sources

enum soc_periph_systimer_clk_src_t

  Type of SYSTIMER clock source.

  Values:

  enumerator SYSTIMER_CLK_SRC_XTAL

    SYSTIMER source clock is XTAL

  enumerator SYSTIMER_CLK_SRC_DEFAULT

    SYSTIMER source clock default choice is XTAL

enum soc_periph_gptimer_clk_src_t

  Type of GPTimer clock source.

  Values:

  enumerator GPTIMER_CLK_SRC_APB

    Select APB as the source clock

  enumerator GPTIMER_CLK_SRC_DEFAULT

    Select APB as the default choice

enum soc_periph_lcd_clk_src_t

  Type of LCD clock source.

  Values:

  enumerator LCD_CLK_SRC_PLL160M

    Select PLL_160M as the source clock

  enumerator LCD_CLK_SRC_DEFAULT

    Select PLL_160M as the default choice

enum soc_periph_rmt_clk_src_t

  Type of RMT clock source.

  Values:

  enumerator RMT_CLK_SRC_APB

    Select APB as the source clock

  enumerator RMT_CLK_SRC_REF_TICK

    Select REF_TICK as the source clock

  enumerator RMT_CLK_SRC_DEFAULT

    Select APB as the default choice

enum soc_periph_pcnt_clk_src_t

  Type of PCNT clock source.

  Values:

  enumerator PCNT_CLK_SRC_APB

    Select APB as the source clock

  enumerator PCNT_CLK_SRC_DEFAULT

    Select APB as the default choice

enum soc_periph_uart_clk_src_legacy_t

  Type of UART clock source, reserved for the legacy UART driver.

  Values:

  enumerator UART_SCLK_APB

    UART source clock is APB CLK

  enumerator UART_SCLK_REF_TICK

    UART source clock is REF_TICK

  enumerator UART_SCLK_DEFAULT

    UART source clock default choice is APB

enum soc_periph_mcpwm_timer_clk_src_t

  Type of MCPWM timer clock source.

  Values:

  enumerator MCPWM_TIMER_CLK_SRC_PLL160M

    Select PLL_F160M as the source clock

  enumerator MCPWM_TIMER_CLK_SRC_DEFAULT

    Select PLL_F160M as the default clock choice

enum soc_periph_mcpwm_capture_clk_src_t

  Type of MCPWM capture clock source.

  Values:

  enumerator MCPWM_CAPTURE_CLK_SRC_APB

    Select APB as the source clock

  enumerator MCPWM_CAPTURE_CLK_SRC_DEFAULT

    Select APB as the default clock choice

enum soc_periph_mcpwm_carrier_clk_src_t

  Type of MCPWM carrier clock source.

  Values:

  enumerator MCPWM_CARRIER_CLK_SRC_PLL160M

    Select PLL_F160M as the source clock

  enumerator MCPWM_CARRIER_CLK_SRC_DEFAULT

    Select PLL_F160M as the default clock choice

enum soc_periph_i2s_clk_src_t

  I2S clock source enum.

  Values:

  enumerator I2S_CLK_SRC_DEFAULT

    Select PLL_F160M as the default source clock

  enumerator I2S_CLK_SRC_PLL_160M

    Select PLL_F160M as the source clock

  enumerator I2S_CLK_SRC_APLL

    Select APLL as the source clock

enum soc_periph_i2c_clk_src_t

  Type of I2C clock source.

  Values:

  enumerator I2C_CLK_SRC_APB
  enumerator I2C_CLK_SRC_DEFAULT

enum soc_periph_spi_clk_src_t

  Type of SPI clock source.

  Values:

  enumerator SPI_CLK_SRC_DEFAULT

    Select APB as SPI source clock

  enumerator SPI_CLK_SRC_APB

    Select APB as SPI source clock

enum soc_periph_sdm_clk_src_t

  Sigma Delta Modulator clock source.

  Values:

  enumerator SDM_CLK_SRC_APB

    Select APB as the source clock

  enumerator SDM_CLK_SRC_DEFAULT

    Select APB as the default clock choice

enum soc_periph_dac_digi_clk_src_t

  DAC digital controller clock source.

  Values:

  enumerator DAC_DIGI_CLK_SRC_PLLD2

    Select PLL_D2 as the source clock

  enumerator DAC_DIGI_CLK_SRC_APLL

    Select APLL as the source clock

  enumerator DAC_DIGI_CLK_SRC_DEFAULT

    Select PLL_D2 as the default source clock

enum soc_periph_dac_cosine_clk_src_t

  DAC cosine wave generator clock source.

  Values:

  enumerator DAC_COSINE_CLK_SRC_RTC_FAST

    Select RTC FAST as the source clock

  enumerator DAC_COSINE_CLK_SRC_DEFAULT

    Select RTC FAST as the default source clock

enum soc_periph_twai_clk_src_t

  TWAI clock source.

  Values:

  enumerator TWAI_CLK_SRC_APB

    Select APB as the source clock

  enumerator TWAI_CLK_SRC_DEFAULT

    Select APB as the default clock choice

enum soc_periph_adc_digi_clk_src_t

  ADC digital controller clock source.

  Note

  ADC DMA mode is clocked from I2S on ESP32, using `ADC_DIGI_` here for compatibility Its clock source is same as I2S

  Values:

  enumerator ADC_DIGI_CLK_SRC_PLL_F160M

    Select F160M as the source clock

  enumerator ADC_DIGI_CLK_SRC_APLL

    Select APLL as the source clock

  enumerator ADC_DIGI_CLK_SRC_DEFAULT

    Select F160M as the default clock choice

enum soc_periph_adc_rtc_clk_src_t

  ADC RTC controller clock source.

  Values:

  enumerator ADC_RTC_CLK_SRC_RC_FAST

    Select RC_FAST as the source clock

  enumerator ADC_RTC_CLK_SRC_DEFAULT

    Select RC_FAST as the default clock choice

enum soc_periph_mwdt_clk_src_t

  MWDT clock source.

  Values:

  enumerator MWDT_CLK_SRC_APB

    Select APB as the source clock

  enumerator MWDT_CLK_SRC_DEFAULT

    Select APB as the default clock choice

enum soc_periph_ledc_clk_src_legacy_t

  Type of LEDC clock source, reserved for the legacy LEDC driver.

  Values:

  enumerator LEDC_AUTO_CLK

    LEDC source clock will be automatically selected based on the giving resolution and duty parameter when init the timer

  enumerator LEDC_USE_APB_CLK

    Select APB as the source clock

  enumerator LEDC_USE_RC_FAST_CLK

    Select RC_FAST as the source clock

  enumerator LEDC_USE_REF_TICK

    Select REF_TICK as the source clock

enum soc_periph_sdmmc_clk_src_t

  Type of SDMMC clock source.

  Values:

  enumerator SDMMC_CLK_SRC_DEFAULT

    Select PLL_160M as the default choice

  enumerator SDMMC_CLK_SRC_PLL160M

    Select PLL_160M as the source clock

enum soc_clkout_sig_id_t

  Values:

  enumerator CLKOUT_SIG_I2S0

    I2S0 clock, depends on the i2s driver configuration

  enumerator CLKOUT_SIG_PLL

    PLL_CLK is the output of crystal oscillator frequency multiplier

  enumerator CLKOUT_SIG_RC_SLOW

    RC slow clock, depends on the RTC_CLK_SRC configuration

  enumerator CLKOUT_SIG_XTAL

    Main crystal oscillator clock

  enumerator CLKOUT_SIG_APLL

    Divided by PLL, frequency is configurable

  enumerator CLKOUT_SIG_REF_TICK

    Divided by APB clock, usually be 1MHz

  enumerator CLKOUT_SIG_PLL_F80M

    From PLL, usually be 80MHz

  enumerator CLKOUT_SIG_RC_FAST

    RC fast clock, about 8MHz

  enumerator CLKOUT_SIG_I2S1

    I2S1 clock, depends on the i2s driver configuration

  enumerator CLKOUT_SIG_INVALID

enum soc_clk_freq_calculation_src_t

  Clock frequency calculation source selection.

  Values:

  enumerator CLK_CAL_RTC_SLOW

    Select to calculate frequency of RTC_SLOW_CLK

  enumerator CLK_CAL_RC_FAST_D256

    Select to calculate frequency of RC_FAST_D256_CLK

  enumerator CLK_CAL_32K_XTAL

    Select to calculate frequency of XTAL32K_CLK

### Header File

- components/esp_hw_support/include/esp_clk_tree.h

- This header file can be included with:

  >     #include "esp_clk_tree.h"

### Functions

esp_err_t esp_clk_tree_src_get_freq_hz(soc_module_clk_t clk_src, esp_clk_tree_src_freq_precision_t precision, uint32_t *freq_value)

  Get frequency of module clock source.

  Parameters:

    - clk_src -- [in] Clock source available to modules, in soc_module_clk_t

    - precision -- [in] Degree of precision, one of esp_clk_tree_src_freq_precision_t values This arg only applies to the clock sources that their frequencies can vary: SOC_MOD_CLK_RTC_FAST, SOC_MOD_CLK_RTC_SLOW, SOC_MOD_CLK_RC_FAST, SOC_MOD_CLK_RC_FAST_D256, SOC_MOD_CLK_XTAL32K For other clock sources, this field is ignored.

    - freq_value -- [out] Frequency of the clock source, in Hz

  Returns:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

    - ESP_FAIL Calibration failed

esp_err_t esp_clk_tree_src_set_freq_hz(soc_module_clk_t clk_src, uint32_t expt_freq_value, uint32_t *ret_freq_value)

  Set frequency of module clock source.

  Parameters:

    - clk_src -- [in] Clock source available to modules, in soc_module_clk_t

    - expt_freq_value -- [in] Expected frequency of the clock source, in Hz

    - ret_freq_value -- [out] Real frequency of the clock source, in Hz

  Returns:

    - ESP_OK Success

    - ESP_ERR_INVALID_ARG Parameter error

    - ESP_ERR_NOT_SUPPORTED Unsupported clock source

### Enumerations

enum esp_clk_tree_src_freq_precision_t

  Degree of precision of frequency value to be returned by esp_clk_tree_src_get_freq_hz()

  Values:

  enumerator ESP_CLK_TREE_SRC_FREQ_PRECISION_CACHED
  enumerator ESP_CLK_TREE_SRC_FREQ_PRECISION_APPROX
  enumerator ESP_CLK_TREE_SRC_FREQ_PRECISION_EXACT
  enumerator ESP_CLK_TREE_SRC_FREQ_PRECISION_INVALID

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.