Linux io_uring uring_cmd 与 NVMe Passthrough：从内核块层到用户态直路的深度工程实战

6 阅读 0 评论 0 点赞

Linux io_uring uring_cmd 与 NVMe Passthrough：从内核块层到用户态直路的深度工程实战

引言

现代 NVMe SSD 的延迟已经进入微秒级（~10μs），IOPS 突破百万，然而传统的 Linux 内核 I/O 栈——系统调用、VFS、块层排队、调度器——每一层都在蚕食这些硬件红利。io_uring 的出现带来了异步 I/O 的革命，而其中的 uring_cmd（IORING_OP_URING_COMMAND）操作更是开辟了一条全新路径：它允许用户空间通过 io_uring 的命令接口直接向内核设备驱动提交自定义命令，绕过传统块层，实现真正意义上的 NVMe Passthrough。

本文将深入剖析 uring_cmd 在内核中的实现机制、NVMe 驱动如何注册和响应这一接口、以及如何构建一个基于 uring_cmd 的高性能 NVMe 用户态 I/O 引擎。这不是简单的 API 调用教程，而是一趟从队列对（Queue Pair）管理、命令编码、内存注册到实测性能调优的完整工程之旅。

一、背景：从 syscall 到 uring_cmd 的演进路径

1.1 传统内核 I/O 栈的开销构成

一次传统的 NVMe 同步写入路径包括：

用户态触发 ioctl(fd, NVME_IOCTL_SUBMIT_IO, &io_cmd) 或 pwrite()
系统调用进入内核（~10-50 cycles）
VFS 层查找 inode 和 file
块层：bio 入队、合并、调度（mq-deadline/kyber/bfq）
NVMe 驱动：从提交队列（SQ）取项、填充命令、门铃更新
中断/MSI-X 完成通知 → 完成队列（CQ）处理
返回用户态

即便使用 io_submit 的异步路径（libaio），每次提交仍需两次 syscall（submit + enter），且块层的排队和合并逻辑对 NVMe 这种低延迟设备常常弊大于利。

1.2 io_uring 解决的核心问题

io_uring 通过 mmap 共享的两个环形队列——提交队列（SQ）和完成队列（CQ）——将"提交"和"完成"的通信成本降为零 syscall（在 SQPOLL 模式下）。但当需要绕过块层直连 NVMe 设备时，我们需要更底层的接口：uring_cmd。

二、uring_cmd 架构深度解析

2.1 uring_cmd 的本质

uring_cmd 定义在 include/linux/io_uring/cmd.h：


struct io_uring_cmd {
    struct file *file;          // 关联的设备文件
    struct io_ring_ctx *ctx;    // 所属 ring 上下文
    __u8   op;                  // 命令操作码（驱动自定义）
    __u8   pad[3];
    __u32  cmd_op;              // 具体命令编码（如 NVMe_IOCTL_ADMIN_CMD）
    __u32  pad2;
    __u8   cmd[0];              // 命令数据（flexible array）
};

用户空间通过 opcode = IORING_OP_URING_COMMAND 将操作放入 SQ entry 的 cmd 字段指向一个 union io_uring_pdu，其中包含上面结构。驱动层通过 io_uring_cmd_to_cmd() 获取原始命令数据。

2.2 驱动注册流程：nvme_uring_cmd 注册入口

NVMe 子系统通过 nvme_uring_cmd_info 向 io_uring 注册处理函数：


static const struct io_uring_cmd_ops nvme_uring_cmd_ops = {
    .cmd_size       = sizeof(struct nvme_uring_cmd),
    .uring_cmd      = nvme_uring_cmd,
    .done           = nvme_uring_cmd_done,
};

static int __init nvme_uring_cmd_init_module(void)
{
    return io_uring_register_range(&nvme_uring_cmd_ops, ...);
}

关键点：

nvme_uring_cmd 是入口回调，从 SQ entry 解析出 NVMe 命令并提交到块设备的 admin queue 或 IO queue
nvme_uring_cmd_done 是完成回调，负责将 CQ 完成事件写回并完成 SQE 的用户态等待
每个 SQ entry 的 cmd 字段指向 struct nvme_uring_cmd，包含 opcode、 nsid、addr、data_len 等

2.3 零拷贝共享内存机制

