0.1 编写目的与读者对象

本文要解决的是「一颗 eMMC 焊到板子上之后，从硬件上电、内核枚举、模式切换、 块设备挂载、一直到产线烧录与 OTA 的整条链路，怎么做才不会踩坑」。

很多团队在 eMMC 上的问题并不是「不会写驱动」，而是分散在多个环节的细节没有对齐： 硬件上电顺序没按规范做、EXT_CSD 没读全就切了 HS400、Cache 开着但掉电策略没配套、 U-Boot 与内核分区表不一致、产线第一次烧录用的工具跟量产工具不是同一个…… 这些坑每一个单独查资料都能解决，但串起来看才能真正省时间。

• 驱动开发者：需要理解 MMC 子系统的分层、控制器驱动怎么接、模式切换怎么调、设备树怎么写。
• BSP / 内核移植工程师：需要 config 清单、DTS 样例、U-Boot 配套、与启动链路的衔接。
• 硬件 / PCB 工程师：需要知道驱动行为对硬件的约束（电源时序、门控、复位、差分走线、测试点）。
• 产线与测试工程师：需要首件烧录 SOP、掉电测试方法、寿命与健康度采集手段。
• 存储产品经理：需要容量/分区规划依据、寿命指标口径、模式与性能的取舍关系。

0.2 术语与缩略语

下表把全文会反复出现的名词一次性讲清，后文不再解释。标星号的三条是最容易误解的。

三个最容易误解的点，先记住： ① eMMC 里的 NAND 不能像 SPI NAND 那样直接写，MTD / UBI 那套在 eMMC 上 完全用不上，内核只把它当块设备； ② eMMC 的硬件分区（Boot0/Boot1/RPMB）不算在标称容量里， 128 GB 的卡实际可用只有 128 GB 减去约 16 MB； ③ 切到 HS400 需要重新训练采样点，不是把频率调高就行。

0.3 内核版本与接口差异

MMC 子系统这几年的改动集中在「CQE 命令队列」与「缓存策略」两块，控制器驱动接口相对稳定。 下面按版本列出对本文内容有实际影响的差异点，避免用新内核的命令去查老内核的树。

0.4 硬件平台与参考器件

本文以「ARM64 主控 + 1 颗 eMMC + 独立 LDO 供电 + SDHCI 兼容控制器」为基准平台。 下表列出参考器件的规格区间，具体型号参数以对应料号正式 datasheet 为准。

第 1 章 · eMMC 器件与协议基础

在动手写驱动之前，先把「eMMC 到底是什么、它有哪些模式、上电后怎么活过来」讲清楚。 这一章的内容决定了后面所有代码的时序约束。

1.1 eMMC 是什么：NAND + FTL + Cache

从主机视角看，eMMC 就是一个能挂到 /dev 下的块设备；但从硬件视角看，它是 「NAND 阵列 + 内部控制器（FTL、ECC、缓存、调度）+ 主机接口」三层叠在一起的东西。 理解这三层的分工，才能明白哪些行为是主机能控制的、哪些只能「请求并等待」。

这张图解释了三个常见现象的成因：

• 为什么 eMMC 不能像 SPI NAND 那样做「整片擦除」——FTL 在中间，主机看到的是 LBA， blkdiscard 只能「告知」器件某段逻辑块可回收，不能强制释放物理块。
• 为什么 eMMC 的坏块不用主机管——坏块管理在 FTL 里，主机只会在 EXT_CSD[230]（Pre-EOL Info）看到寿命状态。
• 为什么「写完立刻断电」会丢数据——数据可能还在器件 Cache 里没落 NAND， 需要主机显式发 Cache Flush（见 10.3 节）。

1.2 卡上存储区布局：Boot / RPMB / 用户区

eMMC 内部把存储划成若干硬件分区，各分区大小在出厂时由器件内部固件固化、 不可通过 EXT_CSD 改写（只有「是否使能」可配）。理解这一点，才能解释分区表里那些「凭空多出来」的设备节点。

