| name | verbs-to-urma-converter |
| description | 将 RDMA verbs 代码迁移到 URMA API。当用户想要将 infiniband verbs 代码转换为 URMA，或在进行 RDMA/InfiniBand 迁移时，或用户提到 verbs API、ibv_*、rdma，或想要使用 URMA 替代传统 RDMA 时使用此 skill。此 skill 处理完整的迁移，包括 API 映射、数据结构转换和 URMA 特定优化。 |
Verbs 到 URMA 迁移 skill
版本: 1.0 | URMA API 版本: 25.12.0
此 skill 将 RDMA Verbs (libibverbs) 代码迁移到 URMA (统一远程内存访问) API。
何时使用此 skill
在以下情况触发此 skill：
- 用户提到 "verbs"、"libibverbs"、"ibv_*" 函数
- 用户提到 "RDMA"、"InfiniBand"、"RoCE"
- 用户想要将 infiniband 代码迁移到 URMA
- 用户提到 "urma" 和 "迁移"、"转换"、"移植"、"翻译"
- 用户想要将 RDMA 应用程序转换为使用 URMA
迁移硬约束（全过程适用）
以下约束贯穿迁移全过程，任何阶段不得违反：
- 原始文件不可变 — 所有输出放入
urma_output/，保留原始目录结构，原始文件不得修改
- 4 阶段不可跳过 — 阶段 4 捕获编译无法发现的运行时语义错误，跳过会导致资源泄漏、逻辑错误等
- 系统头文件是最高权威 — API 签名、类型定义以
urma_api.h / urma_types.h 为准，与参考文档冲突时以头文件为准
- 结构体必须零初始化 — 使用
{0} 或 {.field = value} 指定初始化，未初始化字段导致未定义行为
- 验证不可跳过 — 每个文件的 patterns/pitfalls 逐项检查，FAIL 不可遗留
- 无头文件不可继续 — 缺乏权威 API 来源时 Agent 会编造不存在的函数，必须先找到头文件
URMA vs Verbs 概览
| RDMA Verbs 概念 | URMA 等价物 |
|---|
| PD (保护域) | URMA 中隐式存在 |
| MR (内存区域) | urma_target_seg_t 通过 urma_register_seg() |
| CQ (完成队列) | urma_jfc_t 通过 urma_create_jfc() |
| QP (队列对) | urma_jetty_t 或 urma_jfs_t + urma_jfr_t |
| SRQ (共享接收队列) | urma_jfr_t 带 share_jfr=1 标志 |
| 完成通道 | urma_jfce_t 通过 urma_create_jfce() |
| LID + GID | urma_eid_t (16字节端点ID，LID 已移除) |
| QPN | JPN (Jetty 对编号) |
| PSN | PSN (包序列号) |
快速参考（完整列表见 mapping.md §1）
| Verbs | URMA |
|---|
ibv_open_device() | urma_create_context() |
ibv_reg_mr() | urma_register_seg() |
ibv_create_cq() | urma_create_jfc() |
ibv_create_qp() | urma_create_jetty() |
ibv_modify_qp(RTR/RTS) | urma_import_jetty() + urma_bind_jetty() |
ibv_post_send() | urma_post_jetty_send_wr() |
迁移工作流程
阶段 1: 准备
目标: 理解源代码并建立完整的 API 映射。
必须交付物（阶段结束时必须产出）:
- 源文件分类清单：哪些含 verbs API（需转换），哪些不含（原样复制）
- Verbs API 清单与 URMA 映射表：每个 API 的处理方式（替换/删除/待确认）
- 传输模式与连接模型判断（RC/RM/UM, import+bind 等）
- 用户确认（展示上述交付物，获得许可后方可进入阶段 2）
必须完成（阶段过程中的硬约束）:
- 系统头文件（urma_api.h / urma_types.h / urma_opcode.h）已找到并读取，作为权威来源
- 常见位置：
/usr/include/ub/umdk/urma/
- 若未找到：要求用户安装或提供路径，不可在没有头文件的情况下继续
- 每个 verbs API 均已在 mapping.md 中查找过等价物
- 无法映射的 API 已在 mapping.md §无URMA等价物 中确认删除，或标注为待确认
- 已了解 URMA 完整资源生命周期（参考 patterns.md §1）
参考查阅路径（建议，非强制）:
- patterns.md §1 → 理解 URMA 完整生命周期
- mapping.md → 逐 API 查找映射
- pitfalls.md → 了解常见错误概览
阶段 2: 转换
目标: 在 urma_output/ 目录中创建转换后的代码，原始文件保持不变。
必须交付物（阶段结束时必须产出）:
urma_output/ 目录，包含所有转换后的文件，保留原始目录结构- 每个文件的验证结果（见验证要求）
- 每个文件的映射项执行追溯（见映射追溯）
- 项目级映射追溯汇总（见映射追溯）
- 编译配置已更新
转换约束（必须满足）:
- 所有转换后的代码放入
urma_output/，原始文件不可修改
- 头文件的类型定义变更必须与所有引用它的源文件保持一致
- 构建文件（Makefile）在所有代码文件转换完成后再更新
- 含 verbs API 最多的文件建议优先转换，以尽早发现映射问题
每个文件的转换内容:
#include <infiniband/verbs.h> → #include <ub/umdk/urma/urma_api.h>- Verbs API 调用 → URMA 等价物（查 mapping.md）；无等价物的调用直接删除（查 mapping.md §无URMA等价物）
- 结构体字段名更新（如
wc.qp_num → cr.local_id）
- 枚举值更新（如
IBV_MTU_1024 → URMA_MTU_1024）
- 连接建立流程更新（查 mapping.md §连接建立决策树，按 RC/RM/UM 选择正确操作）
- 地址交换格式更新（
lid:qpn:psn:gid → jpn:eid，查 mapping.md §地址交换格式决策）
- 清理顺序更新（查 mapping.md §清理顺序决策，按传输模式选择正确顺序）
构建配置必须更新:
- 链接库：
-libverbs → -lurma -lurma_common
- 头文件路径：
infiniband/verbs.h → ub/umdk/urma/urma_api.h
- 若原项目无 Makefile，需创建（链接
-lurma -lurma_common）
映射追溯（防止遗漏映射项）
问题：阶段 1 产出映射计划后，阶段 2 逐文件转换时容易遗漏非核心路径的映射项（如 ibv_create_comp_channel → urma_create_jfce），因为验证只对照 patterns/pitfalls（通用知识），不对照阶段 1 的映射计划（项目特定清单）。
两层追溯机制：
文件级追溯（每个文件转换后立即核对）：
- 核对该文件中直接出现的每个 verbs API 是否已处理
- 不得遗漏：包括条件分支内、辅助函数中、初始化/清理路径中的调用
- 核对结果作为该文件验证的一部分
项目级追溯（所有文件转换后汇总核对）：
- 核对阶段 1 映射表中的每一项是否至少在一个文件中被处理过
- 不得有映射项处于"未处理"状态
- 输出追溯汇总：每项映射的状态（已转换/已删除）及处理所在的文件
验证要求（每个文件转换后必须满足）
必须验证:
- patterns.md 的每个章节：此文件的代码是否符合该 pattern
- pitfalls.md 的每个章节：此文件的代码是否踩了该 pitfall
- 编号对应：P-XX 对应 patterns.md 章节号，PIT-XX 对应 pitfalls.md 章节号
- 文件级映射追溯：该文件中的每个 verbs API 是否已处理
必须达到的状态:
- 每项判断为符合（对应 pattern / 未踩 pitfall）或不适用（N/A，需说明原因，如"此文件无 RDMA 操作"）
- 不符合项(FAIL) 必须修复后重新验证，不得遗留
- 不得跳过任何章节 — 遍历参考文件的实际章节编号
- 编号来源于参考文件的实际章节，当参考文件新增章节时自动包含
输出方式: 逐项列出每章节的验证结果与判断依据，确保可审计。不得以"已验证"等笼统表述替代逐项检查。
阶段 3: 验证
目标: 编译、链接并验证转换后的代码。
必须交付物（阶段结束时必须产出）:
- 编译成功（无错误）
- 链接正确（依赖
liburma.so 和 liburma_common.so）
必须完成（阶段过程中的硬约束）:
- 编译通过，无未定义引用、类型不匹配等错误
- 链接验证确认依赖正确的 URMA 库
- 编译错误已排查并修复
常见编译错误与排查方向:
| 错误类型 | 可能原因 | 排查方向 |
|---|
| 未定义引用 | API 名称错误 | 查 urma_api.h 中的正确函数签名 |
| 没有名为 'jetty_id' 的成员 | 字段名错误 | cr.local_id 而非 cr.jetty_id（见 mapping.md） |
| 宏重定义 | 头文件中已存在该宏 | 删除自己定义的宏 |
| 类型不匹配 | 参数类型错误 | 匹配 urma_api.h 中的确切签名 |
| 缺少头文件 | 未包含正确头文件 | 添加 #include <ub/umdk/urma/urma_api.h> |
阶段 4: 审查和优化（强制性）
目标: 以项目视角检查跨文件语义问题，验证编译之外的正确性。
为什么不能只看单个文件: 资源生命周期跨文件（A 文件创建、B 文件销毁）、类型声明在 .h 中修改但 .c 引用未同步、Verbs 残留可能仅出现在"原样复制"的工具文件中——这些都不是单文件视角能发现的问题。
必须交付物（阶段结束时必须产出）:
- 跨文件一致性确认：头文件类型定义与源文件引用同步、共享变量声明一致
- 资源生命周期完整性：每个 URMA 资源的创建→销毁链无遗漏
- Verbs 残留为零：
urma_output/ 中无任何 ibv_* / verbs.h / infiniband 引用
- 运行时语义正确性：import/unimport 配对、wait/ack 配对、清理路径完整
- 用户确认的审查结果摘要
必须完成（阶段过程中的硬约束）:
- 头文件→源文件一致性：.h 中修改的类型定义，确认所有引用该 .h 的 .c 文件均已同步更新，无残留旧类型
- 共享变量一致性：跨文件共享的变量（如全局
ibv_cq *g_cq → urma_jfc_t *g_jfc），确认 .h 声明和所有 .c 使用一致
- 资源归属与生命周期：梳理每个 URMA 资源（context、jfc、jfr、jetty、tseg、tjetty、import_seg）在哪个文件创建、哪个文件销毁，确认创建→销毁链完整无遗漏
- Verbs 残留扫描：确认
urma_output/ 中无任何 Verbs 残留引用
- 重新审视 N/A 项：阶段 2 中标记 N/A 但跨文件看可能适用的项（例如单文件不含 RDMA 代码，但其他文件会触发 import_seg 要求）
- 清理路径完整性：每个成功路径是否都有对应的完整清理序列（unbind→unimport→delete）
- 资源泄漏检查：每个
urma_import_* 是否都有对应的 urma_unimport_*；每个 urma_wait_jfc 是否都有 urma_ack_jfc
修复并重编译，直到干净。
阶段 4 检查点
向用户展示以下信息：
- 阶段 4 中发现并修复的问题
- 遗留风险（已知但无法在迁移中解决的问题）
- 新增知识（迁移中发现的新映射/patterns/pitfalls）
- 是否将新增知识添加到参考文件（需用户同意）
输出格式
强制性: 所有转换后的代码放入新目录。原始文件保持不变。
最终输出结构:
project/
├── (原始文件 - 不变)
└── urma_output/
├── (转换后的 .c 文件)
├── (转换后的 .h 文件)
├── (原样复制的非 verbs 文件)
└── Makefile
贡献新知识
成功迁移后，你可能会发现新的映射、patterns 或 pitfalls。
步骤:
-
收集新发现:
- 新 API 映射 (verbs → urma)
- 新结构体字段映射
- 新代码 patterns
- 新 pitfalls
-
向用户展示发现:
我在迁移过程中发现了以下新信息:
[清晰列出发现]
是否要将这些添加到参考文件中？
-
如果用户同意:
- 新 API 映射: 添加到
references/mapping.md
- 新代码 Patterns: 添加到
references/patterns.md
- 新 Pitfalls: 添加到
references/pitfalls.md
-
如果用户拒绝:
这确保 skill 随着实际使用不断改进，但仅在用户同意时进行。
参考文件概览
| 文件 | 用途 | Agent 使用场景 |
|---|
mapping.md | Verbs → URMA 查找表 | "X 的 URMA 等价物是什么？" |
patterns.md | 完整代码模式 | "展示如何编写 X" |
pitfalls.md | 已知问题和修复 | "为什么 X 失败？" |
urma_sample.md | 完整工作示例 (~1280 行) | 仅当 patterns.md 不够详细时按需阅读 |
推荐阅读顺序:
mapping.md - 学习 API 等价物patterns.md - 查看完整工作代码pitfalls.md - 避免常见错误urma_sample.md - 仅当需要完整参考实现时阅读（~1280 行，按需加载）
