esp-idf/docs/zh_CN/api-reference/peripherals/sdio_slave.rst

SDIO 卡从机驱动程序
===========================

: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

- 1 位 SD 模式：连接 CLK、CMD、DAT0 和 DAT1 管脚并接地。
- 4 位 SD 模式：连接所有管脚并接地。
- SPI 模式：连接 SCLK、MOSI、MISO、中断、#CS 管脚并接地。

.. 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 从机驱动程序的相关术语如下：

- 传输 (transfer)：传输始终由主机发出的命令符启动，可能包含一个响应和多个数据块。{IDF_TARGET_NAME} SDIO 从机驱动程序的核心机制是通过传输进行数据交换和通信。
- 发送 (sending)：从从机到主机的传输。
- 接收 (receiving)：从主机到从机的传输。

.. note::

  在 **{IDF_TARGET_NAME} 技术参考手册** > **SDIO 从机控制器** [`PDF <{IDF_TARGET_TRM_CN_URL}#sdioslave>`__] 中，寄存器从主机的角度进行命名和定义。即，``RX`` 寄存器指的是发送寄存器，``TX`` 寄存器指的是接收寄存器。 我们在驱动程序中不再使用 ``TX`` 或 ``RX``，以避免产生歧义。

- FIFO：在 Function 1 内的特定地址，可以通过使用 CMD53 命令读写大量数据。该地址与在单个传输中请求从从机读取或写入的长度相关：**请求长度** = 0x1F800 – 地址。
- 所有权 (ownership)：拥有缓冲区的所有权时，驱动程序可以随机读写该缓冲区（通常通过 DMA 实现）。在所有权返回给应用程序前，应用程序不应读取/写入该缓冲区。如果应用程序从缓冲区中读取数据时，接收驱动程序拥有缓冲区的所有权，可能会读取到随机数据；如果应用程序向缓冲区写入数据时，发送驱动程序拥有缓冲区的所有权，发送的数据可能会损坏。
- 请求长度 (requested length)：一次传输中的请求长度，由 FIFO 地址确定。
- 传输长度 (transfer length)：一次传输中的请求长度，由 CMD53 字节/块计数字段确定。

.. note::

  请求长度不同于传输长度。在 {IDF_TARGET_NAME} SDIO DMA 中，操作基于 **请求长度** 而非 **传输长度**，即 DMA 控制器会根据 **请求长度** 处理数据传输，确保只传输 **请求长度** 范围内的数据。**传输长度** 必须等于或长于 **请求长度**，并将剩余部分在发送时填充为 0，或在接受时丢弃。

- 接收缓冲区大小 (receiving buffer size)：通信开始前，主机与从机间会预先定义缓冲区大小。初始化过程中，从机应用程序必须通过结构体 ``sdio_slave_config_t`` 中的 ``recv_buffer_size`` 设置缓冲区大小。
- 中断 (interrupts)：{IDF_TARGET_NAME} SDIO 从机支持两个方向的中断，即由主机到从机（以下称从机中断）以及由从机到主机（以下称主机中断）。更多详情，请参阅 :ref:`interrupts`。
- 寄存器 (registers)：通过 CMD52 或 CMD53 命令在 Function 1 中访问的特定地址。

与 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 节），简化版流程可参考 :ref:`esp_slave_init`。

此外，在通过 CMD52/CMD53 访问到 Function 1 这一机制的基础上，还存在一个仅适用于 {IDF_TARGET_NAME} 的上层通信协议。该特定通信协议中，主机和从机通过 CMD52/CMD53 命令进行数据交换和通信。更多详情，请参阅 :ref:`esp_slave_protocol_layer`。

组件 :doc:`/api-reference/protocols/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
^^^^^^^^^^^^^^

准备向从机发送数据包时，主机需要读取从机的缓冲区数据数量，判定从机是否准备好接收数据。

为了支持接收来自主机的数据，应用程序需按照以下步骤，将缓冲区加载到从机驱动程序中：

1. 调用 ``sdio_slave_recv_register_buf`` 注册缓冲区，并获取已注册缓冲区的句柄。驱动程序会为链接到硬件的链表描述符所需的缓冲区分配内存。这些缓冲区的大小应与接收缓冲区大小相等。
2. 将缓冲区句柄传递给 ``sdio_slave_recv_load_buf``，将缓冲区加载到驱动程序中。
3. 调用 ``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``。

4. 调用 ``sdio_recv_load_buf``，将经过处理的缓冲区句柄再次传递给驱动程序。

.. note::

  为减少复制数据的开销，驱动程序本身不具有任何内部缓冲区；应用程序有责任及时提供新的缓冲区，DMA 会自动将接收到的数据存储到缓冲区中。

发送 FIFO
^^^^^^^^^^^^

每当从机要发送数据时，它会触发一个中断，并由主机请求数据包长度。发送模式有两种：

- 数据流模式 (stream mode)：在此模式下，当缓冲区加载到驱动程序中时，无论之前的数据包是否已经发送，该缓冲区的长度会计入主机在传入通信中请求的数据包长度中。换句话说，即使之前还有未发送的数据包，新加载的缓冲区长度也会包括在主机请求的数据包长度中。这样，主机可以在一次传输中获取多个缓冲区的数据。
- 数据包模式 (packet mode)：在此模式下，数据包长度逐个更新，且仅在前一个数据包发送时更新。此时，主机在一次传输中只能获取一个缓冲区的数据。

.. note::

  为减少复制数据的开销，驱动程序本身没有内部缓冲区，DMA 直接从应用程序提供的缓冲区中获取数据。发送完成前，应用程序不应该访问缓冲区，以确保数据传输的正确性。

结构体 ``sdio_slave_config_t`` 中的 ``sending_mode`` 可以设置发送模式，``send_queue_size`` 可以设置缓冲区数量。缓冲区大小均限制在 4092 字节内。尽管在流模式下，一次传输可以发送多个缓冲区，但每个缓冲区在队列中仍然计为一个。

应用程序可以调用 ``sdio_slave_transmit`` 函数发送数据包。此时，函数在传输完成后返回，因此队列并未完全占用。若需要更高效率，应用程序可以改用以下函数：

1. 将缓冲区信息（地址、长度以及表示缓冲区的 ``arg`` 参数）传递给 ``sdio_slave_send_queue``。

   - 如果需要采用非阻塞调用，请设置 ``wait`` 为 0。
   - 如果 ``wait`` 并未设置为 ``portMAX_DELAY`` （等待直到缓冲区传输完成），应用程序应检查返回结果，确认数据是否已放入队列中，或是否已丢弃。

2. 调用 ``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`。


应用示例
-------------------

从机/主机通信的相关应用示例请参阅 :example:`peripherals/sdio`。

API 参考
-------------

.. include-build-file:: inc/sdio_slave_types.inc
.. include-build-file:: inc/sdio_slave.inc