uring_cmd 的厉害之处在于用户态可以直接将 SQ entry 中的缓冲区指针传递给驱动，前提是该内存已通过 IORING_REGISTER_BUFFERS 注册为固定缓冲区（fixed buffers）：


// 用户态注册缓冲区
struct iovec iov[2] = {
    { .buf = buf1, .len = 4096 },
    { .buf = buf2, .len = 4096 },
};
io_uring_register_buffers(&ring, iov, 2);

当 IOSQE_BUFFER_SELECT 置位时驱动可以直接使用 ioq->buf[buf_group] 避免 get_user_pages() 调用，进一步节省开销。

三、NVMe 命令直通详解

3.1 NVMe 命令结构

NVMe 的 I/O 命令是 64 字节固定结构：


struct nvme_command {
    struct nvme_common_command common;    // 16 bytes
    union {
        struct nvme_rw_command rw;        // Read/Write
        struct nvme_admin_command admin;  // Admin（identify, get_log_page等）
    };
};

// RW 命令关键字段
struct nvme_rw_command {
    __u8    opcode;       // 0x01=Write, 0x02=Read
    __u8    flags;        // FUA, PRINFO 等
    __u16   command_id;   // 由驱动分配
    __u32   nsid;         // Namespace ID
    __u64   slba;         // Starting LBA
    __u16   length;       // 逻辑块数（0-based）
    ...
};

uring_cmd 的灵活性在于：用户态可以构造任意 NVMe 命令（不仅是 Read/Write），包括：

NVME_IOCTL_ADMIN_CMD：发送 Identify、Get Feature、Set Feature、Format NVM 等管理命令
NVME_IOCTL_IO_CMD：发送自定义 Vendor Specific 命令或 passthru 调试命令
NVME_IOCTL_RESET / NVME_IOCTL_SUBSYS_RESET：子系统级别操作

对于存储引擎开发者而言，这意味着可以通过同一套 io_uring 传输路径同时处理数据 I/O 和设备管理请求——这是一个巨大的架构优势。

3.2 多队列亲和性（Multi-Queue Affinity）

现代 NVMe 设备支持多达 64K 个 IO 队列对（Queue Pair）。uring_cmd 在设计上天然适配多队列：每个 io_uring 实例可以绑定到一个独立的 NVMe Queue Pair，从而实现：

每个 CPU 一个独立 ring → 一对一映射到 NVMe cqn（Completion Queue Number）
零跨核通信开销
独立的 CQ 中断亲和性配置


# 查看设备支持的队列数
cat /sys/block/nvme0n1/queue/nr_queues

# 设置中断亲和性
echo 04 > /proc irq/<irq_num>/smp_affinity

四、实战：构建基于 uring_cmd 的 NVMe I/O 引擎

4.1 初始化与设备打开


#define QUEUE_DEPTH 1024
#define BLOCK_SIZE  4096

struct nvme_engine {
    struct io_uring ring;
    int              fd;         // /dev/ng0n1 或 /dev/nvme0n1
    unsigned int     qd;         // 队列深度
};

int nvme_engine_init(struct nvme_engine *e, const char *dev_path) {
    struct io_uring_params p = {0};
    
    // 开启 SQPOLL：内核轮询 SQ 免去 syscall
    p.flags = IORING_SETUP_SQPOLL | IORING_SETUP_SQ_AFF;
    p.sq_thread_idle = 2000;    // 2ms idle 休眠
    p.sq_thread_cpu = 0;        // SQ 线程绑定 CPU0
    
    // 每个 IO thread 独立的 ring（避免多线程共享）
    if (io_uring_queue_init_params(QUEUE_DEPTH, &e->ring, &p) < 0) {
        perror("io_uring_queue_init");
        return -1;
    }
    
    // 打开 NVMe 字符设备（允许 uring_cmd）
    e->fd = open(dev_path, O_RDWR);
    if (e->fd < 0) {
        perror("open nvme device");
        io_uring_queue_exit(&e->ring);
        return -1;
    }
    
    return 0;
}

注意：必须打开的是 NVMe 字符设备（/dev/ng0n1），而非块设备（/dev/nvme0n1）。块设备的 uring_cmd 由块层处理，无法实现真正的 Passthrough。

4.2 提交一个 NVMe Read 请求


