Merge branch 'update_CN_for_system_time_index_spi_slave' into 'master'

docs: update CN for index/spi_slave/system_time Closes DOC-4615 See merge request espressif/esp-idf!22383
espressif · Mar 2, 2023 · 242d0a7 · 242d0a7
2 parents e364e1c + 2e4455a
commit 242d0a7
Show file tree

Hide file tree

Showing 6 changed files with 71 additions and 87 deletions.
diff --git a/docs/en/api-reference/peripherals/index.rst b/docs/en/api-reference/peripherals/index.rst
@@ -1,5 +1,5 @@
 Peripherals API
-***************
+****************
 
 :link_to_translation:`zh_CN:[中文]`
 

diff --git a/docs/en/api-reference/peripherals/spi_slave.rst b/docs/en/api-reference/peripherals/spi_slave.rst
@@ -1,13 +1,17 @@
 SPI Slave Driver
 ================
 
+:link_to_translation:`zh_CN:[中文]`
+
 SPI Slave driver is a program that controls {IDF_TARGET_NAME}'s SPI peripherals while they function as slaves.
 
 
 Overview of {IDF_TARGET_NAME}'s SPI peripherals
 -----------------------------------------------
 
-On {IDF_TARGET_NAME}, {SOC_SPI_PERIPH_NUM} SPI controllers are available for general purpose usage. A certain SPI controller has an independent signal bus with the same name.
+{IDF_TARGET_MAX_SLAVE_PERIPH_NUM:default="2", esp32c3="1", esp32c2="1", esp32c6="1", esp32h2="1"}
+
+On {IDF_TARGET_NAME}, {IDF_TARGET_MAX_SLAVE_PERIPH_NUM} SPI controllers are available for general purpose usage. A certain SPI controller has an independent signal bus with the same name.
 
 .. only:: esp32
 
@@ -61,7 +65,7 @@ Driver Features
 
 The SPI slave driver allows using the SPI peripherals as full-duplex Devices. The driver can send/receive transactions up to {IDF_TARGET_MAX_DATA_BUF} bytes in length, or utilize DMA to send/receive longer transactions. However, there are some :ref:`known issues <spi_dma_known_issues>` related to DMA.
 
-The SPI slave driver supports registering the SPI ISR to a certain CPU core. If multiple tasks try to access the same SPI Device, it is recommended to refactor your application so that each SPI peripheral is only accessed by a single task at a time. and use :cpp:member:`spi_bus_config_t::isr_cpu_id` to register the SPI ISR to the same core as SPI peripheral related tasks to ensure thread safe.
+The SPI slave driver supports registering the SPI ISR to a certain CPU core. If multiple tasks try to access the same SPI Device simultaneously, it is recommended that your application be refactored so that each SPI peripheral is only accessed by a single task at a time. Please also use :cpp:member:`spi_bus_config_t::isr_cpu_id` to register the SPI ISR to the same core as SPI peripheral related tasks to ensure thread safety.
 
 SPI Transactions
 ----------------
@@ -70,7 +74,7 @@ A full-duplex SPI transaction begins when the Host asserts the CS line and start
 
 The attributes of a transaction are determined by the configuration structure for an SPI peripheral acting as a slave device :cpp:type:`spi_slave_interface_config_t`, and transaction configuration structure :cpp:type:`spi_slave_transaction_t`.
 
-As not every transaction requires both writing and reading data, you have a choice to configure the :cpp:type:`spi_transaction_t` structure for TX only, RX only, or TX and RX transactions. If :cpp:member:`spi_slave_transaction_t::rx_buffer` is set to NULL, the read phase will be skipped. If :cpp:member:`spi_slave_transaction_t::tx_buffer` is set to NULL, the write phase will be skipped.
+As not every transaction requires both writing and reading data, you can choose to configure the :cpp:type:`spi_transaction_t` structure for TX only, RX only, or TX and RX transactions. If :cpp:member:`spi_slave_transaction_t::rx_buffer` is set to NULL, the read phase will be skipped. Similarly, if :cpp:member:`spi_slave_transaction_t::tx_buffer` is set to NULL, the write phase will be skipped.
 
 .. note::
 
@@ -84,7 +88,7 @@ Driver Usage
 
 .. only:: esp32
 
