From 729d70129af009edb02dfc73d56ff26175bb6313 Mon Sep 17 00:00:00 2001 From: songruojing Date: Fri, 13 May 2022 11:43:42 +0800 Subject: [PATCH] clk_tree: add initial docs for clock tree --- .../esp_hw_support/port/esp32c2/Kconfig.rtc | 6 +- .../esp_hw_support/port/esp32c3/Kconfig.rtc | 4 +- .../esp_hw_support/port/esp32h2/Kconfig.rtc | 2 +- .../esp_hw_support/port/esp32s2/Kconfig.rtc | 4 +- .../esp_hw_support/port/esp32s3/Kconfig.rtc | 4 +- .../soc/esp32/include/soc/clk_tree_defs.h | 46 ++++++------ .../soc/esp32c2/include/soc/clk_tree_defs.h | 60 +++++++-------- .../soc/esp32c3/include/soc/clk_tree_defs.h | 63 ++++++++-------- .../soc/esp32h2/include/soc/clk_tree_defs.h | 52 ++++++------- .../soc/esp32s2/include/soc/clk_tree_defs.h | 55 +++++++------- .../soc/esp32s3/include/soc/clk_tree_defs.h | 65 ++++++++-------- .../en/api-reference/peripherals/clk_tree.rst | 74 ++++++++++++++++++- docs/en/api-reference/system/system_time.rst | 2 + .../api-reference/system/system_time.rst | 2 + 14 files changed, 259 insertions(+), 180 deletions(-) diff --git a/components/esp_hw_support/port/esp32c2/Kconfig.rtc b/components/esp_hw_support/port/esp32c2/Kconfig.rtc index 81edf8fcb0..1fcd0d64b2 100644 --- a/components/esp_hw_support/port/esp32c2/Kconfig.rtc +++ b/components/esp_hw_support/port/esp32c2/Kconfig.rtc @@ -5,11 +5,11 @@ choice RTC_CLK_SRC Choose which clock is used as RTC clock source. config RTC_CLK_SRC_INT_RC - bool "Internal 150kHz RC oscillator" + bool "Internal 136kHz RC oscillator" config RTC_CLK_SRC_EXT_OSC - bool "External 32kHz oscillator at 32K_XP pin" + bool "External 32kHz oscillator at pin0" config RTC_CLK_SRC_INT_8MD256 - bool "Internal 8MHz oscillator, divided by 256 (~32kHz)" + bool "Internal 17.5MHz oscillator, divided by 256" endchoice config RTC_CLK_CAL_CYCLES diff --git a/components/esp_hw_support/port/esp32c3/Kconfig.rtc b/components/esp_hw_support/port/esp32c3/Kconfig.rtc index 5adb511a44..b68d2a9199 100644 --- a/components/esp_hw_support/port/esp32c3/Kconfig.rtc +++ b/components/esp_hw_support/port/esp32c3/Kconfig.rtc @@ -5,7 +5,7 @@ choice RTC_CLK_SRC Choose which clock is used as RTC clock source. config RTC_CLK_SRC_INT_RC - bool "Internal 150kHz RC oscillator" + bool "Internal 136kHz RC oscillator" config RTC_CLK_SRC_EXT_CRYS bool "External 32kHz crystal" select ESP_SYSTEM_RTC_EXT_XTAL @@ -13,7 +13,7 @@ choice RTC_CLK_SRC bool "External 32kHz oscillator at 32K_XP pin" select ESP_SYSTEM_RTC_EXT_OSC config RTC_CLK_SRC_INT_8MD256 - bool "Internal 8MHz oscillator, divided by 256 (~32kHz)" + bool "Internal 17.5MHz oscillator, divided by 256" endchoice config RTC_CLK_CAL_CYCLES diff --git a/components/esp_hw_support/port/esp32h2/Kconfig.rtc b/components/esp_hw_support/port/esp32h2/Kconfig.rtc index 9d43def0e9..55068bf315 100644 --- a/components/esp_hw_support/port/esp32h2/Kconfig.rtc +++ b/components/esp_hw_support/port/esp32h2/Kconfig.rtc @@ -5,7 +5,7 @@ choice RTC_CLK_SRC Choose which clock is used as RTC clock source. config RTC_CLK_SRC_INT_RC - bool "Internal 150kHz RC oscillator" + bool "Internal 136kHz RC oscillator" config RTC_CLK_SRC_EXT_CRYS bool "External 32.768kHz crystal" select ESP_SYSTEM_RTC_EXT_XTAL diff --git a/components/esp_hw_support/port/esp32s2/Kconfig.rtc b/components/esp_hw_support/port/esp32s2/Kconfig.rtc index 059baf3890..338a394b76 100644 --- a/components/esp_hw_support/port/esp32s2/Kconfig.rtc +++ b/components/esp_hw_support/port/esp32s2/Kconfig.rtc @@ -12,11 +12,9 @@ choice RTC_CLK_SRC expense of slightly higher (1uA) deep sleep current consumption. - "External 32kHz oscillator" allows using 32kHz clock generated by an external circuit. In this case, external clock signal must be connected - to 32K_XN pin. Amplitude should be <1.2V in case of sine wave signal, + to 32K_XP pin. Amplitude should be <1.2V in case of sine wave signal, and <1V in case of square wave signal. Common mode voltage should be 0.1 < Vcm < 0.5Vamp, where Vamp is the signal amplitude. - Additionally, 1nF capacitor must be connected between 32K_XP pin and - ground. 32K_XP pin can not be used as a GPIO in this case. - "Internal 8MHz oscillator divided by 256" option results in higher deep sleep current (by 5uA) but has better frequency stability than the internal 90kHz oscillator. It does not require external components. diff --git a/components/esp_hw_support/port/esp32s3/Kconfig.rtc b/components/esp_hw_support/port/esp32s3/Kconfig.rtc index 5adb511a44..b68d2a9199 100644 --- a/components/esp_hw_support/port/esp32s3/Kconfig.rtc +++ b/components/esp_hw_support/port/esp32s3/Kconfig.rtc @@ -5,7 +5,7 @@ choice RTC_CLK_SRC Choose which clock is used as RTC clock source. config RTC_CLK_SRC_INT_RC - bool "Internal 150kHz RC oscillator" + bool "Internal 136kHz RC oscillator" config RTC_CLK_SRC_EXT_CRYS bool "External 32kHz crystal" select ESP_SYSTEM_RTC_EXT_XTAL @@ -13,7 +13,7 @@ choice RTC_CLK_SRC bool "External 32kHz oscillator at 32K_XP pin" select ESP_SYSTEM_RTC_EXT_OSC config RTC_CLK_SRC_INT_8MD256 - bool "Internal 8MHz oscillator, divided by 256 (~32kHz)" + bool "Internal 17.5MHz oscillator, divided by 256" endchoice config RTC_CLK_CAL_CYCLES diff --git a/components/soc/esp32/include/soc/clk_tree_defs.h b/components/soc/esp32/include/soc/clk_tree_defs.h index ac26e6a3e0..7a218bc307 100644 --- a/components/soc/esp32/include/soc/clk_tree_defs.h +++ b/components/soc/esp32/include/soc/clk_tree_defs.h @@ -37,18 +37,18 @@ extern "C" { */ /* With the default value of CK8M_DFREQ = 172, RC_FAST clock frequency is 8.5 MHz +/- 7% */ -#define SOC_CLK_RC_FAST_FREQ_APPROX 8500000 +#define SOC_CLK_RC_FAST_FREQ_APPROX 8500000 /*!< Approximate RC_FAST_CLK frequency in Hz */ /* With the default value of DCAP, range is +/- 5% */ -#define SOC_CLK_RC_SLOW_FREQ_APPROX 150000 -#define SOC_CLK_RC_FAST_D256_FREQ_APPROX (SOC_CLK_RC_FAST_FREQ_APPROX / 256) -#define SOC_CLK_XTAL32K_FREQ_APPROX 32768 +#define SOC_CLK_RC_SLOW_FREQ_APPROX 150000 /*!< Approximate RC_SLOW_CLK frequency in Hz */ +#define SOC_CLK_RC_FAST_D256_FREQ_APPROX (SOC_CLK_RC_FAST_FREQ_APPROX / 256) /*!< Approximate RC_FAST_D256_CLK frequency in Hz */ +#define SOC_CLK_XTAL32K_FREQ_APPROX 32768 /*!< Approximate XTAL32K_CLK frequency in Hz */ +// Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr] +// {loc}: EXT, INT +// {type}: XTAL, RC +// [attr] - optional: [frequency], FAST, SLOW /** * @brief Root clock - * Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr] - * {loc}: EXT, INT - * {type}: XTAL, RC - * [attr] - optional: [frequency], FAST, SLOW */ typedef enum { SOC_ROOT_CLK_INT_RC_FAST, /*!< Internal 8MHz RC oscillator */ @@ -88,28 +88,29 @@ typedef enum { SOC_RTC_FAST_CLK_SRC_RC_FAST = 1, /*!< Select RC_FAST_CLK as RTC_FAST_CLK source */ } soc_rtc_fast_clk_src_t; +// Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr] +// {[upstream]clock_name}: APB, APLL, (BB)PLL, etc. +// [attr] - optional: FAST, SLOW, D, F /** * @brief Supported clock sources for modules (CPU, peripherals, RTC, etc.) - * Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr] - * {[upstream]clock_name}: APB, APLL, (BB)PLL, etc. - * [attr] - optional: FAST, SLOW, D, F + * * @note enum starts from 1, to save 0 for special purpose */ typedef enum { // For CPU domain - SOC_MOD_CLK_CPU = 1, /*< CPU_CLK can be sourced from XTAL, PLL, RC_FAST, or APLL by configuring soc_cpu_clk_src_t */ + SOC_MOD_CLK_CPU = 1, /*!< CPU_CLK can be sourced from XTAL, PLL, RC_FAST, or APLL by configuring soc_cpu_clk_src_t */ // For RTC domain - SOC_MOD_CLK_RTC_FAST = 2, /*< RTC_FAST_CLK can be sourced from XTAL_D4 or RC_FAST by configuring soc_rtc_fast_clk_src_t */ - SOC_MOD_CLK_RTC_SLOW = 3, /*< RTC_SLOW_CLK can be sourced from RC_SLOW, XTAL32K, or RC_FAST_D256 by configuring soc_rtc_slow_clk_src_t */ + 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 */ + 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 */ // For digital domain: peripherals, WIFI, BLE - SOC_MOD_CLK_APB = 4, /*< APB_CLK is highly dependent on the CPU_CLK source */ - SOC_MOD_CLK_PLL_D2 = 5, /*< PLL_D2_CLK is derived from PLL, it has a fixed divider of 2 */ - SOC_MOD_CLK_XTAL32K = 6, /*< XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals */ - SOC_MOD_CLK_RC_FAST = 7, /*< RC_FAST_CLK comes from the internal 8MHz rc oscillator, passing a clock gating to the peripherals */ - SOC_MOD_CLK_RC_FAST_D256 = 8, /*< RC_FAST_D256_CLK comes from the internal 8MHz rc oscillator, divided by 256, and passing a clock gating to the peripherals */ - SOC_MOD_CLK_XTAL = 9, /*< XTAL_CLK comes from the external crystal (2~40MHz) */ - SOC_MOD_CLK_REF_TICK = 10, /*< REF_TICK is derived from APB, it has a fixed frequency of 1MHz even when APB frequency changes */ - SOC_MOD_CLK_APLL = 11, /*< APLL is sourced from PLL, and its frequency is configurable through APLL configuration registers */ + SOC_MOD_CLK_APB, /*!< APB_CLK is highly dependent on the CPU_CLK source */ + SOC_MOD_CLK_PLL_D2, /*!< PLL_D2_CLK is derived from PLL, it has a fixed divider of 2 */ + SOC_MOD_CLK_XTAL32K, /*!< XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals */ + SOC_MOD_CLK_RC_FAST, /*!< RC_FAST_CLK comes from the internal 8MHz rc oscillator, passing a clock gating to the peripherals */ + 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 */ + SOC_MOD_CLK_XTAL, /*!< XTAL_CLK comes from the external crystal (2~40MHz) */ + SOC_MOD_CLK_REF_TICK, /*!< REF_TICK is derived from APB, it has a fixed frequency of 1MHz even when APB frequency changes */ + SOC_MOD_CLK_APLL, /*!< APLL is sourced from PLL, and its frequency is configurable through APLL configuration registers */ } soc_module_clk_t; @@ -117,6 +118,7 @@ typedef enum { /** * @brief Array initializer for all supported clock sources of GPTimer + * * The following code can be used to iterate all possible clocks: * @code{c} * soc_periph_gptimer_clk_src_t gptimer_clks[] = (soc_periph_gptimer_clk_src_t)SOC_GPTIMER_CLKS; diff --git a/components/soc/esp32c2/include/soc/clk_tree_defs.h b/components/soc/esp32c2/include/soc/clk_tree_defs.h index 71f12d83f0..90c9f7f2dd 100644 --- a/components/soc/esp32c2/include/soc/clk_tree_defs.h +++ b/components/soc/esp32c2/include/soc/clk_tree_defs.h @@ -11,7 +11,7 @@ extern "C" { /* ************************ ESP32C2 Root Clock Source *************************** - * 1) Internal 20MHz RC Oscillator: RC_FAST (usually referred as FOSC or CK8M/CLK8M in TRM and reg. description) + * 1) Internal 17.5MHz RC Oscillator: RC_FAST (usually referred as FOSC or CK8M/CLK8M in TRM and reg. description) * * This RC oscillator generates a ~17.5MHz clock signal output as the RC_FAST_CLK. * The ~17.5MHz signal output is also passed into a configurable divider, which by default divides the input clock @@ -21,37 +21,37 @@ extern "C" { * * 2) External 40MHz Crystal Clock: XTAL * - * 3) Internal 1500kHz RC Oscillator: RC_SLOW (usually referrred as RTC in TRM or reg. description) + * 3) Internal 136kHz RC Oscillator: RC_SLOW (usually referrred as RTC in TRM or reg. description) * - * This RC oscillator generates a ~150kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock + * This RC oscillator generates a ~136kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock * can be computed in runtime through calibration. * * 4) External Slow Clock (optional): OSC_SLOW * - * A clock signal generated by an external circuit with frequency no more than 150kHz can be connected to GPIO0 pin + * A clock signal generated by an external circuit with frequency no more than 136kHz can be connected to pin0 * to be the clock source for the RTC_SLOW_CLK. * * OSC_SLOW_CLK can also be calibrated to get its exact frequency. */ /* With the default value of CK8M_DFREQ = 100, RC_FAST clock frequency is 17.5 MHz +/- 7% */ -#define SOC_CLK_RC_FAST_FREQ_APPROX 17500000 -#define SOC_CLK_RC_SLOW_FREQ_APPROX 150000 -#define SOC_CLK_RC_FAST_D256_FREQ_APPROX (SOC_CLK_RC_FAST_FREQ_APPROX / 256) -#define SOC_CLK_OSC_SLOW_FREQ_APPROX 32768 +#define SOC_CLK_RC_FAST_FREQ_APPROX 17500000 /*!< Approximate RC_FAST_CLK frequency in Hz */ +#define SOC_CLK_RC_SLOW_FREQ_APPROX 136000 /*!< Approximate RC_SLOW_CLK frequency in Hz */ +#define SOC_CLK_RC_FAST_D256_FREQ_APPROX (SOC_CLK_RC_FAST_FREQ_APPROX / 256) /*!< Approximate RC_FAST_D256_CLK frequency in Hz */ +#define SOC_CLK_OSC_SLOW_FREQ_APPROX 32768 /*!< Approximate OSC_SLOW_CLK (external slow clock) frequency in Hz */ +// Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr] +// {loc}: EXT, INT +// {type}: XTAL, RC +// [attr] - optional: [frequency], FAST, SLOW /** * @brief Root clock - * Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr] - * {loc}: EXT, INT - * {type}: XTAL, RC - * [attr] - optional: [frequency], FAST, SLOW */ typedef enum { - SOC_ROOT_CLK_INT_RC_FAST, /*!< Internal 8MHz RC oscillator */ - SOC_ROOT_CLK_INT_RC_SLOW, /*!< Internal 150kHz RC oscillator */ + SOC_ROOT_CLK_INT_RC_FAST, /*!< Internal 17.5MHz RC oscillator */ + SOC_ROOT_CLK_INT_RC_SLOW, /*!< Internal 136kHz RC oscillator */ SOC_ROOT_CLK_EXT_XTAL, /*!< External 40MHz crystal */ - SOC_ROOT_CLK_EXT_OSC_SLOW, /*!< External slow clock signal at GPIO0 */ + SOC_ROOT_CLK_EXT_OSC_SLOW, /*!< External slow clock signal at pin0 */ } soc_root_clk_t; /** @@ -70,7 +70,7 @@ typedef enum { */ typedef enum { SOC_RTC_SLOW_CLK_SRC_RC_SLOW = 0, /*!< Select RC_SLOW_CLK as RTC_SLOW_CLK source */ - SOC_RTC_SLOW_CLK_SRC_OSC_SLOW = 1, /*!< Select OSC_SLOW_CLK as RTC_SLOW_CLK source */ + SOC_RTC_SLOW_CLK_SRC_OSC_SLOW = 1, /*!< Select OSC_SLOW_CLK (external slow clock) as RTC_SLOW_CLK source */ SOC_RTC_SLOW_CLK_SRC_RC_FAST_D256 = 2, /*!< Select RC_FAST_D256_CLK (referred as FOSC_DIV or 8m_d256/8md256 in TRM and reg. description) as RTC_SLOW_CLK source */ } soc_rtc_slow_clk_src_t; @@ -84,27 +84,28 @@ typedef enum { SOC_RTC_FAST_CLK_SRC_RC_FAST = 1, /*!< Select RC_FAST_CLK as RTC_FAST_CLK source */ } soc_rtc_fast_clk_src_t; +// Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr] +// {[upstream]clock_name}: (BB)PLL etc. +// [attr] - optional: FAST, SLOW, D, F /** * @brief Supported clock sources for modules (CPU, peripherals, RTC, etc.) - * Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr] - * {[upstream]clock_name}: (BB)PLL etc. - * [attr] - optional: FAST, SLOW, D, F + * * @note enum starts from 1, to save 0 for special purpose */ typedef enum { // For CPU domain - SOC_MOD_CLK_CPU = 1, /*< CPU_CLK can be sourced from XTAL, PLL, or RC_FAST by configuring soc_cpu_clk_src_t */ + SOC_MOD_CLK_CPU = 1, /*!< CPU_CLK can be sourced from XTAL, PLL, or RC_FAST by configuring soc_cpu_clk_src_t */ // For RTC domain - SOC_MOD_CLK_RTC_FAST = 2, /*< RTC_FAST_CLK can be sourced from XTAL_D2 or RC_FAST by configuring soc_rtc_fast_clk_src_t */ - SOC_MOD_CLK_RTC_SLOW = 3, /*< RTC_SLOW_CLK can be sourced from RC_SLOW, XTAL32K, or RC_FAST_D256 by configuring soc_rtc_slow_clk_src_t */ + 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 */ + 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 */ // For digital domain: peripherals, WIFI, BLE - SOC_MOD_CLK_PLL_F40M = 4, /*< PLL_F40M_CLK is derived from PLL, and has a fixed frequency of 40MHz */ - SOC_MOD_CLK_PLL_F60M = 5, /*< PLL_F60M_CLK is derived from PLL, and has a fixed frequency of 60MHz */ - SOC_MOD_CLK_PLL_F80M = 6, /*< PLL_F80M_CLK is derived from PLL, and has a fixed frequency of 80MHz */ - SOC_MOD_CLK_OSC_SLOW = 7, /*< OSC_SLOW_CLK comes from an external slow clock signal, passing a clock gating to the peripherals */ - SOC_MOD_CLK_RC_FAST = 8, /*< RC_FAST_CLK comes from the internal 20MHz rc oscillator, passing a clock gating to the peripherals */ - SOC_MOD_CLK_RC_FAST_D256 = 9, /*< RC_FAST_D256_CLK comes from the internal 20MHz rc oscillator, divided by 256, and passing a clock gating to the peripherals */ - SOC_MOD_CLK_XTAL = 10, /*< XTAL_CLK comes from the external 40MHz crystal */ + SOC_MOD_CLK_PLL_F40M, /*!< PLL_F40M_CLK is derived from PLL, and has a fixed frequency of 40MHz */ + SOC_MOD_CLK_PLL_F60M, /*!< PLL_F60M_CLK is derived from PLL, and has a fixed frequency of 60MHz */ + SOC_MOD_CLK_PLL_F80M, /*!< PLL_F80M_CLK is derived from PLL, and has a fixed frequency of 80MHz */ + SOC_MOD_CLK_OSC_SLOW, /*!< OSC_SLOW_CLK comes from an external slow clock signal, passing a clock gating to the peripherals */ + SOC_MOD_CLK_RC_FAST, /*!< RC_FAST_CLK comes from the internal 20MHz rc oscillator, passing a clock gating to the peripherals */ + 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 */ + SOC_MOD_CLK_XTAL, /*!< XTAL_CLK comes from the external 40MHz crystal */ } soc_module_clk_t; @@ -112,6 +113,7 @@ typedef enum { /** * @brief Array initializer for all supported clock sources of GPTimer + * * The following code can be used to iterate all possible clocks: * @code{c} * soc_periph_gptimer_clk_src_t gptimer_clks[] = (soc_periph_gptimer_clk_src_t)SOC_GPTIMER_CLKS; diff --git a/components/soc/esp32c3/include/soc/clk_tree_defs.h b/components/soc/esp32c3/include/soc/clk_tree_defs.h index 7f91d861e7..897b2754b2 100644 --- a/components/soc/esp32c3/include/soc/clk_tree_defs.h +++ b/components/soc/esp32c3/include/soc/clk_tree_defs.h @@ -11,7 +11,7 @@ extern "C" { /* ************************* ESP32C3 Root Clock Source **************************** - * 1) Internal 20MHz RC Oscillator: RC_FAST (usually referred as FOSC or CK8M/CLK8M in TRM and reg. description) + * 1) Internal 17.5MHz RC Oscillator: RC_FAST (usually referred as FOSC or CK8M/CLK8M in TRM and reg. description) * * This RC oscillator generates a ~17.5MHz clock signal output as the RC_FAST_CLK. * The ~17.5MHz signal output is also passed into a configurable divider, which by default divides the input clock @@ -21,37 +21,36 @@ extern "C" { * * 2) External 40MHz Crystal Clock: XTAL * - * 3) Internal 1500kHz RC Oscillator: RC_SLOW (usually referrred as RTC in TRM or reg. description) + * 3) Internal 136kHz RC Oscillator: RC_SLOW (usually referrred as RTC in TRM or reg. description) * - * This RC oscillator generates a ~150kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock + * This RC oscillator generates a ~136kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock * can be computed in runtime through calibration. * * 4) External 32kHz Crystal Clock (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. + * The clock source for this XTAL32K_CLK can be either a 32kHz crystal connecting to the XTAL_32K_P and XTAL_32K_N + * pins or a 32kHz 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. */ /* With the default value of CK8M_DFREQ = 100, RC_FAST clock frequency is 17.5 MHz +/- 7% */ -#define SOC_CLK_RC_FAST_FREQ_APPROX 17500000 -#define SOC_CLK_RC_SLOW_FREQ_APPROX 150000 -#define SOC_CLK_RC_FAST_D256_FREQ_APPROX (SOC_CLK_RC_FAST_FREQ_APPROX / 256) -#define SOC_CLK_XTAL32K_FREQ_APPROX 32768 +#define SOC_CLK_RC_FAST_FREQ_APPROX 17500000 /*!< Approximate RC_FAST_CLK frequency in Hz */ +#define SOC_CLK_RC_SLOW_FREQ_APPROX 136000 /*!< Approximate RC_SLOW_CLK frequency in Hz */ +#define SOC_CLK_RC_FAST_D256_FREQ_APPROX (SOC_CLK_RC_FAST_FREQ_APPROX / 256) /*!< Approximate RC_FAST_D256_CLK frequency in Hz */ +#define SOC_CLK_XTAL32K_FREQ_APPROX 32768 /*!< Approximate XTAL32K_CLK frequency in Hz */ +// Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr] +// {loc}: EXT, INT +// {type}: XTAL, RC +// [attr] - optional: [frequency], FAST, SLOW /** * @brief Root clock - * Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr] - * {loc}: EXT, INT - * {type}: XTAL, RC - * [attr] - optional: [frequency], FAST, SLOW */ typedef enum { - SOC_ROOT_CLK_INT_RC_FAST, /*!< Internal 8MHz RC oscillator */ - SOC_ROOT_CLK_INT_RC_SLOW, /*!< Internal 150kHz RC oscillator */ + SOC_ROOT_CLK_INT_RC_FAST, /*!< Internal 17.5MHz RC oscillator */ + SOC_ROOT_CLK_INT_RC_SLOW, /*!< Internal 136kHz RC oscillator */ SOC_ROOT_CLK_EXT_XTAL, /*!< External 40MHz crystal */ SOC_ROOT_CLK_EXT_XTAL32K, /*!< External 32kHz crystal/clock signal */ } soc_root_clk_t; @@ -86,34 +85,36 @@ typedef enum { SOC_RTC_FAST_CLK_SRC_RC_FAST = 1, /*!< Select RC_FAST_CLK as RTC_FAST_CLK source */ } soc_rtc_fast_clk_src_t; +// Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr] +// {[upstream]clock_name}: APB, (BB)PLL, etc. +// [attr] - optional: FAST, SLOW, D, F /** * @brief Supported clock sources for modules (CPU, peripherals, RTC, etc.) - * Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr] - * {[upstream]clock_name}: APB, (BB)PLL, etc. - * [attr] - optional: FAST, SLOW, D, F + * * @note enum starts from 1, to save 0 for special purpose */ typedef enum { // For CPU domain - SOC_MOD_CLK_CPU = 1, /*< CPU_CLK can be sourced from XTAL, PLL, or RC_FAST by configuring soc_cpu_clk_src_t */ + SOC_MOD_CLK_CPU = 1, /*!< CPU_CLK can be sourced from XTAL, PLL, or RC_FAST by configuring soc_cpu_clk_src_t */ // For RTC domain - SOC_MOD_CLK_RTC_FAST = 2, /*< RTC_FAST_CLK can be sourced from XTAL_D2 or RC_FAST by configuring soc_rtc_fast_clk_src_t */ - SOC_MOD_CLK_RTC_SLOW = 3, /*< RTC_SLOW_CLK can be sourced from RC_SLOW, XTAL32K, or RC_FAST_D256 by configuring soc_rtc_slow_clk_src_t */ + 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 */ + 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 */ // For digital domain: peripherals, WIFI, BLE - SOC_MOD_CLK_APB = 4, /*< APB_CLK is highly dependent on the CPU_CLK source */ - SOC_MOD_CLK_PLL_F80M = 5, /*< PLL_F80M_CLK is derived from PLL, and has a fixed frequency of 80MHz */ - SOC_MOD_CLK_PLL_F160M = 6, /*< PLL_F160M_CLK is derived from PLL, and has a fixed frequency of 160MHz */ - SOC_MOD_CLK_PLL_D2 = 7, /*< PLL_D2_CLK is derived from PLL, it has a fixed divider of 2 */ - SOC_MOD_CLK_XTAL32K = 8, /*< XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals */ - SOC_MOD_CLK_RC_FAST = 9, /*< RC_FAST_CLK comes from the internal 20MHz rc oscillator, passing a clock gating to the peripherals */ - SOC_MOD_CLK_RC_FAST_D256 = 10, /*< RC_FAST_D256_CLK comes from the internal 20MHz rc oscillator, divided by 256, and passing a clock gating to the peripherals */ - SOC_MOD_CLK_XTAL = 11, /*< XTAL_CLK comes from the external 40MHz crystal */ + SOC_MOD_CLK_APB, /*!< APB_CLK is highly dependent on the CPU_CLK source */ + SOC_MOD_CLK_PLL_F80M, /*!< PLL_F80M_CLK is derived from PLL, and has a fixed frequency of 80MHz */ + SOC_MOD_CLK_PLL_F160M, /*!< PLL_F160M_CLK is derived from PLL, and has a fixed frequency of 160MHz */ + SOC_MOD_CLK_PLL_D2, /*!< PLL_D2_CLK is derived from PLL, it has a fixed divider of 2 */ + SOC_MOD_CLK_XTAL32K, /*!< XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals */ + SOC_MOD_CLK_RC_FAST, /*!< RC_FAST_CLK comes from the internal 20MHz rc oscillator, passing a clock gating to the peripherals */ + 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 */ + SOC_MOD_CLK_XTAL, /*!< XTAL_CLK comes from the external 40MHz crystal */ } soc_module_clk_t; //////////////////////////////////////////////////GPTimer/////////////////////////////////////////////////////////////// /** * @brief Array initializer for all supported clock sources of GPTimer + * * The following code can be used to iterate all possible clocks: * @code{c} * soc_periph_gptimer_clk_src_t gptimer_clks[] = (soc_periph_gptimer_clk_src_t)SOC_GPTIMER_CLKS; diff --git a/components/soc/esp32h2/include/soc/clk_tree_defs.h b/components/soc/esp32h2/include/soc/clk_tree_defs.h index b53e87767c..baee147015 100644 --- a/components/soc/esp32h2/include/soc/clk_tree_defs.h +++ b/components/soc/esp32h2/include/soc/clk_tree_defs.h @@ -20,17 +20,16 @@ extern "C" { * * 2) External 32MHz Crystal Clock: XTAL * - * 3) Internal 1500kHz RC Oscillator: RC_SLOW (usually referrred as RTC in TRM or reg. description) + * 3) Internal 136kHz RC Oscillator: RC_SLOW (usually referrred as RTC in TRM or reg. description) * - * This RC oscillator generates a ~150kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock + * This RC oscillator generates a ~136kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock * can be computed in runtime through calibration. * * 4) External 32kHz Crystal Clock (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. + * The clock source for this XTAL32K_CLK can be either a 32kHz crystal connecting to the XTAL_32K_P and XTAL_32K_N + * pins or a 32kHz 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. * @@ -40,24 +39,23 @@ extern "C" { */ /* With the default value of CK8M_DFREQ = 600, RC_FAST clock frequency nears 7 MHz +/- 7% */ //<---- DFREQ to be adjusted! */ -#define SOC_CLK_RC_FAST_FREQ_APPROX 7000000 +#define SOC_CLK_RC_FAST_FREQ_APPROX 7000000 /*!< Approximate RC_FAST_CLK frequency in Hz */ /* With the default value of DCAP = 128 */ //<---- DCAP to be adjusted! -#define SOC_CLK_RC_SLOW_FREQ_APPROX 130000 -#define SOC_CLK_RC_FAST_D256_FREQ_APPROX (SOC_CLK_RC_FAST_FREQ_APPROX / 256) +#define SOC_CLK_RC_SLOW_FREQ_APPROX 130000 /*!< Approximate RC_SLOW_CLK frequency in Hz */ /* With the default value of DFREQ = 707 */ //<---- DFREQ to be adjusted! -#define SOC_CLK_RC32K_FREQ_APPROX 32768 -#define SOC_CLK_XTAL32K_FREQ_APPROX 32768 +#define SOC_CLK_RC32K_FREQ_APPROX 32768 /*!< Approximate RC32K_CLK frequency in Hz */ +#define SOC_CLK_XTAL32K_FREQ_APPROX 32768 /*!< Approximate XTAL32K_CLK frequency in Hz */ +// Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr] +// {loc}: EXT, INT +// {type}: XTAL, RC +// [attr] - optional: [frequency], FAST, SLOW /** * @brief Root clock - * Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr] - * {loc}: EXT, INT - * {type}: XTAL, RC - * [attr] - optional: [frequency], FAST, SLOW */ typedef enum { SOC_ROOT_CLK_INT_RC_FAST, /*!< Internal 8MHz RC oscillator */ - SOC_ROOT_CLK_INT_RC_SLOW, /*!< Internal 150kHz RC oscillator */ + SOC_ROOT_CLK_INT_RC_SLOW, /*!< Internal 136kHz RC oscillator */ SOC_ROOT_CLK_EXT_XTAL, /*!< External 32MHz crystal */ SOC_ROOT_CLK_EXT_XTAL32K, /*!< External 32kHz crystal/clock signal */ SOC_ROOT_CLK_INT_RC32K /*!< Internal 32kHz RC oscillator */ @@ -94,24 +92,25 @@ typedef enum { SOC_RTC_FAST_CLK_SRC_RC_FAST = 1, /*!< Select RC_FAST_CLK as RTC_FAST_CLK source */ } soc_rtc_fast_clk_src_t; +// Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr] +// {[upstream]clock_name}: AHB etc. +// [attr] - optional: FAST, SLOW, D, F /** * @brief Supported clock sources for modules (CPU, peripherals, RTC, etc.) - * Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr] - * {[upstream]clock_name}: AHB etc. - * [attr] - optional: FAST, SLOW, D, F + * * @note enum starts from 1, to save 0 for special purpose */ typedef enum { // For CPU domain - SOC_MOD_CLK_CPU = 1, /*< CPU_CLK can be sourced from XTAL, PLL, RC_FAST, or XTAL_D2 by configuring soc_cpu_clk_src_t */ + SOC_MOD_CLK_CPU = 1, /*!< CPU_CLK can be sourced from XTAL, PLL, RC_FAST, or XTAL_D2 by configuring soc_cpu_clk_src_t */ // For RTC domain - SOC_MOD_CLK_RTC_FAST = 2, /*< RTC_FAST_CLK can be sourced from XTAL_D2 or RC_FAST by configuring soc_rtc_fast_clk_src_t */ - SOC_MOD_CLK_RTC_SLOW = 3, /*< RTC_SLOW_CLK can be sourced from RC_SLOW, XTAL32K, or RC32K by configuring soc_rtc_slow_clk_src_t */ + 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 */ + SOC_MOD_CLK_RTC_SLOW, /*!< RTC_SLOW_CLK can be sourced from RC_SLOW, XTAL32K, or RC32K by configuring soc_rtc_slow_clk_src_t */ // For digital domain: peripherals, WIFI, BLE - SOC_MOD_CLK_AHB = 4, /*< AHB_CLK sources from CPU with a configurable divider */ - SOC_MOD_CLK_XTAL32K = 5, /*< XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals */ - SOC_MOD_CLK_RC_FAST = 6, /*< RC_FAST_CLK comes from the internal 8MHz rc oscillator, passing a clock gating to the peripherals */ - SOC_MOD_CLK_XTAL = 7, /*< XTAL_CLK comes from the external 32MHz crystal */ + SOC_MOD_CLK_AHB, /*!< AHB_CLK sources from CPU with a configurable divider */ + SOC_MOD_CLK_XTAL32K, /*!< XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals */ + SOC_MOD_CLK_RC_FAST, /*!< RC_FAST_CLK comes from the internal 8MHz rc oscillator, passing a clock gating to the peripherals */ + SOC_MOD_CLK_XTAL, /*!< XTAL_CLK comes from the external 32MHz crystal */ } soc_module_clk_t; @@ -119,6 +118,7 @@ typedef enum { /** * @brief Array initializer for all supported clock sources of GPTimer + * * The following code can be used to iterate all possible clocks: * @code{c} * soc_periph_gptimer_clk_src_t gptimer_clks[] = (soc_periph_gptimer_clk_src_t)SOC_GPTIMER_CLKS; diff --git a/components/soc/esp32s2/include/soc/clk_tree_defs.h b/components/soc/esp32s2/include/soc/clk_tree_defs.h index 5fc3aba962..63dafa779b 100644 --- a/components/soc/esp32s2/include/soc/clk_tree_defs.h +++ b/components/soc/esp32s2/include/soc/clk_tree_defs.h @@ -28,26 +28,25 @@ extern "C" { * * 4) External 32kHz Crystal Clock (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. + * The clock source for this XTAL32K_CLK can be either a 32kHz crystal connecting to the XTAL_32K_P and XTAL_32K_N + * pins or a 32kHz 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. */ /* With the default value of CK8M_DFREQ = 172, RC_FAST clock frequency is 8.5 MHz +/- 7% */ -#define SOC_CLK_RC_FAST_FREQ_APPROX 8500000 -#define SOC_CLK_RC_SLOW_FREQ_APPROX 90000 -#define SOC_CLK_RC_FAST_D256_FREQ_APPROX (SOC_CLK_RC_FAST_FREQ_APPROX / 256) -#define SOC_CLK_XTAL32K_FREQ_APPROX 32768 +#define SOC_CLK_RC_FAST_FREQ_APPROX 8500000 /*!< Approximate RC_FAST_CLK frequency in Hz */ +#define SOC_CLK_RC_SLOW_FREQ_APPROX 90000 /*!< Approximate RC_SLOW_CLK frequency in Hz */ +#define SOC_CLK_RC_FAST_D256_FREQ_APPROX (SOC_CLK_RC_FAST_FREQ_APPROX / 256) /*!< Approximate RC_FAST_D256_CLK frequency in Hz */ +#define SOC_CLK_XTAL32K_FREQ_APPROX 32768 /*!< Approximate XTAL32K_CLK frequency in Hz */ +// Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr] +// {loc}: EXT, INT +// {type}: XTAL, RC +// [attr] - optional: [frequency], FAST, SLOW /** * @brief Root clock - * Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr] - * {loc}: EXT, INT - * {type}: XTAL, RC - * [attr] - optional: [frequency], FAST, SLOW */ typedef enum { SOC_ROOT_CLK_INT_RC_FAST, /*!< Internal 8MHz RC oscillator */ @@ -87,29 +86,30 @@ typedef enum { SOC_RTC_FAST_CLK_SRC_RC_FAST = 1, /*!< Select RC_FAST_CLK as RTC_FAST_CLK source */ } soc_rtc_fast_clk_src_t; +// Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr] +// {[upstream]clock_name}: APB, APLL, (BB)PLL, etc. +// [attr] - optional: FAST, SLOW, D, F /** * @brief Supported clock sources for modules (CPU, peripherals, RTC, etc.) - * Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr] - * {[upstream]clock_name}: APB, APLL, (BB)PLL, etc. - * [attr] - optional: FAST, SLOW, D, F + * * @note enum starts from 1, to save 0 for special purpose */ typedef enum { // For CPU domain - SOC_MOD_CLK_CPU = 1, /*< CPU_CLK can be sourced from XTAL, PLL, RC_FAST, or APLL by configuring soc_cpu_clk_src_t */ + SOC_MOD_CLK_CPU = 1, /*!< CPU_CLK can be sourced from XTAL, PLL, RC_FAST, or APLL by configuring soc_cpu_clk_src_t */ // For RTC domain - SOC_MOD_CLK_RTC_FAST = 2, /*< RTC_FAST_CLK can be sourced from XTAL_D4 or RC_FAST by configuring soc_rtc_fast_clk_src_t */ - SOC_MOD_CLK_RTC_SLOW = 3, /*< RTC_SLOW_CLK can be sourced from RC_SLOW, XTAL32K, or RC_FAST_D256 by configuring soc_rtc_slow_clk_src_t */ + 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 */ + 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 */ // For digital domain: peripherals, WIFI, BLE - SOC_MOD_CLK_APB = 4, /*< APB_CLK is highly dependent on the CPU_CLK source */ - SOC_MOD_CLK_PLL_F160M = 5, /*< PLL_F160M_CLK is derived from PLL, and has a fixed frequency of 160MHz */ - SOC_MOD_CLK_XTAL32K = 6, /*< XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals */ - SOC_MOD_CLK_RC_FAST = 7, /*< RC_FAST_CLK comes from the internal 8MHz rc oscillator, passing a clock gating to the peripherals */ - SOC_MOD_CLK_RC_FAST_D256 = 8, /*< RC_FAST_D256_CLK is derived from the internal 8MHz rc oscillator, divided by 256, and passing a clock gating to the peripherals */ - SOC_MOD_CLK_XTAL = 9, /*< XTAL_CLK comes from the external 40MHz crystal */ - SOC_MOD_CLK_REF_TICK = 10, /*< REF_TICK is derived from XTAL or RC_FAST via a divider, it has a fixed frequency of 1MHz by default */ - SOC_MOD_CLK_APLL = 11, /*< APLL is sourced from PLL, and its frequency is configurable through APLL configuration registers */ - SOC_MOD_CLK_TEMP_SENSOR = 12, /*< TEMP_SENSOR_CLK comes directly from the internal 8MHz rc oscillator */ + SOC_MOD_CLK_APB, /*!< APB_CLK is highly dependent on the CPU_CLK source */ + SOC_MOD_CLK_PLL_F160M, /*!< PLL_F160M_CLK is derived from PLL, and has a fixed frequency of 160MHz */ + SOC_MOD_CLK_XTAL32K, /*!< XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals */ + SOC_MOD_CLK_RC_FAST, /*!< RC_FAST_CLK comes from the internal 8MHz rc oscillator, passing a clock gating to the peripherals */ + SOC_MOD_CLK_RC_FAST_D256, /*!< RC_FAST_D256_CLK is derived from the internal 8MHz rc oscillator, divided by 256, and passing a clock gating to the peripherals */ + SOC_MOD_CLK_XTAL, /*!< XTAL_CLK comes from the external 40MHz crystal */ + SOC_MOD_CLK_REF_TICK, /*!< REF_TICK is derived from XTAL or RC_FAST via a divider, it has a fixed frequency of 1MHz by default */ + SOC_MOD_CLK_APLL, /*!< APLL is sourced from PLL, and its frequency is configurable through APLL configuration registers */ + SOC_MOD_CLK_TEMP_SENSOR, /*!< TEMP_SENSOR_CLK comes directly from the internal 8MHz rc oscillator */ } soc_module_clk_t; @@ -117,6 +117,7 @@ typedef enum { /** * @brief Array initializer for all supported clock sources of GPTimer + * * The following code can be used to iterate all possible clocks: * @code{c} * soc_periph_gptimer_clk_src_t gptimer_clks[] = (soc_periph_gptimer_clk_src_t)SOC_GPTIMER_CLKS; diff --git a/components/soc/esp32s3/include/soc/clk_tree_defs.h b/components/soc/esp32s3/include/soc/clk_tree_defs.h index d2ecad3792..b94deb5a81 100644 --- a/components/soc/esp32s3/include/soc/clk_tree_defs.h +++ b/components/soc/esp32s3/include/soc/clk_tree_defs.h @@ -11,7 +11,7 @@ extern "C" { /* ************************* ESP32S3 Root Clock Source **************************** - * 1) Internal 20MHz RC Oscillator: RC_FAST (usually referred as FOSC or CK8M/CLK8M in TRM and reg. description) + * 1) Internal 17.5MHz RC Oscillator: RC_FAST (usually referred as FOSC or CK8M/CLK8M in TRM and reg. description) * * This RC oscillator generates a ~17.5MHz clock signal output as the RC_FAST_CLK. * The ~17.5MHz signal output is also passed into a configurable divider, which by default divides the input clock @@ -21,37 +21,36 @@ extern "C" { * * 2) External 40MHz Crystal Clock: XTAL * - * 3) Internal 1500kHz RC Oscillator: RC_SLOW (usually referrred as RTC in TRM or reg. description) + * 3) Internal 136kHz RC Oscillator: RC_SLOW (usually referrred as RTC in TRM or reg. description) * - * This RC oscillator generates a ~150kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock + * This RC oscillator generates a ~136kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock * can be computed in runtime through calibration. * * 4) External 32kHz Crystal Clock (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. + * The clock source for this XTAL32K_CLK can be either a 32kHz crystal connecting to the XTAL_32K_P and XTAL_32K_N + * pins or a 32kHz 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. */ /* With the default value of CK8M_DFREQ = 100, RC_FAST clock frequency is 17.5 MHz +/- 7% */ -#define SOC_CLK_RC_FAST_FREQ_APPROX 17500000 -#define SOC_CLK_RC_SLOW_FREQ_APPROX 150000 -#define SOC_CLK_RC_FAST_D256_FREQ_APPROX (SOC_CLK_RC_FAST_FREQ_APPROX / 256) -#define SOC_CLK_XTAL32K_FREQ_APPROX 32768 +#define SOC_CLK_RC_FAST_FREQ_APPROX 17500000 /*!< Approximate RC_FAST_CLK frequency in Hz */ +#define SOC_CLK_RC_SLOW_FREQ_APPROX 136000 /*!< Approximate RC_SLOW_CLK frequency in Hz */ +#define SOC_CLK_RC_FAST_D256_FREQ_APPROX (SOC_CLK_RC_FAST_FREQ_APPROX / 256) /*!< Approximate RC_FAST_D256_CLK frequency in Hz */ +#define SOC_CLK_XTAL32K_FREQ_APPROX 32768 /*!< Approximate XTAL32K_CLK frequency in Hz */ +// Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr] +// {loc}: EXT, INT +// {type}: XTAL, RC +// [attr] - optional: [frequency], FAST, SLOW /** * @brief Root clock - * Naming convention: SOC_ROOT_CLK_{loc}_{type}_[attr] - * {loc}: EXT, INT - * {type}: XTAL, RC - * [attr] - optional: [frequency], FAST, SLOW */ typedef enum { - SOC_ROOT_CLK_INT_RC_FAST, /*!< Internal 8MHz RC oscillator */ - SOC_ROOT_CLK_INT_RC_SLOW, /*!< Internal 150kHz RC oscillator */ + SOC_ROOT_CLK_INT_RC_FAST, /*!< Internal 17.5MHz RC oscillator */ + SOC_ROOT_CLK_INT_RC_SLOW, /*!< Internal 136kHz RC oscillator */ SOC_ROOT_CLK_EXT_XTAL, /*!< External 40MHz crystal */ SOC_ROOT_CLK_EXT_XTAL32K, /*!< External 32kHz crystal/clock signal */ } soc_root_clk_t; @@ -86,29 +85,30 @@ typedef enum { SOC_RTC_FAST_CLK_SRC_RC_FAST = 1, /*!< Select RC_FAST_CLK as RTC_FAST_CLK source */ } soc_rtc_fast_clk_src_t; +// Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr] +// {[upstream]clock_name}: APB, (BB)PLL, etc. +// [attr] - optional: FAST, SLOW, D, F /** * @brief Supported clock sources for modules (CPU, peripherals, RTC, etc.) - * Naming convention: SOC_MOD_CLK_{[upstream]clock_name}_[attr] - * {[upstream]clock_name}: APB, (BB)PLL, etc. - * [attr] - optional: FAST, SLOW, D, F + * * @note enum starts from 1, to save 0 for special purpose */ typedef enum { // For CPU domain - SOC_MOD_CLK_CPU = 1, /*< CPU_CLK can be sourced from XTAL, PLL, or RC_FAST by configuring soc_cpu_clk_src_t */ + SOC_MOD_CLK_CPU = 1, /*!< CPU_CLK can be sourced from XTAL, PLL, or RC_FAST by configuring soc_cpu_clk_src_t */ // For RTC domain - SOC_MOD_CLK_RTC_FAST = 2, /*< RTC_FAST_CLK can be sourced from XTAL_D2 or RC_FAST by configuring soc_rtc_fast_clk_src_t */ - SOC_MOD_CLK_RTC_SLOW = 3, /*< RTC_SLOW_CLK can be sourced from RC_SLOW, XTAL32K, or RC_FAST_D256 by configuring soc_rtc_slow_clk_src_t */ + 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 */ + 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 */ // For digital domain: peripherals, WIFI, BLE - SOC_MOD_CLK_APB = 4, /*< APB_CLK is highly dependent on the CPU_CLK source */ - SOC_MOD_CLK_PLL_F80M = 5, /*< PLL_F80M_CLK is derived from PLL, and has a fixed frequency of 80MHz */ - SOC_MOD_CLK_PLL_F160M = 6, /*< PLL_F160M_CLK is derived from PLL, and has a fixed frequency of 160MHz */ - SOC_MOD_CLK_PLL_D2 = 7, /*< PLL_D2_CLK is derived from PLL, it has a fixed divider of 2 */ - SOC_MOD_CLK_XTAL32K = 8, /*< XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals */ - SOC_MOD_CLK_RC_FAST = 9, /*< RC_FAST_CLK comes from the internal 20MHz rc oscillator, passing a clock gating to the peripherals */ - SOC_MOD_CLK_RC_FAST_D256 = 10, /*< RC_FAST_D256_CLK comes from the internal 20MHz rc oscillator, divided by 256, and passing a clock gating to the peripherals */ - SOC_MOD_CLK_XTAL = 11, /*< XTAL_CLK comes from the external 40MHz crystal */ - SOC_MOD_CLK_TEMP_SENSOR = 12, /*< TEMP_SENSOR_CLK comes directly from the internal 20MHz rc oscillator */ + SOC_MOD_CLK_APB, /*!< APB_CLK is highly dependent on the CPU_CLK source */ + SOC_MOD_CLK_PLL_F80M, /*!< PLL_F80M_CLK is derived from PLL, and has a fixed frequency of 80MHz */ + SOC_MOD_CLK_PLL_F160M, /*!< PLL_F160M_CLK is derived from PLL, and has a fixed frequency of 160MHz */ + SOC_MOD_CLK_PLL_D2, /*!< PLL_D2_CLK is derived from PLL, it has a fixed divider of 2 */ + SOC_MOD_CLK_XTAL32K, /*!< XTAL32K_CLK comes from the external 32kHz crystal, passing a clock gating to the peripherals */ + SOC_MOD_CLK_RC_FAST, /*!< RC_FAST_CLK comes from the internal 20MHz rc oscillator, passing a clock gating to the peripherals */ + 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 */ + SOC_MOD_CLK_XTAL, /*!< XTAL_CLK comes from the external 40MHz crystal */ + SOC_MOD_CLK_TEMP_SENSOR, /*!< TEMP_SENSOR_CLK comes directly from the internal 20MHz rc oscillator */ } soc_module_clk_t; @@ -116,6 +116,7 @@ typedef enum { /** * @brief Array initializer for all supported clock sources of GPTimer + * * The following code can be used to iterate all possible clocks: * @code{c} * soc_periph_gptimer_clk_src_t gptimer_clks[] = (soc_periph_gptimer_clk_src_t)SOC_GPTIMER_CLKS; diff --git a/docs/en/api-reference/peripherals/clk_tree.rst b/docs/en/api-reference/peripherals/clk_tree.rst index f99ea69fa5..03621a9068 100644 --- a/docs/en/api-reference/peripherals/clk_tree.rst +++ b/docs/en/api-reference/peripherals/clk_tree.rst @@ -1,9 +1,79 @@ Clock Tree ========== -Clock Source Definitions ------------------------- +{IDF_TARGET_RC_FAST_VAGUE_FREQ: default="8", esp32="8", esp32s2="8", esp32c3="17.5", esp32s3="17.5", esp32c2="17.5", esp32h2="8"} + +{IDF_TARGET_RC_FAST_ADJUSTED_FREQ: default="8.5", esp32="8.5", esp32s2="8.5", esp32c3="17.5", esp32s3="17.5", esp32c2="17.5", esp32h2="8.5"} + +{IDF_TARGET_XTAL_FREQ: default="40", esp32="2~40", esp32s2="40", esp32c3="40", esp32s3="40", esp32c2="40", esp32h2="32"} + +{IDF_TARGET_RC_SLOW_VAGUE_FREQ: default="136", esp32="150", esp32s2="90"} This section lists definitions of the {IDF_TARGET_NAME}'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. + +{IDF_TARGET_NAME}'s root clocks are listed in :cpp:type:`soc_root_clk_t`: + + .. list:: + + - Internal {IDF_TARGET_RC_FAST_VAGUE_FREQ}MHz RC Oscillator (RC_FAST) + + This RC oscillator generates a ~{IDF_TARGET_RC_FAST_ADJUSTED_FREQ}MHz clock signal output as the RC_FAST_CLK. + + .. only:: not esp32h2 + + The ~{IDF_TARGET_RC_FAST_ADJUSTED_FREQ}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. + + .. only:: esp32h2 + + The exact frequency of RC_FAST_CLK cannot be computed in runtime through calibration, but it is still possible to get its frequency through an oscillscope or a logic analyzer by routing the clock signal to a GPIO pin. + + - External {IDF_TARGET_XTAL_FREQ}MHz Crystal (XTAL) + + - Internal {IDF_TARGET_RC_SLOW_VAGUE_FREQ}kHz RC Oscillator (RC_SLOW) + + This RC oscillator generates a ~{IDF_TARGET_RC_SLOW_VAGUE_FREQ}kHz clock signal output as the RC_SLOW_CLK. The exact frequency of this clock can be computed in runtime through calibration. + + .. only:: not esp32c2 + + - External 32kHz Crystal - optional (XTAL32K) + + .. only:: esp32 + + 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. + + .. only:: not esp32 + + The clock source for this XTAL32K_CLK can be either a 32kHz crystal connecting to the XTAL_32K_P and XTAL_32K_N pins or a 32kHz 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. + + .. only:: esp32c2 + + - External Slow Clock - optional (OSC_SLOW) + + A clock signal generated by an external circuit can be connected to pin0 to be the clock source for the RTC_SLOW_CLK. This clock can also be calibrated to get its exact frequency. + + .. only:: esp32h2 + + - Internal 32kHz RC Oscillator (RC32K) + + The exact frequency of this clock can be computed in runtime through calibration. + +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. {IDF_TARGET_NAME} 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 :ref:`rtc-clock-source-choice` for more details). + +Module Clocks +------------- + +{IDF_TARGET_NAME}'s available module clocks are listed in :cpp:type:`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 +------------- + .. include-build-file:: inc/clk_tree_defs.inc diff --git a/docs/en/api-reference/system/system_time.rst b/docs/en/api-reference/system/system_time.rst index 71122fe6d6..3643e76dc8 100644 --- a/docs/en/api-reference/system/system_time.rst +++ b/docs/en/api-reference/system/system_time.rst @@ -29,6 +29,8 @@ The possible combinations of hardware timers used to keep system time are listed It is recommended that users stick to the default option as it provides the highest accuracy. However, users can also select a different setting via the :ref:`CONFIG_NEWLIB_TIME_SYSCALL` configuration option. +.. _rtc-clock-source-choice: + RTC Timer Clock Sources ------------------------ diff --git a/docs/zh_CN/api-reference/system/system_time.rst b/docs/zh_CN/api-reference/system/system_time.rst index 2a651a8d5d..1d1a8c7e17 100644 --- a/docs/zh_CN/api-reference/system/system_time.rst +++ b/docs/zh_CN/api-reference/system/system_time.rst @@ -29,6 +29,8 @@ 默认时钟源的时间精度最高,建议使用该配置。此外,用户也可以通过配置选项 :ref:`CONFIG_NEWLIB_TIME_SYSCALL` 来选择其他时钟源。 +.. _rtc-clock-source-choice: + RTC 定时器时钟源 -----------------