dd if=/dev/zero of=/dev/mmcblk0 bs=1M        # 清空用户区所有分区，设备变砖
dd if=/dev/zero of=/dev/mmcblk0boot0     # 覆盖 Bootloader，板子变砖且不进系统
sgdisk --zap-all /dev/mmcblk0            # 抹掉分区表，同样不可逆

1.3 速度模式谱系：从 HS 到 HS400EX

eMMC 的「速度模式」是一组时序参数（频率 + 数据线数 + 采样方式 + 电压）的组合。 每种模式都对应 datasheet 里一张时序表和一组 EXT_CSD 位。搞混模式和频率的关系， 是「切了模式但没提速」的根因。

1.4 命令集与 R1 / R1b 响应

主机与卡之间的所有交互都通过「命令索引 + 参数 + CRC」构成的一条命令完成。 驱动代码里看到的 struct mmc_command 就是这个结构。 工程上必须记住的差别只有两点：响应类型与是否带数据。

1.5 EXT_CSD 关键字段速览

EXT_CSD 是 512 字节的扩展寄存器区，通过 CMD6 的读参数模式读出。 Linux 里对应 struct mmc_ext_csd，由 mmc_read_ext_csd() 填充。 驱动开发者最常打交道的字段如下。

C_SIZE_EXT = ((EXT_CSD[183:185] & 0x00FFFF) << 8) | EXT_CSD[185]   /* [185:186] 共 22 bit */
容量 = (C_SIZE_EXT + 1) * 512B * 256 * (C_SIZE_MULT_EXT)
/*   C_SIZE_MULT_EXT = (EXT_CSD[223:222] & 0x03) | (EXT_CSD[221] & 0xC0) >> 6
   ERASE_GRP_DEF 决定这个 256/512 是写还是擦除单位，仅在超大容量时影响结果 */

1.6 上电时序与初始化状态机

eMMC 有自己的内部状态机。上电后卡处于 Pre-Idle 附近， 必须由主机发 CMD1 完成电压协商与初始化，才能进入 Stand-by 接受 CMD2 / CMD3。 驱动代码里 mmc_send_init_ocr() 就是这个循环。

第 2 章 · 硬件设计规范（驱动视角）

本章只讲与驱动行为直接相关的硬件约束。 完整的电路方案、PCB 叠层、回流路径、焊接与生产细节见《eMCP 电路设计指南》， 本章的作用是解释「为什么硬件必须这样设计，否则驱动会怎么坏」。

2.1 引脚定义与连接框图

eMMC 的 153 个焊球里真正需要主控连接的只有 30 来个，其余是电源、地和保留球。 驱动开发者需要清楚每一根信号线的电气角色，因为信号完整性问题最终会以 -ETIMEDOUT 或 CRC 错误的形式暴露在 dmesg 里。

2.2 电源域与上电时序

eMMC 有三路电源，时序关系被 datasheet 明确规定。时序不满足的典型表现是 「冷启动偶尔不识别，热重启正常」——因为热重启时电源已经稳定，反而绕过了问题。

2.3 VDD 门控与低功耗设计

eMMC 待机电流（mA 级）远高于主控的微安级，对电池供电的设备是可观的负担。 主流做法是用主控 GPIO 或 PMIC 的负载开关控制 VCC：不用时彻底断电， 用到时重新上电并重新枚举。这一节讲门控电路与软件配合的完整要求。

2.4 时钟与复位

时钟与复位是最容易被忽略但最影响稳定性的两根线。Linux 侧的表现是 「mmc0: Timeout waiting for hardware interrupt 偶发出现」。

2.5 信号完整性与 HS400 差分

HS400 是双数据线 DDR、200 MHz，等效每周期传 2 bit × 200 MHz × 8 根线。 这个速率下布线规则不是「能连通就行」，而是必须满足严格的等长与阻抗要求。 驱动侧能做的补救非常有限——训练只能纠正采样点，不能修正过大的 skew。

2.6 必留测试点

eMMC 的问题几乎都需要波形才能定位到底。这些测试点不是为了调试方便， 而是量产阶段判断板子好坏、区分「芯片不良」与「板子不良」的唯一手段。

