1. 为什么说 NVMe 是复杂存储驱动开发的入门首选1.1 一个被低估的学习切入点很多人一听到“存储驱动开发”脑子里第一反应是 SCSI、SAS、RAID 这些老牌子系统觉得那才是正统。但如果你真的去啃过 Linux 内核里drivers/scsi那一坨代码你会发现一个很现实的问题SCSI 协议栈的历史包袱太重了。它要兼容几十年的老设备要处理各种奇怪的命令集光是scsi_cmnd这个结构体的字段就够你看一整天。而 NVMe 不一样。NVMe 是 2011 年之后才定型的协议设计之初就假设底层是 PCIe假设主机端有足够的内存和算力假设队列可以做得非常深。它没有历史包袱协议本身干净利落。一个 NVMe 命令就是一个 64 字节的 Submission Queue Entry完成就是一个 16 字节的 Completion Queue Entry。你不需要去理解什么 CDB、sense data、各种奇奇怪怪的状态机。我个人的判断是如果你想入门复杂存储驱动开发NVMe 是目前性价比最高的选择。它足够“现代”能让你接触到 PCIe 枚举、DMA 映射、中断处理、块层对接、多队列这些核心概念同时它又足够“简单”协议规范只有几百页核心数据结构一只手数得过来。1.2 从 U-Boot 到 Linux 内核的完整链路标题里提到了 U-Boot这个点很关键。很多做驱动开发的人只关注 Linux 内核那一侧忽略了 bootloader 阶段其实也有 NVMe 驱动。U-Boot 里的 NVMe 驱动是一个非常好的“简化版教材”——它没有 Linux 内核那么复杂的块层、多队列、电源管理就是一个纯粹的 PCIe 设备驱动负责初始化控制器、创建队列、读写扇区。你可以这样理解U-Boot 的 NVMe 驱动是“最小可用实现”Linux 内核的 NVMe 驱动是“生产级完整实现”。先看 U-Boot 版本把 PCIe 枚举、BAR 空间映射、控制器寄存器操作这些基础打牢再去看 Linux 内核版本理解多队列、中断聚合、命名空间管理这些高级特性。这个学习路径比一上来就啃内核代码要平滑得多。1.3 适合谁来学这篇内容适合三类人第一类是有一定 C 语言和 Linux 驱动基础想往存储方向深入的同学第二类是做嵌入式开发需要在 SoC 平台上适配 NVMe SSD 的工程师第三类是已经会写简单字符设备驱动想挑战更复杂子系统的开发者。如果你连probe函数、file_operations、platform_driver这些概念都还不清楚建议先去补一下 Linux 驱动开发的基础。但如果你已经写过一两个简单的驱动那 NVMe 绝对是一个值得投入的方向。2. NVMe 驱动核心架构拆解2.1 PCIe 枚举与设备发现NVMe SSD 在系统里首先是一个 PCIe 设备。Linux 内核启动时PCIe 子系统会进行枚举扫描总线上的所有设备。对于 NVMe 设备来说它的 Class Code 是0x010802内核的 PCIe 层会根据这个 Class Code 匹配到 NVMe 驱动。这里有一个关键点NVMe 设备通常有两个 BAR 空间。BAR0 是控制器寄存器空间大小一般是 16KB 或 64KBBAR1 是门铃寄存器空间大小通常很小。内核驱动在probe阶段会调用pci_request_mem_regions来申请这些 BAR 空间然后通过ioremap映射到内核虚拟地址。我实测下来很多人在这一步踩坑是因为没有正确理解 BAR 空间的映射方式。NVMe 的寄存器是内存映射的不是 IO 端口映射的。你必须用readl/writel或者readq/writeq来访问不能用inb/outb。而且 NVMe 寄存器里有很多 64 位的字段比如 CAP 寄存器访问的时候要注意高低 32 位的顺序。2.2 控制器初始化流程NVMe 控制器的初始化有一个标准流程我把它拆成几个关键步骤第一步是等待控制器就绪。读取 CAP 寄存器检查CSTS.RDY位。如果控制器还没就绪需要等待。这里要注意超时处理不能无限等下去。第二步是配置 Admin Queue。Admin Queue 是 NVMe 控制器用来接收管理命令的队列包括创建 IO Queue、获取控制器信息、设置特性等。你需要分配一段 DMA 内存来存放 Admin Submission Queue 和 Admin Completion Queue然后把它们的物理地址写入 AQA、ASQ、ACQ 寄存器。第三步是启用控制器。设置 CC 寄存器里的EN位然后等待CSTS.RDY变为 1。这一步完成后控制器就正式工作了。第四步是识别控制器和命名空间。通过 Admin Queue 发送 Identify 命令获取控制器的能力信息、命名空间列表、每个命名空间的容量和格式。注意Admin Queue 的深度通常是 2 的幂次最小是 2最大由 CAP 寄存器的 MQES 字段决定。你在分配内存的时候要按页对齐因为 NVMe 规范要求队列内存必须页对齐。2.3 多队列与中断处理NVMe 最核心的设计之一就是多队列。每个 CPU 核心可以有自己的 Submission Queue 和 Completion Queue 对这样就不需要全局锁来保护队列操作。Linux 内核的 NVMe 驱动会根据 CPU 数量来创建队列通常每个 CPU 一个队列对。中断处理方面NVMe 支持 MSI-X 中断。每个 Completion Queue 可以绑定一个独立的 MSI-X 向量。当命令完成时控制器会往对应的 Completion Queue 里写一个 Completion Entry然后触发中断。驱动在中断处理函数里读取 Completion Entry处理完成状态然后按需唤醒等待的进程。这里有一个性能优化的关键点中断聚合。NVMe 控制器支持设置中断聚合阈值和聚合时间也就是说可以等积累了一定数量的完成事件后再触发一次中断减少中断次数。这个参数需要根据实际负载来调调得太激进会增加延迟调得太保守会浪费 CPU。2.4 块层对接与请求处理NVMe 驱动最终要对接 Linux 的块层。块层会把上层的读写请求转换成request结构然后通过queue_rq回调交给驱动。NVMe 驱动需要把request转换成 NVMe 命令写入 Submission Queue然后按门铃通知控制器。这个转换过程有几个细节需要注意一是数据长度NVMe 命令里的 NLB 字段是“逻辑块数量减一”不是字节数二是 PRP 或 SGL 的构造NVMe 支持两种数据描述方式PRP 适合简单的物理连续内存SGL 适合分散聚合场景三是命令 ID 的管理每个未完成的命令需要一个唯一的 ID完成时用来匹配。3. 从零实现一个最小 NVMe 驱动3.1 环境准备与工具链在开始写代码之前你需要准备以下环境一台支持 PCIe 的 Linux 开发机内核版本建议 5.10 以上一个 NVMe SSD可以是 M.2 接口的也可以是 U.2 接口的内核源码树用于编译模块和查看参考代码lspci、nvme-cli、dd等调试工具我建议在虚拟机里先跑一遍 QEMU 的 NVMe 模拟设备这样即使写崩了也不会影响宿主机。QEMU 支持-device nvme参数来模拟 NVMe 控制器配合-drive filexxx.img,ifnone,idnvme0可以创建一个虚拟 NVMe 盘。qemu-system-x86_64 \ -m 4G \ -smp 4 \ -kernel bzImage \ -append consolettyS0 root/dev/sda \ -drive filerootfs.img,formatraw,ifvirtio \ -drive filenvme.img,formatraw,ifnone,idnvme0 \ -device nvme,drivenvme0,serialdeadbeef \ -nographic这个命令会创建一个 4 核、4G 内存的虚拟机挂载一个虚拟 NVMe 设备。你可以在里面加载自己写的驱动模块用dmesg看输出。3.2 驱动骨架与 PCIe 注册一个最小的 NVMe 驱动需要定义一个pci_driver结构注册probe和remove回调。在probe里你需要做以下几件事static int my_nvme_probe(struct pci_dev *pdev, const struct pci_device_id *id) { int ret; struct my_nvme_dev *dev; ret pci_enable_device(pdev); if (ret) return ret; ret pci_request_mem_regions(pdev, my_nvme); if (ret) goto disable_device; dev kzalloc(sizeof(*dev), GFP_KERNEL); if (!dev) { ret -ENOMEM; goto release_regions; } dev-bar0 pci_iomap(pdev, 0, 0); if (!dev-bar0) { ret -EIO; goto free_dev; } pci_set_drvdata(pdev, dev); pci_set_master(pdev); /* 后续初始化控制器 */ ret my_nvme_init_ctrl(dev); if (ret) goto unmap_bar; return 0; unmap_bar: pci_iounmap(pdev, dev-bar0); free_dev: kfree(dev); release_regions: pci_release_mem_regions(pdev); disable_device: pci_disable_device(pdev); return ret; }这段代码看起来简单但有几个坑我踩过pci_enable_device必须在pci_request_mem_regions之前调用否则申请区域会失败pci_set_master用来启用 DMA不调用的话 DMA 传输会出问题pci_iomap的最后一个参数是映射长度传 0 表示映射整个 BAR 空间。3.3 控制器寄存器操作NVMe 控制器的寄存器布局在规范里有明确定义。你需要定义一组偏移量#define NVME_REG_CAP 0x0000 /* Controller Capabilities */ #define NVME_REG_VS 0x0008 /* Version */ #define NVME_REG_INTMS 0x000C /* Interrupt Mask Set */ #define NVME_REG_INTMC 0x0010 /* Interrupt Mask Clear */ #define NVME_REG_CC 0x0014 /* Controller Configuration */ #define NVME_REG_CSTS 0x001C /* Controller Status */ #define NVME_REG_AQA 0x0024 /* Admin Queue Attributes */ #define NVME_REG_ASQ 0x0028 /* Admin Submission Queue Base Address */ #define NVME_REG_ACQ 0x0030 /* Admin Completion Queue Base Address */读取 CAP 寄存器的时候要注意它是一个 64 位寄存器但 PCIe 配置空间里可能只暴露了低 32 位。你需要先读低 32 位再读高 32 位然后组合起来。CAP 寄存器里的 MQES 字段告诉你最大队列深度TO 字段告诉你超时时间DSTRD 字段告诉你门铃寄存器的步长。static u64 my_nvme_read_cap(struct my_nvme_dev *dev) { u32 low, high; low readl(dev-bar0 NVME_REG_CAP); high readl(dev-bar0 NVME_REG_CAP 4); return ((u64)high 32) | low; }门铃寄存器的写入也有讲究。NVMe 的门铃寄存器不是简单的写一个值就完事你需要根据队列 ID 和门铃类型Submission 还是 Completion来计算偏移。公式是门铃偏移 0x1000 (队列ID * 2 * (4 DSTRD)) (类型 * (4 DSTRD))。其中类型 0 是 Submission类型 1 是 Completion。3.4 Admin Queue 创建与 Identify 命令Admin Queue 的创建是控制器初始化的核心。你需要分配两个 DMA 内存区域一个用于 Submission Queue一个用于 Completion Queue。然后配置 AQA 寄存器设置队列深度配置 ASQ 和 ACQ 寄存器设置物理地址。static int my_nvme_create_admin_queue(struct my_nvme_dev *dev) { int ret; u32 aqa; dev-admin_sq dma_alloc_coherent(dev-pdev-dev, ADMIN_QUEUE_SIZE * sizeof(struct nvme_command), dev-admin_sq_dma, GFP_KERNEL); if (!dev-admin_sq) return -ENOMEM; dev-admin_cq dma_alloc_coherent(dev-pdev-dev, ADMIN_QUEUE_SIZE * sizeof(struct nvme_completion), dev-admin_cq_dma, GFP_KERNEL); if (!dev-admin_cq) { ret -ENOMEM; goto free_sq; } aqa ((ADMIN_QUEUE_SIZE - 1) 16) | (ADMIN_QUEUE_SIZE - 1); writel(aqa, dev-bar0 NVME_REG_AQA); writeq(dev-admin_sq_dma, dev-bar0 NVME_REG_ASQ); writeq(dev-admin_cq_dma, dev-bar0 NVME_REG_ACQ); return 0; free_sq: dma_free_coherent(dev-pdev-dev, ADMIN_QUEUE_SIZE * sizeof(struct nvme_command), dev-admin_sq, dev-admin_sq_dma); return ret; }Identify 命令是获取控制器和命名空间信息的关键。你需要构造一个nvme_command结构设置 opcode 为nvme_admin_identify设置 CNS 字段为 1获取控制器信息或 0获取命名空间信息然后提交到 Admin Queue。提交命令的流程是把命令写入 Submission Queue 的对应位置更新 SQ 的 tail 指针然后写门铃寄存器通知控制器。等待完成的方式有两种轮询 Completion Queue 的 phase 位或者等待中断。在 Admin Queue 阶段通常用轮询方式因为这时候中断还没配置好。3.5 IO Queue 创建与读写测试Admin Queue 工作正常后就可以创建 IO Queue 了。IO Queue 的创建也是通过 Admin 命令完成的opcode 是nvme_admin_create_cq和nvme_admin_create_sq。你需要为每个 IO Queue 分配 DMA 内存设置队列深度和中断向量。创建完 IO Queue 后就可以进行读写测试了。读命令的 opcode 是nvme_cmd_read写命令是nvme_cmd_write。你需要设置 NSID命名空间 ID、SLBA起始逻辑块地址、NLB逻辑块数量和 PRP 列表。static int my_nvme_read(struct my_nvme_dev *dev, u64 slba, u32 nlb, void *buf) { struct nvme_command cmd {0}; dma_addr_t dma_addr; dma_addr dma_map_single(dev-pdev-dev, buf, nlb * 512, DMA_FROM_DEVICE); if (dma_mapping_error(dev-pdev-dev, dma_addr)) return -EIO; cmd.rw.opcode nvme_cmd_read; cmd.rw.nsid cpu_to_le32(dev-nsid); cmd.rw.slba cpu_to_le64(slba); cmd.rw.length cpu_to_le16(nlb - 1); cmd.rw.prp1 cpu_to_le64(dma_addr); cmd.rw.prp2 0; /* 提交命令到 IO Queue 并等待完成 */ /* ... */ dma_unmap_single(dev-pdev-dev, dma_addr, nlb * 512, DMA_FROM_DEVICE); return 0; }提示PRP1 必须指向一个页对齐的物理地址。如果你的缓冲区不是页对齐的需要特殊处理。对于大于一页的传输PRP2 可以指向一个 PRP List里面存放后续页的物理地址。4. 常见问题与排查技巧实录4.1 控制器初始化失败排查控制器初始化失败是最常见的问题表现通常是CSTS.RDY一直不置位或者 Identify 命令超时。我整理了一个排查表现象可能原因排查方法CSTS.RDY 不置位CC.EN 未正确设置读取 CC 寄存器确认 EN 位CSTS.RDY 不置位控制器未上电检查 PCIe 配置空间的 Power StateIdentify 超时Admin Queue 地址错误确认 ASQ/ACQ 写入的是物理地址Identify 超时队列深度配置错误确认 AQA 不超过 CAP.MQES完成状态非 0命令格式错误检查 opcode、NSID、PRP 字段我遇到过一次很诡异的问题控制器初始化一直失败查了半天发现是writeq在 32 位系统上不可用。后来改成两次writel分别写高低 32 位才解决。所以如果你在 32 位平台上开发一定要注意 64 位寄存器的访问方式。4.2 DMA 映射与缓存一致性DMA 映射是另一个容易出问题的地方。dma_alloc_coherent分配的内存是缓存一致的CPU 和设备看到的内容是一样的。但dma_map_single映射的内存需要手动同步缓存读操作要用dma_sync_single_for_cpu写操作要用dma_sync_single_for_device。我踩过的坑是在读取 NVMe 完成队列之前忘记调用dma_sync_single_for_cpu导致读到的完成状态是旧的。因为完成队列是设备写入、CPU 读取的设备写完后CPU 的缓存里可能还是旧数据。加上同步操作后就正常了。4.3 中断不触发或触发异常中断问题通常有几个原因MSI-X 向量没分配成功、中断掩码没清除、Completion Queue 的相位位判断错误。NVMe 的 Completion Entry 里有一个 Phase 位用来区分新老条目。初始时 Phase 为 0队列绕回一次后变为 1。如果你判断相位位的逻辑写反了就会一直认为没有新完成。还有一个常见问题是中断风暴。如果 Completion Queue 里的条目没有被及时处理控制器会一直触发中断。你需要在中断处理函数里把所有已完成的条目都处理掉直到遇到相位位不匹配的条目为止。4.4 性能不达预期的调优思路如果你发现读写性能远低于预期可以从以下几个方面排查队列深度是否足够。NVMe 的优势在于深队列如果队列深度只有 2性能肯定上不去。中断聚合是否合理。聚合阈值太高会增加延迟太低会增加 CPU 占用。是否使用了多队列。单队列无法充分利用多核 CPU 的并行能力。PRP 列表是否过于分散。如果数据缓冲区物理地址不连续PRP 列表会很长增加控制器处理开销。我实测下来在 QEMU 模拟环境下单队列深度 64 的配置顺序读性能大概在 1GB/s 左右。切换到多队列后4 个队列并行性能可以提升到 3GB/s 以上。当然实际硬件上的表现会更好。4.5 与 U-Boot 版本的差异对比U-Boot 的 NVMe 驱动和 Linux 内核版本有几个关键差异理解这些差异对调试很有帮助特性U-Boot 版本Linux 内核版本队列数量通常单队列多队列每 CPU 一个中断处理轮询为主MSI-X 中断内存管理简单物理地址DMA API 映射块层对接无直接扇区读写完整的块设备层电源管理基本没有完整的运行时电源管理命名空间通常只支持一个支持多个命名空间U-Boot 版本适合理解基础流程Linux 内核版本适合理解生产级实现。我建议先看 U-Boot 的drivers/nvme/nvme.c大概一千多行一天就能看完。然后再看内核的drivers/nvme/host/目录那里有 PCIe 层、核心层、块层对接的完整实现。5. 进阶方向与扩展思路5.1 从 NVMe 到 NVMe-oF掌握了本地 NVMe 驱动之后一个自然的扩展方向是 NVMe over Fabrics。NVMe-oF 把 NVMe 命令封装到 RDMA、TCP 或 Fibre Channel 上传输实现远程存储访问。核心的队列机制和命令格式是一样的只是传输层变了。如果你理解了本地 NVMe 的队列和命令处理再看 NVMe-oF 会容易很多。5.2 虚拟化场景下的 NVMe在虚拟化环境中NVMe 设备可以通过 VFIO 直通给虚拟机也可以由宿主机模拟。QEMU 就支持模拟 NVMe 控制器虚拟机里的驱动看到的是一块虚拟 NVMe 盘。如果你在做虚拟化相关的开发理解 NVMe 驱动在虚拟化环境下的行为差异很重要。比如中断注入的方式、DMA 地址的转换、队列内存的映射等。5.3 基于 PCIe 的其他存储协议NVMe 只是 PCIe 存储协议的一种。还有一些其他协议比如 AHCISATA 控制器接口、NVMe-MI管理接口等。理解了 NVMe 的 PCIe 枚举、BAR 映射、DMA 传输这些基础再看其他 PCIe 存储协议会轻松很多。PCIe 本身的知识是通用的包括配置空间访问、能力结构遍历、链路训练等。5.4 调试工具与性能分析最后分享几个我常用的调试工具。lspci -vvv可以查看 PCIe 设备的详细配置空间包括 BAR 大小、能力结构、链路状态。nvme-cli可以发送各种 NVMe 命令包括 Identify、Get Log Page、Format 等非常适合验证驱动行为。perf可以用来分析中断分布和 CPU 占用。blktrace可以跟踪块层的请求流程帮你定位性能瓶颈。提示在调试 NVMe 驱动时建议把内核的CONFIG_NVME_CORE_DEBUG和CONFIG_PCI_DEBUG打开这样可以看到更详细的日志输出。但注意这些调试选项会影响性能生产环境不要开。我个人在实际操作中的体会是NVMe 驱动开发最难的部分不是协议本身而是对 PCIe 子系统和 DMA 机制的理解。很多人卡在控制器初始化阶段其实问题往往出在 PCIe 配置空间的访问上。建议在写 NVMe 驱动之前先花点时间写一个简单的 PCIe 设备驱动把probe、BAR 映射、DMA 分配、中断注册这些基础打牢。基础扎实了NVMe 就是水到渠成的事情。
