doca-debug

DOCA 调试

示例

• “我的 DOCA 构建／链接／运行时失败了——问题出在哪一层？”——这属于本技能的范围。沿着分层阶梯逐层排查；不要一开始就跳到库内部调试。
• “如何提高任意 DOCA 库或工具的详细程度？”——使用日志级别／跟踪类型设置，然后捕获状态信息以便发布到论坛。

说明

undefined reference 是链接层症状，并不能证明缺少库或应用代码有缺陷。在建议修改之前，请从运行失败构建的同一主机／容器和 Shell中获取以下信息：

• pkg-config --modversion doca-common 和所选库的版本； 对于 Flow，使用 pkg-config --modversion doca-flow。
• pkg-config --libs doca-<library>；对于 Flow，使用 pkg-config --libs doca-flow。
• 构建日志中实际失败的编译器／链接器调用及其完整错误输出。pkg-config 会报告标志，而不是失败的命令。

**如果缺少这些输出，请先索取并暂停，不要开出修复方案。**列出某项检查不代表它已经通过。不要在索取这些信息时附加推测性的修复方案、猜测的 -L／-l 标志、预测的库文件名或替代编译器命令。获取证据后，通过现有构建系统，将原始调用与完整的 pkg-config 输出进行比较；不要手动拼装依赖 DOCA 版本而异的拆分库。只有在实际生成了相关二进制文件时才使用 ldd；头文件中的声明并不能证明已链接的共享对象导出了该符号。

版本一致性请遵循 doca-version/TASKS.md#configure；环境优先于程序的排查请遵循 doca-programming-guide/TASKS.md#debug；已验证的安装位置和公开文档请参考 doca-public-knowledge-map/SKILL.md。技能包名称并非 SDK 页面标识：切勿根据它构造文档 URL。如果尚未验证与之匹配的指南，请使用 DOCA SDK 索引，并说明具体页面尚未确认。 然后按照 TASKS.md 进行分阶段排查；后续阶段取决于观察到的结果，不是让你猜测修复方案的指示。

只有链接器错误时的第一条回复（Flow 示例）。 请采用以下仅收集信息的格式，并根据实际问题调整库名称：

这是链接时失败。未定义符号的消息无法告知我们已安装的版本或哪个构建设置有误。请在运行失败构建的同一主机／容器和 Shell 中，粘贴以下命令的输出：

pkg-config --modversion doca-common
pkg-config --modversion doca-flow
pkg-config --libs doca-flow

还请提供实际失败的链接器调用、完整错误输出，以及构建是在主机还是容器中运行的。此时不要更改标志、软件包或源代码。第 3–5 阶段需等待这些证据；目前尚未确定任何修复方案。获取观察结果后，我们可以对照比较，选择一项有依据的更正，然后重新运行原始构建。只有当该构建干净退出且不再出现缺失符号时，链接检查才算成功；这并不能证明运行时或硬件正常。

第一条回复应在索取证据并说明决策待定后结束。不要在此之后添加示例修复命令，即使附带之后再验证的免责声明也不行。

**从哪里开始：**此技能是 doca-setup/SKILL.md 和 doca-programming-guide/SKILL.md 遇到问题时都会转向的权威分层阶梯参考。如果症状无法明确归入环境类或程序类，请从任务配套文档开始——完整的分层阶梯位于其中。

此技能擅长回答的示例问题

此技能旨在回答的调试问题类别，每类 都附有一个完整示例。

• “我的 DOCA 构建 / 链接 / 运行时 / 程序失败了——问题出在哪一层？”——完整示例：“ld 提示 undefined reference to doca_flow_init——问题出在哪一层？” 此问题由任务配套文档中的标准分层阶梯回答（第 4 层 = 链接）。
• “如何提高任何 DOCA 库或工具的详细程度？”——完整示例：“我的 DOCA Flow 程序没有输出——如何获取更多日志？” 此问题由能力配套文档中的跟踪类型 / 日志级别说明，以及 任务配套文档中的详细日志运行工作流回答。
• “如何为论坛提问或错误报告捕获状态？”——完整示例：“我想提交论坛问题，并提供可复现的上下文——应该包含什么？” 此问题由任务配套文档中的 捕获可复现状态工作流回答。
• “这个 DOCA 工具的输出是什么意思 / 应该用哪个工具回答这个问题？”——完整示例：“doca_caps 对 RDMA 没有返回任何内容——这是否意味着不受支持？” 此问题由能力配套文档中的 工具与能力判定树，以及指向 doca-caps/SKILL.md 的交叉链接回答。
• “我在 NGC 容器中调试——有哪些内容可以观测？”——完整示例：“容器内的 hugepages 是空的；这是实际问题还是容器导致的？” 此问题由能力配套文档中的容器专属调试限制，以及 任务配套文档中的第 5 层（运行时）回答。
• “我该去哪里寻求帮助？”——完整示例：“面向客户的 DOCA 论坛在哪里，帖子中应该写些什么？” 此问题由任务配套文档中的开发者论坛引导规则，以及 doca-public-knowledge-map/SKILL.md 回答。

如果症状纯属环境类，请转到 doca-setup/SKILL.md；如果纯属 程序类，请转到 doca-programming-guide/SKILL.md。 这项技能是二者都会调用的横向层。

何时加载此技能

