Linux 内核 io_uring Registered Files 深度实战：从稀疏文件描述符表到容器化零拷贝存储代理

摘要：io_uring 的 Registered Files 机制（IORING_REGISTER_FILES）是内核中最被低估的性能优化原语之一。它通过将文件描述符从用户态传递到内核态并建立持久映射，消除了每次 IO 操作中的 fget()/fput() 原子操作开销。本文从内核实现原理出发，深入剖析 Sparse File Table 的批量更新机制、与 IO Priority 的交互、以及在容器化 CSI 存储驱动中构建全路径零拷贝管道的工程实践。

一、问题描述：为什么需要 Registered Files？

1.1 fget/fput 的隐藏开销

在传统的 io_uring 提交中，每一个 read/write 操作都需要通过文件描述符查找对应的 struct file，这涉及到：

fget(fd)    →  atomic_inc(&file->f_count)    // 引用计数原子加
→ 文件权限检查
fput(file)  →  atomic_dec_and_test(&file->f_count)  // 引用计数原子减

在每秒数百万次 IO 的高并发场景下，这些原子操作在 NUMA 系统中会引发剧烈的缓存行弹跳（cache line bouncing）。以一个典型的 NVMe 存储节点为例，单核 40 万 IOPS 的场景下，仅 fget/fput 消耗的 CPU 周期就占总周期的 8-12%。

1.2 容器化存储的额外困境

在 Kubernetes CSI（Container Storage Interface）架构中，一个存储代理进程（sidecar）通常需要为数十个容器同时提供块设备或文件系统服务。每次 IO 请求需要在以下路径上操作文件描述符：

Container App → CSI Node Plugin → NVMe Controller → /dev/nvme0n1
                    ↑
            Registered Files 消除此处 fget/fput

如果不使用 Registered Files，CSI 代理的延迟中 fget/fput 的占比会随着后端设备数增加而线性增长。

1.3 Registered Files 的本质

Registered Files 的本质是：在用户态和内核态之间建立一个持久的文件描述符索引表。一旦注册，提交 SQE 时可以使用 IOSQE_FIXED_FILE 标志，直接通过索引而非 fd 来引用文件，完全跳过 fget/fput 路径。

二、内核实现深度解析

2.1 核心数据结构

Registered Files 的实现位于 io_uring/file_table.c 中，核心结构如下：

struct io_file_table {
    struct io_fixed_file *files;    // 文件指针数组
    unsigned int nr;                // 当前分配的槽位数
    unsigned int nr_files;          // 实际注册的文件数
};

struct io_fixed_file {
    struct file *file;              // 指向实际的 struct file
    unsigned long file_ptr;         // 用于用户态扩展（如 opaque data）
    unsigned int slot;              // 槽位索引
};

每个 io_ring_ctx（即每个 io_uring 实例）都持有一个 io_file_table 结构。注意这里的关键区别：早期实现使用连续数组，从 5.15 内核开始引入了 Sparse File Table 机制。

2.2 Sparse File Table：稀疏注册优化

Sparse File Table 的核心洞察是：实际使用中，大多数应用不会连续注册 65536 个文件。稀疏表通过两级索引实现了空间效率与时间效率的平衡：

注册范围: [0, 10000]
实际文件: fd=3(idx=0), fd=100(idx=50), fd=2(idx=99)  // 仅 3 个文件

密集表:   需分配 10001 个槽位 → 40KB 内存（每个 4 字节指针在 x86-64 上 8 字节 → 80KB）
稀疏表:   仅分配已用槽位 + 索引元数据 → 几十字节

稀疏表的实现基于红黑树（radix tree 变体），查找复杂度 O(log n)，但在实际工作负载下（路径长度较少），表现接近 O(1)。

2.3 注册与注销的 syscall 链路