-    If transactions will be longer than 32 bytes, allow a DMA channel 1 or 2 by setting the parameter ``dma_chan`` to ``1`` or ``2`` respectively. Otherwise, set ``dma_chan`` to ``0``.
+    If transactions are expected to be longer than 32 bytes, set the parameter ``dma_chan`` to ``1`` or ``2`` to allow a DMA channel 1 or 2 respectively. Otherwise, set ``dma_chan`` to ``0``.
 
 .. only:: esp32s2
 
@@ -121,23 +125,31 @@ GPIO Matrix and IO_MUX
 
     The IO_MUX pins for SPI buses are given below.
 
-    +----------+------+------+
-    | Pin Name | SPI2 | SPI3 |
-    +          +------+------+
-    |          | GPIO Number |
-    +==========+======+======+
-    | CS0      | 15   | 5    |
-    +----------+------+------+
-    | SCLK     | 14   | 18   |
-    +----------+------+------+
-    | MISO     | 12   | 19   |
-    +----------+------+------+
-    | MOSI     | 13   | 23   |
-    +----------+------+------+
-    | QUADWP   | 2    | 22   |
-    +----------+------+------+
-    | QUADHD   | 4    | 21   |
-    +----------+------+------+
+    .. list-table::
+       :widths: 40 30 30
+       :header-rows: 1
+
+       * - Pin Name
+         - GPIO Number (SPI2)
+         - GPIO Number (SPI3)
+       * - CS0
+         - 15
+         - 5
+       * - SCLK
+         - 14
+         - 18
+       * - MISO
+         - 12
+         - 19
+       * - MOSI
+         - 13
+         - 23
+       * - QUADWP
+         - 2
+         - 22
+       * - QUADHD
+         - 4
+         - 21
 
 .. only:: not esp32
 

diff --git a/docs/en/api-reference/system/system_time.rst b/docs/en/api-reference/system/system_time.rst
@@ -1,5 +1,6 @@
 System Time
 ===========
+
 :link_to_translation:`zh_CN:[中文]`
 
 {IDF_TARGET_RTC_CLK_FRE:default="Not updated", esp32="150 kHz", esp32s2="90 kHz", esp32s3="136 kHz", esp32c3="136 kHz", esp32c2="136 kHz", esp32c6="150 kHz"}

diff --git a/docs/zh_CN/api-reference/peripherals/index.rst b/docs/zh_CN/api-reference/peripherals/index.rst
@@ -25,7 +25,9 @@
     :SOC_PARLIO_SUPPORTED: parlio
     :SOC_PCNT_SUPPORTED: pcnt
     :SOC_RMT_SUPPORTED: rmt
-    :SOC_SDMMC_HOST_SUPPORTED: sd_pullup_requirements
+    :esp32: sd_pullup_requirements
+    :esp32s3: sd_pullup_requirements
+    :esp32c6: sd_pullup_requirements
     :SOC_SDMMC_HOST_SUPPORTED: sdmmc_host
     sdspi_host
     :SOC_SDIO_SLAVE_SUPPORTED: sdio_slave

diff --git a/docs/zh_CN/api-reference/peripherals/spi_slave.rst b/docs/zh_CN/api-reference/peripherals/spi_slave.rst
@@ -1,13 +1,17 @@
 SPI 从机驱动程序
 ================
 
+:link_to_translation:`en:[English]`
+
 SPI 从机驱动程序控制在 {IDF_TARGET_NAME} 中作为从机的 SPI 外设。
 
 
 {IDF_TARGET_NAME} 中 SPI 外设概述
 -----------------------------------------------
 
-{IDF_TARGET_NAME} 集成了 {SOC_SPI_PERIPH_NUM} 个通用的 SPI 控制器。该控制器具有与之同名的独立总线信号。
+{IDF_TARGET_MAX_SLAVE_PERIPH_NUM:default="2", esp32c3="1", esp32c2="1", esp32c6="1", esp32h2="1"}
+
+{IDF_TARGET_NAME} 集成了 {IDF_TARGET_MAX_SLAVE_PERIPH_NUM} 个通用的 SPI 控制器。该控制器具有与之同名的独立总线信号。
 
 .. only:: esp32
 
