Clock Tree

This section lists definitions of the ESP32’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.

ESP32’s root clocks are listed in soc_root_clk_t:

Internal 8MHz RC Oscillator (RC_FAST)

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.

The exact frequency of RC_FAST_CLK can be computed in runtime through calibration on the RC_FAST_D256_CLK.

External 2~40MHz Crystal (XTAL)

Internal 150kHz RC Oscillator (RC_SLOW)

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.

External 32kHz Crystal - 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.

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. ESP32 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 RTC Timer Clock Sources for more details).

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 Reference

Header File

components/soc/esp32/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_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_SDM_CLKS: Array initializer for all supported clock sources of SDM.

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

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_XTAL_DIV: Alias name for SOC_RTC_FAST_CLK_SRC_XTAL_D4

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

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

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_tg_clk_src_legacy_t

Type of Timer Group clock source, reserved for the legacy timer group driver.

Values:

enumerator TIMER_SRC_CLK_APB: Timer group source clock is APB

enumerator TIMER_SRC_CLK_DEFAULT: Timer group source clock default choice is APB

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_rmt_clk_src_legacy_t

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

Values:

enumerator RMT_BASECLK_APB: RMT source clock is APB CLK

enumerator RMT_BASECLK_REF: RMT source clock is REF_TICK

enumerator RMT_BASECLK_DEFAULT: RMT source clock default choice is APB

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_D2 as the default source clock

enumerator I2S_CLK_SRC_PLL_160M: Select PLL_D2 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_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

Provide feedback about this document