NVMe 应用层高性能存储编程 Skill

一套面向 AI IDE（Claude Code 等）的 NVMe 编程技能。将 NVMe 协议知识、命令构造、队列管理、性能调优和错误处理编码为 AI 可执行的指令，辅助开发者进行用户态 NVMe 高性能存储应用开发。

---

1. 核心特性

• 协议知识全覆盖：涵盖 NVMe Base Spec 2.3 的核心内容 — 控制器模型、BAR0 寄存器、SQ/CQ 队列模型、PRP/SGL 数据布局、Admin & NVM 命令集
• 系统化性能调优：9 步调优流程 + 11 项检查清单 + 10 个常见陷阱的诊断与修复
• 可搜索 Spec 原文：从 NVMe 2.3 Base Spec PDF 提取的关键章节（~2MB），支持 grep 精确搜索
• 可编译代码示例：4 个基于 Linux NVMe ioctl 接口的完整 C 示例，覆盖 Identify、Read/Write、多队列配置、性能调优

2. 技能结构

nvme-programming/
├── SKILL.md                         ← 主技能文件（~520 行）：核心哲学、工作流、速查表、陷阱表
├── README.md                        ← 本文件
├── CLAUDE.md                        ← 项目级指引：结构说明、编译命令、扩展指南
├── spec/                            ← 规范文档 PDF
│   └── NVM-Express-Base-Specification-Revision-2.3-2025.08.01-Ratified.pdf
├── references/                      ← 结构化参考文档（人可读）
│   ├── architecture.md              ← 控制器模型、BAR0 寄存器字段、初始化序列
│   ├── command-sets.md              ← Admin & NVM I/O 命令 opcode、参数、示例代码
│   ├── data-structures.md           ← SQE(64B)、CQE(16B)、PRP、SGL 完整格式
│   ├── queue-management.md          ← SQ/CQ 生命周期、Doorbell、3 种多队列模式
│   ├── namespace-mgmt.md            ← NS 创建/删除/附加/格式化、LBA 格式选择
│   ├── performance-tuning.md        ← 9 步调优流程、fio 基准测试、NUMA、中断合并
│   ├── error-handling.md            ← CQE 状态码全表、分级恢复、SMART 监控
│   ├── specifications-page.md       ← nvmexpress.org 规范列表索引
│   └── base-spec-docs/              ← 🔍 NVMe Base Spec 2.3 原文（可 grep 搜索）
│       ├── INDEX.md                 ← 搜索指南
│       ├── ch03-architecture.txt    ← Controller Properties、寄存器、队列模型、初始化
│       ├── ch04-data-structures.txt ← SQE、CQE、PRP、SGL 完整定义
│       ├── ch05-admin-commands.txt  ← Identify、Set/Get Features、Create SQ/CQ 等
│       ├── ch07-io-commands.txt     ← Flush、Cancel、Reservation 命令
│       ├── ch09-error-reporting.txt ← 错误报告与恢复
│       └── annex-b-host-considerations.txt ← 主机端实现指南
└── examples/                        ← 可编译的 C 代码示例
    ├── admin-identify.c             ← Identify Controller & Namespace，解析能力结构
    ├── nvm-read-write.c             ← NVM Read/Write + PRP + Flush + 数据验证
    ├── multi-queue-setup.c          ← 多 I/O SQ/CQ 对创建 + CPU/NUMA 绑定
    └── perf-tuning-example.c        ← 中断合并、仲裁、Write Cache、SMART 设置

总计：22 个文件，~2.1MB

3. 触发关键词

当对话中出现以下关键词时，Claude Code 会自动激活此技能：

英文: NVMe, SSD, nvme, namespace, PRP, SGL, submission queue, completion queue, SQ, CQ, doorbell, SPDK, libnvme, NVMe-oF, interrupt coalescing, queue depth

中文: 队列深度, 中断合并, 多队列, ZNS

4. 快速开始

4.1 安装技能

