Clock Tree

[中文]

The clock subsystem of ESP32-H2 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-H2'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-H2'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 exact frequency of RC_FAST_CLK can be computed in runtime through calibration.

External 32 MHz Crystal (XTAL)

Internal 136 kHz RC Oscillator (RC_SLOW)

This RC oscillator generates a about 136kHz 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 XTAL_32K_P and XTAL_32K_N pins or a 32 kHz 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.

External Slow Clock - optional (OSC_SLOW)

A clock signal generated by an external circuit can be connected to GPIO13 to be the clock source for the RTC_SLOW_CLK. This clock can also be calibrated to get its exact frequency.

Internal 32 kHz RC Oscillator (RC32K)

The exact frequency of this clock can be computed in runtime through calibration.

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-H2 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-H2'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/esp32h2/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_RC32K_FREQ_APPROX: Approximate RC32K_CLK frequency in Hz

SOC_CLK_XTAL32K_FREQ_APPROX: Approximate XTAL32K_CLK frequency in Hz

SOC_CLK_OSC_SLOW_FREQ_APPROX: Approximate OSC_SLOW_CLK (external slow clock) 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_RMT_CLKS: Array initializer for all supported clock sources of RMT.

SOC_TEMP_SENSOR_CLKS: Array initializer for all supported clock sources of Temperature Sensor.

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_ANA_CMPR_CLKS: Array initializer for all supported clock sources of Analog Comparator.

SOC_GLITCH_FILTER_CLKS: Array initializer for all supported clock sources of Glitch Filter.

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_MWDT_CLKS: Array initializer for all supported clock sources of MWDT.

SOC_LEDC_CLKS: Array initializer for all supported clock sources of LEDC.

SOC_PARLIO_CLKS: Array initializer for all supported clock sources of PARLIO.

SOC_MSPI_CLKS: Array initializer for all supported clock sources of MSPI digital controller.

Enumerations

enum soc_root_clk_t

Root clock.

Values:

enumerator SOC_ROOT_CLK_INT_RC_FAST: Internal 8.5MHz RC oscillator

enumerator SOC_ROOT_CLK_INT_RC_SLOW: Internal 136kHz RC oscillator

enumerator SOC_ROOT_CLK_EXT_XTAL: External 32MHz crystal

enumerator SOC_ROOT_CLK_EXT_XTAL32K: External 32kHz crystal/clock signal

enumerator SOC_ROOT_CLK_INT_RC32K: Internal 32kHz RC oscillator

enumerator SOC_ROOT_CLK_EXT_OSC_SLOW: External slow clock signal at pin13

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 one of the outputs of 32MHz crystal oscillator frequency multiplier, 96MHz)

enumerator SOC_CPU_CLK_SRC_RC_FAST: Select RC_FAST_CLK as CPU_CLK source

enumerator SOC_CPU_CLK_SRC_FLASH_PLL: Select FLASH_PLL_CLK as CPU_CLK source (FLASH_PLL_CLK is the other output of 32MHz crystal oscillator frequency multiplier, 64MHz)

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_RC32K: Select RC32K_CLK as RTC_SLOW_CLK source

enumerator SOC_RTC_SLOW_CLK_SRC_OSC_SLOW: Select OSC_SLOW_CLK (external slow clock) 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_RC_FAST: Select RC_FAST_CLK as RTC_FAST_CLK source

enumerator SOC_RTC_FAST_CLK_SRC_XTAL_D2: Select XTAL_D2_CLK (may referred as XTAL_CLK_DIV_2) as RTC_FAST_CLK source

enumerator SOC_RTC_FAST_CLK_SRC_XTAL_DIV: Alias name for SOC_RTC_FAST_CLK_SRC_XTAL_D2

enumerator SOC_RTC_FAST_CLK_SRC_LP_PLL: Select LP_PLL_CLK as RTC_FAST_CLK source (LP_PLL_CLK is a 8MHz clock sourced from RC32K or XTAL32K)

enumerator SOC_RTC_FAST_CLK_SRC_INVALID: Invalid RTC_FAST_CLK source

enum soc_lp_pll_clk_src_t

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

Note

Enum values are matched with the register field values on purpose

Values:

enumerator SOC_LP_PLL_CLK_SRC_RC32K: Select RC32K_CLK as LP_PLL_CLK source

enumerator SOC_LP_PLL_CLK_SRC_XTAL32K: Select XTAL32K_CLK as LP_PLL_CLK source

