一、为什么需要三层模型
没有分层时，一个典型的"大杂烩"驱动长这样：
/* ❌ 反例：初始化、传输、错误处理全混在一起 */
void my_card_read(struct my_host *h, u32 sector, void *buf)
{
/* 卡类型判断散落在传输函数里 */
if (!h->initialized) {
if (h->card_type == CARD_EMMC)
emmc_send_op_cond(h); /* CMD1：eMMC 专属初始化 */
else
sd_send_op_cond(h); /* ACMD41：SD 专属初始化 */
}
/* CMD17 READ_SINGLE_BLOCK，SD 和 eMMC 均使用相同命令 */
send_cmd(h, MMC_READ_SINGLE_BLOCK, sector);
wait_for_dma(h); /* 同步阻塞，无法复用 */
check_crc(buf); /* CRC 逻辑与传输逻辑耦合 */
}
这类代码无法在 SDHCI 和自研 Host 之间复用，无法在 SD 和 eMMC 之间切换，无法支持异步提交。Linux MMC 子系统用三层模型解决这个问题：
三层的职责边界：
1mmc_host：对控制器硬件的抽象。Host 驱动实现 mmc_host_ops 回调，描述硬件能力。
2mmc_card：对已识别卡的抽象。MMC Core 在枚举时填充，Host 驱动不应直接操作。
3mmc_request：对一次总线传输的抽象。上层填参数，Host 执行，Core 调度与重试。
三者是实现—契约—数据关系，不是继承关系。Host 驱动不关心卡是 SD 还是 eMMC，只负责把 mrq 交给硬件并在中断里填好 error 字段；Core 不关心控制器型号，只负责调度和重试；功能驱动不关心硬件细节，只负责把 bio 转换成 mrq。
二、mmc_host：控制器的抽象
核心字段
struct mmc_host（include/linux/mmc/host.h）描述一个 Host 控制器实例：
struct mmc_host {
const struct mmc_host_ops *ops; /* Host 驱动实现的回调表 */
/* 总线能力——必须正确填写，Core 据此协商卡的工作模式 */
u32 ocr_avail; /* 支持的工作电压，如 MMC_VDD_32_33 | MMC_VDD_33_34 */
u32 caps; /* MMC_CAP_4_BIT_DATA、MMC_CAP_SD_HIGHSPEED 等 */
u32 caps2; /* MMC_CAP2_HS200_1_8V_SDR、MMC_CAP2_HS400_1_8V 等 */
/* 时钟范围 */
unsigned int f_min; /* 识别阶段 400 kHz */
unsigned int f_max; /* 最高工作频率 */
/* DMA 约束——与描述符表大小对齐，填错会导致 SG 列表越界 */
unsigned int max_seg_size; /* 单个 SG 条目最大字节数 */
unsigned int max_segs; /* SG 列表最多条目数 */
unsigned int max_req_size; /* 单次请求最大总字节数 */
unsigned int max_blk_size; /* 单块最大字节数（SD/eMMC = 512） */
unsigned int max_blk_count; /* 单次请求最多块数 */
struct mmc_card *card; /* 已识别的卡，无卡时为 NULL */
/* ... */
};
caps 和 caps2 是最容易漏设的字段。漏设 MMC_CAP_4_BIT_DATA 会让卡初始化停在 1-bit SDR12（~6 MB/s），即使硬件和卡都支持 4-bit 也无济于事。
mmc_host_ops：Host 的实现契约
struct mmc_host_ops {
/* 必须实现 */
void (*request)(struct mmc_host *host, struct mmc_request *mrq);
void (*set_ios)(struct mmc_host *host, struct mmc_ios *ios);
/* 卡检测（无硬件检测脚时可返回固定值） */
int (*get_ro)(struct mmc_host *host);
int (*get_cd)(struct mmc_host *host);
/* UHS / HS200 / HS400（可选，不实现则不协商对应模式） */
int (*start_signal_voltage_switch)(struct mmc_host *, struct mmc_ios *);
int (*execute_tuning)(struct mmc_host *host, u32 opcode);
/* SDIO 中断 */
void (*enable_sdio_irq)(struct mmc_host *host, int enable);
/* ... */
};
request()：最核心的回调
Host 驱动必须异步启动硬件后立即返回，在中断或 workqueue 里调用 mmc_request_done() 完成请求。在 request() 里同步等待完成会死锁 MMC Core 调度线程（详见第六章陷阱一）。
set_ios()：总线参数配置
接收一个 struct mmc_ios 快照，Host 据此写寄存器：
struct mmc_ios {
unsigned int clock; /* 目标时钟频率（Hz），0 = 关闭 */
unsigned char bus_width; /* MMC_BUS_WIDTH_1 / _4 / _8 */
unsigned char signal_voltage; /* MMC_SIGNAL_VOLTAGE_330 / _180 */
unsigned char timing; /* MMC_TIMING_SD_HS、MMC_TIMING_MMC_HS200 等 */
/* ... */
};
每次 Core 需要切换总线参数（时钟频率、位宽、信号电压）时都会调用 set_ios()，Host 必须原子地完成配置。
生命周期与 mmc_of_parse
/* 1. 分配 host 结构体（私有数据紧跟其后） */
host = mmc_alloc_host(sizeof(struct my_priv), &pdev->dev);
/* 2. 填写硬件能力 */
host->ops = &my_mmc_ops;
host->f_min = 400000;
host->f_max = 200000000;
/* 3. 从 DTS 自动读取 bus-width、mmc-hs200-1_8v 等属性，
填充 caps / caps2 / ocr_avail——多数平台驱动用这一行代替手写 */
mmc_of_parse(host);
/* 4. 手动补充 DTS 无法表达的约束（DMA 描述符表大小等） */
host->max_segs = 128;
host->max_seg_size = SZ_64K;
host->max_req_size = SZ_64K * 128;
host->max_blk_size = 512;
host->max_blk_count = host->max_req_size / host->max_blk_size;
/* 5. 注册——触发 mmc_rescan 工作队列，开始枚举卡 */
mmc_add_host(host);
/* 移除时 */
mmc_remove_host(host);
mmc_free_host(host);
mmc_of_parse() 读取 bus-width、mmc-ddr-1_8v、mmc-hs200-1_8v、mmc-hs400-1_8v 等 DTS 属性并自动设置对应 caps 位，避免手写遗漏。DMA 约束仍需手动填，因为它取决于 Host 的描述符表实现，DTS 无法表达。
三、mmc_card：已识别卡的抽象
核心字段
struct mmc_card（include/linux/mmc/card.h）由 MMC Core 在枚举时动态分配：
struct mmc_card {
struct mmc_host *host; /* 所属 Host */
unsigned int type;
/* MMC_TYPE_MMC = eMMC / MMC
* MMC_TYPE_SD = SD 卡
* MMC_TYPE_SDIO = 纯 SDIO 设备
* MMC_TYPE_SD_COMBO= SD + SDIO 复合 */
unsigned int state; /* MMC_STATE_PRESENT、MMC_STATE_READONLY 等 */
/* 原始寄存器数据（枚举时从卡读取） */
u32 raw_cid[4]; /* Card Identification Register */
u32 raw_csd[4]; /* Card Specific Data */
u32 raw_scr[2]; /* SD Configuration Register（SD 卡专属） */
u8 raw_ext_csd[512]; /* Extended CSD（eMMC 专属） */
/* 解码后的结构体 */
struct mmc_cid cid; /* 制造商、产品名、序列号 */
struct mmc_csd csd; /* 读写速度、块大小、容量 */
struct mmc_ext_csd ext_csd;/* eMMC 分区、HS400、RPMB 等扩展信息 */
u16 rca; /* Relative Card Address（识别阶段分配） */
/* 已知缺陷（对照 drivers/mmc/core/quirks.h 中的卡缺陷列表） */
unsigned int quirks;
unsigned int quirks2;
/* ... */
};
raw_scr 和 ext_csd 分别是 SD 卡和 eMMC 专属寄存器。SD 卡没有 ext_csd，eMMC 没有 raw_scr——两者共用同一个 mmc_card 结构体，通过 type 字段区分。
quirks 字段
内核在 drivers/mmc/core/quirks.h 维护了一张已知问题卡的匹配表，例如某些 SanDisk 卡在 DDR52 模式下偶发读响应超时，匹配后会自动设置 MMC_QUIRK_BROKEN_DDR52，Core 据此降级到 SDR52。
对于自研产品（eMMC 固定焊在板上），如果测试发现某型号卡在特定速率下不稳定，可以在 DTS 中通过 no-1-8-v（禁用 1.8V 切换）、mmc-ddr-1_8v（强制 DDR 模式）等属性降低速率规避，或在 quirks.h 中为该型号增加 quirk 条目，而不必修改 Core 通用逻辑。
安全访问 host->card
mmc_host.card 在卡拔出时被 Core 置 NULL。任何访问 host->card 的代码都必须持有总线锁，否则可能读到悬挂指针：
mmc_claim_host(host);
if (host->card && mmc_card_present(host->card)) {
/* 在锁保护内安全访问 card 字段 */
u32 sectors = host->card->ext_csd.sectors;
}
mmc_release_host(host);
四、mmc_request：一次总线传输的抽象
mmc_request 由三个子结构体组成，字段分工如下：
mmc_command
struct mmc_command {
u32 opcode; /* 命令索引，如 MMC_READ_SINGLE_BLOCK = 17 */
u32 arg; /* 32 位参数（块地址、RCA 等） */
u32 resp[4]; /* Host 填入的响应数据 */
unsigned int flags; /* 响应类型 | 命令类型 */
int error; /* 0 = 成功，-ETIMEDOUT / -EILSEQ = 失败 */
unsigned int retries; /* Core 已重试次数 */
};
flags 高 16 位是响应类型，低 16 位是命令类型，两者用 | 组合：
/* CMD17 单块读：有 R1 响应 + 有数据传输 */
cmd.flags = MMC_RSP_R1 | MMC_CMD_ADTC;
/* CMD0 GO_IDLE：广播，无响应 */
cmd.flags = MMC_RSP_NONE | MMC_CMD_BC;
/* CMD12 STOP_TRANSMISSION：有 R1b 繁忙响应，无数据 */
cmd.flags = MMC_RSP_R1B | MMC_CMD_AC;
mmc_data
struct mmc_data {
unsigned int blksz; /* 单块字节数（SD/eMMC = 512） */
unsigned int blocks; /* 本次请求的块数 */
unsigned int flags; /* MMC_DATA_READ 或 MMC_DATA_WRITE */
struct scatterlist *sg; /* DMA SG 列表（由上层分配） */
unsigned int sg_len; /* SG 条目数 */
unsigned int bytes_xfered; /* 实际传输字节数（Host 填写） */
int error; /* 数据错误（Host 填写） */
};
cmd->error 与 data->error 的区别
Host 驱动必须将硬件错误映射到正确字段，Core 根据字段决定重试策略：
| 硬件事件 |
应设字段 |
Core 的响应 |
| CMD 响应 CRC7 不匹配 |
cmd->error = -EILSEQ |
重试命令，最多 retries 次 |
| 命令超时（卡无响应） |
cmd->error = -ETIMEDOUT |
重试命令，触发卡复位 |
| DAT 线 CRC16 不匹配 |
data->error = -EILSEQ |
触发 CRC 错误恢复（降速/重试） |
| 数据传输超时 |
data->error = -ETIMEDOUT |
重试，或上报 -EIO 到块层 |
把 DAT CRC 错设到 cmd->error 是常见错误——Core 会走命令重试路径而不是数据 CRC 恢复路径，掩盖真实原因。
mmc_wait_for_req 与 mmc_start_req 的区别
/* 同步：提交后阻塞，等 mrq->done 触发再返回
适用于初始化、ioctl、调试路径 */
mmc_wait_for_req(host, &mrq);
/* 异步：提交后立即返回，可以同时准备下一条请求
适用于 blk-mq 高吞吐路径，内部用 completion 串行化 */
mmc_start_req(host, &mrq, &err);
blk-mq 路径用 mmc_start_req() 以便流水线化多条请求；单次命令（CMD6 SWITCH 切参数、eMMC RPMB 读写等）用 mmc_wait_for_req() 保持代码简洁。
五、一次读操作的完整生命周期
以 CMD17 READ_SINGLE_BLOCK 为例，完整调用链如下（实线=调用，虚线=返回/通知）：
mmc_request 是唯一跨层传递的数据载体：[3] 填参数，[7] 填结果，[8] 读结果做决策——三层的边界由此清晰，谁填哪个字段，谁负责读。
六、三个高频误用陷阱
陷阱一：在 request() 里同步等待完成
request() 必须在启动硬件后立即返回；若在回调里同步轮询等待，会让 MMC Core 调度线程永久阻塞，无法接收任何完成通知：
/* ❌ 在 request() 里轮询，MMC Core 调度线程挂死 */
void bad_request(struct mmc_host *host, struct mmc_request *mrq)
{
start_transfer();
while (!transfer_done()) /* Core 持锁等这里返回，死锁 */
cpu_relax();
mmc_request_done(host, mrq);
}
/* ✅ 启动硬件后立即返回，在中断里完成 */
void good_request(struct mmc_host *host, struct mmc_request *mrq)
{
priv->mrq = mrq; /* 保存引用，中断里用 */
start_transfer(); /* 写寄存器触发 DMA，立即返回 */
}
irqreturn_t my_irq(int irq, void *dev)
{
struct my_priv *priv = dev;
if (status & DATA_CRC_ERROR)
priv->mrq->data->error = -EILSEQ;
mmc_request_done(priv->host, priv->mrq);
return IRQ_HANDLED;
}
陷阱二：caps 漏设导致性能缺失
/* ❌ 漏设 4-bit，卡以 1-bit SDR12 运行，速度约 6 MB/s */
host->caps = MMC_CAP_SD_HIGHSPEED;
/* ✅ 按硬件实际能力填写（mmc_of_parse 会处理 DTS 里的部分） */
host->caps = MMC_CAP_4_BIT_DATA
| MMC_CAP_8_BIT_DATA /* eMMC 专属 */
| MMC_CAP_SD_HIGHSPEED
| MMC_CAP_MMC_HIGHSPEED;
host->caps2 = MMC_CAP2_HS200_1_8V_SDR
| MMC_CAP2_HS400_1_8V;
诊断命令：
# 查看当前协商的时序模式（clock、bus_width、timing 等）
cat /sys/kernel/debug/mmc0/ios
# 查看已绑定的驱动名
ls -l /sys/bus/mmc/devices/mmc0:0001/driver
陷阱三：mmc_claim_host 未配对释放
/* ❌ 异常路径漏了 release，总线永久锁定 */
int bad_ioctl(struct mmc_host *host)
{
mmc_claim_host(host);
ret = do_cmd();
if (ret)
return ret; /* 漏了 mmc_release_host，其他任务永远拿不到总线 */
mmc_release_host(host);
return 0;
}
/* ✅ goto 统一出口 */
int good_ioctl(struct mmc_host *host)
{
mmc_claim_host(host);
ret = do_cmd();
if (ret)
goto out;
ret = do_more_cmd();
out:
mmc_release_host(host); /* 无论成功失败都释放 */
return ret;
}
mmc_claim_host 是可重入计数锁（同一线程可嵌套 claim），但每次 claim 必须对应一次 release，否则引用计数永不归零，其他任务无限阻塞在 mmc_claim_host() 内部的 wait_event()。
七、小结
| 结构体 |
所属层 |
生命周期管理 |
核心职责 |
mmc_host |
控制器层 |
Host 驱动 mmc_alloc_host / mmc_free_host |
实现 ops 回调，描述硬件能力与约束 |
mmc_card |
卡层 |
MMC Core 枚举时分配，拔卡时释放 |
存储卡身份、能力寄存器、已知缺陷 |
mmc_request |
请求层 |
上层驱动（mmc_blk 等）分配，mrq->done 后释放 |
编码一次总线传输的参数与结果 |
三层模型让三件事彼此独立：换一块控制器只需重写 mmc_host_ops 实现；换一张卡只需更新 mmc_card.quirks；换一种存储协议（SD→eMMC→SDIO）只需换功能驱动，Core 和 Host 不动。理解三层边界，是读懂 sdhci 框架、ADMA2 配置、Tuning 机制等后续话题的前提。