int nvme_read_sync(struct nvme_engine *e, void *buf, 
                   uint64_t offset, size_t len) {
    struct io_uring_sqe *sqe;
    struct nvme_uring_cmd cmd = {0};
    
    sqe = io_uring_get_sqe(&e->ring);
    if (!sqe) return -EAGAIN;   // 队列满
    
    // 填充 NVMe uring_cmd 结构
    cmd.opcode = NVME_URING_CMD_IO;   // IO 队列操作
    cmd.nsid  = 1;                    // Namespace 1
    cmd.addr  = (uint64_t)buf;        // 数据缓冲区用户态地址
    cmd.data_len = len;
    cmd.slba  = offset / BLOCK_SIZE;  // 扇区偏移
    cmd.length = len / BLOCK_SIZE - 1;
    
    // 填充 SQE：指向驱动需要的数据
    sqe->opcode     = IORING_OP_URING_COMMAND;
    sqe->fd         = e->fd;          // NVMe 字符设备 fd
    sqe->cmd_op     = NVME_IOCTL_IO_CMD;
    sqe->addr       = (uint64_t)&cmd; // nvme_uring_cmd 结构地址
    sqe->len        = sizeof(cmd);
    sqe->user_data  = (uint64_t)buf;  // 用于完成时的上下文匹配
    
    io_uring_submit(&e->ring);
    return 0;
}

4.3 等待完成并处理结果


int nvme_wait_complete(struct nvme_engine *e, 
                       struct io_uring_cqe **cqe) {
    int ret = io_uring_wait_cqe(&e->ring, cqe);
    
    if (ret < 0) {
        // EAGAIN=无完成可等, EINTR=被中断
        return ret;
    }
    
    // cqe->res: NVMe 状态码（0=成功, 非0=NVMe SC）
    if ((*cqe)->res != 0) {
        fprintf(stderr, "NVMe error: status=0x%x\n", (*cqe)->res);
    }
    
    // 注意：必须手动 advance 完成队列
    io_uring_cqe_seen(&e->ring, *cqe);
    return 0;
}

4.4 高级：IOMMU + Fixed Buffer 零拷贝

要完全消除数据拷贝（Dbuf 缓冲区物理地址直接用于 PRP/SGL），需要：


// 1. 分配对齐的 DMA 可访问内存
void *dma_buf;
posix_memalign(&dma_buf, BLOCK_SIZE, BUF_SIZE);

// 2. 注册为 fixed buffer（建立 DMA 映射）
struct iovec iov = { .iov_base = dma_buf, .iov_len = BUF_SIZE };
io_uring_register_buffers(&e->ring, &iov, 1);

// 3. 提交 SQE 时标记使用 fixed 缓冲区
sqe->buf_index = 0;       // 缓冲区组 ID
sqe->ioprio  |= IORING_RECVSEND_FIXED_BUF;

这样 NVMe 驱动可以直接将 dma_addr 填入 PRP Entry，完全跳过内核 get_user_pages() 和 kmap() 路径。

五、性能基准测试与分析

5.1 测试环境

组件	配置
CPU	AMD EPYC 7763 64c/128t @ 2.45GHz
内存	DDR4-3200 ECC
存储	Samsung PM1733 7.68TB NVMe SSD (PCIe 4.0 x4)
内核	Linux 6.6 (启用 io_uring + nvme-core polling)
队列深度	256
块大小	4KB

5.2 4K 随机读性能对比（IOPS）

模式	IOPS	延迟(avg)	CPU占用(1核)
pwrite/read (同步)	180K	22μs	100%
libaio + submit batch	850K	12μs	85%
io_uring (块层, 非poll)	1.1M	11μs	78%
io_uring (块层, SQPOLL)	1.3M	9.5μs	65%
uring_cmd passthrough (SQPOLL+poll)	1.8M	7.2μs	48%

核心差异来源：

绕过块层调度器 → 消除合并尝试和调度延迟
消除 bio 拆分逻辑（当 LBA 不连续时特别有用）
uring_cmd 完成直接写回 CQ，避免 workqueue 中转

5.3 延迟稳定性对比（P999）

当吞吐接近极限时：


uring_cmd passthrough P999:  18μs
io_uring block layer P999:  45μs
libaio             P999:  120μs

