docs/zh_CN/api-reference/peripherals/sdio_slave.rst
:link_to_translation:en:[English]
.. only:: esp32
如下表所示，ESP32 SDIO 卡的主机与从机外设共享两组管脚。SPI0 总线通常会占用第一组管脚，该总线负责运行代码，与 SPI flash 相连。因此，在 SDIO 主机不使用第二组管脚时，SDIO 从机驱动程序只能在第二组管脚上运行。
SDIO 从机支持以下三种运行模式：SPI、1 位 SD 和 4 位 SD。从机设备可以根据接口上的信号确定当前模式，并相应地配置自身以适配该模式。随后，从机驱动程序可以与从机设备进行通信，正确处理命令和数据传输。根据 SDIO 规范，无论是在 1 位 SD、4 位 SD 还是 SPI 模式下，CMD 和 DAT0-3 信号线都应设置为高电平。
连接方式 ^^^^^^^^^^^
.. only:: esp32
.. list-table::
:header-rows: 1
:widths: 25 25 25 25
:align: center
* - 管脚名称
- SPI 模式的对应管脚
- GPIO 编号（卡槽 1）
- GPIO 编号（卡槽 2）
* - CLK
- SCLK
- 6
- 14
* - CMD
- MOSI
- 11
- 15
* - DAT0
- MISO
- 7
- 2
* - DAT1
- 中断
- 8
- 4
* - DAT2
- N.C.（拉高）
- 9
- 12
* - DAT3
- #CS
- 10
- 13
.. only:: esp32c6
.. list-table::
:header-rows: 1
:widths: 30 40 30
:align: center
* - 管脚名称
- SPI 模式的对应管脚
- GPIO 编号
* - CLK
- SCLK
- 19
* - CMD
- MOSI
- 18
* - DAT0
- MISO
- 20
* - DAT1
- 中断
- 21
* - DAT2
- N.C.（拉高）
- 22
* - DAT3
- #CS
- 23
.. note::
请确保使用 10 KOhm - 90 KOhm 的上拉电阻将 SDIO 卡的 CMD 和数据线 DAT0-DAT3 配置为上拉，包括在 1 位模式或 SPI 模式下。大多数官方模组内部并未提供此类上拉电阻，使用官方开发板时，请参阅 :ref:compatibility_overview_espressif_hw_sdio，确认所用开发板是否配置此类上拉电阻。
.. only:: esp32
.. note::
多数官方模组的 strapping 管脚与 SDIO 从机功能配置存在冲突。若在内置 3.3 V flash 的 ESP32 模组上进行首次开发，需要在开发之前进行 eFuse 烧录，以调整模组的管脚配置，使其与 SDIO 功能兼容。请参阅 :ref:`compatibility_overview_espressif_hw_sdio`，了解具体配置方法。
以下是内置 3.3 V flash 的模组/开发板列表：
- 模组：除 ESP32-WROVER、ESP32-WROVER-I、ESP32-S3-WROOM-2 外的所有模组，模组列表见 `模组概览 <https://www.espressif.com/zh-hans/products/modules>`__
- 开发板：ESP32-PICO-KIT、ESP32-DevKitC（最高版本为 v4）、ESP32-WROVER-KIT（v4.1 [也称 ESP32-WROVER-KIT-VB]、v2、v1 [也称 DevKitJ v1]）
通过开发板上模组的型号可以判断 ESP32-WROVER-KIT 的版本：v4.1 使用 ESP32-WROVER-B 模组，v3 使用 ESP32-WROVER 模组，v2 和 v1 使用 ESP32-WROOM-32 模组。
要了解有关上拉电阻的更多技术细节，请参阅 :doc:sd_pullup_requirements。
.. toctree:: :hidden:
sd_pullup_requirements
主机可以配置 DAT3 管脚为高电平并发送 CMD0 命令，将从机初始化为 SD 模式；或配置 CS 管脚为低电平并发送 CMD0 命令，将从机初始化为 SPI 模式。CS 管脚与 DAT3 管脚相同。
初始化完成后，主机可以发送 CMD52 命令，将数据写入 CCCR 寄存器 0x07，启用 4 位 SD 模式。所有总线检测均由从机外设处理。
主机与从机的通信必须通过 ESP 从机特定协议进行。
通过 CMD52 和 CMD53 命令，从机驱动程序基于 Function 1 提供了以下三种服务：
(1) 发送和接收 FIFO (2) 主机和从机共享的 52 个 8 位 读写寄存器 (3) 16 个中断源（8 个从主机到从机，8 个从从机到主机）
术语 ^^^^^^^^^^^
SDIO 从机驱动程序的相关术语如下：
.. note::
在 {IDF_TARGET_NAME} 技术参考手册 > SDIO 从机控制器 [PDF <{IDF_TARGET_TRM_CN_URL}#sdioslave>__] 中，寄存器从主机的角度进行命名和定义。即，RX 寄存器指的是发送寄存器，TX 寄存器指的是接收寄存器。 我们在驱动程序中不再使用 TX 或 RX，以避免产生歧义。
.. note::
请求长度不同于传输长度。在 {IDF_TARGET_NAME} SDIO DMA 中，操作基于 请求长度 而非 传输长度，即 DMA 控制器会根据 请求长度 处理数据传输，确保只传输 请求长度 范围内的数据。传输长度 必须等于或长于 请求长度，并将剩余部分在发送时填充为 0，或在接受时丢弃。
sdio_slave_config_t 中的 recv_buffer_size 设置缓冲区大小。interrupts。与 ESP SDIO 从机通信 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
在使用主机初始化 SDIO 从机时，应遵循标准 SDIO 初始化流程（请参阅 SDIO 简化规范 <https://www.sdcard.org/downloads/pls/pdf/?p=PartE1_SDIO_Simplified_Specification_Ver3.00.jpg&f=PartE1_SDIO_Simplified_Specification_Ver3.00.pdf&e=EN_SSE1>_ 的第 3.1.2 节），简化版流程可参考 ESP SDIO Slave 初始化 <https://espressif.github.io/idf-extra-components/latest/esp_serial_slave_link/sdio_slave_protocol.html#esp-sdio-slave-initialization>_ 。
此外，在通过 CMD52/CMD53 访问到 Function 1 这一机制的基础上，还存在一个仅适用于 {IDF_TARGET_NAME} 的上层通信协议。该特定通信协议中，主机和从机通过 CMD52/CMD53 命令进行数据交换和通信。更多详情，请参阅 ESP SDIO 从机协议 <https://espressif.github.io/idf-extra-components/latest/esp_serial_slave_link/sdio_slave_protocol.html#esp-sdio-slave-protocol>_ 。
组件 ESSL <https://components.espressif.com/components/espressif/esp_serial_slave_link>_ 也支持 {IDF_TARGET_NAME} 主机与 {IDF_TARGET_NAME} SDIO 从机通信。在开发主机应用程序时，请参阅 :example:peripherals/sdio 中的示例。
.. _interrupts:
中断 ^^^^^^^^^^
为了方便通信，SDIO 从机驱动程序中既存在由主机到从机的中断信号，也存在由从机到主机的中断信号。
从机中断 """"""""""""""""
主机可以通过在寄存器 0x08D 中写入任意一个位来向从机发起中断。一旦置位了寄存器中的任意一位，就会产生一个中断，促使 SDIO 从机驱动调用特定回调函数，该回调函数由 sdio_slave_config_t 结构体中的 slave_intr_cb 定义。
.. note::
该回调函数在中断服务例程中调用，请勿在其中使用任何延迟、循环或可能阻塞的函数，如互斥锁。
类似前述情况，还有一组备选函数可供使用。可以调用 sdio_slave_wait_int 在一定时间内等待中断，或调用 sdio_slave_clear_int 清除来自主机的中断。回调函数可以与等待函数完美配合。
主机中断 """""""""""""""
从机可以在特定时间通过中断线向主机发起中断，这个中断是电平触发的。主机检测到中断线电平拉低时，它可以读取从机中断状态寄存器，以查看中断源。主机可以清除特定的中断位，或选择禁用中断源。在清除或禁用所有中断源前，中断线会保持激活状态。
在 SDIO 从机驱动程序中，还存在一些专用中断源和通用中断源，详情请参阅 sdio_slave_hostint_t。
共享寄存器 ^^^^^^^^^^^^^^^^
在主机与从机之间共有 52 个共享的 8 位读写寄存器，用于在主机和从机之间共享信息。通过 sdio_slave_read_reg 和 sdio_slave_write_reg，从机可以随时读取或写入寄存器。主机可以通过 CMD52 或 CMD53 访问（读写）这些寄存器。
接收 FIFO ^^^^^^^^^^^^^^
准备向从机发送数据包时，主机需要读取从机的缓冲区数据数量，判定从机是否准备好接收数据。
为了支持接收来自主机的数据，应用程序需按照以下步骤，将缓冲区加载到从机驱动程序中：
调用 sdio_slave_recv_register_buf 注册缓冲区，并获取已注册缓冲区的句柄。驱动程序会为链接到硬件的链表描述符所需的缓冲区分配内存。这些缓冲区的大小应与接收缓冲区大小相等。
将缓冲区句柄传递给 sdio_slave_recv_load_buf，将缓冲区加载到驱动程序中。
调用 sdio_slave_recv 或 sdio_slave_recv_packet 获取接收到的数据。如果需要采取非阻塞式调用，可以设置 wait 为 0。
这两个 API 的区别在于，sdio_slave_recv_packet 会提供更多有关数据包的信息，数据包可以由多个缓冲区组成。
当此 API 返回 ESP_ERR_NOT_FINISHED 时，应循环调用此 API，直到返回值为 ESP_OK。此时，在主机发送的数据包中，包含了所有与 ESP_ERR_NOT_FINISHED 一起返回的连续缓冲区，以及与 ESP_OK 一起返回的最后一个缓冲区。
调用 sdio_slave_recv_get_buf 获取所接收数据的地址，以及每个缓冲区实际接收到的长度。数据包的长度是数据包中所有缓冲区接收长度的总和。
如果主机发送的数据始终小于接收缓冲区的大小，或者数据包的边界（例如，数据只是一个字节流）无关紧要，则可以使用更简单的 sdio_slave_recv。
调用 sdio_recv_load_buf，将经过处理的缓冲区句柄再次传递给驱动程序。
.. note::
为减少复制数据的开销，驱动程序本身不具有任何内部缓冲区；应用程序有责任及时提供新的缓冲区，DMA 会自动将接收到的数据存储到缓冲区中。
发送 FIFO ^^^^^^^^^^^^
每当从机要发送数据时，它会触发一个中断，并由主机请求数据包长度。发送模式有两种：
.. note::
为减少复制数据的开销，驱动程序本身没有内部缓冲区，DMA 直接从应用程序提供的缓冲区中获取数据。发送完成前，应用程序不应该访问缓冲区，以确保数据传输的正确性。
结构体 sdio_slave_config_t 中的 sending_mode 可以设置发送模式，send_queue_size 可以设置缓冲区数量。缓冲区大小均限制在 4092 字节内。尽管在流模式下，一次传输可以发送多个缓冲区，但每个缓冲区在队列中仍然计为一个。
应用程序可以调用 sdio_slave_transmit 函数发送数据包。此时，函数在传输完成后返回，因此队列并未完全占用。若需要更高效率，应用程序可以改用以下函数：
将缓冲区信息（地址、长度以及表示缓冲区的 arg 参数）传递给 sdio_slave_send_queue。
wait 为 0。wait 并未设置为 portMAX_DELAY （等待直到缓冲区传输完成），应用程序应检查返回结果，确认数据是否已放入队列中，或是否已丢弃。调用 sdio_slave_send_get_finished 来获取并处理已完成的传输。在缓冲区 sdio_slave_send_get_finished 返回前不应修改缓冲区。这意味着缓冲区实际上发送给了主机，而非在队列中等待。
要使用队列参数中 arg ，可以采用以下几种方法：
1. 直接将 ``arg`` 指向一个动态分配的缓冲区，并在传输完成后使用 ``arg`` 释放该缓冲区。
2. 在传输结构体中封装传输信息，并将 ``arg`` 指向该结构体。使用该结构体还可以执行更多操作，例如::
typedef struct {
uint8_t* buffer;
size_t size;
int id;
}sdio_transfer_t;
//发送传输：
sdio_transfer_t trans = {
.buffer = ADDRESS_TO_SEND,
.size = 8,
.id = 3, //第 3 个传输
};
sdio_slave_send_queue(trans.buffer, trans.size, &trans, portMAX_DELAY);
//… 在此还可能发送更多传输
//处理完成的传输：
sdio_transfer_t* arg = NULL;
sdio_slave_send_get_finished((void**)&arg, portMAX_DELAY);
ESP_LOGI("tag", "(%d) successfully send %d bytes of %p", arg->id, arg->size, arg->buffer);
some_post_callback(arg); //执行更多操作
3. 用于该驱动程序的接收部分，将 ``arg`` 指向该缓冲区的接收缓冲区句柄。这样，可以在发送数据时直接使用该缓冲区来接收数据::
uint8_t buffer[256]={1,2,3,4,5,6,7,8};
sdio_slave_buf_handle_t handle = sdio_slave_recv_register_buf(buffer);
sdio_slave_send_queue(buffer, 8, handle, portMAX_DELAY);
//… 在此还可能发送更多传输
//加载已完成的传输，准备接收
sdio_slave_buf_handle_t handle = NULL;
sdio_slave_send_get_finished((void**)&handle, portMAX_DELAY);
sdio_slave_recv_load_buf(handle);
更多详情，请参阅 :example:`peripherals/sdio`。
重置 SDIO ^^^^^^^^^^^^
调用 sdio_slave_reset 可以重置 SDIO 从机驱动程序软件层面的 PKT_LEN (从机发送包长度累加值) 和 TOKEN1 (接收 buffer 累计数量), 便于与主机重新同步收发计数。
如果存在 ESP 芯片保持上电状态，但 HOST 端会下电的使用场景。HOST 端下电期间, SDIO 信号线上可能会产生一些未知的信号导致 SDIO 硬件状态机异常。HOST 重新启动, 执行卡识别流程, ESP 将不会正常响应。这种情况下，考虑调用 sdio_slave_reset_hw, 重置 SDIO 硬件。
.. note::
重置 SDIO 硬件，中断使能状态和共享寄存器的值会丢失，可能需要调用 sdio_slave_set_host_intena、 sdio_slave_write_reg 设置。
peripherals/sdio/host 和 :example:peripherals/sdio/slave 演示了如何使用主机与 ESP SDIO 从机进行通信。.. include-build-file:: inc/sdio_slave_types.inc .. include-build-file:: inc/sdio_slave.inc