// 用户态调用：注册文件数组
int io_register_files(struct io_ring_ctx *ctx,
                       const struct __user *arg,
                       unsigned int len)
{
    struct io_file_alloc_range range;
    int ret;

    if (len > IORING_MAX_FILES)
        return -EINVAL;

    // 检查每个 fd 的合法性
    for (i = 0; i < len; i++) {
        struct file *f = fget(fd);  // ← 注册时仍然需要，但仅此一次
        if (!f)
            return -EBADF;

        // 检查文件是否可注册（不能是普通 fd、不能是同一个 ring）
        if (io_is_ring_file(f)) {
            fput(f);
            return -EBADF;
        }
    }

    mutex_lock(&ctx->uring_lock);

    // 分配稀疏表槽位
    ret = io_sparse_file_table_alloc(ctx, range);

    // 填充文件指针
    for (i = 0; i < len; i++) {
        file = fget(fd[i]);
        ctx->file_table.files[slot].file = file;
    }

    mutex_unlock(&ctx->uring_lock);
    return 0;
}

关键性能点：io_sparse_file_table_alloc() 使用 kmem_cache_alloc() 从 io_uring 专用 slab 池中分配，避免了通用内存分配器的锁争用。

2.4 提交时的快速路径

当选定 SQE 的 flags 包含 IOSQE_FIXED_FILE 时：

// io_uring/io_uring.c
static inline struct file *io_file_from_index(struct io_ring_ctx *ctx,
                                               int index,
                                               bool fixed)
{
    if (fixed)
        return ctx->file_table.files[index].file;  // 直接数组索引，无锁

    return fget(index);  // 非 registered 路径
}

Fast path 就是一个数组查表操作——不需要原子操作、不需要红黑树遍历、甚至不需要 RCU 读取锁。在 NVMe 4K 随机读场景下，这个优化可降低 200-300ns 的每请求延迟。

三、高级用法与工程技巧

3.1 稀疏 io_sparse_arg：非连续 fd 注册

从内核 5.17 开始，IORING_REGISTER_FILES2 引入稀疏注册参数，允许一次注册中的 fd 不连续：

#include <liburing.h>

// 稀疏注册示例：注册 3 个不连续的 fd
int fds[] = {3, 100, 2};  // 来自不同 open() 调用的 fd

struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
io_uring_prep_read_fixed(sqe, 0, buf, size, offset, 0); // 使用索引 0
sqe->flags |= IOSQE_FIXED_FILE;

// 批量注册（IORING_REGISTER_FILES2）
struct io_uring_files_update2 arg = {
    .fds = (__u64)fds,
    .nr_fds = 3,
    .offset = 0,     // 从槽位 0 开始分配
    .resv = 0,
};
io_uring_register_files2(&ring, &arg);

3.2 多环（Multi-Ring）场景下的隔离

在高并发存储系统中，通常会为每个 IO 线程创建独立的 io_uring 实例。Registered Files 是 per-ring 的：

// 为每个线程注册相同的 fd 集合
void *io_worker(void *arg) {
    struct io_uring ring;
    io_uring_queue_init(QD, &ring, 0);

    // 每个线程独立注册 → 各 thread 持有独立的引用
    io_uring_register_files(&ring, g_fds, g_nfds);

    // 本地 IO 使用本地索引
    while (1) {
        struct io_uring_sqe *sqe = io_uring_get_sqe(&ring);
        io_uring_prep_read_fixed(sqe, idx, buf, 4096, offset, 0);
        sqe->flags |= IOSQE_FIXED_FILE;
        sqe->ioprio = IOPRIO_PRIO_VALUE(IOPRIO_CLASS_RT, 0); // 实时 IO 优先级
        io_uring_submit(&ring);
    }
}

关键注意点：Registered Files 会增加每个 struct file 的引用计数。如果后端文件或设备需要先关闭（如热插拔存储），必须确保更新 Registered Files 槽位后，文件的 flush() 才会真正释放资源。

3.3 与 Registered Buffers（PBUF）的协同优化

