docs: Provide Chinese translation for api-reference/protocols/esp_serial_slave_link.rst

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

@@ -1,7 +1,9 @@
 ASIO Port
 =========
 
-Asio is a cross-platform C++ library, see https://think-async.com/Asio/. It provides a consistent asynchronous model using a modern C++ approach.
+:link_to_translation:`zh_CN:[中文]`
+
+ASIO is a cross-platform C++ library, see https://think-async.com/Asio/. It provides a consistent asynchronous model using a modern C++ approach.
 
 The ESP-IDF component ``ASIO`` has been moved from ESP-IDF since version v5.0 to a separate repository:
 
@@ -14,4 +16,4 @@ Hosted Documentation
 
 The documentation can be found on the link below:
 
-* `ASIO documentation (English) <https://docs.espressif.com/projects/esp-protocols/asio/docs/latest/index.html>`__
+* `ASIO documentation (English) <https://docs.espressif.com/projects/esp-protocols/asio/docs/latest/index.html>`__

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

@@ -1,13 +1,23 @@
 ESP Serial Slave Link
 =====================
 
+:link_to_translation:`zh_CN:[中文]`
+
 Overview
 --------
 
 Espressif provides several chips that can work as slaves. These slave devices rely on some common buses, and have their own communication protocols over those buses. The ``esp_serial_slave_link`` component is designed for the master to communicate with ESP slave devices through those protocols over the bus drivers.
 
-After an ``esp_serial_slave_link`` device is initialized properly, the application can use it to communicate with the ESP
-slave devices conveniently.
+After an ``esp_serial_slave_link`` device is initialized properly, the application can use it to communicate with the ESP slave devices conveniently.
+
+.. note::
+
+  The ESP-IDF component ``esp_serial_slave_link`` has been moved from ESP-IDF since version v5.0 to a separate repository:
+
+  * `ESSL component on GitHub <https://github.com/espressif/idf-extra-components/tree/master/esp_serial_slave_link>`__
+
+  To add ESSL component in your project, please run ``idf.py add-dependency espressif/esp_serial_slave_link``.
+
 
 Espressif Device Protocols
 --------------------------
@@ -52,15 +62,15 @@ There are some common services provided by the Espressif slaves:
 
 2. Frhost Interrupts: The master can inform the slave about certain events.
 
-3. TX FIFO (master to slave): the slave can send data in stream to the master. The SDIO slave can also indicate it has new data to send to master by the interrupt line.
+3. TX FIFO (master to slave): The slave can receive data from the master in units of receiving buffers.
 
    The slave updates the TX buffer num to inform the master how much data it can receive, and the master then read the TX buffer num, and take off the used buffer number to know how many buffers are remaining.
 
-4. RX FIFO (slave to master): the slave can receive data from the master in units of receiving buffers.
+4. RX FIFO (slave to master): The slave can send data in stream to the master. The SDIO slave can also indicate it has new data to send to master by the interrupt line.
 
    The slave updates the RX data size to inform the master how much data it has prepared to send, and then the master read the data size, and take off the data length it has already received to know how many data is remaining.
 
-5. Shared registers: the master can read some part of the registers on the slave, and also write these registers to let the slave read.
+5. Shared registers: The master can read some part of the registers on the slave, and also write these registers to let the slave read.
 
 .. only:: SOC_SDIO_SLAVE_SUPPORTED
 
@@ -79,9 +89,9 @@ Initialization of ESP Serial Slave Link
 ESP SDIO Slave
 ^^^^^^^^^^^^^^
 
-The ESP SDIO slave link (ESSL SDIO) devices relies on the sdmmc component. It includes the usage of communicating with ESP SDIO Slave device via SDSPI feature. The ESSL device should be initialized as below:
+The ESP SDIO slave link (ESSL SDIO) devices relies on the SDMMC component. It includes the usage of communicating with ESP SDIO Slave device via the SDMMC Host or SDSPI Host feature. The ESSL device should be initialized as below:
 
-1. Initialize a sdmmc card (see :doc:` Document of SDMMC driver </api-reference/storage/sdmmc>`) structure.
+1. Initialize a SDMMC card (see :doc:` Document of SDMMC driver </api-reference/storage/sdmmc>`) structure.
 
 2. Call :cpp:func:`sdmmc_card_init` to initialize the card.
 
@@ -124,14 +134,14 @@ Frhost Interrupts
 TX FIFO
 ^^^^^^^
 
-1. Call :cpp:func:`essl_get_tx_buffer_num` to know how many buffers the slave has prepared to receive data from the master. This is optional. The master will poll ``tx_buffer_num`` when it try to send packets to the slave, until the slave has enough buffer or timeout.
+1. Call :cpp:func:`essl_get_tx_buffer_num` to know how many buffers the slave has prepared to receive data from the master. This is optional. The master will poll ``tx_buffer_num`` when it tries to send packets to the slave, until the slave has enough buffer or timeout.
 
 2. Call :cpp:func:`essl_send_packet` to send data to the slave.
 
 RX FIFO
 ^^^^^^^
 
