# 时钟树

[English]

ESP32-C2 的时钟子系统用于从一系列根时钟中提取并分配系统/模块时钟。时钟树驱动程序负责维护系统时钟的基本功能，并管理模块时钟间的复杂关系。

本文档首先介绍了根时钟和模块时钟，随后介绍了可供用户调用的时钟树 API，调用这些 API，可以监测模块时钟的运行状态。

## 简介

本节列出了 ESP32-C2 支持的根时钟和模块时钟的定义，这些定义通常用于驱动程序配置，有助于为外设选择合适的时钟源。

### 根时钟

根时钟会产生可靠的时钟信号，经各种门、复用器、分频器或倍频器传递，这些时钟信号最终成为 CPU 内核、Wi-Fi、蓝牙、RTC 及外设等功能模块的时钟源。

ESP32-C2 的根时钟列在 `soc_root_clk_t` 中：

> - 内部 17.5 MHz RC 振荡器 (RC_FAST)

>   > 此 RC 振荡器可产生约 17.5 MHz 的时钟信号输出，标识为 `RC_FAST_CLK`。

>   > 此约 17.5 MHz 的信号也会传入可配置的分频器，默认情况下，该分频器会将输入的时钟频率分频 256 倍，生成信号 `RC_FAST_D256_CLK`。

>   > 在运行时，通过在 `RC_FAST_D256_CLK` 上校准，可以计算 `RC_FAST_CLK` 的实际频率。

> - 外部 40/26 MHz 晶振 (XTAL)

> - 内部 136 kHz RC 振荡器 (RC_SLOW)

>   > 此 RC 振荡器产生约 136 kHz 的时钟信号输出，标识为 `RC_SLOW_CLK`。在运行时，通过校准，可以计算该时钟信号的实际频率。

> - 外部慢速时钟 - 可选 (OSC_SLOW)

>   > 将外部电路生成的时钟信号连接到 pin0（时钟信号频率不超过 136 kHz 时），可作为 `RTC_SLOW_CLK` 的时钟源。通过校准，可以计算该时钟信号的实际频率。

与晶振产生的信号相比，从 RC 振荡器电路产生的信号通常精度较低，且容易受环境影响。因此，ESP32-C2 为 `RTC_SLOW_CLK` 提供了几种时钟源选项，可以根据对系统时间精度和对功耗的要求选择。更多详情，请参阅 RTC 定时器时钟源。

### 模块时钟

ESP32-C2 的可用模块时钟在 `soc_module_clk_t` 中列出，每个模块时钟都有其唯一 ID。查阅文档中的枚举值，即可获取各模块时钟的详细信息。

## 使用 API

时钟树驱动程序提供了一个一体化接口，可以获取模块时钟的频率，即 `esp_clk_tree_src_get_freq_hz()`。通过该函数，你可以在任何时刻，通过提供时钟名称 `soc_module_clk_t` 和指定返回频率值的精度级别 `esp_clk_tree_src_freq_precision_t`，获取时钟频率。

## API 参考

### Header File

- components/soc/esp32c2/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_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_TEMP_SENSOR_CLKS

  Array initializer for all supported clock sources of Temperature Sensor.

SOC_UART_CLKS

  Array initializer for all supported clock sources of UART.

SOC_SPI_CLKS

  Array initializer for all supported clock sources of SPI.

SOC_I2C_CLKS

  Array initializer for all supported clock sources of I2C.

SOC_ADC_DIGI_CLKS

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

SOC_GLITCH_FILTER_CLKS

  Array initializer for all supported clock sources of Glitch Filter.

SOC_MWDT_CLKS

  Array initializer for all supported clock sources of MWDT.

SOC_LEDC_CLKS

  Array initializer for all supported clock sources of LEDC.

### Enumerations

enum soc_root_clk_t

  Root clock.

  Values:

  enumerator SOC_ROOT_CLK_INT_RC_FAST

    Internal 17.5MHz RC oscillator

  enumerator SOC_ROOT_CLK_INT_RC_SLOW

    Internal 136kHz RC oscillator

  enumerator SOC_ROOT_CLK_EXT_XTAL

    External 26/40MHz crystal

  enumerator SOC_ROOT_CLK_EXT_OSC_SLOW

    External slow clock signal at pin0, only support 32.768 KHz currently

