0. 目的与范围

本规范约束 eMMC 器件在嵌入式固件中的主机侧软件行为：初始化状态机、EXT_CSD 配置、分区切换、 读写擦命令序列、Cache 与掉电保护、后台操作与健康管理。凡本文与器件 datasheet 冲突，以 datasheet 为准。

• 统一初始化路径：CMD0 → CMD1 → CMD2 → CMD3 → CMD7 → CMD8 固化为唯一标准流程，提速必须「先宽度、后时序、切完必验」。
• 统一配置入口：所有器件配置只走 CMD6 写 EXT_CSD，禁止裸写、禁止批量改字节。
• 统一 busy 判据：以 DAT0 释放 + CMD13 状态位为准，禁止用固定延时代替。
• 统一掉电语义：明确哪些操作是原子的、哪些必须 flush、哪些必须提前通知器件。
• 统一健康策略：寿命字段读什么、读到什么值做什么动作，形成可运维的闭环。

一句话结论：eMMC 是「把麻烦事都封进 BGA 里的 Managed NAND」—— 坏块、ECC、磨损均衡、映射表全部由器件内部完成，主机只面对 512 B 扇区的块设备接口。 代价是主机必须自己管好三件事：Cache 什么时候 flush、掉电前怎么通知器件、后台操作什么时候让器件做。 这三件事没做好，是 eMMC 项目里 90% 的丢数据与掉速事故的根因。

文档使用说明

• 本文是《eMMC 电路设计指南》的软件配套篇：硬件篇解决「怎么接、怎么供电、怎么走线」，本文解决「驱动怎么写、协议怎么等、错误怎么救」。
• 命令码、EXT_CSD 偏移、时序值取自 JESD84-B51。不同厂商、不同固件版本的器件在可选特性上存在差异，移植前必须逐条核对 datasheet。
• 文中 C 代码为协议骨架伪代码，演示命令序列与判断条件，非特定平台可直接编译的完整实现；mmc_send_cmd()、now_ms() 等为平台相关底层。
• EXT_CSD 偏移量统一写作 EXT_CSD[179] 形式，方括号内为字节偏移（0~511），不是 bit 位。

1 · 器件定位与系统架构

eMMC 不是一颗裸 NAND，而是「NAND 阵列 + 控制器 + FTL + MMC 接口」的完整子系统。 软件设计的第一件事，是认清主机到底能管什么、管不了什么——把器件内部的事当成自己的事，是新手最常见的过度设计。

1.1 器件定位与关键参数

参数取自 JESD84-B51 与主流器件 datasheet；具体数值（Cache 容量、Erase Group 大小、P/E 次数）以所用料号 datasheet 为准。

1.2 系统分层与器件内部架构

eMMC 对外只暴露一组 MMC 总线（CLK / CMD / DAT0~7 / DS / RST_n），且是点对点连接—— 一条总线上只能挂一颗 eMMC，不支持多设备并联（这与 SD 卡的多卡总线是本质区别）。

1.3 地址空间与访问粒度

eMMC 把复杂的 NAND 几何全部藏了起来，主机看到的是一个连续的 32 bit 扇区地址空间。 但有三种粒度在软件里迟早要碰到：

• Sector（512 B）：读写的最小单位，也是所有地址参数的单位（容量 > 2 GB 的器件）。读写必须 512 B 对齐。
• Erase Group：擦除粒度 = HC_ERASE_GRP_SIZE × 512 KB（本器件 = 1 → 512 KB）。CMD35/CMD36 的地址会被器件向下取整到 Erase Group 边界。
• Write Protect Group：写保护粒度 = HC_WP_GRP_SIZE × HC_ERASE_GRP_SIZE × 512 KB（本器件 = 16 × 512 KB = 8 MB）。写保护只能按它整块施加。

1.4 与 SD NAND / SPI NAND / SPI NOR 的关键差异（移植必读）

2 · 术语与缩写

本章统一术语口径。eMMC 的术语体系与 NAND 系（页/块/备用区）完全不同，混用会导致文档与代码对不上。

2.1 接口与协议术语

2.2 存储与分区术语

2.3 特性与机制术语

2.4 本文书写约定

• 命令写作 CMD13 形式（不加 h 后缀），与 JEDEC 文本一致。
• EXT_CSD 字段写作 EXT_CSD[179]，方括号内为字节偏移；位域写作 EXT_CSD[179][2:0]。
• 数值：十六进制用 0x 前缀；位序 bit0 为最低位。
• 时序：「典型值 / 最大值」成对给出时，软件超时一律按最大值预算；typ 值只用于安排轮询节奏。
• 代码示例为 C 伪代码，省略主机控制器寄存器细节，只表达命令序列与判据。