@@ -61,6 +65,7 @@ SPI 从机驱动程序控制在 {IDF_TARGET_NAME} 中作为从机的 SPI 外设
 
 SPI 从机驱动程序允许将 SPI 外设作为全双工设备使用。驱动程序可以发送/接收长度不超过 {IDF_TARGET_MAX_DATA_BUF} 字节的传输事务，或者利用 DMA 来发送/接收更长的传输事务。然而，存在一些与 DMA 有关的 :ref:`已知问题 <spi_dma_known_issues>`。
 
+SPI 从机驱动程序支持将 SPI ISR 注册至指定 CPU 内核。如果多个任务同时尝试访问一个 SPI 设备，建议您重构应用程序，以使每个 SPI 外设一次只由一个任务访问。此外，请使用 :cpp:member:`spi_bus_config_t::isr_cpu_id` 将 SPI ISR 注册至与 SPI 外设相关任务相同的内核，确保线程安全。
 
 SPI 传输事务
 ----------------
@@ -69,7 +74,7 @@ SPI 传输事务
 
 传输事务的属性由作为从机设备的 SPI 外设的配置结构体 :cpp:type:`spi_slave_interface_config_t` 和传输事务配置结构体 :cpp:type:`spi_slave_transaction_t` 决定。
 
-由于并非每次传输事务都需要写入和读取数据，您可以选择配置 :cpp:type:`spi_transaction_t` 为仅 TX、仅 RX 或同时 TX 和 RX 传输事务。如果将 :cpp:member:`spi_slave_transaction_t::rx_buffer` 设置为 NULL，读取阶段将被跳过。如果将 :cpp:member:`spi_slave_transaction_t::tx_buffer` 设置为 NULL，则写入阶段将被跳过。
+由于并非每次传输事务都需要写入和读取数据，您可以选择配置 :cpp:type:`spi_transaction_t` 为仅 TX、仅 RX 或同时 TX 和 RX 传输事务。如果将 :cpp:member:`spi_slave_transaction_t::rx_buffer` 设置为 NULL，读取阶段将被跳过。与之类似，如果将 :cpp:member:`spi_slave_transaction_t::tx_buffer` 设置为 NULL，则写入阶段将被跳过。
 
 .. note::
 
@@ -83,7 +88,7 @@ SPI 传输事务
 
 .. only:: esp32
 
-    如果传输事务的数据大于 32 字节，需要将参数 ``dma_chan`` 分别设置为 ``1`` 或 ``2`` 以使能 DMA 通道 1 或通道 2。若数据小于 32 字节，则应将 ``dma_chan`` 设为 ``0``。
+    如果传输事务的数据大于 32 字节，需要将参数 ``dma_chan`` 分别设置为 ``1`` 或 ``2`` 以使能 DMA 通道 1 或通道 2，否则应将 ``dma_chan`` 设为 ``0``。
 
 .. only:: esp32s2
 
@@ -148,76 +153,37 @@ GPIO 交换矩阵和 IO_MUX
 
 .. only:: not esp32
 
+    {IDF_TARGET_SPI2_IOMUX_PIN_CS:default="N/A",   esp32s2="10", esp32s3="10", esp32c2="10", esp32c3="10", esp32c6="16", esp32h2="1"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_CLK:default="N/A",  esp32s2="12", esp32s3="12", esp32c2="6",  esp32c3="6",  esp32c6="6",  esp32h2="4"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_MOSI:default="N/A", esp32s2="11"  esp32s3="11", esp32c2="7"   esp32c3="7",  esp32c6="7",  esp32h2="5"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_MISO:default="N/A", esp32s2="13"  esp32s3="13", esp32c2="2"   esp32c3="2",  esp32c6="2",  esp32h2="0"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_HD:default="N/A",   esp32s2="9"   esp32s3="9",  esp32c2="4"   esp32c3="4",  esp32c6="4",  esp32h2="3"}
+    {IDF_TARGET_SPI2_IOMUX_PIN_WP:default="N/A",   esp32s2="14"  esp32s3="14", esp32c2="5"   esp32c3="5",  esp32c6="5",  esp32h2="2"}
+
     {IDF_TARGET_NAME} 的大多数外设信号都直接连接到其专用的 IO_MUX 管脚。不过，也可以使用 GPIO 交换矩阵，将信号路由到任何可用的其他管脚。如果通过 GPIO 交换矩阵路由了至少一个信号，则所有信号都将通过 GPIO 交换矩阵路由。
 
     当 SPI 主机频率配置为 80 MHz 或更低时，则通过 GPIO 交换矩阵或 IO_MUX 路由 SPI 管脚效果相同。
 
     下表列出了 SPI 总线的 IO_MUX 管脚。
 
