DOCA调试Skill doca-debug

开源协议	Apache-2.0
名称	doca-debug
描述	> 当用户调试任何DOCA症状时使用此技能——构建无法编译、链接步骤无法解析doca_符号、运行时调用返回DOCA_ERROR_、服务或工具静默，或遇到栈跟踪/valgrind/核心转储——并且需要分层阶梯（安装→版本→构建→链接→运行时→程序→驱动）、详细级别控制（–sdk-log-level、DOCA_LOG_LEVEL、doca-{lib}-trace构建风格）、容器调试约束，或如何为开发者论坛帖子捕获状态。即使当用户不说“DOCA debug”时也触发——隐含的说法包括“undefined reference to doca_*”、“如何获取更多日志”、“数据包未到达网络线路”、“doca_caps没有返回内容”或“容器内hugepages为空”。对于库特定调试（Flow管道跟踪、RDMA QP、Comch统计）、环境类pkg-config或hugepages症状、DOCA_ERROR_*分类和生命周期解释，以及性能或事件响应工作，请拒绝并路由到其他技能。 metadata: kind: library compatibility: > 阅读此技能不需要安装DOCA（它是加载到任何DOCA工件技能上的覆盖层）；其中的验证步骤需要在/opt/mellanox/doca中有一个可用的DOCA安装。

DOCA 调试

从哪里开始： 此技能是规范的层次阶梯参考，doca-setup ## debug和doca-programming-guide ## debug都会升级到此技能。如果症状不能明确归为环境类或程序类，请从TASKS.md ## debug开始——完整的层次阶梯位于那里。

此技能能很好回答的示例问题

此技能旨在回答的调试问题类别，每类带一个已完成的示例。

• “我的DOCA构建/链接/运行时/程序失败——是哪一层？” — 示例：“ld 报错 undefined reference to doca_flow_init —— 哪一层？” 由TASKS.md ## debug中的规范层次阶梯（第4层=链接）回答。

• “如何提高任何DOCA库或工具的详细级别？” — 示例：“我的DOCA Flow程序静默——在哪里可以获得更多日志输出？” 由CAPABILITIES.md ## 可观测性和TASKS.md ## 运行中的详细级别运行工作流回答。

• “如何为论坛问题或bug报告捕获状态？” — 示例：“我想提交一个带有可复现上下文的论坛问题——应该包含哪些内容？” 由TASKS.md ## 测试中的捕获可重现状态工作流回答。

• “这个DOCA工具的输出是什么意思/哪个工具可回答这个问题？” — 示例：“doca_caps 对RDMA没有返回任何内容——这是否意味着不支持？” 由CAPABILITIES.md ## 能力与模式和doca-caps回答。

• “我正在NGC容器内调试——哪些是可观测的？” — 示例：“hugepages 在容器内为空；这是真实问题还是容器问题？” 由CAPABILITIES.md ## 安全策略和TASKS.md ## 调试第5层（运行时）回答。

• “我应该在哪里寻求帮助？” — 示例：“面向客户的DOCA论坛在哪里，帖子应该包含什么？” 由TASKS.md ## 调试和doca-public-knowledge-map回答。

如果症状纯粹是环境类，路由到doca-setup ## debug；如果纯粹是程序类，路由到doca-programming-guide ## debug。此技能是两者都调用的跨领域层。

何时加载此技能

当用户调试任何与DOCA相关的内容时——构建无法编译、链接步骤无法解析doca_*符号、运行时调用抛出DOCA_ERROR_*、数据包未出现在导线上、服务无法启动、工具也无有效输出——请加载此技能。具体来说：

• 用户报告症状时需要找到导致该问题的层（安装/版本/构建/链接/运行时/程序）。

• 用户询问“如何获取更多日志？”或“如何提高任何DOCA库或工具的详细级别？”

• 用户希望为论坛问题或内部bug报告捕获状态（此技能不拥有内部bug报告渠道；它路由到公开的DOCA开发者论坛）。

• 用户在阅读DOCA程序中的堆栈跟踪、valgrind输出或核心转储，并希望知道首选从哪里检查。

• 用户在NGC DOCA容器内调试，需要知道从容器内哪些可观察、哪些不可观察。

不要为以下情况加载此技能：

• “什么是DOCA_ERROR_BAD_STATE？”、“DOCA会返回什么错误代码？” — 这是跨库错误分类法，由doca-programming-guide拥有。此技能消费该分类法，但不重新定义它。

• “我的pkg-config找不到doca-flow”、“hugepages未挂载”、“我的representor不可见” — 这些是环境类症状，由doca-setup ## debug拥有。此技能是规范性指针。

• 库特定的调试（Flow管道跟踪、RDMA队列对状态、Comch通道统计）— 这些在匹配的库技能中（例如doca-flow ## debug）。此技能提供跨领域的调试阶梯；库技能在其上叠加自己的调试表面。

此技能提供什么

这是一个轻量加载器。实质性的调试资料位于两个伴随文件中：

• CAPABILITIES.md — DOCA暴露的调试表面种类：分层调试模型（安装/版本/构建/链接/运行时/程序）、只读优先立场、调试工具的版本可用性（例如DOCA 2.6.0起提供doca_caps）、跨库错误分类法（仅交叉链接——由doca-programming-guide拥有）、可观测性原语（stderr日志、--sdk-log-level、doca-<lib>-trace、库计数器）以及安全约束（只读优先，不要在调查中途修改安装树）。

• TASKS.md — 调试工作流：## configure、## test、## debug，以及在哪里寻求帮助路由（NVIDIA DOCA开发者论坛）。

加载顺序

1. 首先阅读此SKILL.md，确认用户的症状是跨领域调试。

2. 有关分层调试模型、只读立场、调试工具版本可用性和可观测性表面，请参阅CAPABILITIES.md。

3. 有关规范的层次调试阶梯和捕获并报告工作流，请参阅TASKS.md。

4. 如果症状是环境类则交给doca-setup ## debug；程序类交给doca-programming-guide ## debug；库内部交给匹配库技能的## debug。

相关技能

• doca-public-knowledge-map — 公共DOCA文档路由和已安装包布局。

• doca-setup — 环境类调试。

• doca-programming-guide — 程序类调试。

• 库技能（如doca-flow、doca-dms、doca-caps）— 库特定的调试覆盖层。