2.7 BOM 选型与分区容量约束

选型阶段的很多决定会锁死后面的软件方案。软件能补救的越来越少， 所以这一节要把「哪些选型决定不可逆」讲清楚。

第 2 章自检

• VCCQ 电平与 SoC IO 域已逐路核对（万用表实测，不是看 datasheet）
• RST_n 有确定的上电默认电平，且 DT 里有 reset-delay-ms
• CMD 上拉已确认；HS400 的 DAT 已按 2 组 4 根差分对布线，CLK 与 DAT 长度差 2 mm 以内
• VCC 纹波实测峰峰值满足判据；上电斜率单调
• 若用 VDD 门控：断电前 Flush 路径已实现，唤醒延时 300 ms 已落实
• CMD / CLK / DAT / RST_n 均有就近测试点；VCC 纹波测试点已留
• 料号已锁定，EXT_CSD 差异与训练块格式已记录到第 16 章适配表

第 3 章 · Linux MMC 子系统架构

MMC 子系统是内核里结构最规整的子系统之一：核心层（core）稳定且几乎不用改， 所有适配工作都落在 host/ 目录下的控制器驱动里。 先把这层结构看明白，才知道要改哪个文件。

3.1 整体分层总览

3.2 源码目录与文件职责

内核 drivers/mmc/ 的实际目录结构如下。定位问题时先确定问题在哪一层， 能省掉大量无效的搜索。

drivers/mmc/
├── core/                       # 协议栈：与具体控制器无关
│   ├── core.c                  # MMC 设备模型、总线、电源管理、init/ocr
│   ├── mmc_card.c              # 整卡初始化、Cache 管理、ext_csd 解析
│   ├── mmc_ops.c               # 命令构造：erase / sanitize / hp / ext_csd
│   ├── mmc_ext_csd.c           # 模式切换、电压切换、卡状态位定义
│   ├── mmc_ioctl.c             # ioctl 转命令
│   ├── debugfs.c               # /sys/kernel/debug/mmc0 全部节点
│   ├── mmc-bus.c               # 虚拟 MMC 总线（给 SDIO 用）
│   ├── sd.c / sd_io.c          # SD 协议（本项目一般不用）
│   ├── block.c / block/*       # bus 无关的块设备辅助
│   └── of.c                    # 设备树解析：mmc_of_parse()
├── block/
│   ├── mmcblk.c                # /dev/mmcblk0 的实现
│   └── mmc_ioctl.c             # ioctl 实现
├── host/                       # 控制器驱动：所有适配工作在这里
│   ├── sdhci.c                 # SDHCI 通用框架
│   ├── sdhci-pci.c             # PCIe 枚举的 SDHCI
│   ├── sdhci-pltfrm.c          # platform 总线包装（含 DT 解析）
│   ├── sdhci-of-dwcmsh.c       # Synopsys DesignWare 核心（Rockchip/ZynqMP/紫光等）
│   ├── sdhci-of-arasan.c       # Arasan 系列 IP
│   ├── mmc_dw.c / mmc_dw_mmc.c # Synopsys DesignWare 核心（旧路径）
│   ├── mmc-sunxi.c             # 全志
│   ├── mtk-sd.c                # 联发科
│   ├── sdhci-msm.c             # 高通
│   ├── sdhci-sprd.c            # 展锐
│   ├── sdhci-tec.c / -nxp.c    # T-Engine / NXP
│   ├── uniphier-sd.c           # 松下
│   ├── cavium-mmc.c            # Marvell
│   ├── meson-gx-mmc.c          # Amlogic
│   ├── samsung-sdhci.c         # 三星 Exynos
│   ├── au1xmmc.c               # MIPS
│   └── mmc-slot-gpio.c         # 卡检测与写保护 GPIO（通用）

各个 common.h（如 drivers/mmc/host/sdhci.h、 drivers/mmc/host/mmc-sdhci-core.h）里定义了控制器寄存器与 quirks， 排查「为什么这个平台的 SDHCI 行为不一样」时，第一个要看的就是它对 quirks 加了什么。

3.3 关键数据结构

MMC 子系统的核心是三个结构体：mmc_host（控制器）、 mmc_card（卡）、mmc_ext_csd（扩展寄存器）。 驱动代码里出现的绝大多数问题都能归结为「这三个结构体的某个字段填错了」。

3.4 mmc_request 与命令流

struct mmc_request 是驱动与 core 之间的「工单」： core 填好命令、参数、数据缓冲，调用 host->ops->request()， host 把它翻译成寄存器操作，命令完成后回调 req->complete 通知 core。

struct mmc_request {
    struct mmc_card *card;          /* 关联的卡，驱动据此选 RCA 与时序 */
    struct mmc_host *host;
    struct mmc_command cmd;         /* 命令：opcode / arg / flags / resp */
    struct mmc_data  *data;         /* 数据：buf / blocks / blksz / dma */
    struct mmc_req_cookie *cookie;  /* CQE 时代的 cookie */
    struct mmc_req_complete complete;/* 完成回调（core 提供） */
    int (*error_check)(struct mmc_card *, struct mmc_request *);
};

