Merge branch 'add_CN_trans_for_/protocols/esp_spi_slave_protocol.rst'…

… into 'master'

docs: Provide Chinese translation for /protocols/esp_spi_slave_protocol.rst

Closes DOC-6001

See merge request espressif/esp-idf!25374

docs/en/api-reference/protocols/esp_spi_slave_protocol.rst

@@ -1,11 +1,13 @@
 ESP SPI Slave HD (Half Duplex) Mode Protocol
 ============================================
 
+:link_to_translation:`zh_CN:[中文]`
+
 .. only:: esp32
 
     .. warning::
 
-        The driver for ESP32 has not been developed yet.
+        ESP32 does not support this feature.
 
 .. _esp_spi_slave_caps:
 
@@ -31,15 +33,15 @@ SPI Slave Capabilities of Espressif Chips
 Introduction
 ------------
 
-In the half duplex mode, the master has to use the protocol defined by the slave to communicate with the slave. Each transaction may consist of the following phases (list by the order they should exist):
+In the half duplex mode, the master has to use the protocol defined by the slave to communicate with the slave. Each transaction may consist of the following phases (listed by the order they should exist):
 
 - Command: 8-bit, master to slave
 
     This phase determines the rest phases of the transactions. See :ref:`spi_slave_hd_supported_cmds`.
 
 - Address: 8-bit, master to slave, optional
 
-    For some commands (WRBUF, RDBUF), this phase specifies the address of the shared buffer to write to/read from. For other commands with this phase, they are meaningless but still have to exist in the transaction.
+    For some commands (WRBUF, RDBUF), this phase specifies the address of the shared register to write to/read from. For other commands with this phase, they are meaningless but still have to exist in the transaction.
 
 - Dummy: 8-bit, floating, optional
 
@@ -54,10 +56,10 @@ The **direction** means which side (master or slave) controls the MOSI, MISO, WP
 Data IO Modes
 -------------
 
-In some IO modes, more data wires can be used to send the data. As a result, the SPI clock cycles required for the same amount of data will be less than in the 1-bit mode. For example, in QIO mode, address and data (IN and OUT) should be sent on all 4 data wires (MOSI, MISO, WP, and HD). Here are the modes supported by the ESP32-S2 SPI slave and the wire number used in corresponding modes.
+In some IO modes, more data wires can be used to send the data. As a result, the SPI clock cycles required for the same amount of data will be less than in the 1-bit mode. For example, in QIO mode, address and data (IN and OUT) should be sent on all 4 data wires (MOSI, MISO, WP, and HD). Here are the modes supported by the ESP32-S2 SPI slave and the wire number (WN) used in corresponding modes.
 
 +-------+------------+------------+--------------+---------+
-| Mode  | command WN | address WN | dummy cycles | data WN |
+| Mode  | Command WN | Address WN | Dummy cycles | Data WN |
 +=======+============+============+==============+=========+
 | 1-bit | 1          | 1          | 1            | 1       |
 +-------+------------+------------+--------------+---------+
@@ -113,7 +115,7 @@ Supported Commands
 | EXQPI    | Exit QPI mode       | 0xDD    | -        | -                                                        |
 +----------+---------------------+---------+----------+----------------------------------------------------------+
 
-Moreover, WRBUF, RDBUF, WRDMA, RDDMA commands have their 2-bit and 4-bit version. To do transactions in 2-bit or 4-bit mode, send the original command ORed by the corresponding command mask below. For example, command 0xA1 means WRBUF in QIO mode.
+Moreover, WRBUF, RDBUF, WRDMA, and RDDMA commands have their 2-bit and 4-bit version. To do transactions in 2-bit or 4-bit mode, send the original command ORed by the corresponding command mask below. For example, command 0xA1 means WRBUF in QIO mode.
 
 +-------+------+
 | Mode  | Mask |
@@ -134,15 +136,15 @@ Moreover, WRBUF, RDBUF, WRDMA, RDDMA commands have their 2-bit and 4-bit version
 Segment Transaction Mode
 ------------------------
 
-Segment transaction mode is the only mode supported by the SPI Slave HD driver for now. In this mode, for a transaction the slave load onto the DMA, the master is allowed to read or write in segments. This way the master does not have to prepare a large buffer as the size of data provided by the slave. After the master finishes reading/writing a buffer, it has to send the corresponding termination command to the slave as a synchronization signal. The slave driver will update new data (if exist) onto the DMA upon seeing the termination command.
+Segment transaction mode is the only mode supported by the SPI Slave HD driver for now. In this mode, for a transaction the slave loads onto the DMA, the master is allowed to read or write in segments. In this way, the master does not have to prepare a large buffer as the size of data provided by the slave. After the master finishes reading/writing a buffer, it has to send the corresponding termination command to the slave as a synchronization signal. The slave driver will update new data (if exist) onto the DMA upon seeing the termination command.
 