-1. Call :cpp:func:`essl_get_rx_data_size` to know how many data the slave has prepared to send to the master. This is optional. When the master tries to receive data from the slave, it will update the ``rx_data_size`` for once, if the current ``rx_data_size`` is shorter than the buffer size the master prepared to receive. And it may poll the ``rx_data_size`` if the ``rx_dat_size`` keeps 0, until timeout.
+1. Call :cpp:func:`essl_get_rx_data_size` to know how many data the slave has prepared to send to the master. This is optional. When the master tries to receive data from the slave, it updates the ``rx_data_size`` for once, if the current ``rx_data_size`` is shorter than the buffer size the master prepared to receive. And it may poll the ``rx_data_size`` if the ``rx_data_size`` keeps 0, until timeout.
 
 2. Call :cpp:func:`essl_get_packet` to receive data from the slave.
 
@@ -144,9 +154,9 @@ Call :cpp:func:`essl_reset_cnt` to reset the internal counter if you find the sl
 Application Example
 -------------------
 
-The example below shows how {IDF_TARGET_NAME} SDIO host and slave communicate with each other. The host use the ESSL SDIO.
+The example below shows how {IDF_TARGET_NAME} SDIO host and slave communicate with each other. The host uses the ESSL SDIO:
 
-:example:`peripherals/sdio`.
+:example:`peripherals/sdio`
 
 Please refer to the specific example README.md for details.
 

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

@@ -1 +1,19 @@
-.. include:: ../../../en/api-reference/protocols/asio.rst
+ASIO 端口
+===========
+
+:link_to_translation:`en:[English]`
+
+ASIO 是一个跨平台的 C++ 库，参见 https://think-async.com/Asio/。它采用现代 C++ 方法提供了一个一致的异步模型。
+
+``ASIO`` 组件自 ESP-IDF 版本 v5.0 起移到了单独的仓库：
+
+* `GitHub ASIO 组件  <https://github.com/espressif/esp-protocols/tree/master/components/asio>`__
+
+运行 ``idf.py add-dependency espressif/asio`` 将 ASIO 组件添加到你的项目中。
+
+文档
+------
+
+访问以下链接查看相关文档：
+
+* `ASIO 文档 (English) <https://docs.espressif.com/projects/esp-protocols/asio/docs/latest/index.html>`__

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