uring_cmd 的 P999 更低、更稳定，因为它避免了块层的请求竞争和调度不确定性。

六、生产环境工程考量

6.1 何时使用 uring_cmd，何时使用块层 uring？

场景	推荐	理由
通用文件系统（ext4/xfs）	io_uring 块层	利用文件系统缓存、一致性
数据库裸设备管理（如 RocksDB）	uring_cmd passthrough	绕过 FS/fsync 开销
NVMe 设备监控 / SMART 数据	uring_cmd (admin)	原生 NVMe Admin 命令
ZNS SSD 的 Zone Management	uring_cmd passthrough	需要发送 Zone Append 等原生命令
安全擦除 / Format NVM	uring_cmd (admin)	管理类操作无法通过块设备完成

6.2 错误处理与超时

NVMe uring_cmd 失败时的错误码为 NVMe Status Code（非 errno）：


// NVMe 命令常见的失败码
#define NVME_SC_SUCCESS            0x0
#define NVME_SC_INVALID_OPCODE     0x1
#define NVME_SC_INVALID_FIELD      0x2
#define NVME_SC_CMDID_CONFLICT     0x3
#define NVME_SC_DATA_XFER_ERROR    0x4
#define NVME_SC_ABORT_REQUEST      0x7      // 命令被Abort
#define NVME_SC_NS_NOT_READY       0xb      // Namespace 未就绪
#define NVME_SC_LBA_RANGE          0x80     // LBA 越界
#define NVME_SC_CAP_EXCEEDED       0x81     // 容量不足

建议对 sqpoll 模式下的 uring_cmd 实现超时重试机制：


// 设置命令超时（秒）
sqe->timeout_us = 1000000;  // 1s 超时
// 或通过 io_uring 设置 ring 级别超时
struct __kernel_timespec ts = { .tv_sec = 1, .tv_nsec = 0 };
io_uring_register_timeout(&ring, &ts, 1);

6.3 安全边界：IOMMU 与设备映射

uring_cmd 允许用户态直接向设备传递缓冲区地址，这意味着安全问题：

PRP（Physical Region Page）模式：设备作为 Bus Master 直接 DMA 到用户态物理地址。需确保 IOMMU 已保护设备只能访问授权的地址范围。
SGL（Scatter-Gather List）模式：每个条目含物理地址和长度。用户态若篡改可导致任意物理内存 R/W。

生产部署建议：

启用 IOMMU（intel_iommu=on / amd_iommu=on）
配合 VFIO 将 VF 绑定到特定的用户态进程
使用 nvme_mpath 确保多路径下命令不跨节点

七、内核实现揭秘（5.x → 6.x 的演进）

5.15 之前：早期 uring_cmd 实现（仅限 loop 设备）

最初 uring_cmd 仅支持 loop 设备做测试，NVMe 驱动不原生支持。

5.19+：NVMe 核心驱动原生支持

关键提交：nvme: add support for io_uring passthrough commands（2022年），引入了：

nvme_uring_cmd 回调
/dev/ng0n1（NVMe 通用字符设备）接口
Admin 命令和 IO 命令的 passthrough 路径

6.4+：增强功能

支持 cq_run 即时提交完成通知（减少 latency）
Buffer group 注册（避免每次都做 pin）
多文件描述符场景的异步取消（IORING_ASYNC_CANCEL_FD）

八、总结与展望

uring_cmd 代表了 Linux 存储栈演进的重要方向：将内核的"通路"开销压缩到极致，把控制权还给用户空间。对于需要极致 IOPS 和低延迟的存储中间件（KV 引擎、日志系统、分布式存储节点），它已经是 2024+ 时代的事实标准。

未来方向：

vdpa-blk 场景：uring_cmd 将延伸至 virtio-blk 设备，实现 VM 内的高性能 storage
CXL.mem 扩展：CXL Type3 设备通过 uring_cmd 直接映射设备内存
eBPF 辅助过滤：在 uring_cmd 提交路径加入 BPF 钩子实现动态限流/审计

工程人的最终目标，是让每一分硬件能力都不被操作系统浪费。uring_cmd + NVMe Passthrough 正是这一理念的最佳实践。

参考资源