struct mmc_command {
    u32 opcode;                     /* 命令索引，如 MMC_SEND_EXT_CSD */
    u32 arg;                        /* 32 位参数 */
    unsigned int flags;             /* MMC_RSP_PRESENT / MMC_RSP_R1B / ... */
    unsigned int *resp;             /* 响应数组（指向 host->resp） */
    unsigned int resp_len;          /* 1 / 2 / 4 / 6 个 word */
    void *data;                     /* 单块数据指针 */
    unsigned int datalen;           /* 单块数据长度 */
};

struct mmc_data {
    unsigned int blksz;             /* 块大小（字节），eMMC 常为 512 */
    unsigned int blocks;            /* 块数 */
    unsigned int flags;             /* MMC_DATA_PRELATCH / MMC_DATA_WRITE */
    void *buf;                      /* 数据缓冲 */
    unsigned int timeout_ns;        /* 数据超时（纳秒）*/
    unsigned int xfer_len;          /* 总传输长度 */
    dma_addr_t dma_addr;            /* DMA 地址（若用 DMA）*/
    unsigned int sg_len;            /* sg 表长度 */
    struct scatterlist *sg;         /* sg 表（多段传输）*/
};

3.5 probe 执行流程

从 module_init() 到 /dev/mmcblk0 出现，完整链路如下。 理解这条链路，才能判断「设备节点没出来」时该查哪一步。

3.6 mmcblk 块设备层

mmcblk 把「协议栈的一次 ADTC 命令」抽象成「一次块设备 bio」。 它的设计是直通式的：mmcblk_submit_bio() 直接调 mmc_blk_data_cmd() 发命令，没有额外的中间层。因此 eMMC 的性能特征基本等于器件特征， 这也是为什么「eMMC 随机写慢」这件事在软件层几乎无法优化。

3.7 队列、中断与 DMA

eMMC 走的是「中断 + DMA」路径。理解这条路径对定位「偶发卡死」「高负载丢数据」很关键。

3.8 编码规范与 remove 路径

eMMC 控制器的 remove 路径比多数块设备复杂：要先停队列、flush 块设备、 移除 pwrseq、释放 GPIO 与 regulator，顺序错了就会在 suspend 或模块卸载时 panic。

static int xxx_mmc_remove(struct platform_device *pdev)
{
    struct device *dev = &pdev->dev;
    struct mmc_host *mmc = dev_get_drvdata(dev);
    struct xxx_host *host = mmc_get_drvdata(mmc);

    /* 1. 先关卡：停止新的请求，等待 in-flight 完成 */
    mmc_remove_host(mmc);

    /* 2. 再拆块设备：flush 掉所有脏数据并注销 /dev/mmcblkN */
    mmc_blk_remove(mmc);
    mmc->card = NULL;

    /* 3. 关电源时序（若用了 pwrseq） */
    if (host->pwrseq)
        mmc_pwrseq_power_off(&host->pwrseq);

    /* 4. 释放资源：DMA 通道、中断、regulator、GPIO、寄存器映射 */
    dma_release_channel(host->dma);
    free_irq(host->irq, dev);
    if (host->vq)
        regulator_disable(host->vq);
    gpiod_put(host->reset_gpiod);
    devm_clk_put(dev, host->clocks[0]);

    /* 5. 最后销毁 mmc_host 本身 */
    mmc_free_host(mmc);
    dev_set_drvdata(dev, NULL);
    return 0;
}

