源码阅读

写入建立对象，读取和淘汰决定缓存系统能否长期稳定运行。本篇沿 Get、Remove 与后台 Eviction 三条路径，观察 Mooncake Store 如何维护副本可读性和容量平衡。 源码基线仍为 777cc77。 一、Get 首先读取的是元数据 Client 不知道对象当前在哪台机器，也不应缓存一份永远不变的地址。 读取开始时，Client 向 Master 请求副本列表。核心入口之一是 MasterService::GetReplicaList。 Master 查找 key 对应的 ObjectMetadata，然后筛选当前允许读取的副本。返回结果包含 Segment、offset、长度和介质等信息。 随后 Client 才通过 Transfer Engine 把对象复制到本地 Buffer。 二、不是列表里的每个副本都可读 一个对象可能同时存在以下副本： 已完成并可读的内存副本。 正在复制的动态副本。 写入失败、等待清理的副本。 位于本地盘的副本。 所在 Segment 正在卸载的副本。 因此 Get 不能只检查 replicas 是否非空。源码中的 HasReadableReplica 以及各种状态判断，负责把控制面中的暂态副本排除掉。 读取正确性的一个重要来源，就是“只从已提交的副本集合中选择”。 三、副本选择优化什么 拥有多个可读副本后，系统还要选择来源。 理想选择通常考虑： 是否位于本机或同一故障域。 介质是 DRAM、VRAM 还是磁盘。 传输协议和拓扑成本。 副本是否正在被回收。 是否能满足本次 Buffer 类型。 Mooncake 将元数据筛选与实际传输分开，使选择策略可以持续演进。Master 保证候选集合合法，Client 和 Transfer Engine 完成具体数据路径。 四、读取失败不等于对象不存在 控制面返回副本后，数据面仍可能失败。例如节点刚好退出、网络断开，或 Segment 已经不可访问。 ...

Mooncake Store 的 Put 不是一次 RPC。它是一段跨越 Client、Master、分配器和 Transfer Engine 的两阶段流程。 本文继续使用提交 777cc77。阅读重点是 real_client.cpp 与 master_service.cpp 中的写入路径。 一、为什么 Put 必须拆成两段 如果 Master 收到 Put 请求后立刻把对象标记为可读，其他 Client 可能读到尚未传完的数据。 如果等所有数据都发送给 Master，再由 Master 落到目标节点，控制面又会成为数据面瓶颈。 Mooncake Store 的做法是：Master 先预留副本，Client 直接传输，最后由 Master 提交状态。 PutStart -> 返回目标副本 -> 直接传输对象 -> PutEnd 这相当于围绕一次数据面操作建立轻量级提交协议。 二、Client 侧的准备工作 Put 开始前，RealClient 需要确定源 Buffer 的位置和长度。源数据可能来自普通主机内存，也可能来自已经注册的加速器内存。 Client 会把大对象切成适合传输的任务。每个任务包含本地地址、远端 Segment、远端 offset 和长度，然后交给 Transfer Engine。 Store 不重复实现 RDMA、TCP 或 GPU Direct 细节。它只把“对象副本”翻译成 Transfer Engine 能执行的传输描述。 ...

