Merge branch 'docs/add_Chinese_translation_for_api-reference_peripher…

…als_sdspi_host.rst' into 'master'

docs: provide CN translation for api-reference/peripherals/sdspi_host.rst

Closes DOC-5726

See merge request espressif/esp-idf!24675

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

@@ -1,27 +1,29 @@
 SD SPI Host Driver
 ==================
 
+:link_to_translation:`zh_CN:[中文]`
+
 Overview
 --------
 
-The SD SPI host driver allows communicating with one or more SD cards by the SPI Master driver which makes use of the SPI host. Each card is accessed through an SD SPI device represented by an `sdspi_dev_handle_t` spi_handle returned when attaching the device to an SPI bus by calling `sdspi_host_init_device`. The bus should be already initialized before (by `spi_bus_initialize`).
+The SD SPI host driver allows communication with one or more SD cards using the SPI Master driver, which utilizes the SPI host. Each card is accessed through an SD SPI device, represented by an SD SPI handle :cpp:type:`sdspi_dev_handle_t`, which returns when the device is attached to an SPI bus by calling :cpp:func:`sdspi_host_init_device`. It is important to note that the SPI bus should be initialized beforehand by :cpp:func:`spi_bus_initialize`.
 
 .. only:: esp32
 
-    This driver's naming pattern was adopted from the :doc:`SDMMC Host <sdmmc_host>` driver due to their similarity. Likewise, the APIs of both drivers are also very similar.
+    This driver's naming pattern was adopted from the :doc:`sdmmc_host` due to their similarity. Likewise, the APIs of both drivers are also very similar.
 
-    SD SPI driver (access the SD card in SPI mode) offers lower throughput but makes pin selection more flexible. With the help of the GPIO matrix, an SPI peripheral's signals can be routed to any {IDF_TARGET_NAME} pin. Otherwise, if SDMMC host driver is used (See :doc:`SDMMC Host <sdmmc_host>`) to access the card in SD 1-bit/4-bit mode, higher throughput can be reached but it requires routing the signals through their dedicated IO_MUX pins only.
+    SD SPI driver that accesses the SD card in SPI mode offers lower throughput but makes pin selection more flexible. With the help of the GPIO matrix, an SPI peripheral's signals can be routed to any {IDF_TARGET_NAME} pin. Otherwise, if an SDMMC host driver is used (see :doc:`sdmmc_host`) to access the card in SD 1-bit/4-bit mode, higher throughput can be reached while requiring routing the signals through their dedicated IO_MUX pins only.
 
-With the help of :doc:`SPI Master driver <spi_master>` based on, the SPI bus can be shared among SD cards and other SPI devices. The SPI Master driver will handle exclusive access from different tasks.
+With the help of :doc:`spi_master` the SD SPI host driver based on, the SPI bus can be shared among SD cards and other SPI devices. The SPI Master driver will handle exclusive access from different tasks.
 
 The SD SPI driver uses software-controlled CS signal.
 
 How to Use
 ----------
 
-Firstly, use the macro :c:macro:`SDSPI_DEVICE_CONFIG_DEFAULT` to initialize a structure :cpp:type:`sdspi_device_config_t`, which is used to initialize an SD SPI device. This macro will also fill in the default pin mappings, which is same as the pin mappings of SDMMC host driver. Modify the host and pins of the structure to desired value. Then call `sdspi_host_init_device` to initialize the SD SPI device and attach to its bus.
+Firstly, use the macro :c:macro:`SDSPI_DEVICE_CONFIG_DEFAULT` to initialize the structure :cpp:type:`sdspi_device_config_t`, which is used to initialize an SD SPI device. This macro will also fill in the default pin mappings, which are the same as the pin mappings of the SDMMC host driver. Modify the host and pins of the structure to desired value. Then call ``sdspi_host_init_device`` to initialize the SD SPI device and attach to its bus.
 
-Then use :c:macro:`SDSPI_HOST_DEFAULT` macro to initialize a :cpp:type:`sdmmc_host_t` structure, which is used to store the state and configurations of upper layer (SD/SDIO/MMC driver). Modify the `slot` parameter of the structure to the SD SPI device spi_handle just returned from `sdspi_host_init_device`. Call `sdmmc_card_init` with the :cpp:type:`sdmmc_host_t` to probe and initialize the SD card.
+Then use the :c:macro:`SDSPI_HOST_DEFAULT` macro to initialize the :cpp:type:`sdmmc_host_t` structure, which is used to store the state and configurations of the upper layer (SD/SDIO/MMC driver). Modify the ``slot`` parameter of the structure to the SD SPI device SD SPI handle just returned from ``sdspi_host_init_device``. Call ``sdmmc_card_init`` with the :cpp:type:`sdmmc_host_t` to probe and initialize the SD card.
 
 Now you can use SD/SDIO/MMC driver functions to access your card!
 
@@ -35,14 +37,12 @@ Only the following driver's API functions are normally used by most applications
 - :cpp:func:`sdspi_host_remove_device`
 - :cpp:func:`sdspi_host_deinit`
 