# 将技能链接到 Claude Code 技能目录
ln -s "$(pwd)/nvme-programming" ~/.claude/skills/nvme-programming

4.2 在 Claude Code 中使用

直接在对话中用自然语言提问：

# 理解协议
"NVMe 命令的生命周期是怎样的？SQE 和 CQE 的格式是什么？"

# 编写代码
"帮我写一个 NVMe Identify Controller 的 C 程序，用 Linux ioctl 接口"

# 配置多队列
"我有 8 核 CPU，如何给 NVMe SSD 配置多队列？帮我写一个完整的初始化程序"

# 性能调优
"NVMe 随机 4K 读的 IOPS 不够高，帮我分析可能的原因并给出优化方案"

# 排查错误
"NVMe Write 命令返回 CQE status=0x0302，这是什么错误？怎么修复？"

# 搜索 Spec 原文
"帮我在 spec 里搜索 Interrupt Coalescing 的 TIME 和 THR 参数定义"

4.3 编译与运行代码示例

# Identify
gcc -O2 -Wall -o admin-identify examples/admin-identify.c
sudo ./admin-identify /dev/nvme0

# Read/Write（⚠️ 会写入 namespace 最后 8 个 block）
gcc -O2 -Wall -o nvm-read-write examples/nvm-read-write.c
sudo ./nvm-read-write /dev/nvme0

# Multi-Queue（需要 libnuma-dev）
gcc -O2 -Wall -o multi-queue-setup examples/multi-queue-setup.c -lnuma
sudo ./multi-queue-setup /dev/nvme0 64

# Perf Tuning
gcc -O2 -Wall -o perf-tuning-example examples/perf-tuning-example.c
sudo ./perf-tuning-example /dev/nvme0

5. 三层知识体系

层	内容	何时加载	文件示例
SKILL.md 概要层	核心哲学、工作流、速查表、陷阱表	每次触发 Skill 时自动加载	520 行，可直接读完
references/ 详解层	结构化详解（含字段表格、代码片段）	深入某个主题时按需加载	每个文件 200–350 行
base-spec-docs/ 原文层	NVMe 2.3 Spec 章节原文	grep 精确搜索字段定义时	6 个文件，~2MB

6. 使用场景

场景	推荐操作
首次学习 NVMe 编程	阅读 SKILL.md 的 Architecture + Command Construction + PRP 部分
编写 NVMe 用户态驱动	参考 examples/admin-identify.c + references/architecture.md
性能压测与调优	按 references/performance-tuning.md 的 9 步流程操作
排查命令失败	查 references/error-handling.md 的 CQE 状态码表和分级恢复策略
配置多队列 NUMA 亲和	参考 examples/multi-queue-setup.c + references/queue-management.md
查找 Spec 某个字段的准确定义	用 grep -r "关键词" references/base-spec-docs/ 搜索原文

7. 技术设计决策

• 语言：C + Linux NVMe ioctl 接口（linux/nvme_ioctl.h）。无需外部依赖，是 Linux 上最通用的 NVMe 编程方式
• 范围：用户态应用层 — 不涉及内核驱动开发。聚焦命令构造、队列管理、性能调优
• 模式：遵循 cuda-knowledge skill 的三层渐进式结构（概要→详解→原文）
• 语言约定：Agent 面（SKILL.md 正文、references）使用英文；人面（README、注释）使用中文

8. 外部参考资源

• NVMe Specifications — NVMe 规范官方下载
• nvme-cli — Linux NVMe 命令行管理工具
• SPDK — Intel 开源的用户态 NVMe 驱动
• libnvme — NVMe 管理库
• Linux NVMe Driver — Linux 内核 NVMe 驱动源码
• fio — Flexible I/O Tester，NVMe 性能基准测试工具

9. 许可与规范版权

本 Skill 中的协议知识参考自 NVM Express Base Specification, Revision 2.3。规范文档版权归 © 2008–2025 NVM Express, Inc. 所有。下载完整规范请访问 https://nvmexpress.org/specifications/。