enumerator SOC_LP_PLL_CLK_SRC_INVALID: Invalid LP_PLL_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 PLL2 by configuring soc_cpu_clk_src_t

enumerator SOC_MOD_CLK_RTC_FAST: RTC_FAST_CLK can be sourced from XTAL_D2 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, OSC_SLOW, or RC32K by configuring soc_rtc_slow_clk_src_t

enumerator SOC_MOD_CLK_PLL_F48M: PLL_F48M_CLK is derived from PLL (clock gating + fixed divider of 2), it has a fixed frequency of 48MHz

enumerator SOC_MOD_CLK_PLL_F64M: PLL_F64M_CLK is derived from FLASH_PLL (clock gating), it has a fixed frequency of 64MHz

enumerator SOC_MOD_CLK_PLL_F96M: PLL_F96M_CLK is derived from PLL (clock gating), it has a fixed frequency of 96MHz

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_XTAL: XTAL_CLK comes from the external 32MHz crystal

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_RC_FAST: SYSTIMER source clock is RC_FAST

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_PLL_F48M: Select PLL_F48M as the source clock

enumerator GPTIMER_CLK_SRC_RC_FAST: Select RC_FAST as the source clock

enumerator GPTIMER_CLK_SRC_XTAL: Select XTAL as the source clock

enumerator GPTIMER_CLK_SRC_DEFAULT: Select PLL_F48M 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_PLL_F48M: Timer group clock source is PLL_F48M

enumerator TIMER_SRC_CLK_XTAL: Timer group clock source is XTAL

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

enum soc_periph_rmt_clk_src_t

Type of RMT clock source.

Values:

enumerator RMT_CLK_SRC_RC_FAST: Select RC_FAST as the source clock

enumerator RMT_CLK_SRC_XTAL: Select XTAL as the source clock

enumerator RMT_CLK_SRC_DEFAULT: Select XTAL 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_XTAL: RMT source clock is XTAL

enumerator RMT_BASECLK_DEFAULT: RMT source clock default choice is XTAL

enum soc_periph_temperature_sensor_clk_src_t

Type of Temp Sensor clock source.

Values:

enumerator TEMPERATURE_SENSOR_CLK_SRC_XTAL: Select XTAL as the source clock

enumerator TEMPERATURE_SENSOR_CLK_SRC_RC_FAST: Select RC_FAST as the source clock

enumerator TEMPERATURE_SENSOR_CLK_SRC_DEFAULT: Select XTAL 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_PLL_F48M: UART source clock is PLL_F48M

enumerator UART_SCLK_RTC: UART source clock is RC_FAST

enumerator UART_SCLK_XTAL: UART source clock is XTAL

enumerator UART_SCLK_DEFAULT: UART source clock default choice is PLL_F48M

enum soc_periph_mcpwm_timer_clk_src_t

Type of MCPWM timer clock source.

Values:

enumerator MCPWM_TIMER_CLK_SRC_PLL96M: Select PLL_F96M as the source clock

enumerator MCPWM_TIMER_CLK_SRC_XTAL: Select XTAL as the source clock

enumerator MCPWM_TIMER_CLK_SRC_DEFAULT: Select PLL_F96M 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_PLL96M: Select PLL_F96M as the source clock

enumerator MCPWM_CAPTURE_CLK_SRC_XTAL: Select XTAL as the source clock

enumerator MCPWM_CAPTURE_CLK_SRC_DEFAULT: Select PLL_F96M 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_PLL96M: Select PLL_F96M as the source clock

enumerator MCPWM_CARRIER_CLK_SRC_XTAL: Select XTAL as the source clock

enumerator MCPWM_CARRIER_CLK_SRC_DEFAULT: Select PLL_F96M as the default clock choice

enum soc_periph_i2s_clk_src_t

I2S clock source enum.

Values:

enumerator I2S_CLK_SRC_DEFAULT: Select PLL_F96M as the default source clock

enumerator I2S_CLK_SRC_PLL_96M: Select PLL_F96M as the source clock

enumerator I2S_CLK_SRC_PLL_64M: Select PLL_F64M as the source clock

enumerator I2S_CLK_SRC_XTAL: Select XTAL as the source clock

enum soc_periph_i2c_clk_src_t

Type of I2C clock source.

Values:

enumerator I2C_CLK_SRC_XTAL: Select XTAL as the source clock

enumerator I2C_CLK_SRC_RC_FAST: Select RC_FAST as the source clock

enumerator I2C_CLK_SRC_DEFAULT: Select XTAL as the default source clock