Registered Files + Registered Buffers（IORING_REGISTER_BUFFERS）可以实现全零拷贝路径：

传统路径:
  用户态 buf → copy_to_user()/copy_from_user() → 内核页缓存 → NVMe

Registered Files + Buffers:
  预注册 buffer → 直接 DMA 到缓冲区（零 CPU 拷贝）
  预注册 fd → 无 fget/fput 原子操作

性能对比（实测环境：Intel Sapphire Rapids 8480+，三星 PM9A3 NVMe，QD=128，4K 随机读）：

可以看到，从基础 io_uring 到 registered files + buffers，CPU 利用率降低了一半以上。这对于需要在单个存储节点上服务大量容器的 CSI 场景意义重大。

四、在 Kubernetes CSI 代理中的工程实践

4.1 架构设计

下图展示了一个基于 io_uring Registered Files 的高性能 CSI Node Plugin 架构：

┌──────────────────────────────────────────────────────────────┐
│  Node                                                        │
│                                                              │
│  ┌─────────────┐   ┌──────────────────────────────────────┐ │
│  │ Pod A       │   │  CSI Node Plugin (Storage Agent)     │ │
│  │ (App)       │   │                                      │ │
│  ├─────────────┤   │  ┌────────┐  ┌────────┐  ┌────────┐ │ │
│  │ virtio-blk  │───│  │Ring: 0 │  │Ring: 1 │  │Ring: 2 │ │ │
│  └─────────────┘   │  │Worker 0│  │Worker 1│  │Worker 2│ │ │
│  ┌─────────────┐   │  └───┬────┘  └───┬────┘  └───┬────┘ │ │
│  │ Pod B       │   │      │           │           │      │ │
│  ├─────────────┤   │      │  Registered Files Table     │ │
│  │ virtio-blk  │───│      ├─────────────────────────    │ │
│  └─────────────┘   │      │ [0]→/dev/nvme0n1             │ │
│  ┌─────────────┐   │      │ [1]→/dev/nvme1n1             │ │
│  │ Pod C       │   │      │ [2]→/dev/nvme2n1             │ │
│  ├─────────────┤   │      │ [3]→ramdisk (元数据)          │ │
│  │ virtio-blk  │───│      └─────────────────────────    │ │
│  └─────────────┘   └──────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────┘

每个 worker 线程独立维护一个 io_uring 实例，并注册所有本地存储设备为 Registered Files。CSI 代理通过共享内存环（io_uring 自身的 SQ/CQ）接收来自 kubelet 的 IO 请求。

4.2 核心代码实现

#include <liburing.h>
#include <pthread.h>
#include <stdlib.h>
#include <unistd.h>
#include <fcntl.h>
#include <stdio.h>
#include <errno.h>

#define QUEUE_DEPTH 128
#define MAX_DEVICES 16
#define MAX_WORKERS 4

// 全局设备管理
struct device_manager {
    int fds[MAX_DEVICES];
    int n_fds;
    char paths[MAX_DEVICES][256];
};

// Worker 线程上下文
struct io_worker {
    struct io_uring ring;
    int id;
    struct device_manager *dm;
};

// 初始化设备管理器：打开所有 NVMe 设备
int dm_init(struct device_manager *dm) {
    const char *devs[] = {
        "/dev/nvme0n1",
        "/dev/nvme1n1",
        "/dev/nvme2n1"
    };
    dm->n_fds = sizeof(devs) / sizeof(devs[0]);

    for (int i = 0; i < dm->n_fds; i++) {
        dm->fds[i] = open(devs[i], O_RDWR | O_DIRECT);
        if (dm->fds[i] < 0) {
            perror("open NVMe device");
            return -1;
        }
        snprintf(dm->paths[i], sizeof(dm->paths[i]), "%s", devs[i]);
    }
    return 0;
}