-The termination command is WR_DONE (0x07) for the WRDMA and CMD8 (0x08) for the RDDMA.
+The termination command is WR_DONE (0x07) for WRDMA and CMD8 (0x08) for RDDMA.
 
 Here is an example for the flow the master read data from the slave DMA:
 
-1. The slave loads 4092 bytes of data onto the RDDMA
-2. The master do seven RDDMA transactions, each of them is 512 bytes long, and reads the first 3584 bytes from the slave
+1. The slave loads 4092 bytes of data onto the RDDMA.
+2. The master do seven RDDMA transactions, each of them is 512 bytes long, and reads the first 3584 bytes from the slave.
 3. The master do the last RDDMA transaction of 512 bytes (equal, longer, or shorter than the total length loaded by the slave are all allowed). The first 508 bytes are valid data from the slave, while the last 4 bytes are meaningless bytes.
-4. The master sends CMD8 to the slave
-5. The slave loads another 4092 bytes of data onto the RDDMA
-6. The master can start new reading transactions after it sends the CMD8
+4. The master sends CMD8 to the slave.
+5. The slave loads another 4092 bytes of data onto the RDDMA.
+6. The master can start new reading transactions after it sends the CMD8.

docs/zh_CN/api-reference/protocols/esp_spi_slave_protocol.rst

