ESP-IDF SD 总线与 SDIO 上拉需求详解管脚兼容性、冲突排查与解决方案【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf导读本文档源自 ESP-IDF 官方 API 参考中关于SD 上拉需求SD Pull-up Requirements的说明是使用 SPI 或 SDMMC 控制器驱动 SD 卡 / SDIO 设备时的必读资料。乐鑫硬件产品面向多种应用场景设计不同场景对管脚上拉状态的要求各不相同因此某些产品需要调整特定管脚的上拉状态以满足 SD 总线对上拉电阻的需求。阅读本文后你将能够理解 SD 总线为何需要 10 kΩ 上拉、掌握 ESP32 / ESP32-S3 等产品管脚默认上拉状态与 SD 总线需求之间的兼容性差异、针对无上拉DAT2 与 strapping 冲突GPIO13 上拉冲突GPIO2 下载模式失效等典型问题给出正确的硬件接线或固件配置方案并了解 eFuse 烧录这一不可逆操作的正确姿势。SD 总线上拉需求与适用场景当{IDF_TARGET_NAME}使用SPI 控制器或SDMMC 控制器与 SD 卡通信时必须满足 SD 卡的上拉需求。核心规则如下当 SD 卡工作在SPI 模式或1 位 SD 模式时SD 总线的CMD和DATADAT0 - DAT3线必须通过10 kΩ 电阻上拉SD 卡和 SDIO 设备同样应在上述所有管脚上配置上拉电阻——无论这些管脚是否连接到主机以防止设备进入错误状态。这一要求的原因在于SD 卡的 CMD / DATA 线在默认状态下需要保持确定的高电平若总线上拉缺失浮空或误触发的电平可能导致卡无法被正确初始化、枚举或进入异常状态。另外对于 ESP32默认情况下MTDI strapping 管脚GPIO12与 DAT2 线的上拉不兼容当 flash 电压为 3.3 V 时详见下文 MTDI Strapping 管脚 一节。兼容性概述本节概述使用 SDIOSecure Digital Input Output时可能出现的兼容性问题。由于 SD 总线需要连接上拉电阻这些问题无论与主机host还是从机slave相关都应妥善解决每个问题都对应一节解决方案且主机与从机的解决方案可能不同。片上系统SoCsESP32除 D2WD 版本外无上拉电阻带有 3.3 V flash 芯片的型号存在 DAT2 与 strapping 冲突ESP32-D2WD无上拉电阻GPIO12 无上拉支持 GPIO 矩阵的 SoCs如 ESP32-S3SDMMC 主机控制器允许 SD 接口信号使用任意 GPIO但建议避免使用 strapping GPIO、带内部弱下拉的 GPIO 以及常用于其他用途的 GPIO以防出现冲突。以 ESP32-S3 为例应避免的 GPIO 包括GPIO原因GPIO0strapping 管脚GPIO45、GPIO46strapping 管脚内部弱下拉GPIO26 - GPIO32通常用于 SPI flash 和 PSRAMGPIO33 - GPIO37用于带有八线 SPI flash 或八线 PSRAM 的芯片和模组GPIO43、GPIO44默认用于 UART0 的 GPIOGPIO19、GPIO20默认用于 USB 的 GPIO系统级封装SIPESP32-PICO-D4无上拉电阻、DAT2 与 strapping 冲突模组模组系列兼容性问题ESP32-WROOM-32 系列ESP32-WROOM-32 / -D / -U、ESP32-SOLO-1无上拉电阻、DAT2 与 strapping 冲突ESP32-WROVER 系列ESP32-WROVER / WROVER-I无上拉电阻ESP32-WROVER-B 系列WROVER-B / WROVER-IB无上拉电阻、DAT2 与 strapping 冲突ESP32-WROVER-E 系列WROVER-E / WROVER-IE无上拉电阻、DAT2 与 strapping 冲突开发板ESP32 系列开发板开发板上拉情况与问题ESP32-PICO-KITv4.1 / v4.0 / v3无上拉电阻、DAT2 与 strapping 冲突、GPIO2 下载模式问题ESP32-DevKitCv4 / v2无上拉电阻、DAT2 与 strapping 冲突、GPIO2 下载模式问题ESP-WROVER-KIT已提供所需上拉电阻GPIO13 上拉冲突v4.1、v3、v2、v1DAT2 与 strapping 冲突v4.1、v2、v1GPIO2 下载模式问题v2、v1ESP32-LyraTD-MSC已提供所需上拉电阻DAT2 与 strapping 冲突ESP32-LyraT已提供所需上拉电阻GPIO13 上拉冲突可以通过检查板上搭载的模组来确定 ESP-WROVER-KIT 的版本v4.1 搭载 ESP32-WROVER-Bv3 搭载 ESP32-WROVERv1 和 v2 搭载 ESP32-WROOM-32。ESP32-S3 系列开发板开发板上拉情况ESP32-S3-DevKitC-1无上拉电阻ESP32-S3-USB-OTG可在 1 线 / 4 线 SD 模式或 SPI 模式下使用GPIO33 - 38 已提供所需上拉ESP32-S3-EYE仅限 1 线 SD 模式GPIO38 - 40 已提供所需上拉非乐鑫主机Non-Espressif Hosts若你使用非乐鑫的 SDIO 主机请务必确保该主机为所有 SD 总线信号提供了必要的上拉电阻。解决方案无上拉电阻No Pull-ups当使用没有上拉电阻的开发板时如果主机和从机设备位于不同的板子上可将其中一块替换为带上拉的板子乐鑫带开发板上拉列表见上文 开发板 小节或者外接上拉电阻将每个需要上拉的管脚通过10 kΩ 电阻连接到 VDD。GPIO13 上拉冲突Pull-up Conflicts on GPIO13如果设备从机的DAT3未被正确上拉可采用以下方案使用1 位 SD 模式并将设备的 DAT3 直接接到 VDD使用SPI 模式针对 GPIO13 管脚执行以下任一操作移除下拉电阻外接小于 5 kΩ 的上拉电阻建议 2 kΩ在 1 位 SD 模式下通过主机将其上拉或驱动为高电平或将 VDD 置为 3.3 V。DAT2 与 Strapping 的冲突Bootstrap vs SDIO on DAT2ESP32 的启动 strapping 要求与 SDIO 协议在 DAT2GPIO12即 MTDI上存在冲突细节见 MTDI Strapping 管脚 一节。可选解决方案如下方案一推荐烧录 flash 电压选择 eFuse该操作将内部稳压器的输出电压永久配置为 3.3 V此后 GPIO12 不再作为 strapping 管脚使用。完成烧录后为 GPIO12 外接一个上拉电阻即可。⚠️警告烧录 eFuse 是不可逆操作上文列出的模组兼容性列表可能已过时请在烧录前通过乐鑫官网确认待烧录模组确实搭载3.3 V flash 芯片。若将 3.3 V eFuse 烧录到 1.8 V flash 芯片的模组上模组将停止工作。确认需要烧录后进入 ESP-IDF 目录使用espefuse工具执行以下命令espefuse set-flash-voltage 3.3V该命令会烧录XPD_SDIO_TIEH、XPD_SDIO_FORCE和XPD_SDIO_REG三个 eFuse。当这三个 eFuse 全部被烧录为 1 后内部 VDD_SDIO flash 电压稳压器将被永久设置为 3.3 V。烧录成功时会看到类似以下日志espefuse v5.0.2 Connecting.... Run set-flash-voltage command Enable internal flash voltage regulator (VDD_SDIO) to 3.3V. The following eFuses are burned: XPD_SDIO_FORCE, XPD_SDIO_REG, XPD_SDIO_TIEH. VDD_SDIO setting complete. Check all blocks for burn... idx, BLOCK_NAME, Conclusion [00] BLOCK0 is not empty (written ): 0x0000000400182226000004320000a8b0002bc8f09e47e69800000000 (to write): 0x00000000000000000001c00000000000000000000000000000000000 (coding scheme NONE) . This is an irreversible operation! Type BURN (all capitals) to continue. BURN BURN BLOCK0 - OK (write block read block) Reading updated eFuses... Successful.查看 eFuse 状态可运行idf.py efuse-summary如果是从自动化烧录脚本中调用建议使用独立工具espefuse它支持--do-not-confirm选项可跳过确认步骤直接烧录。更多细节可参阅对应芯片的《技术参考手册》中 eFuse 相关章节。方案二使用 1 位 SD 模式或 SPI 模式时断开 DAT2 并确保其被拉高让主机的 DAT2悬空并将从机的 DAT2直接连接到 VDD对于从机设备可使用SDIO_SLAVE_FLAG_DAT2_DISABLED选项编译固件并重新烧录。该选项可避免从机在 DAT2 线上进行检测。注意启用该选项后标准 CCCRCard Common Control Register不再声明支持 4 位 SD 模式但主机对此并不知情因此必须在主机侧禁用 4 位模式的使用。在 ESP-IDF 源码中该选项定义于 components/esp_driver_sdio/include/driver/sdio_slave.h#define SDIO_SLAVE_FLAG_DAT2_DISABLED BIT(0) /** 按 SD 规范要求即使是在 1 位模式或 SPI 模式下 所有 4 条数据线也应当被使用并上拉。但作为一项特性用户可指定此标志 以在 1 位模式下复用 DAT2 管脚。注意主机无法通过读取 CCCR 得知我们 已不再支持 4 位模式请自行承担风险。 */同一个头文件中还定义了其他相关标志位sdio_slave.hSDIO_SLAVE_FLAG_HOST_INTR_DISABLEDBIT(1)SDIO 协议中 DAT1 用作中断线指定此标志可在 1 位模式下复用 DAT1 管脚此时主机必须通过轮询中断寄存器来获知从机中断SDIO_SLAVE_FLAG_INTERNAL_PULLUPBIT(2)为启用的管脚使能内部上拉。头文件明确注释内部上拉不足以保证稳定通信请务必在总线上外接上拉该标志仅用于示例和调试SDIO_SLAVE_FLAG_DEFAULT_SPEEDBIT(3)禁用硬件的高速模式支持默认SDIO_SLAVE_FLAG_HIGH_SPEED 0为启用高速支持主机能看到高速能力但实际使用的模式由主机决定。这些标志与本文档内部上拉并不可靠、优先使用外部电阻的结论完全一致。GPIO12 无上拉No Pull-up on GPIO12仅适用于 ESP32-D2WD该模组与 SDIO 协议兼容只需将 GPIO12 通过10 kΩ 电阻连接到 VDD 即可。GPIO2 下载模式失效Download Mode Not Working当 GPIO2 依据 SD 上拉需求被拉高时将无法进入下载模式——因为 GPIO2 是 strapping 管脚进入下载模式时它必须被拉低。可选方案对于需要跳线短接 GPIO0 与 GPIO2的板子装好跳线自动复位电路会在进入下载模式前将 GPIO2 与 GPIO0 一同拉低对于 GPIO2 上连接了其他元件如下拉电阻、LED的板子请查看开发板原理图中 GPIO2 的连接情况——LED在大多数情况下不会影响操作下拉电阻会干扰 DAT0 信号必须移除。若以上方案均无效请确认是主机还是从机设备的上拉影响了 GPIO2定位到这些上拉电阻并移除。其他相关信息MTDI Strapping 管脚与 VDD_SDIOMTDIGPIO12被用作 strapping 管脚用于选择为 flash 芯片供电的内部稳压器VDD_SDIO的输出电压。该管脚带有内部下拉若保持悬空启动时读为低电平将选择默认的 3.3 V 工作电压。各型号差异使用1.8 V flash的 ESP32 模组如 ESP32-WROVER 和 ESP32-WROVER-IGPIO12 上有上拉电阻使用3.3 V flash的 ESP32 模组GPIO12 上没有上拉电阻该管脚内部被轻微下拉。为 SD 卡操作给 GPIO12 添加上拉时需区分以下情形板子类型GPIO12 复位要求与 SD 卡操作的兼容性不使用内部稳压器VDD_SDIO给 flash 供电的板子可拉高兼容使用 1.8 V flash 芯片的板子复位时需拉高完全兼容使用内部稳压器 3.3 V flash 芯片的板子复位时必须拉低与 SD 卡操作不兼容见 兼容性概述内部上拉与 Strapping 要求始终优先使用外部电阻。不过乐鑫产品内部带有弱上拉 / 弱下拉电阻可被使能并替代外部电阻使用。请务必牢记该方案无法保证可靠的 SDIO 通信——在 ESP-IDF 的 SDIO 从机驱动头文件 components/esp_driver_sdio/include/driver/sdio_slave.h 中SDIO_SLAVE_FLAG_INTERNAL_PULLUP的注释也明确写道内部上拉不足以实现稳定通信请务必在总线上外接上拉电阻此选项仅供示例与调试使用。尽管如此这些内部上拉与 strapping 要求的信息仍具参考价值。乐鑫硬件产品在 CMD 和 DATA 管脚上连接了不同的弱上拉 / 弱下拉电阻下表展示了 CMD 和 DATA 管脚的默认上拉 / 下拉状态针对 ESP32表内缩写说明WPUSoC 内部的弱上拉WPDSoC 内部的弱下拉PU模组内部、SoC 外部的上拉GPIO 编号管脚名称启动状态Strapping 要求15CMDWPU-2DAT0WPD下载模式需为低4DAT1WPD-12DAT21.8 V flash 为 PU3.3 V flash 为 WPD1.8 V flash 需为高3.3 V flash 需为低13DAT3WPU-对于非 ESP32 芯片一般不建议将 strapping 管脚复用于 SDIOSD 与 strapping 的上拉 / 下拉需求可能相互冲突各芯片的 strapping 管脚列表请查阅对应数据手册。与 ESP-IDF 驱动实现的对应关系上拉需求不仅体现在硬件层面也体现在 ESP-IDF 的驱动 API 中开发者可以在软件侧配合使用新版 SDMMC 主机驱动中槽位初始化配置结构体sd_host_slot_sdmmc_init_cfg_t的slot_flags提供了internal_pullup位用于使能内部上拉components/esp_driver_sdmmc/include/driver/sd_host_sdmmc.hstruct { uint32_t internal_pullup: 1; /// 是否使能内部上拉 uint32_t wp_active_high: 1; /// WP 信号是否为高电平有效 } slot_flags;旧版legacy驱动同样支持该能力在 components/esp_driver_sdmmc/legacy/src/sdmmc_host.c 中SDMMC_SLOT_FLAG_INTERNAL_PULLUP会被转换为上述slot_flags.internal_pullup传入新驱动。需要注意的是正如本文档反复强调的软件使能内部弱上拉只是应急或调试手段量产与可靠性要求较高的场景应以外接 10 kΩ 上拉电阻为准。实践清单在实际项目中建议按以下顺序排查 SD / SDIO 上拉问题确认 SD 卡工作模式SPI / 1 位 / 4 位 SD并核对 CMD 与 DAT0 - DAT3 是否均通过 10 kΩ 电阻上拉到 VDD对照 兼容性概述 中对应芯片 / 模组 / 开发板的条目确认是否存在已知的无上拉strapping 冲突问题若为 ESP32 且涉及 GPIO12DAT2确认 flash 电压为 1.8 V 还是 3.3 V再决定是直接外接上拉、烧录 eFuse还是使用 1 位 / SPI 模式并借助SDIO_SLAVE_FLAG_DAT2_DISABLED规避若 GPIO2 用于 DAT0 且无法进入下载模式检查板载下拉电阻与跳线设置最后始终优先使用外部电阻将内部上拉SDIO_SLAVE_FLAG_INTERNAL_PULLUP/internal_pullup仅作为调试手段。本文对应的英文与中文官方文档位于 docs/en/api-reference/peripherals/sd_pullup_requirements.rst 与 docs/zh_CN/api-reference/peripherals/sd_pullup_requirements.rstSD 卡 / SDIO 相关的驱动源码与测试用例可进一步参考 components/esp_driver_sdmmc、components/esp_driver_sdio 以及 examples/storage 下的 SD 卡示例。【免费下载链接】esp-idfEspressif IoT Development Framework. Official development framework for Espressif SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-idf创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考