enum soc_cpu_clk_src_t

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

  备注

  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 26/40MHz crystal oscillator frequency multiplier, 480MHz)

  enumerator SOC_CPU_CLK_SRC_RC_FAST

    Select RC_FAST_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.

  备注

  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_OSC_SLOW

    Select OSC_SLOW_CLK (external slow clock) 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.

  备注

  Enum values are matched with the register field values on purpose

  Values:

  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_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_D2_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_D2`

enum soc_xtal_freq_t

  Possible main XTAL frequency options on the target.

  备注

  Enum values equal to the frequency value in MHz

  备注

  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_26M

    26MHz XTAL

  enumerator SOC_XTAL_FREQ_32M

    32MHz XTAL

  enumerator SOC_XTAL_FREQ_40M

    40MHz XTAL

enum soc_module_clk_t

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

  备注

  enum starts from 1, to save 0 for special purpose

  Values:

  enumerator SOC_MOD_CLK_CPU

    CPU_CLK can be sourced from XTAL, PLL, or RC_FAST 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, or RC_FAST_D256 by configuring soc_rtc_slow_clk_src_t

  enumerator SOC_MOD_CLK_APB

    APB_CLK is always 40MHz no matter it derives from XTAL or PLL

  enumerator SOC_MOD_CLK_PLL_F40M

    PLL_F40M_CLK is derived from PLL, and has a fixed frequency of 40MHz

  enumerator SOC_MOD_CLK_PLL_F60M

    PLL_F60M_CLK is derived from PLL, and has a fixed frequency of 60MHz

  enumerator SOC_MOD_CLK_PLL_F80M

    PLL_F80M_CLK is derived from PLL, and has a fixed frequency of 80MHz

  enumerator SOC_MOD_CLK_OSC_SLOW

    OSC_SLOW_CLK comes from an external slow clock signal, passing a clock gating to the peripherals

  enumerator SOC_MOD_CLK_RC_FAST

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

  enumerator SOC_MOD_CLK_RC_FAST_D256

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

  enumerator SOC_MOD_CLK_XTAL

    XTAL_CLK comes from the external 26/40MHz 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_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_F40M

    Select PLL_F40M as the source clock

  enumerator GPTIMER_CLK_SRC_XTAL

    Select XTAL as the source clock

  enumerator GPTIMER_CLK_SRC_DEFAULT

    Select PLL_F40M 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_F40M

    Timer group clock source is PLL_F40M

  enumerator TIMER_SRC_CLK_XTAL

    Timer group clock source is XTAL

  enumerator TIMER_SRC_CLK_DEFAULT

    Timer group clock source default choice is PLL_F40M

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_F40M

    UART source clock is PLL_F40M CLK

  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_F40M

enum soc_periph_spi_clk_src_t

  Type of SPI clock source.

  Values:

  enumerator SPI_CLK_SRC_DEFAULT

    Select PLL_40M as SPI source clock

  enumerator SPI_CLK_SRC_PLL_F40M

    Select PLL_40M as SPI source clock

  enumerator SPI_CLK_SRC_XTAL

    Select XTAL as SPI 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 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_F80M

    Select PLL_F80M as the source clock

  enumerator ADC_DIGI_CLK_SRC_DEFAULT

    Select PLL_F80M as the default clock choice

enum soc_periph_glitch_filter_clk_src_t

  Glitch filter clock source.

  Values:

  enumerator GLITCH_FILTER_CLK_SRC_APB

    Select APB clock as the source clock

  enumerator GLITCH_FILTER_CLK_SRC_DEFAULT

    Select APB clock 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_F40M

    Select PLL 40 Mhz as the source clock

  enumerator MWDT_CLK_SRC_DEFAULT

    Select PLL 40 Mhz 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_F60M 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_clkout_sig_id_t

  Values:

  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_PLL_F80M

    From PLL, usually be 80MHz

  enumerator CLKOUT_SIG_RC_FAST

    RC fast clock, about 8MHz

  enumerator CLKOUT_SIG_INVALID

### 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.

  参数:

    - 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

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

此文档对您有帮助吗？

- 反馈已收到，谢谢！
- 如果您有其他意见，欢迎填写乐鑫文档反馈表。

- 我们重视您的反馈。
- 您可以填写乐鑫文档反馈表告诉我们如何改进该文档。