Mooncake Transfer Engine 解决的是“怎样快速搬数据”，Mooncake Store 解决的则是更上层的问题：一个对象叫什么、放在哪些节点、有哪些副本、何时可读、空间不足时淘汰谁，以及 Master 重启后怎样恢复这些事实。 本文使用 Mooncake 仓库提交 777cc77 作为源码基线。这个版本的 Store 已经远超早期原型，包含多租户配额、内存与本地盘分层、动态副本、批量淘汰、快照和热备等能力。 一、先看整体分层 Mooncake Store 可以拆成四层。 第一层是上层调用者。vLLM、SGLang 或其他推理系统通过 Python、C++、Rust、Go 等接口访问对象。 第二层是 Client。RealClient 负责本地缓冲区、Master RPC、数据传输、重试和资源清理。 第三层是 Master。MasterService 保存对象元数据，管理 Segment、分配副本、维护租户配额，并驱动淘汰和复制。 第四层是数据资源。DRAM、VRAM、本地 SSD 或其他后端提供真正保存字节的空间，Transfer Engine 执行跨节点传输。 数据不会先发送到 Master，再由 Master 转发。Master 只告诉 Client 应该访问哪些副本，真正的大块数据直接在 Client 与目标内存之间移动。 二、源码目录怎样阅读 建议先抓住以下文件。 mooncake-store/include/real_client.h：Client 的主要状态和接口。 mooncake-store/src/real_client.cpp：Put、Get、Remove 与初始化流程。 mooncake-store/include/master_service.h：Master 的核心数据结构。 mooncake-store/src/master_service.cpp：元数据状态机和控制逻辑。 mooncake-store/include/replica.h：副本描述与状态。 mooncake-store/include/segment.h：可分配存储资源。 mooncake-store/src/allocation_strategy.cpp：副本放置策略。 mooncake-store/src/allocator.cpp：具体空间分配。 mooncake-store/src/transfer_task.cpp：Store 到 Transfer Engine 的任务封装。 不要一开始就顺序阅读体量巨大的 master_service.cpp。更有效的方法是从 RPC 接口出发，沿 PutStart、PutEnd、GetReplicaList 和 Remove 四条链路向下追踪。 ...

Mooncake 仓库同时存在经典 Transfer Engine 和 TENT（Transfer Engine Next）。TENT 不是简单增加一种 Transport，而是重构了 Segment 生命周期、运行时调度、拓扑选择、QoS、故障转移和插件体系。 阅读版本： Mooncake commit: 777cc7782417b6e554cf7c2d53210d0d8f89f5cc 一、为什么需要下一代引擎 经典 TE 已经支持 RDMA、TCP、NVLink 和多种硬件，但随着后端增加，TransferEngineImpl + MultiTransport + 各 Transport 容易出现几个问题： Segment 生命周期分散在元数据和后端注册逻辑中； 传输选择主要依赖静态协议与局部规则； 多 rail、拥塞、故障和 QoS 难以统一调度； 不同后端各自维护进度线程和资源模型； 新硬件接入需要理解大量经典内部约定； 请求取消、deadline 和 failover 缺少统一运行时。 TENT 将这些能力上移到 Runtime 层。 二、目录结构 TENT 核心位于： tent/src/runtime/ ├── transfer_engine_impl.cpp ├── segment.cpp ├── segment_manager.cpp ├── segment_registry.cpp ├── segment_tracker.cpp ├── transport_loader.cpp ├── transport_selector.cpp ├── progress_worker.cpp ├── admission_queue.cpp ├── qos_contract.cpp ├── receiver_credit.cpp ├── topology.cpp ├── control_plane.cpp └── proxy_manager.cpp 外围包括： ...

Transfer Engine 的公共 API 很统一，但 RDMA 和 TCP 的实现差异很大。RDMA 需要 MR、QP、WR 和 CQ；TCP 需要连接、lane、消息 framing 和接收端主动拷贝。本文沿源码比较两条路径，并分析 Batch 状态如何完成。 阅读版本： Mooncake commit: 777cc7782417b6e554cf7c2d53210d0d8f89f5cc 一、Transport 抽象 Transport 基类统一定义： install / uninstall registerLocalMemory / unregisterLocalMemory submitTransfer getTransferStatus allocateBatchID / freeBatchID 它还定义 TransferRequest、TransferStatus 和内部 BufferEntry。 公共抽象要求每个后端回答三个问题： 本地内存如何准备为可传输状态； 请求怎样排队和执行； 如何查询每个 task 的最终状态和字节数。 具体连接模型不属于公共 API。 二、RDMA 初始化 RDMA 后端主要位于： rdma_transport.cpp rdma_context.cpp rdma_endpoint.cpp endpoint_store.cpp worker_pool.cpp 安装阶段通常完成： 枚举 RDMA devices / ports / GID -> 创建每张 HCA 的 context -> 建立 PD、CQ 等资源 -> 启动 worker / poller -> 发布 NIC endpoint metadata -> 准备 endpoint store Mooncake 支持多 HCA、多端口和 GPU 内存，因此一个逻辑请求可能被切到多个 rail 上并行发送。 ...

