docs/zh_CN/api-reference/peripherals/sdspi_host.rst
: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 函数：
sdspi_host_initsdspi_host_init_devicesdspi_host_remove_devicesdspi_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
.. include-build-file:: inc/sdspi_host.inc