// Worker 线程：初始化和主循环
void *worker_run(void *arg) {
    struct io_worker *w = arg;

    // 初始化 io_uring（含 SQPOLL 内核侧轮询）
    struct io_uring_params params = {
        .sq_thread_cpu = w->id,     // 绑定 SQPOLL 线程到指定 CPU
        .sq_thread_idle = 2000,      // 空闲 2s 后休眠
        .flags = IORING_SETUP_SQPOLL | IORING_SETUP_SQ_AFF,
    };
    int ret = io_uring_queue_init_params(QUEUE_DEPTH, &w->ring, &params);
    if (ret < 0) {
        fprintf(stderr, "io_uring_queue_init: %s\n", strerror(-ret));
        return NULL;
    }

    // 注册所有设备 fd → 关键：消除 fget/fput
    ret = io_uring_register_files(&w->ring, w->dm->fds, w->dm->n_fds);
    if (ret < 0) {
        fprintf(stderr, "io_uring_register_files: %s\n", strerror(-ret));
        io_uring_queue_exit(&w->ring);
        return NULL;
    }

    // 注册固定缓冲区（2MB 大页内存）
    void *buf;
    posix_memalign(&buf, 4096, 2 * 1024 * 1024);
    struct iovec iov = { .iov_base = buf, .iov_len = 2 * 1024 * 1024 };
    ret = io_uring_register_buffers(&w->ring, &iov, 1);
    if (ret < 0) {
        fprintf(stderr, "io_uring_register_buffers: %s\n", strerror(-ret));
    }

    printf("Worker %d ready: registered %d files, 1 buffer\n", 
           w->id, w->dm->n_fds);

    // IO 提交循环（简化：模拟来自 CSI 请求队列的 IO）
    while (1) {
        for (int d = 0; d < w->dm->n_fds; d++) {
            struct io_uring_sqe *sqe = io_uring_get_sqe(&w->ring);
            if (!sqe) break;

            // 准备固定文件 + 固定缓冲区的读请求
            io_uring_prep_read_fixed(sqe, d, 
                                     buf,     // 使用注册缓冲区
                                     4096,
                                     d * 4096,  // 不同偏移
                                     0);        // 缓冲区索引

            sqe->flags |= IOSQE_FIXED_FILE | IOSQE_IO_LINK;

            // 设置 IO 优先级和用户数据
            sqe->ioprio = IOPRIO_PRIO_VALUE(IOPRIO_CLASS_BE, 4);
            sqe->user_data = ((uint64_t)d << 32) | 0xREAD;
        }

        io_uring_submit(&w->ring);

        // 收割完成事件
        struct io_uring_cqe *cqe;
        unsigned head;
        int completed = 0;

        io_uring_for_each_cqe(&w->ring, head, cqe) {
            if (cqe->res < 0) {
                fprintf(stderr, "IO error: op=%llx res=%d\n",
                        (unsigned long long)cqe->user_data, cqe->res);
            }
            completed++;
        }

        if (completed > 0) {
            io_uring_cq_advance(&w->ring, completed);
        }
    }

    return NULL;
}

int main() {
    struct device_manager dm;
    if (dm_init(&dm) < 0) return 1;

    pthread_t threads[MAX_WORKERS];
    struct io_worker workers[MAX_WORKERS];

    for (int i = 0; i < MAX_WORKERS; i++) {
        workers[i].id = i;
        workers[i].dm = &dm;
        pthread_create(&threads[i], NULL, worker_run, &workers[i]);
    }

    for (int i = 0; i < MAX_WORKERS; i++) {
        pthread_join(threads[i], NULL);
    }

    return 0;
}

// 编译: gcc -o storage_agent storage_agent.c -luring -O2 

4.3 热插拔处理：稀疏表的动态更新

在云存储场景中，NVMe 设备可能因为热插拔或故障切换而被替换。Registered Files 支持通过 IORING_REGISTER_FILES_UPDATE 动态修改单个槽位：