Mooncake Transfer Engine 的核心抽象不是“远端指针”，而是 Segment + BufferDesc + Metadata。应用注册本地内存后，TE 将地址范围、设备位置和传输协议发布为 Segment 描述，其他节点才能定位并建立连接。 阅读版本： Mooncake commit: 777cc7782417b6e554cf7c2d53210d0d8f89f5cc 一、为什么不能直接发送指针 一个进程中的地址： 0x7f12... 在另一个进程中通常没有意义。即使两台机器都使用相同数值，它们也不指向同一块物理内存。 高性能传输还需要额外信息： 这是 CPU DRAM 还是 GPU VRAM； 对应哪张 GPU； 是否注册成 RDMA MR； rkey 和网卡 endpoint 是什么； 是否能用 NVLink、GPU IPC 或 CXL； 节点当前是否存活； 地址区间是否已经注销。 因此 TE 把地址空间包装成 Segment，并通过元数据服务交换描述。 二、SegmentDesc TransferMetadata::SegmentDesc 是远端发现的中心结构，主要承载： Segment ID Segment 名称 协议或协议集合 本机 RPC / endpoint 信息 BufferDesc 列表 设备与拓扑信息 后端扩展元数据 可以把一个 Segment 理解成某个 TE 实例公开的可传输地址空间： Segment: decode-node-7 ├── Buffer A: CPU metadata pool, protocol=rdma ├── Buffer B: GPU KV pool, protocol=rdma └── Buffer C: GPU KV pool, protocol=hip 同一块 GPU buffer 可以被多个后端注册，从而同时支持： ...

Mooncake Transfer Engine（简称 TE）是 Mooncake 数据平面的基础组件。它不负责决定 KV Cache 应该放在哪里，而是提供统一接口，把一段本地内存搬到远端 Segment，或者从远端 Segment 读取到本地内存。 本文基于 Mooncake 官方仓库： commit: 777cc7782417b6e554cf7c2d53210d0d8f89f5cc commit date: 2026-08-21 当前仓库同时保留经典 Transfer Engine 和下一代 TENT。前三篇先阅读经典实现，第四篇再分析 TENT 如何重构控制面、调度和传输后端。 一、源码布局 核心目录为 mooncake-transfer-engine/： 路径 作用 include/transfer_engine.h 对外 C++ API include/transfer_engine_impl.h 经典实现内部接口 include/transport/transport.h Transport 抽象、请求和状态 include/transfer_metadata.h Segment、Buffer 与元数据接口 src/transfer_engine.cpp 公共 API 转发层，同时兼容经典 TE 与 TENT src/transfer_engine_impl.cpp 初始化、内存注册、Segment 与批次管理 src/multi_transport.cpp 安装和选择具体 Transport src/transport/ RDMA、TCP、NVLink、NVMe-oF、EFA 等后端 tent/ Transfer Engine Next 实现 TE 的经典架构可以概括为： 应用 / Mooncake Store │ ▼ TransferEngine │ ▼ TransferEngineImpl ┌────┼──────────────┐ ▼ ▼ ▼ Metadata MultiTransport Batch 生命周期 │ ┌──────┼───────────────┐ ▼ ▼ ▼ ▼ RDMA TCP NVLink NVMe-oF ... 二、公共 API 是一层门面 TransferEngine 类本身很薄，大多数函数转发给 TransferEngineImpl： ...