-.. only:: esp32s2 or esp32s3
-
     .. list-table::
        :widths: 40 30
        :header-rows: 1
 
        * - 管脚名称
          - GPIO 编号 (SPI2)
-       * - CS0*
-         - 10
+       * - CS0
+         - {IDF_TARGET_SPI2_IOMUX_PIN_CS}
        * - SCLK
-         - 12
+         - {IDF_TARGET_SPI2_IOMUX_PIN_CLK}
        * - MISO
-         - 13
+         - {IDF_TARGET_SPI2_IOMUX_PIN_MISO}
        * - MOSI
-         - 11
+         - {IDF_TARGET_SPI2_IOMUX_PIN_MOSI}
        * - QUADWP
-         - 14
+         - {IDF_TARGET_SPI2_IOMUX_PIN_WP}
        * - QUADHD
-         - 9
-
-.. only:: esp32c2 or esp32c3
-
-    .. list-table::
-       :widths: 40 30
-       :header-rows: 1
-
-       * - 管脚名称
-         - GPIO 编号 (SPI2)
-       * - CS0*
-         - 10
-       * - SCLK
-         - 6
-       * - MISO
-         - 2
-       * - MOSI
-         - 7
-       * - QUADWP
-         - 5
-       * - QUADHD
-         - 4
-
-.. only:: esp32c6
-
-    .. list-table::
-       :widths: 40 30
-       :header-rows: 1
-
-       * - 管脚名称
-         - GPIO 编号 (SPI2)
-       * - CS0*
-         - 16
-       * - SCLK
-         - 6
-       * - MISO
-         - 2
-       * - MOSI
-         - 7
-       * - QUADWP
-         - 5
-       * - QUADHD
-         - 4
-
-* 只有连接到总线上的第一个从机设备可以使用 CS0 管脚。
+         - {IDF_TARGET_SPI2_IOMUX_PIN_HD}
 
 
 速度与时钟
@@ -238,7 +204,7 @@ GPIO 交换矩阵和 IO_MUX
 时钟频率要求
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-{IDF_TARGET_MAX_FREQ:default="60", esp32="10", esp32s2="40"}
+{IDF_TARGET_MAX_FREQ:default="60", esp32="10", esp32s2="40", esp32c6="40", esp32h2="32"}
 
 SPI 从机的工作频率最高可达 {IDF_TARGET_MAX_FREQ} MHz。如果时钟频率过快或占空比不足 50%，数据就无法被正确识别或接收。
 

diff --git a/docs/zh_CN/api-reference/system/system_time.rst b/docs/zh_CN/api-reference/system/system_time.rst
@@ -1,12 +1,13 @@
 系统时间
 =========
+
 :link_to_translation:`en:[English]`
 
-{IDF_TARGET_RTC_CLK_FRE:default="未更新", esp32="150 kHz", esp32s2="90 kHz", esp32s3="136 kHz", esp32c3="136 kHz", esp32c2="136 kHz"}
-{IDF_TARGET_INT_OSC_FRE:default="未更新", esp32="8.5 MHz", esp32s2="8.5 MHz", esp32s3="17.5 MHz", esp32c3="17.5 MHz", esp32c2="17.5 MHz"}
+{IDF_TARGET_RTC_CLK_FRE:default="未更新", esp32="150 kHz", esp32s2="90 kHz", esp32s3="136 kHz", esp32c3="136 kHz", esp32c2="136 kHz", esp32c6="150 kHz"}
+{IDF_TARGET_INT_OSC_FRE:default="未更新", esp32="8.5 MHz", esp32s2="8.5 MHz", esp32s3="17.5 MHz", esp32c3="17.5 MHz", esp32c2="17.5 MHz", esp32c6="20 MHz"}
 {IDF_TARGET_INT_OSC_FRE_DIVIDED:default="未更新", esp32="~33 kHz", esp32s2="~33 kHz", esp32s3="~68 kHz", esp32c3="~68 kHz", esp32c2="~68 kHz"}
