mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-02 03:00:34 +03:00
Merge branch 'sdio-example-4bit-bringup' into 'master'
example(sdio_slave): add docs and examples for SI testing See merge request espressif/esp-idf!49371
This commit is contained in:
Michael (XIAO Xufeng)
@@ -153,7 +153,7 @@ The host should initialize the {IDF_TARGET_NAME} SDIO slave according to the sta
|
||||
|
||||
Furthermore, there is an {IDF_TARGET_NAME}-specific upper-level communication protocol built upon the foundation of CMD52/CMD53 to Function 1. Within this particular communication protocol, the master and slave engage in data exchange and communication through the utilization of CMD52/CMD53 commands. For more detailed information, please consult the `ESP SDIO Slave Protocol <https://espressif.github.io/idf-extra-components/latest/esp_serial_slave_link/sdio_slave_protocol.html#esp-sdio-slave-protocol>`_ section.
|
||||
|
||||
There is also a component `ESSL <https://components.espressif.com/components/espressif/esp_serial_slave_link>`_ designed for {IDF_TARGET_NAME} master to communicate with {IDF_TARGET_NAME} SDIO slave. See example :example:`peripherals/sdio` when programming your host.
|
||||
There is also a component `ESSL <https://components.espressif.com/components/espressif/esp_serial_slave_link>`_ designed for {IDF_TARGET_NAME} master to communicate with {IDF_TARGET_NAME} SDIO slave. See example :example:`peripherals/sdio/basic` when programming your host.
|
||||
|
||||
|
||||
.. _interrupts:
|
||||
@@ -274,7 +274,7 @@ There are several ways to use the ``arg`` in the queue parameter:
|
||||
sdio_slave_send_get_finished((void**)&handle, portMAX_DELAY);
|
||||
sdio_slave_recv_load_buf(handle);
|
||||
|
||||
For more about this, see :example:`peripherals/sdio`.
|
||||
For more about this, see :example:`peripherals/sdio/basic`.
|
||||
|
||||
Reset SDIO
|
||||
^^^^^^^^^^^^
|
||||
@@ -287,10 +287,45 @@ If there is a usage scenario where the ESP chip remains powered on but the HOST
|
||||
|
||||
Reset the SDIO hardware. The interrupt enable status and shared register values will be lost. You may need to call ``sdio_slave_set_host_intena`` and ``sdio_slave_write_reg`` to set them.
|
||||
|
||||
Signal Quality Checks
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
For SDIO slave links, command-only initialization can succeed even when one or more data lines are disconnected or have poor signal quality. In the ESP-IDF host stack, SDIO card discovery and configuration use ``CMD0``, ``CMD5``, and ``CMD52`` transactions on the command line. For example, the :example:`peripherals/sdio/hw_test` host can complete ``sdmmc_card_init()`` and its ``enable_slave_function()`` step before any payload transfer starts on ``DAT0-DAT3``.
|
||||
|
||||
The first payload transfer on ``DAT0`` appears when the host starts the first ``CMD53`` data transaction in 1-bit mode, so this example does contain a real 1-bit-only payload path when the user selects 1-line mode before initialization. ``DAT1-DAT3`` do not carry payload traffic until 4-bit mode has already been enabled and the first 4-bit ``CMD53`` transfer begins. Enabling 4-bit mode itself still uses command-line ``CMD52`` transactions, so 1-bit mode and 4-bit mode should be tested separately by choosing the bus width before initialization; the 4-bit flow does not first send payload in 1-bit mode.
|
||||
|
||||
When checking wiring, use the following checkpoints:
|
||||
|
||||
- If the link fails before command-only initialization completes, inspect ``CMD`` and ``CLK`` first.
|
||||
- If command-only initialization succeeds but 1-bit mode fails, inspect ``DAT0`` first.
|
||||
- If 1-bit mode works but 4-bit reads fail, inspect ``DAT1-DAT3``, pull-ups, and the return path between host and slave.
|
||||
|
||||
If the problem is caused by simultaneous switching noise (SSN), the symptoms usually look like this:
|
||||
|
||||
- 1-line mode works, while 4-line mode fails consistently or intermittently.
|
||||
- Communication fails when the boards are connected with jumper wires or other high-impedance ground paths, but improves after slightly changing the grounding or adding more ground connections, and disappears on a well-grounded setup.
|
||||
- Adjusting the data-line drive strength or adding small series resistors on the data lines reduces or removes the failure.
|
||||
- The host reports timeout or CRC errors.
|
||||
- Lowering the clock frequency has limited effect, and the issue can still appear even at 400 kHz.
|
||||
- The failure is easiest to reproduce when four data lines switch together, for example with the repeated ``FF 00`` payload used by :example:`peripherals/sdio/hw_test`.
|
||||
|
||||
To confirm this type of problem, use a logic analyzer or oscilloscope and probe as close to the slave pins as possible. The :example:`peripherals/sdio/hw_test` example is one convenient way to generate a repeatable pattern, but the same checks can also be done with any setup that can issue repeated 4-bit SDIO reads with payload that makes all four data lines switch at the same time.
|
||||
|
||||
- With a logic analyzer, capture ``CMD``, ``CLK``, and ``DAT0-DAT3``. A common symptom is data compression: some bits disappear because the slave interprets a clock glitch as an extra clock edge, so later data appears earlier than expected. With the ``hw_test`` example, the normal 4-bit read pattern is one low start bit on all four data lines, then a repeating sequence of two clocks high and two clocks low for eight cycles, followed by CRC. Missing data in this pattern indicates that the slave observed a false clock edge.
|
||||
- With an oscilloscope, observe the clock near the slave pins, especially after the data phase begins. If this issue is present, the later part of the clock waveform often becomes visibly worse. The effect can become smaller after improving grounding, adjusting drive strength, or adding small series resistors.
|
||||
- Correlate both captures. When data compression is visible on the logic analyzer, there should be a severe clock glitch shortly before the missing data point.
|
||||
|
||||
The typical fix is to improve the grounding between host and slave.
|
||||
|
||||
To reproduce this type of issue, let the host issue repeated 4-bit SDIO reads with payload that makes all four data lines switch together. The receive mode of :example:`peripherals/sdio/hw_test` is one such repeatable traffic source: its fixed ``FF 00`` frame makes all four data lines switch during every transfer.
|
||||
|
||||
One representative case happens during slave-to-host reads in 4-bit mode. When the host outputs a rising clock edge and the slave drives all four data lines from ``1`` to ``0`` at the same time, the slave ground can bounce upward. This can distort the observed clock at the slave, create a false extra edge, shorten the expected low-level width of the start bit or data bits, and finally cause a CRC error in the host driver. During practical debugging, changing the GPIO drive strength on the host or slave side may also change how severe the interference appears; :example:`peripherals/sdio/hw_test` lets the host adjust drive strength from the menu and the slave from macros.
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
- :example:`peripherals/sdio/host` and :example:`peripherals/sdio/slave` demonstrate how to use a host to communicate with an ESP SDIO slave device.
|
||||
- :example:`peripherals/sdio/basic/host` and :example:`peripherals/sdio/basic/slave` demonstrate how to use a host to communicate with an ESP SDIO slave device.
|
||||
- :example:`peripherals/sdio/hw_test/host` and :example:`peripherals/sdio/hw_test/slave` show how to turn the SDIO host/slave pair into a signal-integrity test setup.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
@@ -124,7 +124,7 @@ Alternatively, a pre-allocated DMA-capable buffer can be provided via the :cpp:m
|
||||
|
||||
.. only:: SOC_SDMMC_HOST_SUPPORTED and SOC_SDIO_SLAVE_SUPPORTED
|
||||
|
||||
There is a component `ESSL <https://components.espressif.com/components/espressif/esp_serial_slave_link>`_ (ESP Serial Slave Link) to use if you are communicating with an ESP32 SDIO slave. See example :example:`peripherals/sdio/host`.
|
||||
There is a component `ESSL <https://components.espressif.com/components/espressif/esp_serial_slave_link>`_ (ESP Serial Slave Link) to use if you are communicating with an ESP32 SDIO slave. See example :example:`peripherals/sdio/basic/host`.
|
||||
|
||||
Combo (Memory + IO) Cards
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -153,7 +153,7 @@ SDIO 从机驱动程序的相关术语如下：
|
||||
|
||||
此外，在通过 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` 中的示例。
|
||||
组件 `ESSL <https://components.espressif.com/components/espressif/esp_serial_slave_link>`_ 也支持 {IDF_TARGET_NAME} 主机与 {IDF_TARGET_NAME} SDIO 从机通信。在开发主机应用程序时，请参阅 :example:`peripherals/sdio/basic` 中的示例。
|
||||
|
||||
|
||||
.. _interrupts:
|
||||
@@ -274,7 +274,7 @@ SDIO 从机驱动程序的相关术语如下：
|
||||
sdio_slave_send_get_finished((void**)&handle, portMAX_DELAY);
|
||||
sdio_slave_recv_load_buf(handle);
|
||||
|
||||
更多详情，请参阅 :example:`peripherals/sdio`。
|
||||
更多详情，请参阅 :example:`peripherals/sdio/basic`。
|
||||
|
||||
重置 SDIO
|
||||
^^^^^^^^^^^^
|
||||
@@ -287,10 +287,45 @@ SDIO 从机驱动程序的相关术语如下：
|
||||
|
||||
重置 SDIO 硬件，中断使能状态和共享寄存器的值会丢失，可能需要调用 ``sdio_slave_set_host_intena``、 ``sdio_slave_write_reg`` 设置。
|
||||
|
||||
信号质量检查
|
||||
^^^^^^^^^^^^
|
||||
|
||||
对于 SDIO 从机链路，即使一条或多条数据线接错、未连接或者信号质量较差，仅依赖命令线的初始化过程仍然可能成功。在 ESP-IDF 的主机协议栈中，SDIO 卡识别和配置阶段主要使用 ``CMD0``、``CMD5`` 和 ``CMD52``，这些事务都走命令线。例如，:example:`peripherals/sdio/hw_test` 中的 host 端可以先完成 ``sdmmc_card_init()`` 和它自己的 ``enable_slave_function()`` 步骤，此时还没有在 ``DAT0-DAT3`` 上开始 payload 传输。
|
||||
|
||||
``DAT0`` 上第一次真正的 payload 传输，出现在 host 以 1 线模式发起第一笔 ``CMD53`` 数据事务时，因此这个 example 确实存在只用 ``DAT0`` 传 payload 的情况，但前提是用户在初始化前明确选择 1 线模式。``DAT1-DAT3`` 只有在已经切换到 4 线模式之后，第一笔 4 线 ``CMD53`` 事务开始时，才会真正承载 payload 数据。切换到 4 线模式本身仍然通过命令线上的 ``CMD52`` 完成，因此应分别测试 1 线模式和 4 线模式，在初始化前选择总线宽度，而不是先跑 1 线再在同一流程中切到 4 线；4 线流程本身不会先用 1 线传 payload。
|
||||
|
||||
排查接线时，可以先看以下几个检查点：
|
||||
|
||||
- 如果在仅依赖命令线的初始化完成之前就失败，优先检查 ``CMD`` 和 ``CLK``。
|
||||
- 如果仅依赖命令线的初始化成功，但 1 线模式失败，优先检查 ``DAT0``。
|
||||
- 如果 1 线模式正常而 4 线读失败，优先检查 ``DAT1-DAT3``、上拉以及 host 与 slave 之间的回流路径。
|
||||
|
||||
如果问题由 simultaneous switching noise (SSN) 引起，现象通常如下：
|
||||
|
||||
- 1 线模式正常，而 4 线模式稳定失败或者概率性失败。
|
||||
- 使用杜邦线等接地阻抗较高的连接方式时通信失败，微调接地或增加地线后问题缓解或消失；接地良好的系统中问题消失。
|
||||
- 调整数据线驱动强度，或者在数据线上串联小电阻后，问题缓解或消失。
|
||||
- host 侧报错常见为 timeout 或 CRC error。
|
||||
- 降低时钟频率影响有限，即使降低到 400 kHz 仍可能出现问题。
|
||||
- 当四条数据线同时切换时问题最容易复现，例如 :example:`peripherals/sdio/hw_test` 中重复的 ``FF 00`` payload。
|
||||
|
||||
要确认是否存在这类问题，建议使用逻辑分析仪或示波器，并尽量在靠近 slave 管脚的位置取样。:example:`peripherals/sdio/hw_test` 是一种方便的可复现流量来源，但并不必须依赖该示例；任何能够重复执行 4 线 SDIO 读操作、并且数据会在四条线上同时切换的系统，都可以用来完成相同检查。
|
||||
|
||||
- 使用逻辑分析仪时，抓取 ``CMD``、``CLK`` 和 ``DAT0-DAT3``。一个典型现象是数据长度被压缩：由于 slave 把时钟毛刺误认为额外时钟沿，某些位会丢失，后续数据提前出现。若使用 ``hw_test`` 示例，正常的 4 线读数据应当表现为四条数据线同时出现 1 位低电平起始位，之后是 2 个时钟高电平、2 个时钟低电平的循环，共 8 轮，最后跟 CRC。如果这段模式里出现数据缺失，就说明 slave 观察到了错误时钟边沿。
|
||||
- 使用示波器时，在靠近 slave 管脚的位置观察时钟，尤其是数据开始出现之后的后半段。如果问题存在，时钟波形在后段通常会明显变差。改善接地、调整驱动强度或者串联小电阻后，这种现象往往会减轻。
|
||||
- 把两种抓图结果交叉比对：如果逻辑分析仪看到数据被压缩，那么在数据缺失点之前，示波器上通常可以看到明显的时钟毛刺。
|
||||
|
||||
解决这类问题的典型方法，是改善 host 与 slave 之间的接地。
|
||||
|
||||
若要复现这类问题，应让 host 反复执行 4 线读，并使用会在四条数据线上同时切换的 payload。:example:`peripherals/sdio/hw_test` 的 receive 模式就是这样一种可重复流量来源，其固定的 ``FF 00`` 帧会在每个传输周期让四条数据线同时切换。
|
||||
|
||||
一个典型案例发生在 4 线模式的 slave-to-host 读操作中。当 host 输出时钟上升沿，同时 slave 让四条数据线从 ``1`` 同时切换到 ``0`` 时，slave 侧地电平可能被抬高。这会让 slave 看到的时钟波形发生下陷并产生伪额外边沿，导致起始位或者数据位的预期低电平宽度变短，最终让 host 驱动报告 CRC 错误。实际排查时，调整 host 或 slave 侧的 GPIO 驱动强度也可能改变干扰表现的严重程度；:example:`peripherals/sdio/hw_test` 允许 host 通过菜单、slave 通过宏来尝试不同驱动强度。
|
||||
|
||||
应用示例
|
||||
--------
|
||||
|
||||
- :example:`peripherals/sdio/host` 和 :example:`peripherals/sdio/slave` 演示了如何使用主机与 ESP SDIO 从机进行通信。
|
||||
- :example:`peripherals/sdio/basic/host` 和 :example:`peripherals/sdio/basic/slave` 演示了如何使用主机与 ESP SDIO 从机进行通信。
|
||||
- :example:`peripherals/sdio/hw_test/host` 和 :example:`peripherals/sdio/hw_test/slave` 展示了如何将 SDIO 主从示例改造成信号完整性测试组合。
|
||||
|
||||
API 参考
|
||||
-------------
|
||||
|
||||
@@ -124,7 +124,7 @@ SD/SDIO/MMC 驱动支持 SD 存储器、SDIO 卡和 eMMC 芯片。这是一个
|
||||
|
||||
.. only:: SOC_SDMMC_HOST_SUPPORTED and SOC_SDIO_SLAVE_SUPPORTED
|
||||
|
||||
如果需要与 ESP32 的 SDIO 从设备通信，请使用 `ESSL <https://components.espressif.com/components/espressif/esp_serial_slave_link>`_ 组件（ESP 串行从设备链接）。请参阅示例 :example:`peripherals/sdio/host`。
|
||||
如果需要与 ESP32 的 SDIO 从设备通信，请使用 `ESSL <https://components.espressif.com/components/espressif/esp_serial_slave_link>`_ 组件（ESP 串行从设备链接）。请参阅示例 :example:`peripherals/sdio/basic/host`。
|
||||
|
||||
复合卡（存储 + IO）
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Reference in New Issue
Block a user