# nvme-programming-skill **Repository Path**: william_william/nvme-programming-skill ## Basic Information - **Project Name**: nvme-programming-skill - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-11 - **Last Updated**: 2026-08-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 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. 技能结构 ```text 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 安装技能 ```bash # 将技能链接到 Claude Code 技能目录 ln -s "$(pwd)/nvme-programming" ~/.claude/skills/nvme-programming ``` ### 4.2 在 Claude Code 中使用 直接在对话中用自然语言提问： ```text # 理解协议 "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 编译与运行代码示例 ```bash # 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](https://nvmexpress.org/specifications/) — NVMe 规范官方下载 - [nvme-cli](https://github.com/linux-nvme/nvme-cli) — Linux NVMe 命令行管理工具 - [SPDK](https://spdk.io/) — Intel 开源的用户态 NVMe 驱动 - [libnvme](https://github.com/linux-nvme/libnvme) — NVMe 管理库 - [Linux NVMe Driver](https://github.com/torvalds/linux/tree/master/drivers/nvme/host) — Linux 内核 NVMe 驱动源码 - [fio](https://github.com/axboe/fio) — Flexible I/O Tester，NVMe 性能基准测试工具 ## 9. 许可与规范版权 本 Skill 中的协议知识参考自 **NVM Express Base Specification, Revision 2.3**。规范文档版权归 © 2008–2025 NVM Express, Inc. 所有。下载完整规范请访问 https://nvmexpress.org/specifications/。