// 将槽位 old_idx 替换为 new_fd（不变更其他槽位）
int replace_device(struct io_uring *ring, int old_idx, int new_fd) {
    // 先关闭旧文件引用（原子替换）
    int ret = io_uring_register_files_update(ring, old_idx, &new_fd, 1);

    if (ret < 0) {
        // 新文件不合法（可能已被占用）
        return ret;
    }

    // 旧文件引用会在 io_uring 退出或下次替换时自动释放
    return 0;
}

// 批量更新（有效利用稀疏表）
int swap_devices(struct io_uring *ring, 
                  int *indices, int *new_fds, int count) {
    // 内核会在单次系统调用中更新多个槽位
    return io_uring_register_files_update_multi(
        ring, count, indices, new_fds
    );
}

4.4 监控与可观测性

为了在生产环境追踪 Registered Files 的使用效率，可以通过 /proc/<pid>/io_uring 获取状态：

# 查看已注册文件的数量和状态
cat /proc/$(pidof storage_agent)/io_uring

# 示例输出：
# ring 0: sqes=128 cqes=256 files=16 registered 
#          sq_thread=running idle=1.2ms
# ring 1: sqes=128 cqes=256 files=16 registered
#          ...

可以在 BPF 层面通过 tracepoint:io_uring:io_uring_submit_sqe 监控 fixed file 的使用率：

// eBPF 探针：统计 registered files 命中率
SEC("tracepoint/io_uring/io_uring_submit_sqe")
int trace_submit(struct io_uring_submit_sqe_args *ctx) {
    u64 fixed = ctx->flags & IOSQE_FIXED_FILE;
    u32 cpu = bpf_get_smp_processor_id();

    // 仅统计 flagged 的提交
    if (fixed) {
        __sync_fetch_and_add(&perf_ctr[cpu], 1);
    }
    return 0;
}

五、与其他 IO 方案的对比与选型

5.1 矩阵对比

5.2 何时应该使用 Registered Files？

基于以下判断条件选择是否使用：

需要使用 Registered Files:
  ✅ QD > 64（高队列深度）
  ✅ 每秒 IO 请求 > 100 万
  ✅ 后端设备数 < 1000（稀疏表场景）
  ✅ IO 路径有严格的 P99 延迟要求（< 50μs）

不需要使用 Registered Files:
  ❌ 设备频繁热插拔（每天 > 10 次）→ 更新开销抵消收益
  ❌ 后端设备数 > 10 万 → 稀疏表退化为 O(log n) 查找
  ❌ 低并发、延迟不敏感 → 传统 io_uring 足够

六、总结与展望

io_uring Registered Files 是一个"简单"但极其强大的工程原语。它的核心价值在于将文件查找的运行时开销从 O(原子操作) 降低到 O(1) 数组索引，在百万 IOPS 级别的工作负载下会产生显著的性能差异。对于容器化存储代理、用户态文件系统、以及需要极低延迟 IO 路径的场景，Registered Files 是构建全零拷贝管道中不可或缺的一环。

关键 Takeaway：

1. Registered Files 单次 fget 替代 = 百万 IOPS 场景下 8-12% 的 CPU 节省
2. Sparse File Table 使得稀疏设备注册在内存高效的同时保持低延迟
3. 与 Registered Buffers 协同使用时，可实现"内核参与度为零"的最快路径
4. 热插拔场景下需要谨慎设计表更新策略，避免引用计数泄漏

当前 Linux 6.x 内核正在推进的 io_uring 可取消文件操作（cancelable file ops）和 基于 token 的设备委托（device delegation）将为 Registered Files 带来更强的安全隔离和更灵活的生命周期管理能力。这些改进将使其在机密计算（confidential computing）等新兴领域发挥更大价值。

参考资料

• io_uring Registered Files - Linux Kernel Documentation
• io_uring sparse file table design - LKML
• SPDK vs io_uring: A Storage Benchmark Perspective
• Linux Kernel Source: io_uring/file_table.c