/* 关键：remove 与 suspend 共用同一套「优雅下线」逻辑，不要重复写两份 */
static void xxx_mmc_shutdown(struct device *dev)
{
    struct mmc_host *mmc = dev_get_drvdata(dev);
    /* 无响应命令（例如在写卡时突然关电源）无法 abort，这里只能等超时 */
    if (mmc->card)
        mmc_shutdown(mmc);
}

第 4 章 · 控制器驱动：SDHCI 与厂商实现

绝大多数 SoC 的 eMMC 控制器都兼容 SDHCI 规范，Linux 用一套通用框架覆盖了它们。 本章先讲 SDHCI 通用部分，再按厂商拆解差异，最后给出「厂商私有补丁该怎么写」的范式。

4.1 SDHCI 寄存器组

SDHCI 寄存器按「能力寄存器 / 状态寄存器 / 寄存器组 / 时钟与复位 / 中断」五类划分。 驱动开发者需要记住的只有下面这十几个，其余可查 drivers/mmc/host/sdhci.h。

4.2 SDHCI 通用驱动家族

Linux 里 SDHCI 通用框架的入口是 sdhci.c，往上分三路总线：

mmc0: SDHCI controller [d4200000.mmc] at ... 200 MHz, 4-bit, ADMA
mmc0: new SDHC card at address 59b1c74d  [quirks=0x00008001: ...]

4.3 Rockchip dwcmsd

Rockchip 的 SDHCI 控制器在主线里是 sdhci-of-dwcmsh.c， 最需要注意的是它把 HS200 与 HS400 训练及 DSR（驱动强度、采样点）绑定在一起， 参数缺失会导致「能识别但切不到高速」。

4.4 Allwinner sunxi-mmc

全志平台的 mmc-sunxi.c 是自研控制器，不走 SDHCI 框架。 它有两个特别容易踩的点：相位配置与电源门控的时序要求。

4.5 联发科 MSDC

MTK 的 mtk-sd.c 是自研控制器，复杂度主要来自上电相位校准 与电压切换时序。它也是「驱动自己不发 CMD1，而是复用 SD 路径再切回 eMMC」的典型实现。

• CMD1 由谁发：MTK 驱动在 mtk_sd_probe_hw() 里 用 mmc_send_init_ocr() 发完成，才注册块设备；自定义 pwrseq 时要注意 不要重复发 CMD1。
• 相位校准：MSDC 在 HS200 与 HS400 前会跑一轮相位校准（msdc_calibrate_phase）， 耗时几十毫秒；若校准失败会降档，日志里会打印校准结果。
• 电压切换：MTK 需要配合相应的 DT 属性；eMMC 场景关注的是 mmc-hs200-postpone-clk 与 VCCQ 电压确认。

4.6 高通 sdhci-msm

高通平台的 SDHCI 增强版。实际项目中要关注两点：

• 电压缩放器（PMIC vdd-io）：eMMC 用 1.8 V IO 时需要 PMIC 支持 qcom,vdd-io-voltages 属性列出可切电压，驱动据此切 GPIO 控制 vreg； 配置不对会在 CMD11 时切电压失败。
• 总线时钟来源：部分 SoC 上 eMMC 总线时钟是独立的，需要在 sdhci-msm.c 里确认 clk_get 拿到的是哪一路。

4.7 NXP USDHC 与 i.MX USDHC

NXP 的 USDHC 支持 eMMC 4.5 及以上，实际项目常见两个坑：