enum soc_periph_spi_clk_src_t

Type of SPI clock source.

Values:

enumerator SPI_CLK_SRC_DEFAULT: Select PLL_48M as SPI source clock

enumerator SPI_CLK_SRC_PLL_F48M: Select PLL_48M as SPI source clock

enumerator SPI_CLK_SRC_XTAL: Select XTAL as SPI source clock

enumerator SPI_CLK_SRC_RC_FAST: Select RC_FAST as SPI source clock

enum soc_periph_sdm_clk_src_t

Sigma Delta Modulator clock source.

Values:

enumerator SDM_CLK_SRC_XTAL: Select XTAL clock as the source clock

enumerator SDM_CLK_SRC_PLL_F48M: Select PLL_F48M clock as the source clock

enumerator SDM_CLK_SRC_DEFAULT: Select PLL_F48M as the default clock choice

enum soc_periph_ana_cmpr_clk_src_t

Sigma Delta Modulator clock source.

Values:

enumerator ANA_CMPR_CLK_SRC_XTAL: Select XTAL clock as the source clock

enumerator ANA_CMPR_CLK_SRC_PLL_F48M: Select PLL_F48M clock as the source clock

enumerator ANA_CMPR_CLK_SRC_DEFAULT: Select PLL_F48M as the default clock choice

enum soc_periph_glitch_filter_clk_src_t

Glitch filter clock source.

Values:

enumerator GLITCH_FILTER_CLK_SRC_XTAL: Select XTAL clock as the source clock

enumerator GLITCH_FILTER_CLK_SRC_PLL_F48M: Select PLL_F48M clock as the source clock

enumerator GLITCH_FILTER_CLK_SRC_DEFAULT: Select PLL_F48M clock as the default clock choice

enum soc_periph_twai_clk_src_t

TWAI clock source.

Values:

enumerator TWAI_CLK_SRC_XTAL: Select XTAL as the source clock

enumerator TWAI_CLK_SRC_DEFAULT: Select XTAL as the default clock choice

enum soc_periph_adc_digi_clk_src_t

ADC digital controller clock source.

Values:

enumerator ADC_DIGI_CLK_SRC_XTAL: Select XTAL as the source clock

enumerator ADC_DIGI_CLK_SRC_PLL_F96M: Select PLL_F96M as the source clock

enumerator ADC_DIGI_CLK_SRC_RC_FAST: Select RC_FAST as the source clock

enumerator ADC_DIGI_CLK_SRC_DEFAULT: Select PLL_F96M as the default clock choice

enum soc_periph_mwdt_clk_src_t

MWDT clock source.

Values:

enumerator MWDT_CLK_SRC_XTAL: Select XTAL as the source clock

enumerator MWDT_CLK_SRC_PLL_F48M: Select PLL fixed 48 MHz as the source clock

enumerator MWDT_CLK_SRC_RC_FAST: Select RTC fast as the source clock

enumerator MWDT_CLK_SRC_DEFAULT: Select PLL 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_PLL_DIV_CLK: Select PLL_F96M clock as the source clock

enumerator LEDC_USE_RC_FAST_CLK: Select RC_FAST as the source clock

enumerator LEDC_USE_XTAL_CLK: Select XTAL as the source clock

enumerator LEDC_USE_RTC8M_CLK: Alias of 'LEDC_USE_RC_FAST_CLK'

enum soc_periph_parlio_clk_src_t

PARLIO clock source.

Values:

enumerator PARLIO_CLK_SRC_XTAL: Select XTAL as the source clock

enumerator PARLIO_CLK_SRC_PLL_F96M: Select PLL_F96M as the source clock

enumerator PARLIO_CLK_SRC_DEFAULT: Select PLL_F96M as the default clock choice

enum soc_periph_mspi_clk_src_t

MSPI digital controller clock source.

Values:

enumerator MSPI_CLK_SRC_XTAL: Select XTAL as the source clock

enumerator MSPI_CLK_SRC_RC_FAST: Select RC_FAST as the source clock

enumerator MSPI_CLK_SRC_PLL_F64M: Select PLL_F64M as the source clock

enumerator MSPI_CLK_SRC_PLL_F48M: Select PLL_F48M as the source clock

enumerator MSPI_CLK_SRC_DEFAULT: Select PLL_F64M as the default clock choice

enumerator MSPI_CLK_SRC_ROM_DEFAULT: Select XTAL as ROM default clock source

Header File

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

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

Provide feedback about this document