RT-Thread SDIO/MMC 设备模型（DM）：基于 Device Model 的宿主控制器驱动框架详解

• 操作系统
• 嵌入式
• 物联网
• 嵌入式OS
• RTOS

RT-Thread 的 SDIO/MMC 设备模型（Device Model，简称 DM）是在传统 MMC/SD 核心层之上新增的一层驱动辅助框架，它让 MMC/SD 宿主控制器（Host Controller）的命名、设备树（OFW）解析、电源供给（vmmc/vqmmc）以及 SDHCI 平台驱动全部纳入统一的 DM 设备管理体系中。本文以components/drivers/sdio目录下的实际源码为准，讲解 DM 层的编译开关、核心 API（sdio_host_set_name、sdio_ofw_parse、sdio_regulator_*）与 SDHCI 平台接入方式，帮助读者理解如何基于 DM 快速编写可移植、可配置的 SD/MMC 宿主驱动。

一、MMC/SD Core 与 DM 层的分层关系

RT-Thread 的 SDIO 驱动体系分为两个层次：

• MMC/SD 核心层：由dev_mmcsd_core.c、dev_sd.c、dev_sdio.c、dev_mmc.c、dev_block.c组成，只需要开启RT_USING_SDIO即可参与编译，它实现了 SD/MMC/eMMC 协议栈与块设备接入。
• DM 辅助层：由dev_sdio_dm.c（以及dev_sdhci*.c、dev_regulator.c）组成，只有在开启RT_USING_DM后才会被构建系统加入。

这一编译依赖关系可以直接在 components/drivers/sdio/SConscript 中看到：当RT_USING_SDIO未开启时整个目录直接跳过；开启后默认编译核心源文件；当GetDepend(['RT_USING_DM'])为真时追加dev_sdio_dm.c；若同时开启RT_USING_SDHCI则继续追加dev_sdhci.c、dev_sdhci_dm.c、dev_sdhci_host.c；若同时开启RT_USING_REGULATOR则再追加dev_regulator.c。

各特性的 Kconfig 开关与对应源码可汇总如下表：

注意：host/Kconfig中可见RT_SDIO_DW_MMC（Synopsys DesignWare MMC）还额外依赖RT_USING_PINCTRL、RT_USING_RESET、RT_USING_REGULATOR并自动选中RT_USING_DEVICE_IPC与RT_USING_SYSTEM_WORKQUEUE；RT_SDIO_SDHCI_DWCMSHC（Synopsys DWC MSHC SDHCI）则依赖RT_USING_OFW并自动选中RT_USING_SDHCI。

不使用 DM 时的替代方案：若RT_USING_DM未开启，框架不会编译任何dev_sdhci_*或sdio_regulator_*源码，此时需要自行实现struct rt_mmcsd_host_ops并直接对接 SDIO 设备模型文档 描述的接口，所有解析、命名、供电逻辑均由驱动自行处理。

二、Host 命名：sdio_host_set_name

sdio_host_set_name(host, out_devname)是 DM 层提供的稳定 Host 命名接口，实现位于 dev_sdio_dm.c。其核心行为是为host->name填充一个稳定的sd%u格式字符串，命名策略分两级：

1. OFW 别名优先：当RT_USING_OFW开启且host->ofw_node已设置时，先调用rt_ofw_get_alias_id(host->ofw_node, "mmc")，尝试取设备树aliases { mmc0 = &...; }中定义的别名序号，使 Host 名与板级连线保持一致。
2. 原子自增兜底：若别名解析失败（返回负值），则通过rt_atomic_add(&uid, 1)分配一个单调递增的数字 id。为防止纯软件 Host 与已占用别名序号冲突，首次分配时以rt_ofw_get_alias_last_id("mmc")为种子（uid_min = 别名最大索引 + 1）。

可选的out_devname参数会收到相同字符串的副本（长度受RT_NAME_MAX限制），方便驱动在 probe 阶段同时保存一份设备名。

实际调用示例

#include "dev_sdio_dm.h" int rt_sdio_host_probe(struct rt_platform_device *pdev) { struct rt_mmcsd_host *host; host = rt_mmcsd_alloc_host(&pdev->parent); if (!host) return -RT_ENOMEM; /* 尽早命名，确保后续枚举时设备名稳定 */ sdio_host_set_name(host, RT_NULL); /* 填充 host->ops 等字段后注册到核心层 ... */ }

从源码结构看，该函数被设计为在宿主控制器的probe阶段调用，而不是在首次数据传输时才命名，以保证上层块设备名（如sd0、sd1）从一开始就是确定的。

三、Open Firmware 解析：sdio_ofw_parse

当RT_USING_OFW开启时，sdio_ofw_parse(dev_np, host)负责把设备树节点dev_np中的通用 MMC 控制器属性解析进struct rt_mmcsd_host。完整实现见 dev_sdio_dm.c，可解析属性与对应行为如下表：

此外，sdio_ofw_parse还有两个固定副作用：

• 若host->ofw_node尚未赋值，则补设为dev_np（源码中即host->ofw_node ? : dev_np）；
• 无条件在host->flags中强制置位MMCSD_MUTBLKWRITE（多块写支持）。