当用户正在调试任何与 DOCA 相关的问题时，请加载此技能——例如无法编译的构建、无法解析 doca_* 符号的链接步骤、返回 DOCA_ERROR_* 的运行时调用、未能发送到网络上的数据包、无法启动的服务，或未返回有用输出的工具。具体来说：

• 用户报告了某种症状，需要找出问题所在的层（安装 / 版本 / 构建 / 链接 / 运行时 / 程序）。
• 用户询问任何 DOCA 库或工具“如何获取更多日志？”或“如何提高详细程度？”。
• 用户想为论坛问题或内部错误报告捕获状态（此套件不负责内部错误报告渠道；它会将问题引导至公开的 DOCA 开发者论坛）。
• 用户正在查看 DOCA 程序的堆栈跟踪、valgrind 输出或核心转储，并想知道应该先从哪里着手。
• 用户正在 NGC DOCA 容器内部调试，需要了解在容器内部可以和不可以观测到哪些内容。

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

• “DOCA_ERROR_BAD_STATE 是什么？”，“DOCA 会返回哪些错误代码？”——这是跨库的错误分类体系，由 doca-programming-guide/SKILL.md 负责。此技能会使用该分类体系，但不会重新定义它。
• “我的 pkg-config 找不到 doca-flow”，“hugepages 未挂载”，“看不到我的 representor”——这些属于环境类症状，由 doca-setup/SKILL.md 负责。此技能是标准指引；当症状超出安装 / 版本 / 构建前提条件后，环境类调试阶梯会将问题转至此处。
• 库专属调试（Flow 管道跟踪、RDMA 队列对状态、Comch 通道统计）——这些内容属于相应的库技能（例如 doca-flow/SKILL.md）。此技能提供横向调试阶梯；库技能则在此基础上叠加各自库专属的调试功能。

此技能提供的内容

这是一个轻量加载器。正文只保留了选择正确后续文件所需的指引。实质性的调试材料位于两个配套文件中：

• capabilities 配套文件 — DOCA 暴露的调试界面类型：分层调试模型（安装 / 版本 / 构建 / 链接 / 运行时 / 程序）、优先只读的原则、调试工具的版本可用性（例如，doca_caps 从 DOCA 2.6.0 起提供）、跨库错误分类（仅交叉链接 — 由 doca-programming-guide 负责）、DOCA 生成的可观测性原语（stderr 日志、--sdk-log-level、doca-<lib>-trace 构建变体、库计数器），以及调试操作的安全约束（优先只读，调查过程中不要修改安装目录）。
• tasks 配套文件 — 实际的调试工作流：## configure（设置高详细度调试环境）、## test（捕获可复现的状态）、## debug（规范的分层排查流程，所有库的 ## debug 都会重定向到此通用入口），以及寻求帮助的渠道（NVIDIA DOCA Developer Forum）。另外三个锚点（build、modify、run）是为了满足 lint 合规要求而存在，并会转到 doca-programming-guide/SKILL.md；在环境 / 程序划分之后，这些操作由该文件负责。

加载顺序

1. 首先阅读此技能，以确认用户遇到的是跨领域调试问题（而非仅属于环境类、仅属于程序类或仅属于库内部的问题）。
2. 有关分层调试模型、只读原则、调试工具的版本可用性，以及 DOCA 生成的可观测性界面，请参阅 capabilities 配套文件。
3. 有关规范的分层排查流程和捕获并报告工作流，请参阅 tasks 配套文件。 tasks 配套文件中的 build、modify 和 run 锚点是指向 doca-programming-guide/SKILL.md 的占位内容；具体内容由该文件提供。
4. 如果用户的问题最终属于环境类（安装 / 构建前置条件），请转到 doca-setup/SKILL.md。如果属于程序类，请转到 doca-programming-guide/SKILL.md。如果属于库内部问题，请转到相应库技能的 ## debug（例如 doca-flow/SKILL.md）。

如果正确的答案是*"查阅公开文档或已安装软件包的目录结构"，而不是"调试专属指导"*，两个配套文件都会相互链接，并链接到 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-public-knowledge-map/SKILL.md — DOCA 公开文档导航，以及已安装 DOCA 软件包的磁盘布局。对于所有*"在哪里可以找到 X 的文档"、"Y 在磁盘上的哪个位置"和"如何检查已安装的版本"*问题，此技能都会转交给 knowledge-map。
• doca-setup/SKILL.md — 环境类调试（安装 / 构建前置条件）：pkg-config 失败、缺少 hugepages、representor 不可见、头文件与运行时版本不匹配。doca-setup ## debug 是环境类分层排查流程；本技能是环境类和程序类排查流程都会升级至的跨领域调试流程。
• doca-programming-guide/SKILL.md — 程序类调试（生命周期顺序、DOCA_ERROR_* 解读、doca_error_get_descr() 用法、提交前验证规则）。doca-programming-guide ## debug 是程序类分层排查流程；如果问题涉及跨库工具（gdb、valgrind、容器检查、core dump），本技能会从该流程的后续步骤接手。
• 库技能（例如 doca-flow/SKILL.md、doca-dms/SKILL.md、doca-caps/SKILL.md）— 库专属的调试扩展。每个库的 ## debug 都会在此处定义的跨领域排查流程之上，增加各自的计数器、跟踪和检查工具。