3 · 驱动架构与初始化

eMMC 的初始化是一条不能跳步的状态机：每一步都把器件推到下一个状态，跳步的直接后果是「命令发出去没响应」。 提速则是初始化之后单独的一段，必须「先慢后快、切完必验」。

3.1 分层职责

3.2 上电初始化流程

完整的识别流程只有一条标准路径，六步缺一不可：

int mmc_init(void)
{
    uint32_t resp, rca = 0x0001;
    uint8_t  ext_csd[512];

    /* ① 电源与复位就绪：VCC/VCCQ 稳定、RST_n 释放、输出 400 kHz 以下时钟 */
    host_set_clock(400000);              /* 识别阶段必须低速 */
    host_set_width(1);

    /* ② CMD0：复位到 Idle */
    send_cmd(CMD0, 0x00000000, RSP_NONE);     /* GO_IDLE_STATE → Idle（0xF0F0F0F0 是 GO_PRE_IDLE_STATE，用于复位后重引导 boot） */
    delay_us(200);

    /* ③ CMD1：电压协商 + 等待上电完成（bit31 = 1） */
    if (wait_cmd1_ready(1000) != 0)      /* 超时 1 s，循环重发 */
        return -E_MMC_NO_RESPONSE;

    /* ④ CMD2 / CMD3：读 CID、分配 RCA */
    send_cmd(CMD2, 0, RSP_R2);           /* 128 bit CID */
    send_cmd(CMD3, rca << 16, RSP_R1);   /* → Standby */

    /* ⑤ CMD7：选中，进入 Transfer 态 */
    send_cmd(CMD7, rca << 16, RSP_R1);

    /* ⑥ CMD8：读 512 B EXT_CSD（只能在 Transfer 态发） */
    if (mmc_send_ext_csd(ext_csd) != 0)
        return -E_MMC_EXT_CSD;

    return mmc_setup_from_ext_csd(ext_csd);   /* 提速 + 分区（见 3.4 / 第 5 章） */
}

/* CMD1 必须循环重发并设超时 —— 固定延时必然在某些器件上翻车 */
static int wait_cmd1_ready(uint32_t timeout_ms)
{
    uint32_t t0 = now_ms(), resp;
    do {
        send_cmd(CMD1, 0x40FF8080, RSP_R3);
        resp = host_last_resp();
        if (resp & 0x80000000u)          /* bit31 = 上电完成 */
            return 0;
        delay_ms(10);
    } while (now_ms() - t0 < timeout_ms);
    return -E_TIMEOUT;
}

3.3 器件识别与能力协商

初始化完成后，器件的全部能力都在 CID / CSD / EXT_CSD 里。驱动必须从寄存器读，不许硬编码：

/* 能力解析：全部从 EXT_CSD 取，禁止硬编码容量与几何 */
static int mmc_setup_from_ext_csd(const uint8_t *e)
{
    uint32_t sec   = le32(e + 212);       /* SEC_COUNT[215:212] */
    uint64_t cap   = (uint64_t)sec * 512; /* 用户区字节容量 */
    uint8_t  rev   = e[192];              /* EXT_CSD_REV      */
    uint8_t  dtype = e[196];              /* DEVICE_TYPE      */
    uint32_t cache = le32(e + 249);       /* CACHE_SIZE[252:249] */

    mmc.capacity   = cap;
    mmc.rev        = rev;
    mmc.hs200_1v8  = !!(dtype & 0x02);    /* HS200 @ 1.8 V */
    mmc.hs400_1v8  = !!(dtype & 0x04);    /* HS400 @ 1.8 V */
    mmc.cache_kb   = cache;               /* 0 = 无 Cache */

    log_i("eMMC rev=%d cap=%llu MB cache=%u KB hs400=%d",
          rev, cap >> 20, cache, mmc.hs400_1v8);
    return 0;
}

3.4 提速：先宽度、后时序、切完必验

上电后器件默认1-bit + Legacy（最高 26 MHz），所有高速档位都要主机主动切换。顺序错了会直接通信失败。