• USDHC 的总线宽度属性名与通用 DT 不同； 8 bit 支持需要 SoC 引脚配置正确，否则 PRESENT_STATE 的 DAT 线数读出来是 4。
• HS400 支持的型号有限：并非所有 i.MX 型号都有 USDHC3 与增强选通； DT 里写 cap-hs400 也可能停在 HS200。查 SoC 手册确认增强选通引脚是否存在。

4.8 ZynqMP 与其它 SoC

ZynqMP 用 sdhci-of-dwcmsh.c，有个特殊点：SD 控制器与 eMMC 控制器 共用 zynqmp_sdhci_probe_hw() 的部分逻辑，改代码时要区分。 其余平台（紫光展锐、兆易创新、龙、全志、瑞芯微、晶晨等）多数已有主线支持， 少数仍需厂商 out-of-tree 驱动，此时先查 drivers/mmc/host/ 下 有没有同名文件（可能已经进主线了），再考虑移植 out-of-tree。

4.9 厂商私有补丁范式

当通用框架确实不够用（私有寄存器、私有时序、私有 quirk），需要在厂商驱动里加代码。 关键是把这些代码写成「可上游化」的形式，否则每次内核升级都要重打一遍。

/* 范式：所有平台私有逻辑用 quirk 位控制，主线逻辑保持通用 */
static const unsigned int xxx_mmc_of_quirks[] = {
    /* 该 SoC 的 SDHCI 需要在切 HS400 前额外写 DSN 延时，否则训练失败 */
    XXX_QUIRK_NEED_DSN_DELAY      | (3 << XXX_QUIRK_DSN_SHIFT),
    /* CMD6 busy 需要更长的超时时间 */
    XXX_QUIRK_LONG_SWITCH_TIMEOUT | (2000 << XXX_QUIRK_TMO_SHIFT),
    /* 硬件只在 3.3 V 下工作，不能切 1.8 V */
    XXX_QUIRK_NO_1V8_SWITCH       | 0,
};

static const struct mmc_of_quirk xxx_mmc_of_quirks[] = {
    { .compatible = "rockchip,rk3399-dwcmshc",
      .quirks = xxx_mmc_of_quirks },
    { /* 新的 SoC 复用同一套 quirks，加 compatible 即可，不要复制代码 */
      .compatible = "rockchip,rk3588-dwcmshc",
      .quirks = xxx_mmc_of_quirks },
    {}
};

/* 在 xxx_mmc_probe() 末尾按 quirk 生效，而不是在 DT 解析里硬编码 */
static void xxx_apply_quirks(struct mmc_host *mmc)
{
    struct device *dev = mmc->dev;
    int quirks = of_property_read_int(dev, "vendor,quirks", 0);

    if (quirks & XXX_QUIRK_NEED_DSN_DELAY)
        xxx_write_dsn_delay(mmc, (quirks >> XXX_QUIRK_DSN_SHIFT) & 0xff);
    if (quirks & XXX_QUIRK_LONG_SWITCH_TIMEOUT)
        mmc->max_switch_timeout = (quirks >> XXX_QUIRK_TMO_SHIFT) & 0xfff;
}

/* 写日志，方便现场定位「到底哪个 quirk 在起作用」 */
    dev_info(dev, "quirks=0x%08x: %s%s%s\n", quirks,
             (quirks & XXX_QUIRK_NEED_DSN_DELAY)     ? "NEED_DSN_DELAY "     : "",
             (quirks & XXX_QUIRK_LONG_SWITCH_TIMEOUT) ? "LONG_SWITCH_TIMEOUT " : "",
             (quirks & XXX_QUIRK_NO_1V8_SWITCH)       ? "NO_1V8_SWITCH "       : "");

第 4 章自检

• dmesg 已记录 quirks= 完整列表，陌生 quirk 位已查明含义
• 已核对 SDHCI_CAPABILITIES 与 DT 声明的交集，确认目标模式在此范围内
• 若用 out-of-tree 驱动：已确认主线 drivers/mmc/host/ 中没有替代实现
• 私有逻辑已全部收敛到 quirk 位，且每个 quirk 都有日志输出
• 已记录当前内核版本下该平台的 quirks 基线，升级内核后回归对比