Merge branch 'docs/add_Chinese_translation_for_api-reference/peripherals/clk_trees.rst_backport_v5.1' into 'release/v5.1'

docs: provide CN translation for api-reference/peripherals/clk_tree.rst (Backport v5.1)

See merge request espressif/esp-idf!26108

docs/en/api-reference/peripherals/clk_tree.rst

@@ -1,6 +1,8 @@
 Clock Tree
 ==========
 
+:link_to_translation:`zh_CN:[中文]`
+
 {IDF_TARGET_RC_FAST_VAGUE_FREQ: default="8", esp32c3="17.5", esp32s3="17.5", esp32c2="17.5", esp32c6="17.5"}
 
 {IDF_TARGET_RC_FAST_ADJUSTED_FREQ: default="8.5", esp32c3="17.5", esp32s3="17.5", esp32c2="17.5", esp32c6="17.5"}
@@ -9,19 +11,21 @@ Clock Tree
 
 {IDF_TARGET_RC_SLOW_VAGUE_FREQ: default="136", esp32="150", esp32s2="90"}
 
+{IDF_TARGET_RC_SLOW_CLK: default="GPIO0", esp32c2="pin0 (when its frequency is no more than 136 kHz)", "esp32c6="GPIO0", esp32h2="GPIO13"}
+
 The clock subsystem of {IDF_TARGET_NAME} 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 users can call to monitor the status of the module clocks at runtime.
+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 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.
+This section lists definitions of {IDF_TARGET_NAME}'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), WIFI, BT, the RTC, and the peripherals.
+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.
 
 {IDF_TARGET_NAME}'s root clocks are listed in :cpp:type:`soc_root_clk_t`:
 
@@ -29,27 +33,27 @@ Root clocks generate reliable clock signals. These clock signals then pass throu
 
         - 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.
+            This RC oscillator generates a about {IDF_TARGET_RC_FAST_ADJUSTED_FREQ} MHz clock signal output as the ``RC_FAST_CLK``.
 
             .. only:: SOC_CLK_RC_FAST_D256_SUPPORTED
 
-                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 about {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.
+                The exact frequency of ``RC_FAST_CLK`` can be computed in runtime through calibration on the ``RC_FAST_D256_CLK``.
 
             .. only:: not SOC_CLK_RC_FAST_D256_SUPPORTED and SOC_CLK_RC_FAST_SUPPORT_CALIBRATION
 
-                The exact frequency of RC_FAST_CLK can be computed in runtime through calibration.
+                The exact frequency of ``RC_FAST_CLK`` can be computed in runtime through calibration.
 
             .. only:: not SOC_CLK_RC_FAST_SUPPORT_CALIBRATION
 
-                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.
+                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 oscilloscope 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.
+            This RC oscillator generates a about {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:: SOC_CLK_XTAL32K_SUPPORTED
 
@@ -57,19 +61,19 @@ Root clocks generate reliable clock signals. These clock signals then pass throu
 
                 .. 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.
+                    The clock source for this ``XTAL32K_CLK`` can be either a 32 kHz crystal connecting to the ``32K_XP`` and ``32K_XN`` pins or a 32 kHz clock signal generated by an external circuit. The external signal must be connected to the ``32K_XN`` pin. Additionally, a 1 nF 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.
+                     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.
+                ``XTAL32K_CLK`` can also be calibrated to get its exact frequency.
 
         .. only:: SOC_CLK_OSC_SLOW_SUPPORTED
 
             - 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.
+                A clock signal generated by an external circuit can be connected to {IDF_TARGET_RC_SLOW_CLK} to be the clock source for the ``RTC_SLOW_CLK``. This clock can also be calibrated to get its exact frequency.
 
         .. only:: SOC_CLK_RC32K_SUPPORTED
 
@@ -77,7 +81,7 @@ Root clocks generate reliable clock signals. These clock signals then pass throu
 
                 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).
+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. {IDF_TARGET_NAME} 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 :ref:`rtc-clock-source-choice`.
 
 Module Clocks
 ^^^^^^^^^^^^^
@@ -87,7 +91,7 @@ Module Clocks
 API Usage
 ---------
 
-The clock tree driver provides an all-in-one API to get the frequency of the module clocks, :cpp:func:`esp_clk_tree_src_get_freq_hz`. Users can call this function at any moment, with specifying the clock name (:cpp:enum:`soc_module_clk_t`) and the desired degree of precision of the returned frequency value (:cpp:enum:`esp_clk_tree_src_freq_precision_t`).
+The clock tree driver provides an all-in-one API to get the frequency of the module clocks, :cpp:func:`esp_clk_tree_src_get_freq_hz`. This function allows you to obtain the clock frequency at any time by providing the clock name :cpp:enum:`soc_module_clk_t` and specifying the desired precision level for the returned frequency value :cpp:enum:`esp_clk_tree_src_freq_precision_t`.
 
 API Reference
 -------------

docs/zh_CN/api-reference/peripherals/clk_tree.rst

@@ -1 +1,100 @@
-.. include:: ../../../en/api-reference/peripherals/clk_tree.rst
+时钟树
+==========
+
+:link_to_translation:`en:[English]`
+
+{IDF_TARGET_RC_FAST_VAGUE_FREQ: default="8", esp32c3="17.5", esp32s3="17.5", esp32c2="17.5", esp32c6="17.5"}
+
+{IDF_TARGET_RC_FAST_ADJUSTED_FREQ: default="8.5", esp32c3="17.5", esp32s3="17.5", esp32c2="17.5", esp32c6="17.5"}
+
+{IDF_TARGET_XTAL_FREQ: default="40", esp32="2 ~ 40", esp32c2="40/26", esp32h2="32"}
+
+{IDF_TARGET_RC_SLOW_VAGUE_FREQ: default="136", esp32="150", esp32s2="90"}
+
+{IDF_TARGET_RC_SLOW_CLK: default="GPIO0", esp32c2="pin0（时钟信号频率不超过 136 kHz 时）", "esp32c6="GPIO0", esp32h2="GPIO13"}
+
+{IDF_TARGET_NAME} 的时钟子系统用于从一系列根时钟中提取并分配系统/模块时钟。时钟树驱动程序负责维护系统时钟的基本功能，并管理模块时钟间的复杂关系。
+
+本文档首先介绍了根时钟和模块时钟，随后介绍了可供用户调用的时钟树 API，调用这些 API，可以监测模块时钟的运行状态。
+
+简介
+------------
+
+本节列出了 {IDF_TARGET_NAME} 支持的根时钟和模块时钟的定义，这些定义通常用于驱动程序配置，有助于为外设选择合适的时钟源。
+
+根时钟
+^^^^^^^^^^^
+
+根时钟会产生可靠的时钟信号，经各种门、复用器、分频器或倍频器传递，这些时钟信号最终成为 CPU 内核、Wi-Fi、蓝牙、RTC 及外设等功能模块的时钟源。
+
+{IDF_TARGET_NAME} 的根时钟列在 :cpp:type:`soc_root_clk_t` 中：
+
+    .. list::
+
+        - 内部 {IDF_TARGET_RC_FAST_VAGUE_FREQ} MHz RC 振荡器 (RC_FAST)
+
+            此 RC 振荡器可产生约 {IDF_TARGET_RC_FAST_ADJUSTED_FREQ} MHz 的时钟信号输出，标识为 ``RC_FAST_CLK``。
+
+            .. only:: SOC_CLK_RC_FAST_D256_SUPPORTED
+
+                此约 {IDF_TARGET_RC_FAST_ADJUSTED_FREQ} MHz 的信号也会传入可配置的分频器，默认情况下，该分频器会将输入的时钟频率分频 256 倍，生成信号  ``RC_FAST_D256_CLK``。
+
+                在运行时，通过在 ``RC_FAST_D256_CLK`` 上校准，可以计算 ``RC_FAST_CLK`` 的实际频率。
+
+            .. only:: not SOC_CLK_RC_FAST_D256_SUPPORTED and SOC_CLK_RC_FAST_SUPPORT_CALIBRATION
+
+                在运行时，通过校准，可以计算 ``RC_FAST_CLK`` 的实际频率。
+
+            .. only:: not SOC_CLK_RC_FAST_SUPPORT_CALIBRATION
+
+                在运行时，无法通过校准计算 ``RC_FAST_CLK`` 的实际频率，但仍可以将时钟信号引出到 GPIO 管脚，通过示波器或逻辑分析仪获取频率。
+
+        - 外部 {IDF_TARGET_XTAL_FREQ} MHz 晶振 (XTAL)
+
+        - 内部 {IDF_TARGET_RC_SLOW_VAGUE_FREQ} kHz RC 振荡器 (RC_SLOW)
+
+            此 RC 振荡器产生约 {IDF_TARGET_RC_SLOW_VAGUE_FREQ} kHz 的时钟信号输出，标识为 ``RC_SLOW_CLK``。在运行时，通过校准，可以计算该时钟信号的实际频率。
+
+        .. only:: SOC_CLK_XTAL32K_SUPPORTED
+
+            - 外部 32 kHz 晶振 - 可选 (XTAL32K)
+
+                .. only:: esp32
+
+                    ``XTAL32K_CLK`` 的时钟源可以是连接到 ``32K_XP`` 和 ``32K_XN`` 管脚的 32 kHz 晶振，也可以是外部电路生成的 32 kHz 时钟信号。如果使用外部电路生成的时钟信号，该信号必须连接到 ``32K_XN`` 管脚，并且在 ``32K_XP`` 管脚和地之间连接一个 1 nF 的电容。此时，``32K_XP`` 管脚不能用作 GPIO 管脚。
+
+                .. only:: not esp32
+
+                     ``XTAL32K_CLK`` 的时钟源可以是连接到 ``XTAL_32K_P`` 和 ``XTAL_32K_N`` 管脚的 32 kHz 晶振，也可以是外部电路生成的 32 kHZ 时钟信号。如果使用外部电路生成的时钟信号，该信号必须连接到 ``XTAL_32K_P`` 管脚。
+
+                通过校准，可以计算 ``XTAL32K_CLK`` 的实际频率。
+
+        .. only:: SOC_CLK_OSC_SLOW_SUPPORTED
+
+            - 外部慢速时钟 - 可选 (OSC_SLOW)
+
+                将外部电路生成的时钟信号连接到 {IDF_TARGET_RC_SLOW_CLK}，可作为 ``RTC_SLOW_CLK`` 的时钟源。通过校准，可以计算该时钟信号的实际频率。
+
+        .. only:: SOC_CLK_RC32K_SUPPORTED
+
+            - 内部 32 kHz RC 振荡器 (RC32K)
+
+                在运行时，通过校准，可以计算该时钟信号的实际频率。
+
+与晶振产生的信号相比，从 RC 振荡器电路产生的信号通常精度较低，且容易受环境影响。因此，{IDF_TARGET_NAME} 为 ``RTC_SLOW_CLK`` 提供了几种时钟源选项，可以根据对系统时间精度和对功耗的要求选择。更多详情，请参阅 :ref:`rtc-clock-source-choice`。
+
+模块时钟
+^^^^^^^^^^^^^
+
+{IDF_TARGET_NAME} 的可用模块时钟在 :cpp:type:`soc_module_clk_t` 中列出，每个模块时钟都有其唯一 ID。查阅文档中的枚举值，即可获取各模块时钟的详细信息。
+
+使用 API
+---------
+
+时钟树驱动程序提供了一个一体化接口，可以获取模块时钟的频率，即 :cpp:func:`esp_clk_tree_src_get_freq_hz`。通过该函数，你可以在任何时刻，通过提供时钟名称 :cpp:enum:`soc_module_clk_t` 和指定返回频率值的精度级别 :cpp:enum:`esp_clk_tree_src_freq_precision_t`，获取时钟频率。
+
+API 参考
+-------------
+
+.. include-build-file:: inc/clk_tree_defs.inc
+.. include-build-file:: inc/esp_clk_tree.inc