1. 确认 VCCQ 已切到 1.8 V：HS200/HS400 只在低电压档位下保证，3.3 V 下不许切（本器件 DEVICE_TYPE=0x57 只开放 1.8 V 档的 HS200/HS400，不支持 1.2 V）。
2. 先配总线宽度：CMD6 写 EXT_CSD[183] BUS_WIDTH —— 0 = 1-bit，1 = 4-bit，2 = 8-bit，5 = 4-bit DDR，6 = 8-bit DDR。
3. 再切时序：CMD6 写 EXT_CSD[185] HS_TIMING —— 0 = Legacy，1 = High Speed，2 = HS200，3 = HS400，4 = HS400ES。
4. HS200 必须 tuning：反复发 CMD21，主机在不同采样相位上采集并选出有效窗口。
5. HS400 必须先经 HS200：完成 HS200 tuning 后，写 HS_TIMING = 3 并启用 DS 选通。
6. 切完必验：做一次已知数据的写入 → 读回 → 比对，失败则逐级回退（HS400 → HS200 → HS → Legacy）。

/* 提速：每一步都等 busy、每一步都检查 SWITCH_ERROR */
static int mmc_switch(uint8_t index, uint8_t value, uint32_t timeout_ms)
{
    uint32_t arg = (0x03u << 24)          /* Access = Write Byte */
                 | ((uint32_t)index << 16)
                 | ((uint32_t)value << 8)
                 | 0x00u;                /* CmdSet = 标准命令集 */
    uint32_t st;

    send_cmd(CMD6, arg, RSP_R1b);
    if (wait_dat0_release(timeout_ms))   /* 关键：CMD6 也带 busy */
        return -E_TIMEOUT;
    send_cmd(CMD13, mmc.rca << 16, RSP_R1);
    st = host_last_resp();
    if (st & (1u << 7))                  /* SWITCH_ERROR */
        return -E_SWITCH_ERR;
    return 0;
}

int mmc_upgrade_to_hs400(void)
{
    mmc_switch(183, 2,  500);            /* BUS_WIDTH  = 8-bit      */
    mmc_switch(185, 2,  500);            /* HS_TIMING  = HS200      */
    if (host_hs200_tuning())             /* CMD21 采样相位调谐       */
        return -E_TUNING;
    mmc_switch(183, 6,  500);            /* 8-bit DDR               */
    mmc_switch(185, 3,  500);            /* HS_TIMING  = HS400      */
    return mmc_speed_verify();           /* 读写回环校验，失败即回退 */
}

3.5 初始化自检清单

• 上电时钟 ≤ 400 kHz，CMD1 循环轮询 bit31 且超时 ≥ 1 s
• CMD8 在 Transfer 态发送，已成功读回 512 B EXT_CSD
• 容量从 SEC_COUNT 计算，未硬编码；已与预期容量对账
• 提速前已确认 DEVICE_TYPE 与 VCCQ 电压档位匹配
• 总线宽度与 HS_TIMING 的写入顺序正确（宽度在前）
• HS200/HS400 已完成 tuning，并有读写回环验证
• 提速失败有逐级回退路径，且回退后功能可用
• 初始化日志记录了 REV、容量、速度档位、Cache 容量，便于现场追溯

4 · EXT_CSD 寄存器体系

EXT_CSD 是 eMMC 的管理面：512 字节，包罗万象。 所有配置只有一个入口——CMD6。理解它的分段、写入规则与生效时机，是写对 eMMC 驱动的前提。

4.1 512 字节的分段

• Properties Segment（0~191）：只读。容量、版本、能力、时序、寿命都在这里。
• Mode Segment（192~511）：可读写。总线宽度、时序、分区、Cache、BKOPS、写保护都在这里。

4.2 CMD6：唯一的写入口

4.3 写 EXT_CSD 六步准则

1. 先读后写：用本地缓存的 512 B EXT_CSD 确认当前值，避免无意义的改写。
2. 一次只改一个字节：CMD6 的 Index 是单字节偏移，没有批量写。
3. 用 Write Byte 模式：Access = 0x3（写字节）；置位/清位模式只在少数场景需要。
4. 等 busy 释放：轮询 DAT0 或用主机控制器的 R1b 完成中断，超时按 GENERIC_CMD6_TIME 预算。
5. 检查 SWITCH_ERROR：发 CMD13 读状态，R1 bit7 = 1 表示这次写入被拒绝。
6. 回读确认：关键配置（总线宽度、时序、分区）写完后重新 CMD8 读回比对。

4.4 生效时机：三种，别搞混

4.5 高频字段速查

完整字段定义见 JESD84-B51 第 7 章；厂商自定义字段以器件 datasheet 为准。本器件（XT28EG32/64GA2YUECGA）上电默认实测值见附录 F.1——其中 RST_n_FUNCTION[162] = 0（硬件复位默认未使能）、HPI_MGMT[161] = 0、BKOPS_EN[163] = 0、CACHE_CTRL[33] = 0、CMQ_MODE_EN[15] = 0 都是「支持但默认关」，必须由主机显式打开。

4.6 常见陷阱