-Other functions are mostly used by the protocol level SD/SDIO/MMC driver via function pointers in the :cpp:type:`sdmmc_host_t` structure. For more details, see :doc:`the SD/SDIO/MMC Driver <../storage/sdmmc>`.
-
-
+Other functions are mostly used by the protocol level SD/SDIO/MMC driver via function pointers in the :cpp:type:`sdmmc_host_t` structure. For more details, see :doc:`../storage/sdmmc`.
 
 .. note::
 
     SD over SPI does not support speeds above :c:macro:`SDMMC_FREQ_DEFAULT` due to the limitations of the SPI driver.
-    
+
 .. warning::
 
     If you want to share the SPI bus among SD card and other SPI devices, there are some restrictions, see :doc:`sdspi_share`.

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

@@ -1 +1,69 @@
-.. include:: ../../../en/api-reference/peripherals/sdspi_host.rst
+SD SPI 主机驱动程序
+=====================
+
+:link_to_translation:`en:[English]`
+
+概述
+--------
+
+SD SPI 主机驱动程序支持使用 SPI 主控驱动程序与一或多张 SD 卡通信，SPI 主控驱动程序则利用 SPI 主机实现功能。每张 SD 卡都通过一个 SD SPI 设备访问，相应设备以 SD SPI 设备句柄 :cpp:type:`sdspi_dev_handle_t` 表示。调用 :cpp:func:`sdspi_host_init_device` 将设备连接到 SPI 总线上时会返回所需 SPI 设备句柄。注意，在使用 SPI 总线前，需要先通过 :cpp:func:`spi_bus_initialize` 初始化总线。
+
+.. only:: esp32
+
+    SD SPI 主机驱动程序的命名模式参照 :doc:`sdmmc_host`，因为二者本身及支持的 API 都非常相似。
+
+    SD SPI 驱动程序使用 SPI 模式访问 SD 卡，此时的吞吐量较低，但可以更自由地选择管脚。通过 GPIO 矩阵，SPI 外设的信号可以路由到 {IDF_TARGET_NAME} 上的任意管脚。反之，若使用 SDMMC 主机驱动程序（请参阅 :doc:`sdmmc_host`）通过 SD 1 位/4 位模式访问 SD 卡，则可以实现更高的吞吐量，但需要使用专用的 IO_MUX 管脚路由信号。
+
+SD SPI 主机驱动程序基于 :doc:`spi_master` 实现。借助 SPI 主控驱动程序，SD 卡及其他 SPI 设备可以共享同一 SPI 总线。SPI 主机驱动程序将处理来自不同任务的独占访问。
+
+SD SPI 驱动程序使用受软件控制的 CS 信号。
+
+使用方法
+----------
+
+首先，使用宏 :c:macro:`SDSPI_DEVICE_CONFIG_DEFAULT` 初始化结构体 :cpp:type:`sdspi_device_config_t`，该结构体用于初始化 SD SPI 设备。该宏还会填充默认的管脚映射，与 SDMMC 主机驱动的管脚映射相同。随后根据需要，修改结构体中的主机和管脚配置。然后调用 ``sdspi_host_init_device`` 初始化 SD SPI 设备，并将其连接到所属的总线上。
+
+接着，使用宏 :c:macro:`SDSPI_HOST_DEFAULT` 初始化结构体 :cpp:type:`sdmmc_host_t`，该结构体用于存储上层（SD/SDIO/MMC 驱动）的状态和配置信息。将结构体中的 ``slot`` 参数设置为从 ``sdspi_host_init_device`` 返回的 SD SPI 设备的 SD SPI 句柄。使用 :cpp:type:`sdmmc_host_t` 调用 ``sdmmc_card_init``，检测并初始化 SD 卡。
+
+初始化完成后，即可使用 SD/SDIO/MMC 驱动函数访问 SD 卡。
+
+其他细节
+-------------
+
+通常，大多数应用程序仅使用驱动程序的以下 API 函数：
+
+- :cpp:func:`sdspi_host_init`
+- :cpp:func:`sdspi_host_init_device`
+- :cpp:func:`sdspi_host_remove_device`
+- :cpp:func:`sdspi_host_deinit`
+
+对于其他函数，大多由协议层的 SD/SDIO/MMC 驱动程序通过 :cpp:type:`sdmmc_host_t` 结构体中的函数指针使用。更多详情，请参阅 :doc:`../storage/sdmmc`。
+
+.. note::
+
+    由于 SPI 驱动程序的限制，SD 卡在通过 SPI 总线与主设备进行数据传输和通信时，速度不超过 :c:macro:`SDMMC_FREQ_DEFAULT`。
+
+.. warning::
+
+    在 SD 卡之间以及其他 SPI 设备间共享 SPI 总线时，存在部分限制，详情请参阅 :doc:`sdspi_share`。
+
+.. todo
+
+..    The SD SPI API reference could use more detail such as:
+..    - Configuration. What are some key points of concern regarding slot configuration.
+..    - Which function/how is a transaction done?
+..    - Are there code snippets or corresponding application examples?
+
+相关文档
+--------------
+
+.. toctree::
+   :maxdepth: 1
+
+   sdspi_share
+
+
+API 参考
+-------------
+
+.. include-build-file:: inc/sdspi_host.inc