前两篇分别介绍了 nvidia-fs 的模块结构，以及 GPU virtual address 到 peer DMA address 的映射。本文沿一次 cuFileRead 对应的内核路径，分析文件 I/O 如何提交、完成和清理，并介绍 batch、稀疏文件、RDMA 与 /proc 诊断接口。 阅读版本： commit: 328d1d8cce1175c013720985c30e123e9a35242c GDS_VERSION: 2.29.4 一、I/O 入口 nvfs_ioctl() 接收： NVFS_IOCTL_READ NVFS_IOCTL_WRITE NVFS_IOCTL_BATCH_IO 单次读写共用两阶段结构： nvfs_io_init(op, ioargs) -> 验证并构造 nvfs_io nvfs_io_start_op(nvfsio) -> 向目标文件提交真正 I/O 分成两步的意义在于：参数验证、对象引用和资源分配都应在进入异步 I/O 前完成。一旦请求提交，完成回调可能很快发生，初始化不完整会造成竞态。 二、nvfs_io_init 做了什么 nvfs_io_init() 是用户参数到内核 I/O 对象的转换层，主要工作包括： 根据文件描述符取得目标 struct file； 检查读写权限； 查找已经注册的 GPU buffer/mgroup； 验证 GPU buffer offset、文件 offset 和长度； 建立影子 page 对应的 iov 或迭代器； 初始化 kiocb、完成函数和统计字段； 为同步、异步和特殊文件系统路径设置标志。 源码还会检查文件系统类型、direct I/O 条件和文件权限。写操作比读操作更复杂，因为它可能涉及文件扩展、页缓存一致性及磁盘空间预分配。 ...

上一篇从 nvfs_init()、字符设备和 ioctl 看到了 nvidia-fs 的外部形态。本文进入 GDS direct path 的核心：怎样把用户分配的 GPU virtual address 变成存储设备能够 DMA 的地址，同时又让 Linux 文件 I/O 栈能够携带它。 阅读版本仍为 NVIDIA gds-nvidia-fs： commit: 328d1d8cce1175c013720985c30e123e9a35242c GDS_VERSION: 2.29.4 一、问题本质 普通块 I/O 最终围绕 bio_vec、struct page、scatterlist 和 DMA mapping 展开。但 cudaMalloc 得到的是 GPU 虚拟地址，对 Linux 页缓存和块层来说，它并不是普通 CPU 内存页。 驱动需要解决三次“翻译”： GPU virtual address -> NVIDIA P2P page table 中的 GPU physical pages -> Linux I/O 栈可携带的影子 struct page -> 某个存储 PCIe 设备可使用的 DMA address 三个地址空间不能混为一谈： ...

nvidia-fs 是 NVIDIA GPUDirect Storage（GDS）的 Linux 内核模块。它不是一种文件系统，而是连接 libcufile、NVIDIA GPU 驱动、Linux 文件 I/O 和支持 GPUDirect 的存储驱动的一层内核协调组件。 这组文章阅读 NVIDIA 官方 gds-nvidia-fs 仓库，采用的版本为： commit: 328d1d8cce1175c013720985c30e123e9a35242c GDS_VERSION: 2.29.4 commit date: 2026-06-01 系列分为三篇： 模块初始化、设备接口与整体架构； GPU 内存注册、页表与 DMA 映射； 文件 I/O、批量请求、完成路径与可观测性。 本文先回答一个问题：加载 nvidia_fs.ko 后，内核里究竟多了什么？ 一、源码目录 核心代码都位于 src/： 文件 职责 nvfs-core.c/.h 字符设备、ioctl、GPU 内存注册和文件 I/O 主流程 nvfs-mod.c 与 NVMe、RDMA 等外部模块动态注册 DMA 回调 nvfs-mmap.c/.h GPU 页对应的影子 struct page 和 mmap 管理 nvfs-dma.c/.h block request 到 GPU DMA 地址的映射 nvfs-batch.c/.h 批量 I/O 提交与完成 nvfs-rdma.c/.h RDMA 注册信息管理 nvfs-pci.c/.h GPU 与存储设备的 PCIe 拓扑、距离和亲和性 nvfs-proc.c、nvfs-stat.c /proc 配置、统计和诊断接口 nvfs-kernel-interface.c 不同 Linux 内核版本的兼容封装 主线集中在 nvfs-core.c，但真正的数据直达能力是多个文件共同完成的。 ...