当RT_USING_OFW未开启时，dev_sdio_dm.h中提供了rt_inline的桩实现：sdio_ofw_parse直接返回RT_EOK，不做任何解析。

解析时机：必须在枚举开始前

官方文档强调：调用sdio_ofw_parse应当在填充struct rt_mmcsd_host的过程中、核心层开始枚举（card enumeration）之前完成。理由很直接——如果bus-width非法，函数会返回-RT_EIO，此时应把错误处理放在宿主驱动自己的probe函数中返回，而不是拖到第一次事务时才报错。推荐的 DTS 节点示例：

mmc0: mmc@10000000 { compatible = "vendor,sdhci"; reg = <0x10000000 0x1000>; interrupts = <0x2a>; bus-width = <4>; max-frequency = <50000000>; non-removable; cap-sd-highspeed; };

四、电源供给钩子：sdio_regulator_*（DM + Regulator）

dev_regulator.c仅在RT_USING_DM与RT_USING_REGULATOR同时开启时编译（Regulator 框架本身也依赖 DM）。它围绕vmmc（主电源）与vqmmc（信号电平电源）两个供给展开，相关 API 声明见 dev_sdio_dm.h：

实现细节上，ocrbitnum_to_vdd把 OCR 位号换算成电压：位对应 1.65–1.95V 区间时取 1650–1950mV；其余按1900mV + (vdd_bit - ilog2(VDD_165_195)) * 100mV逐档递增。sdio_regulator_set_vqmmc的 3.3V 分支还会结合host->io_cfg.vdd计算允许的电压区间（下限不低于 2.7V、上限不高于 3.6V），并先尝试区间设置、失败后再尝试直接设置目标电压——这是为了兼容仅声明 1.8V 的 GPIO regulator。完整电源语义可进一步参考 SDIO Regulator 文档 与 Regulator 文档。

五、SDHCI 平台驱动：dev_sdhci_dm.c（DM 专属）

RT_USING_SDHCI只在 DM 模式下有仓内实现。平台驱动直接使用 dev_sdhci_dm.c 提供的一组便捷接口完成标准 SDHCI 宿主接入，接口声明见 dev_sdhci_dm.h：

rt_sdhci_get_property解析的属性与效果：

典型的 DM SDHCI 平台驱动 probe 可以这样写：

#include "dev_sdhci_dm.h" static const struct rt_sdhci_pltfm_data my_pdata = { .quirks = RT_SDHCI_QUIRK_BROKEN_CARD_DETECTION, .quirks2 = 0, }; static int my_sdhci_probe(struct rt_platform_device *pdev) { return rt_sdhci_pltfm_init_and_add_host(pdev, &my_pdata, sizeof(struct my_priv)); }

SDHCI 栈的完整实现与寄存器级细节参见 SDHCI 文档。针对具体 SoC，sdio/host/目录还提供了sdhci-dwcmshc（Synopsys DWC MSHC）与sdio-dw（DesignWare MMC）等现成宿主实现，以及 PCI 总线上挂接 SDHCI/DW MMC 的sdhci-pci.c、sdio-dw-pci.c。

六、BSP 驱动接入实战建议

综合官方文档 dm.md 与源码，编写 DM 模式下的宿主驱动时建议遵循以下要点：

1. 解析先于卡片活动：在填充struct rt_mmcsd_host的过程中调用sdio_ofw_parse，且必须在核心层开始枚举之前；对非法bus-width返回的-RT_EIO要在probe中处理，不要拖到首次事务。
2. 优先使用稳定的 Host 名：在 DTS 中声明aliases { mmc0 = &...; }，让sdio_host_set_name的命名与板级连线、用户态脚本保持一致；纯软件 Host 仍依赖rt_ofw_get_alias_last_id("mmc")避免与已占用的别名序号冲突。
3. 电源供给按需声明：vmmc/vqmmc依赖 DM + Regulator，二者缺一不可；DTS 中通过vmmc-supply、vqmmc-supply指向对应的 regulator 节点。
4. SDHCI 只走 DM：RT_USING_SDHCI仅在 DM 下实现，平台驱动应使用dev_sdhci_dm.c的rt_sdhci_pltfm_init、rt_dm_dev_iomap、rt_dm_dev_get_irq、rt_sdhci_get_property组合，而不是自行编写寄存器初始化。

七、关联文档与深入阅读

• DM 层源码与头文件：components/drivers/sdio/dev_sdio_dm.c、components/drivers/sdio/dev_sdio_dm.h
• 构建依赖：components/drivers/sdio/SConscript
• SDHCI DM 平台层：components/drivers/sdio/dev_sdhci_dm.c、components/drivers/sdio/dev_sdhci_dm.h
• Regulator 钩子：components/drivers/sdio/dev_regulator.c
• SoC 宿主 Kconfig：components/drivers/sdio/host/Kconfig
• 协议栈入口：SDIO 设备模型文档、SDHCI 文档、SDIO Regulator 文档
• 基础机制：总线/驱动绑定文档、OFW 运行时 API 文档

• 操作系统
• 嵌入式
• 物联网
• 嵌入式OS
• RTOS