@@ -1 +1,150 @@
-.. include:: ../../../en/api-reference/protocols/esp_spi_slave_protocol.rst
+ESP SPI 从机 HD（半双工）模式协议
+==========================================
+
+:link_to_translation:`en:[English]`
+
+.. only:: esp32
+
+    .. warning::
+
+        ESP32 不支持此功能。
+
+.. _esp_spi_slave_caps:
+
+乐鑫芯片的 SPI 从机功能支持概况
+---------------------------------
+
++-------------+-------+----------+----------+----------+----------+----------+----------+
+|             | ESP32 | ESP32-S2 | ESP32-C3 | ESP32-S3 | ESP32-C2 | ESP32-C6 | ESP32-H2 |
++-------------+-------+----------+----------+----------+----------+----------+----------+
+| SPI 从机 HD | N     | Y (v2)   | Y (v2)   | Y (v2)   | Y (v2)   | Y (v2)   | Y (v2)   |
++-------------+-------+----------+----------+----------+----------+----------+----------+
+| Tohost intr |       | N        | N        | N        | N        | N        | N        |
++-------------+-------+----------+----------+----------+----------+----------+----------+
+| Frhost intr |       | 2 *      | 2 *      | 2 *      | 2 *      | 2 *      | 2 *      |
++-------------+-------+----------+----------+----------+----------+----------+----------+
+| TX DMA      |       | Y        | Y        | Y        | Y        | Y        | Y        |
++-------------+-------+----------+----------+----------+----------+----------+----------+
+| RX DMA      |       | Y        | Y        | Y        | Y        | Y        | Y        |
++-------------+-------+----------+----------+----------+----------+----------+----------+
+| 共享寄存器  |       | 72       | 64       | 64       | 64       | 64       | 64       |
++-------------+-------+----------+----------+----------+----------+----------+----------+
+
+概述
+----
+
+在半双工模式下，主机须使用从机定义的协议与从机通信。每个传输事务按顺序可能包括以下阶段：
+
+- 命令阶段：8 位，主机到从机
+
+    此阶段决定事务的其它阶段。参见 :ref:`spi_slave_hd_supported_cmds`。
+
+- 地址阶段：8 位，主机到从机，可选
+
+    对于某些命令 (如 WRBUF、RDBUF)，此阶段指定要写入/读取的共享寄存器地址。对于其他包括此阶段的命令，这没有实际意义，但仍必须存在于事务中。
+
+- Dummy 阶段：8 位，浮动，可选
+
+    此阶段是主机和从机在总线上的周转时间，并为从机向主机发送数据提供了充分的准备时间。
+
+- 数据阶段：长度可变，方向由命令确定。
+
+    这一阶段可以输出数据（OUT，方向为由从机向主机），或者输入数据（IN，方向为由主机向从机）。
+
+**方向** 是指哪一方（主机或从机）控制 MOSI、MISO、WP 和 HD 管脚。
+
+数据 IO 模式
+-------------
+
+在某些 IO 模式下，可以使用更多数据线来发送数据。因此，与 1 位模式相比，发送相同数据量所需的 SPI 时钟周期更少。例如，在 QIO 模式下，地址和数据 (IN 和 OUT) 应发送到全部 4 条数据线上 (MOSI、MISO、WP 和 HD)。下表展示了 ESP32-S2 SPI 从机支持的模式，以及相应模式下使用的数据线数量。
+
++-------+----------+----------+------------+----------+
+| Mode  | 命令线数 | 地址线数 | dummy 次数 | 数据线数 |
++-------+----------+----------+------------+----------+
+| 1-bit | 1        | 1        | 1          | 1        |
++-------+----------+----------+------------+----------+
+| DOUT  | 1        | 1        | 4          | 2        |
++-------+----------+----------+------------+----------+
+| DIO   | 1        | 2        | 4          | 2        |
++-------+----------+----------+------------+----------+
+| QOUT  | 1        | 1        | 4          | 4        |
++-------+----------+----------+------------+----------+
+| QIO   | 1        | 4        | 4          | 4        |
++-------+----------+----------+------------+----------+
+| QPI   | 4        | 4        | 4          | 4        |
++-------+----------+----------+------------+----------+
+
+除 QPI 模式外，使用哪种模式通常取决于主机发送的命令（请参考 :ref:`spi_slave_hd_supported_cmds`）。
+
+QPI 模式
+^^^^^^^^
+
+QPI 模式是 SPI 从机的一种特殊状态。主机可发送 ENQPI 命令，使从机进入 QPI 模式。在 QPI 模式下，命令以 4 位形式发送，因此与其他正常模式不兼容。只有在从机处于 QPI 模式时，主机才能发送 QPI 命令。主机可发送 EXQPI 命令退出 QPI 模式。
+
+.. _spi_slave_hd_supported_cmds:
+
+支持的命令
+----------
+
+.. note::
+    命令名称是从主机视角确定的。例如，WRBUF 表示由主机向从机的缓冲区写入。
+
++----------+---------------+------+----------+------------------------------+
+| 名称     | 描述          | 命令 | 地址     | 数据                         |
++----------+---------------+------+----------+------------------------------+
+| WRBUF    | 写入缓冲区    | 0x01 | Buf addr | 主到从，不超过缓冲区大小     |
++----------+---------------+------+----------+------------------------------+
+| RDBUF    | 读取缓冲区    | 0x02 | Buf addr | 从到主，不超过缓冲区大小     |
++----------+---------------+------+----------+------------------------------+
+| WRDMA    | 写入 DMA      | 0x03 | 8 位     | 主到从，不超过从机提供的长度 |
++----------+---------------+------+----------+------------------------------+
+| RDDMA    | 读取 DMA      | 0x04 | 8 位     | 从到主，不超过从机提供的长度 |
++----------+---------------+------+----------+------------------------------+
+| SEG_DONE | 段完成        | 0x05 | -        | -                            |
++----------+---------------+------+----------+------------------------------+
+| ENQPI    | 进入 QPI 模式 | 0x06 | -        | -                            |
++----------+---------------+------+----------+------------------------------+
+| WR_DONE  | 写入段完成    | 0x07 | -        | -                            |
++----------+---------------+------+----------+------------------------------+
+| CMD8     | 中断          | 0x08 | -        | -                            |
++----------+---------------+------+----------+------------------------------+
+| CMD9     | 中断          | 0x09 | -        | -                            |
++----------+---------------+------+----------+------------------------------+
+| CMDA     | 中断          | 0x0A | -        | -                            |
++----------+---------------+------+----------+------------------------------+
+| EXQPI    | 退出 QPI 模式 | 0xDD | -        | -                            |
++----------+---------------+------+----------+------------------------------+
+
+此外，WRBUF、RDBUF、WRDMA 和 RDDMA 命令都有 2 位和 4 位版本。要在 2 位或 4 位模式下操作，请用下表中的对应命令掩码与原始命令按位或（bit OR）后发送。例如，命令 0xA1 表示 QIO 模式下的 WRBUF。
+
++-------+------+
+| 模式  | 掩码 |
++-------+------+
+| 1-bit | 0x00 |
++-------+------+
+| DOUT  | 0x10 |
++-------+------+
+| DIO   | 0x50 |
++-------+------+
+| QOUT  | 0x20 |
++-------+------+
+| QIO   | 0xA0 |
++-------+------+
+| QPI   | 0xA0 |
++-------+------+
+
+段事务模式
+------------------
+
+目前，SPI 从机 HD 驱动程序仅支持段事务模式。在此模式下，对于从机加载到 DMA 的事务，主机可以分段读取或写入。这样，主机就无需准备与从机数据大小相同的大缓冲区。主机在一个缓冲区的读取/写入完成后，须向从机发送相应的终止命令作为同步信号。在从机收到终止命令后，从机驱动程序会将新数据（如有）更新到 DMA 上。
+
+WRDMA 的终止命令是 WR_DONE (0x07)，RDDMA 的终止命令是 CMD8 (0x08)。
+
+以下是主机自从机 DMA 读取数据的流程示例：
+
+1. 从机将 4092 字节数据加载到 RDDMA。
+2. 主机进行七次 RDDMA 事务，每个事务长 512 字节，并自从机读取前 3584 字节。
+3. 主机进行最后一次 RDDMA 事务，长度为 512 字节（长度可以与从机相同、更长或更短）。前 508 字节是从机发送的有效数据，最后 4 字节无意义。
+4. 主机向从机发送 CMD8。
+5. 从机将其他的 4092 字节数据加载到 RDDMA。
+6. 主机发送 CMD8 后，可以开始新的读取事务。