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_CLKcan be computed in runtime through calibration on theRC_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_CLKcan be either a 32 kHz crystal connecting to the32K_XPand32K_XNpins or a 32 kHz clock signal generated by an external circuit. The external signal must be connected to the32K_XNpin. Additionally, a 1 nF capacitor must be placed between the32K_XPpin and ground. In this case, the32K_XPpin cannot be used as a GPIO pin.
XTAL32K_CLKcan 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.
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.
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.
Approximate RC_FAST_CLK frequency in Hz
Approximate RC_SLOW_CLK frequency in Hz
Approximate RC_FAST_D256_CLK frequency in Hz
Approximate XTAL32K_CLK frequency in Hz
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`
}
Array initializer for all supported clock sources of LCD.
Array initializer for all supported clock sources of RMT.
Array initializer for all supported clock sources of UART.
Array initializer for all supported clock sources of MCPWM Timer.
Array initializer for all supported clock sources of MCPWM Capture Timer.
Array initializer for all supported clock sources of MCPWM Carrier.
Array initializer for all supported clock sources of I2S.
Array initializer for all supported clock sources of I2C.
Array initializer for all supported clock sources of SPI.
Array initializer for all supported clock sources of SDM.
Array initializer for all supported clock sources of DAC digital controller.
Array initializer for all supported clock sources of DAC cosine wave generator.
Array initializer for all supported clock sources of TWAI.
Array initializer for all supported clock sources of ADC digital controller.
Array initializer for all supported clock sources of ADC RTC controller.
Array initializer for all supported clock sources of MWDT.
Array initializer for all supported clock sources of LEDC.
Array initializer for all supported clock sources of SDMMC.
Root clock.
Values:
Internal 8MHz RC oscillator
Internal 150kHz RC oscillator
External 2~40MHz crystal
External 32kHz crystal/clock signal
ROOT clock circuit, which requires explicitly enabling the targeting circuit to use.
Values:
BBPLL_CLK is the output of the BBPLL generator circuit
APLL_CLK is the output of the APLL generator circuit
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:
Select XTAL_CLK as CPU_CLK source
Select PLL_CLK as CPU_CLK source (PLL_CLK is the output of 40MHz crystal oscillator frequency multiplier, can be 480MHz or 320MHz)
Select RC_FAST_CLK as CPU_CLK source
Select APLL_CLK as CPU_CLK source
Invalid CPU_CLK source
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:
Select RC_SLOW_CLK as RTC_SLOW_CLK source
Select XTAL32K_CLK as RTC_SLOW_CLK source
Select RC_FAST_D256_CLK (referred as FOSC_DIV or 8m_d256/8md256 in TRM and reg. description) as RTC_SLOW_CLK source
Invalid RTC_SLOW_CLK source
RC_SLOW_CLK is the default clock source for RTC_SLOW_CLK
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:
Select XTAL_D4_CLK (may referred as XTAL_CLK_DIV_4) as RTC_FAST_CLK source
Select RC_FAST_CLK as RTC_FAST_CLK source
Invalid RTC_FAST_CLK source
XTAL_D4_CLK is the default clock source for RTC_FAST_CLK
Alias name for SOC_RTC_FAST_CLK_SRC_XTAL_D4
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:
Automatic XTAL frequency detention
24MHz XTAL
26MHz XTAL
40MHz XTAL
Supported clock sources for modules (CPU, peripherals, RTC, etc.)
Note
enum starts from 1, to save 0 for special purpose
Values:
CPU_CLK can be sourced from XTAL, PLL, RC_FAST, or APLL by configuring soc_cpu_clk_src_t
RTC_FAST_CLK can be sourced from XTAL_D4 or RC_FAST by configuring soc_rtc_fast_clk_src_t
RTC_SLOW_CLK can be sourced from RC_SLOW, XTAL32K, or RC_FAST_D256 by configuring soc_rtc_slow_clk_src_t
APB_CLK is highly dependent on the CPU_CLK source
PLL_D2_CLK is derived from PLL, it has a fixed divider of 2
PLL_F160M_CLK is derived from PLL, and has a fixed frequency of 160MHz
XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals
RC_FAST_CLK comes from the internal 8MHz rc oscillator, passing a clock gating to the peripherals
RC_FAST_D256_CLK comes from the internal 8MHz rc oscillator, divided by 256, and passing a clock gating to the peripherals
XTAL_CLK comes from the external crystal (2~40MHz)
REF_TICK is derived from APB, it has a fixed frequency of 1MHz even when APB frequency changes
APLL is sourced from PLL, and its frequency is configurable through APLL configuration registers
Indication of the end of the available module clock sources
Type of SYSTIMER clock source.
Values:
SYSTIMER source clock is XTAL
SYSTIMER source clock default choice is XTAL
Type of GPTimer clock source.
Values:
Select APB as the source clock
Select APB as the default choice
Type of Timer Group clock source, reserved for the legacy timer group driver.
Values:
Timer group source clock is APB
Timer group source clock default choice is APB
Type of LCD clock source.
Values:
Select PLL_160M as the source clock
Select PLL_160M as the default choice
Type of RMT clock source.
Values:
Select APB as the source clock
Select REF_TICK as the source clock
Select APB as the default choice
Type of RMT clock source, reserved for the legacy RMT driver.
Values:
RMT source clock is APB CLK
RMT source clock is REF_TICK
RMT source clock default choice is APB
Type of UART clock source, reserved for the legacy UART driver.
Values:
UART source clock is APB CLK
UART source clock is REF_TICK
UART source clock default choice is APB
Type of MCPWM timer clock source.
Values:
Select PLL_F160M as the source clock
Select PLL_F160M as the default clock choice
Type of MCPWM capture clock source.
Values:
Select APB as the source clock
Select APB as the default clock choice
Type of MCPWM carrier clock source.
Values:
Select PLL_F160M as the source clock
Select PLL_F160M as the default clock choice
I2S clock source enum.
Values:
Select PLL_F160M as the default source clock
Select PLL_F160M as the source clock
Select APLL as the source clock
Type of I2C clock source.
Values:
Type of SPI clock source.
Values:
Select APB as SPI source clock
Select APB as SPI source clock
Sigma Delta Modulator clock source.
Values:
Select APB as the source clock
Select APB as the default clock choice
DAC digital controller clock source.
Values:
Select PLL_D2 as the source clock
Select APLL as the source clock
Select PLL_D2 as the default source clock
DAC cosine wave generator clock source.
Values:
Select RTC FAST as the source clock
Select RTC FAST as the default source clock
TWAI clock source.
Values:
Select APB as the source clock
Select APB as the default clock choice
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:
Select F160M as the source clock
Select APLL as the source clock
Select F160M as the default clock choice
ADC RTC controller clock source.
Values:
Select RC_FAST as the source clock
Select RC_FAST as the default clock choice
MWDT clock source.
Values:
Select APB as the source clock
Select APB as the default clock choice
Type of LEDC clock source, reserved for the legacy LEDC driver.
Values:
LEDC source clock will be automatically selected based on the giving resolution and duty parameter when init the timer
Select APB as the source clock
Select RC_FAST as the source clock
Select REF_TICK as the source clock
Alias of 'LEDC_USE_RC_FAST_CLK'
Type of SDMMC clock source.
Values:
Select PLL_160M as the default choice
Select PLL_160M as the source clock
Values:
I2S0 clock, depends on the i2s driver configuration
PLL_CLK is the output of crystal oscillator frequency multiplier
RC slow clock, depends on the RTC_CLK_SRC configuration
Main crystal oscillator clock
Divided by PLL, frequency is configurable
Divided by APB clock, usually be 1MHz
From PLL, usually be 80MHz
RC fast clock, about 8MHz
I2S1 clock, depends on the i2s driver configuration
This header file can be included with:
#include "esp_clk_tree.h"
Get frequency of module clock source.
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
ESP_OK Success
ESP_ERR_INVALID_ARG Parameter error
ESP_FAIL Calibration failed
Degree of precision of frequency value to be returned by esp_clk_tree_src_get_freq_hz()
Values:
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4