RDMA101 是一套面向工程实践与系统研究的 RDMA 教程。项目源于 Mooncake Transfer Engine 的开发与推广实践，但并不局限于 Mooncake TE 本身。它试图为希望理解、使用、运维或开发 RDMA 系统的读者提供一条相对完整的学习路径。
Mooncake TE 面向 AI 推理、KVCache 迁移、分布式缓存和异构存储等场景，RDMA 是其中重要的高性能传输方式之一。在实际使用和开发过程中，RDMA 的门槛往往并不只体现为 API 数量多、关系复杂，而是体现为编程模型、软硬配置、错误语义和性能调优之间的相互关联。一个程序能够运行，并不意味着读者已经理解了 RDMA 编程模型；一个程序在示例环境中正确，也不意味着它在真实集群中一定容易部署、排错和优化。
因此，RDMA101 的目标不是替代 Verbs API 手册，也不是编写一份 Mooncake TE 操作说明。它关注的是二者之间的空白：从第一个可运行的 RDMA 程序出发，逐步建立 RDMA 的编程模型，理解一次传输在系统内部的执行过程，掌握常见优化方法，并最终回到真实系统中分析设计取舍。
当前课程分为五篇。每篇内部继续细分章节、实验和案例。
在线文档发布在 https://renfeng.org/rdma101/，项目源码和示例程序托管在 https://github.com/alogfans/RDMA101。
- 第一篇：快速入门 建立实验环境，识别 RDMA 设备，运行基础工具，并完成一个最小 RDMA Hello World。
- 第二篇：编程模型 解释 RDMA 程序的基本结构，重点讨论 MR、QP、CQ、WR、远端地址、访问权限和 completion 等概念之间的关系。
- 第三篇：机制探秘 从应用代码出发，追踪一次 RDMA 请求经过用户态库、驱动、网卡、PCIe、NUMA 和 RoCE 网络的过程。
- 第四篇：优化技巧 讨论 RDMA 性能优化中常见的机制和边界，包括 batching、inline data、queue depth、MR cache 和 polling 等主题。
- 第五篇：实例研究 回到真实系统，分析 Mooncake TE 以及其他 RDMA 系统在数据路径、控制路径、内存管理、故障处理和性能优化方面的设计。
如果目标是尽快使用 Mooncake TE，建议优先阅读第一篇和第二篇。若需要排查性能和稳定性问题，第三篇和第四篇会提供更直接的背景。若希望参与 Mooncake TE 或其他 RDMA 系统的底层开发，建议按顺序阅读全部五篇。
本教程主要面向以下读者：
- 希望使用 Mooncake TE，但需要先理解 RDMA 基础概念的工程人员；
- 希望参与 Mooncake TE 或其他 RDMA 系统开发的开发者；
- 需要处理 RDMA、RoCE 或高性能网络问题的运维和系统工程人员；
- 研究分布式系统、分布式存储、远程内存和 AI 基础设施的学生与研究人员。
读者最好具备基本的 C/C++ 编程能力和 Linux 使用经验。本教程不要求读者事先具备网络开发经验。
对于 Mooncake TE 的使用者和运维人员，本教程希望帮助他们判断运行环境是否满足 RDMA transport 的基本要求，并在面对连接失败、带宽异常、延迟抖动或 QP 状态异常时，能够更快地确定排查方向。
对于系统开发人员，本教程希望帮助他们理解 RDMA transport 的基本代码结构，建立概念与代码实现之间的联系，从而更有效地参与故障修复、性能优化和新功能开发。
对于科研人员，本教程希望提供进入 RDMA 系统研究的必要背景，使其能够阅读相关论文、复现实验，并基于 Mooncake TE 或其他 RDMA 系统开展进一步研究。
此外，RDMA101 也希望沉淀为一份面向 AI 编程助手的 RDMA 领域语料库。通过将术语、对象关系、数据路径和常见错误组织在同一套文档中，可以为代码理解、排错建议、实验步骤生成和性能现象解释提供更可靠的上下文。
项目仍处于早期阶段。当前采用“篇/章”两级结构。每一篇都有 index.md 作为篇首页，具体正文按章节放在对应目录下；第三到第五篇先保留篇首页，后续逐章补充。
docs/
index.md
01-introduction/
index.md
01-hello-world.md
02-programming-model/
index.md
01-one-sided-write.md
03-internals/
index.md
04-optimization/
index.md
05-case-studies/
index.md
后续将优先补充可运行示例、实验环境说明、常见错误排查路径，以及 Mooncake TE 中 RDMA transport 与底层 RDMA 概念之间的对应关系。
欢迎提交文档修正、概念解释、实验代码、排障记录、系统案例和论文解读。尤其欢迎真实环境中的 RDMA 或 Mooncake TE 排障记录，包括问题现象、软硬件环境、排查过程和最终原因。
提交文档贡献前，请注意本项目的出版权安排：贡献者保留自己贡献内容的版权；同时，贡献者一旦向本项目提交文档、示例解释、图示、实验记录或案例分析，即表示同意项目发起人可以在 RDMA101 以及基于 RDMA101 的后续文章、讲义、书籍、课程或其他独立出版物中使用、整理、改写、重组和发布这些贡献内容，包括以独立作者身份出版的作品。除非另有书面约定，此类使用不需要再次取得贡献者许可，也不产生稿酬、版税或其他报酬义务。
RDMA101 的公开文档版本会持续保留。上述出版权安排并不意味着项目作者可以撤回已经公开发布的 RDMA101 文档，也不影响读者和贡献者在 CC BY-NC-SA 4.0 条款下继续访问、分享和改编公开版本。
请通过 issue 或 pull request 参与。
本仓库中的公开文档材料采用 Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License（CC BY-NC-SA 4.0）发布。
这个许可主要适用于教程、文章、图示、解释性示例等文档内容，尤其是 docs/ 目录下的材料。仓库中的源码、可执行示例或软件组件如有单独许可，应以对应文件中的说明为准。
你可以在遵守许可要求的前提下分享和改编这些文档材料：
- 署名：需要注明 RDMA101 和原始贡献者；
- 非商业使用：未经相关版权持有人许可，不得用于商业用途；
- 相同方式共享：如果改编这些材料，需要以相同许可发布改编内容。
每位贡献者保留自己贡献内容的版权。与此同时，项目发起人保留基于 RDMA101 全部材料，包括社区贡献内容，创作、改写、整理并以独立作者身份出版文章、讲义、书籍、课程或其他作品的权利。
RDMA101 的公开文档版本会持续保留，并继续按照 CC BY-NC-SA 4.0 条款提供给公众访问、分享和改编。第三方商业使用 RDMA101 文档材料仍需提前获得相关版权持有人的书面许可。