@@ -1 +1,168 @@
-.. include:: ../../../en/api-reference/protocols/esp_serial_slave_link.rst
+ESP 串行从机链路
+=================
+
+:link_to_translation:`en:[English]`
+
+概述
+----
+
+乐鑫有多款芯片可用作从机的芯片。这些从机依赖于一些通用总线，并在总线上实现了各自的通信协议。 ``esp_serial_slave_link`` 组件能让主机通过总线驱动和相应的协议与 ESP 从机进行通信。
+
+``esp_serial_slave_link`` 设备初始化完成后，应用程序就能通过它与 ESP 从机方便地通信。
+
+.. note::
+
+  ``esp_serial_slave_link`` 组件自 ESP-IDF 版本 v5.0 起移到了单独的仓库：
+
+  * `ESSL component on GitHub <https://github.com/espressif/idf-extra-components/tree/master/esp_serial_slave_link>`__
+
+  运行 ``idf.py add-dependency espressif/esp_serial_slave_link`` 将 ESSL 组件添加到你的项目中。
+
+
+乐鑫设备协议
+--------------------
+
+如需了解关于乐鑫设备协议详情，请参考以下文档：
+
+.. toctree::
+    :maxdepth: 1
+
+    :SOC_SDIO_SLAVE_SUPPORTED: esp_sdio_slave_protocol
+    esp_spi_slave_protocol
+
+术语解释
+--------
+
+- ESSL：ESP 串行从机链路 (ESP Serial Slave Link)，即本文档描述的组件。
+
+- 主机：运行 ``esp_serial_slave_link`` 组件的设备。
+
+- ESSL 设备：主机上的虚拟设备，关联到一个 ESP 从机，其设备上下文中具有如何通过总线驱动和从机的总线协议与其通信的信息。
+
+- ESSL 设备句柄：ESSL 设备上下文的一个句柄，包含配置信息、状态信息和 ESSL 组件所需的数据。设备上下文中储存了驱动配置、通信状态和主从机共享的数据等。
+
+   - 在使用前，应将上下文初始化；如不再使用，应该反初始化。主机应用程序通过这一句柄操作 ESSL 设备。
+
+- ESP 从机：连接到总线的从机，ESSL 组件的通信对象。
+
+- 总线：特指用于主机和从机相互通信的总线。
+
+- 从机协议：Espressif 硬件和软件在总线上使用的特殊通信协议。
+
+- TX buffer num：计数器，位于从机，可由主机读取。指示由从机加载到硬件上、用于接收主机数据的累计 buffer 总数。
+
+- RX data size：计数器，位于从机，可由主机读取。指示由从机加载到硬件上、需发送给主机的累计数据大小。
+
+ESP 从机提供的服务
+---------------------------
+
+Espressif 从机提供下列服务：
+
+1. Tohost 中断：从机可通过中断线向主机通知某些事件。（可选）
+
+2. Frhost 中断：主机可向从机通知某些事件。
+
+3. TX FIFO（主机到从机）：从机能够以接收 buffer 为单位，接收主机发送的数据。
+
+   从机通过更新 TX buffer num 的方式，将可以接收多少数据的信息通知主机。主机读取 TX buffer num，减去已使用的 buffer 数，得到剩余 buffer 数量。
+
+4. RX FIFO（从机到主机）：从机可向主机发送数据流。SDIO 从机也可通过中断线通知主机，从机有待发送的新数据。
+
+   从机通过更新 RX data size，将准备发送的数据大小通知主机。主机读取该数据大小，减去已接收的数据长度，得到剩余数据大小。
+
+5. 共享寄存器：主机可以读取从机寄存器上的部分内容，也可写入从机寄存器供从机读取。
+
+.. only:: SOC_SDIO_SLAVE_SUPPORTED
+
+   从机提供的服务取决于从机的模型。如需了解详情，请参考 :ref:`esp_sdio_slave_caps` 和 :ref:`esp_spi_slave_caps`。
+
+.. only:: not SOC_SDIO_SLAVE_SUPPORTED
+
+   从机提供的服务取决于从机的模型。如需了解详情，请参考 :ref:`esp_spi_slave_caps`。
+
+
+初始化 ESP 串行从机链路
+--------------------------------
+
+.. _essl_sdio_slave_init:
+
+ESP SDIO 从机
+^^^^^^^^^^^^^^^^^
+
+ESP SDIO 从机链路 (ESSL SDIO) 设备依赖于 SDMMC 组件。它可通过 SDMMC Host 或 SDSPI Host 功能均可与 ESP SDIO 从机通信。ESSL 设备初始化步骤如下：
+
+1. 初始化 SDMMC 卡（参考 :doc:`SDMMC 驱动相关文档 </api-reference/storage/sdmmc>` ）结构体。
+
+2. 调用 :cpp:func:`sdmmc_card_init` 初始化该卡。
+
+3. 用 :cpp:type:`essl_sdio_config_t` 初始化 ESSL 设备。其中， ``card`` 成员应为第二步中的 :cpp:type:`sdmmc_card_t`， ``recv_buffer_size`` 成员应填写为预先协商的值。
+
+4. 调用 :cpp:func:`essl_init` 对 SDIO 部分进行初始化。
+
+5. 调用 :cpp:func:`essl_wait_for_ready` 等待从机就绪。
+
+ESP SPI 从机
+^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+    如果你正在用 SPI 接口与 ESP SDIO 从机进行通信，则应该用 :ref:`SDIO 接口 <essl_sdio_slave_init>` 代替。
+
+暂不支持。
+
+API
+--------
+
+初始化完成后，你可调用以下 API 使用从机提供的服务：
+
+Tohost 中断（可选）
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. 调用 :cpp:func:`essl_get_intr_ena` 了解哪些事件触发了对主机的中断。
+
+2. 调用 :cpp:func:`essl_set_intr_ena` 设置能够触发主机中断的事件。
+
+3. 调用 :cpp:func:`essl_wait_int` 等待从机中断或超时。
+
+4. 中断触发后，调用 :cpp:func:`essl_get_intr` 了解哪些事件处于活跃状态，并调用 :cpp:func:`essl_clear_intr` 将其清空。
+
+Frhost 中断
+^^^^^^^^^^^^^^^^^
+
+1. 调用 :cpp:func:`essl_send_slave_intr` 触发从机的通用中断。
+
+TX FIFO
+^^^^^^^
+
+1. 调用 :cpp:func:`essl_get_tx_buffer_num` 了解从机准备用于接收主机数据的 buffer 数。你可选择是否调用该函数。主机向从机发送数据包前，也会轮询 ``tx_buffer_num``，直到从机的 buffer 数量足够或超时。
+
+2. 调用 :cpp:func:`essl_send_packet` 向从机发送数据。
+
+RX FIFO
+^^^^^^^
+
+1. 调用 :cpp:func:`essl_get_rx_data_size` 了解从机需发送给主机的数据大小。你可选择是否调用该函数。当主机尝试接收数据时，如果目前的 ``rx_data_size`` 小于主机准备接收数据的 buffer 大小，就会对 ``rx_data_size`` 进行一次更新。如果 ``rx_data_size`` 一直为 0，主机可能会轮询 ``rx_data_size`` 直到超时。
+
+2. 调用 :cpp:func:`essl_get_packet` 接收来自从机的数据。
+
+重置计数器（可选）
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+如果从机计数器已重置，调用 :cpp:func:`essl_reset_cnt` 重置内部计数器。
+
+
+应用示例
+--------------
+
+以下示例展示了 {IDF_TARGET_NAME} SDIO 主机如何与从机互相通信，其中主机使用了 ESSL SDIO：
+
+:example:`peripherals/sdio`
+
+如需了解详情，请参考 README.md 中的示例。
+
+API 参考
+----------
+
+.. include-build-file:: inc/essl.inc
+.. include-build-file:: inc/essl_sdio.inc
+.. include-build-file:: inc/essl_spi.inc