[io_uring 官方 man-pages](https://man7.org/linux/man-pages/dir_generated_by_io_uring.html)
[Linux NVMe 内核源码：drivers/nvme/host/ioctl.c](https://elixir.bootlin.com/linux/latest/source/drivers/nvme/host/ioctl.c)
[SPDK NVMe driver uring_cmd 适配](https://spdk.io/doc/nvme.html)
Jens Axboe, "Efficient IO with io_uring", 2019
Samsung, "NVMe Specification Overview", Rev 2.0

点赞(0) 打赏

本文分类：AI应用开发
本文标签：Linux io_uring NVMe Kernel Storage Performance
浏览次数：6 次浏览
发布日期：2026-09-29 10:21:18
本文链接：https://www.ybb.press/ai-applications/9814.html

Linux io_uring uring_cmd 与 NVMe Passthrough：从内核块层到用户态直路的深度工程实战

Linux io_uring uring_cmd 与 NVMe Passthrough：从内核块层到用户态直路的深度工程实战

引言

一、背景：从 syscall 到 uring_cmd 的演进路径

1.1 传统内核 I/O 栈的开销构成

1.2 io_uring 解决的核心问题

二、uring_cmd 架构深度解析

2.1 uring_cmd 的本质

2.2 驱动注册流程：nvme_uring_cmd 注册入口

2.3 零拷贝共享内存机制

三、NVMe 命令直通详解

3.1 NVMe 命令结构

3.2 多队列亲和性（Multi-Queue Affinity）

四、实战：构建基于 uring_cmd 的 NVMe I/O 引擎

4.1 初始化与设备打开

4.2 提交一个 NVMe Read 请求

4.3 等待完成并处理结果

4.4 高级：IOMMU + Fixed Buffer 零拷贝

五、性能基准测试与分析

5.1 测试环境

5.2 4K 随机读性能对比（IOPS）

5.3 延迟稳定性对比（P999）

六、生产环境工程考量

6.1 何时使用 uring_cmd，何时使用块层 uring？

6.2 错误处理与超时

6.3 安全边界：IOMMU 与设备映射

七、内核实现揭秘（5.x → 6.x 的演进）

5.15 之前：早期 uring_cmd 实现（仅限 loop 设备）

5.19+：NVMe 核心驱动原生支持

6.4+：增强功能

八、总结与展望

参考资源

评论列表共有 0 条评论

发表评论取消回复

Linux io_uring uring_cmd 与 NVMe Passthrough：从内核块层到用户态直路的深度工程实战

Linux io_uring uring_cmd 与 NVMe Passthrough：从内核块层到用户态直路的深度工程实战

引言

一、背景：从 syscall 到 uring_cmd 的演进路径

1.1 传统内核 I/O 栈的开销构成

1.2 io_uring 解决的核心问题

二、uring_cmd 架构深度解析

2.1 uring_cmd 的本质

2.2 驱动注册流程：nvme_uring_cmd 注册入口

2.3 零拷贝共享内存机制

三、NVMe 命令直通详解

3.1 NVMe 命令结构

3.2 多队列亲和性（Multi-Queue Affinity）

四、实战：构建基于 uring_cmd 的 NVMe I/O 引擎

4.1 初始化与设备打开

4.2 提交一个 NVMe Read 请求

4.3 等待完成并处理结果

4.4 高级：IOMMU + Fixed Buffer 零拷贝

五、性能基准测试与分析

5.1 测试环境

5.2 4K 随机读性能对比（IOPS）

5.3 延迟稳定性对比（P999）

六、生产环境工程考量

6.1 何时使用 uring_cmd，何时使用块层 uring？

6.2 错误处理与超时

6.3 安全边界：IOMMU 与设备映射

七、内核实现揭秘（5.x → 6.x 的演进）

5.15 之前：早期 uring_cmd 实现（仅限 loop 设备）

5.19+：NVMe 核心驱动原生支持

6.4+：增强功能

八、总结与展望

参考资源

Linux 内核 io_uring 深度剖析：零 syscall IO 的架构革命与 NVMe 百万 IOPS 实战

Linux 内核 Netlink Protocol 协议族：用户态与内核通信的终极管道

Linux KVM 虚拟化核心技术深入剖析：从 VMX 硬件加速到 QEMU 设备模型

评论列表 共有 0 条评论

发表评论 取消回复

评论列表共有 0 条评论

发表评论取消回复