-{IDF_TARGET_EXT_CRYSTAL_PIN:default="未更新", esp32="32K_XP 和 32K_XN", esp32s2="XTAL_32K_P 和 XTAL_32K_N", esp32s3="XTAL_32K_P 和 XTAL_32K_N", esp32c3="XTAL_32K_P 和 XTAL_32K_N"}
-{IDF_TARGET_EXT_OSC_PIN:default="未更新", esp32="32K_XN", esp32s2="XTAL_32K_P", esp32s3="XTAL_32K_P", esp32c3="XTAL_32K_P", esp32c2="GPIO0"}
+{IDF_TARGET_EXT_CRYSTAL_PIN:default="未更新", esp32="32K_XP 和 32K_XN", esp32s2="XTAL_32K_P 和 XTAL_32K_N", esp32s3="XTAL_32K_P 和 XTAL_32K_N", esp32c3="XTAL_32K_P 和 XTAL_32K_N", esp32c6="XTAL_32K_P 和 XTAL_32K_N"}
+{IDF_TARGET_EXT_OSC_PIN:default="未更新", esp32="32K_XN", esp32s2="XTAL_32K_P", esp32s3="XTAL_32K_P", esp32c3="XTAL_32K_P", esp32c2="GPIO0", esp32c6="XTAL_32K_P"}
 {IDF_TARGET_HARDWARE_DESIGN_URL:default="未更新", esp32="`ESP32 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32_hardware_design_guidelines_cn.pdf#page=10>`_", esp32s2="`ESP32-S2 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-s2_hardware_design_guidelines_cn.pdf#page=10>`_", esp32s3="`ESP32-S3 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-s3_hardware_design_guidelines_cn.pdf#page=12>`_", esp32c3="`ESP32-C3 硬件设计指南 <https://www.espressif.com/sites/default/files/documentation/esp32-c3_hardware_design_guidelines_cn.pdf#page=9>`_"}
 
 
@@ -44,13 +45,15 @@ RTC 定时器有以下时钟源：
 
     - ``管脚 {IDF_TARGET_EXT_OSC_PIN} 外置 32 kHz 振荡器``：允许使用由外部电路产生的 32 kHz 时钟。外部时钟信号必须连接到管脚 {IDF_TARGET_EXT_OSC_PIN}。正弦波信号的振幅应小于 1.2 V，方波信号的振幅应小于 1 V。正常模式下，电压范围应为 0.1 < Vcm < 0.5 xVamp，其中 Vamp 代表信号振幅。使用此时钟源时，管脚 {IDF_TARGET_EXT_OSC_PIN} 无法用作 GPIO 管脚。
 
-    - ``内置 {IDF_TARGET_INT_OSC_FRE} 振荡器的 256 分频时钟 ({IDF_TARGET_INT_OSC_FRE_DIVIDED})``：频率稳定性优于 ``内置 {IDF_TARGET_RTC_CLK_FRE} RC 振荡器``，同样无需外部元件，但 Deep-sleep 模式下电流消耗更高（比默认模式高 5 μA）。
+    :not esp32c6: - ``内置 {IDF_TARGET_INT_OSC_FRE} 振荡器的 256 分频时钟 ({IDF_TARGET_INT_OSC_FRE_DIVIDED})``：频率稳定性优于 ``内置 {IDF_TARGET_RTC_CLK_FRE} RC 振荡器``，同样无需外部元件，但 Deep-sleep 模式下电流消耗更高（比默认模式高 5 μA）。
+
+    :esp32c6: - ``内置 32 kHz RC 振荡器``
 
 时钟源的选择取决于系统时间精度要求和睡眠模式下的功耗要求。要修改 RTC 时钟源，请在项目配置中设置 :ref:`CONFIG_RTC_CLK_SRC`。
 
-.. Need to add esp32c2 hardware design guideline link after it is publsihed.
+.. Need to add esp32c2 and esp32c6 hardware design guideline link after it is publsihed.
 
-.. only:: not esp32c2
+.. only:: not esp32c2 and not esp32c6
 
     想要了解外置晶振或外置振荡器的更多布线要求，请参考 {IDF_TARGET_HARDWARE_DESIGN_URL}。