doca-mgmt

DOCA 管理

示例

• “在 VF 上切换 data-direct。”——这属于适用范围。使用管理／representor 上下文；不要降级为原始 mlxconfig。
• “raw_cmd 返回 DOCA_ERROR_IO_FAILED。”——固件拒绝了该命令：请重新检查四项版本是否匹配、操作码以及最精确的正确作用域（CONFIGURATION、DEBUG_READ_ONLY、DEBUG_WRITE、DEBUG_WRITE_FULL）。fwctl 或权限故障则会显示为 DOCA_ERROR_OPERATING_SYSTEM。

说明

请遵循下文的加载顺序。针对 configure／raw-cmd／debug，请打开 tasks companion；针对作用域和设备能力，请打开 capabilities companion。不要打开所有 companion 文件。

从哪里开始：此技能假定已安装 DOCA，且用户正在针对 BlueField／ConnectX 设备进行管理平面实操——通常是需要以编程方式查询或修改设备级状态的机群管理或编排工具。若用户想要执行某项操作（安装／配置／构建／修改／运行／测试／调试／使用），请打开 tasks companion；若问题是此版本的 doca-mgmt 能表达什么——管理上下文模型、原始命令作用域层级、子域接口（caps-general、cc-global-status、diagnostics-data、icm-quota）、版本兼容性和安全覆盖机制——请打开 capabilities companion。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。

**如何使用此技能。**阅读此文件，然后在 companion 文件中搜索问题所需的 ## <name> 标题，并阅读该标题下的完整章节。仅依据其中内容完整作答，只引用其中的符号和命令。不要浏览文档；请使用 doca-public-knowledge-map 中的入口。环境检查请用面向用户 DOCA 主机的命令提供。任何会更改设备状态的操作也必须遵循 doca-hardware-safety：请说明这一点并引用该技能。对于超出范围的请求，请指出负责该请求的技能并停止。

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

此技能旨在回答的管理平面问题类别，每类附有一个完整示例。Agent 应将类别视为核心内容；完整示例只是其中一个具体实例。

• "doca-mgmt 真的是合适的接口吗？还是我需要 telemetry / bench / caps？"——完整示例："我正在构建一个设备群清单工具——我该用 doca-mgmt 查询每个 BlueField 的 data-direct 能力，还是用 doca-telemetry，或 doca_caps？". 由 ## Capabilities and modes 中的管理平面与可观测性平面及只读 CLI 选择规则表回答。
• "如何在设备（以及 representor）上建立管理上下文？"——完整示例："在设备上打开一个 doca_mgmt_dev_ctx，然后在特定 VF representor 上打开一个 doca_mgmt_dev_rep_ctx，用于 caps-general 编程". 由 ## Capabilities and modes 中的管理上下文生命周期，以及 ## configure 中的配置流程回答。
• "如何查询设备能力——例如，它是否支持 data-direct？"——完整示例："创建一个 caps-general 句柄，在 representor 上下文中调用 doca_mgmt_device_caps_general_get，读取 data-direct 标志". 由 ## Capabilities and modes 中的能力查询模式，以及 ## test 中的测试步骤回答。
• "如何安全地修改设备级功能标志？"——完整示例："在 representor 上切换 data_direct；记录修改前状态、写入、验证，并准备回滚". 由 ## modify 中的应用并回滚工作流回答，该工作流基于 ## Safety policy 中引用的、适用于整个工具包的硬件安全元策略。
• "doca_mgmt_raw_cmd 的作用范围是什么意思？我该用哪个范围？"——完整示例："我有一个供应商文档中说明的 DEBUG_READ_ONLY 查询操作码——它需要什么范围，影响范围有多大？". 由 ## Capabilities and modes 中的命令范围层级，以及 ## use 中的原始命令动词回答。
• "来自 doca_mgmt_* 调用的这个 DOCA_ERROR_* 是什么意思？是哪个层导致的？"——完整示例："doca_mgmt_raw_cmd 返回 DOCA_ERROR_IO_FAILED". 由 ## Error taxonomy 中跨库错误分类上的管理层补充说明，以及 ## debug 中的分层排查流程回答；该流程会在原因是设备状态变化时升级至 doca-debug/SKILL.md 和 doca-hardware-safety/SKILL.md。

何时加载此技能

当用户在配备一个或多个 BlueField / ConnectX 设备的主机上实际操作 DOCA Management时，加载此技能。 具体包括：

• 在 doca_dev 上创建 doca_mgmt_dev_ctx，以检查 或修改设备级状态。
• 在 doca_dev_rep 上创建 doca_mgmt_dev_rep_ctx（或 在代表端口不可用时通过 doca_mgmt_dev_rep_ctx_create_by_pci_addr），以检查或修改 VF / 功能级配置。
• 通过 doca_mgmt_device_caps_general_* 查询设备的通用能力（数据直连支持及 类似的设备级属性）。
• 通过相同的 set 路径配置代表端口的通用能力。
• 通过 doca_mgmt_cc_global_status_* 查询或修改拥塞控制全局状态（RP / NP 协议类型、 优先级、启用 / 禁用）。
• 针对特定设备，通过 doca_mgmt_diagnostics_data_* 修改或查询多域诊断数据。
• 通过 doca_mgmt_icm_quota_* 设置每个设备或代表端口的 ICM 配额限制，并读取当前分配量 / 是否达到上限。
• 针对设备的固件控制端点发出 doca_mgmt_raw_cmd，并根据操作的影响范围选择合适的 enum doca_mgmt_cmd_scope。
• 调试 doca_mgmt_* 调用返回的 DOCA_ERROR_*，并判断原因是配置错误、生命周期顺序问题、 设备缺少能力、fwctl ioctl 失败，还是固件端拒绝。

一般性的 DOCA 入门、DOCA 本身的安装、实时性能基准测试或基于流的遥测不适用此技能。对于这些情况，请分别使用 doca-public-knowledge-map/SKILL.md、 doca-setup/SKILL.md、 doca-bench/SKILL.md 和 doca-telemetry/SKILL.md。

此技能提供什么

这是一个轻量加载器。正文仅保留用于选择合适后续文件的必要指引。管理专属的实质性材料位于两个配套文件中：

• 能力配套文件——说明此版本的 doca-mgmt 能表达什么：管理上下文对象模型 （doca_mgmt_dev_ctx + doca_mgmt_dev_rep_ctx）、原始命令作用域层级（DOCA_MGMT_CMD_SCOPE_CONFIGURATION、 DOCA_MGMT_CMD_SCOPE_DEBUG_READ_ONLY、 DOCA_MGMT_CMD_SCOPE_DEBUG_WRITE、 DOCA_MGMT_CMD_SCOPE_DEBUG_WRITE_FULL）、子域接口（caps-general、cc-global-status、diagnostics-data、 icm-quota）及其能力查询门控、EXPERIMENTAL 符号集策略（每个公共 doca_mgmt_* 符号都 标记为 EXPERIMENTAL）、跨库 DOCA_ERROR_* 分类体系在 mgmt 中的叠加规则、可观测性接口（写入前 状态捕获 + 写入后重新查询），以及针对各项操作的安全规则对整个套件硬件安全元策略的补充。
• 任务配套文件——针对八个适用动词的分步工作流：install、configure、build、modify、run、 test、debug、use。此外还有一个 Deferred task verbs 部分，将不在适用范围内的问题指向合适的后续技能。

此技能假设主机或 BlueField 已在标准位置安装 DOCA，且用户具备其公开安装配置所要求的权限（管理平面操作通常需要 root 或同等的设备管理能力）。此技能不涵盖安装 DOCA——该流程请参阅 doca-setup/SKILL.md。

此技能明确不提供的内容

此技能是Agent 指引，不是示例或模板包。为明确界限，此技能特意不包含以下内容，且不应通过拉取请求添加：

• **任何语言编写的预先编写 DOCA Management 应用源代码。**管理平面代码会触及设备状态，错误写入可能导致设备离线；根据文档文字编写此类代码是此技能所禁止的，尤其是针对形态可能随版本变化的 EXPERIMENTAL 符号集。Agent 的职责是引导用户使用经过验证的参考代码（已安装软件包集中的 DOCA 示例是标准的完整示例），并通过 doca-programming-guide/SKILL.md 中通用的修改示例工作流，规定最小差异修改。
• **放置在技能目录中的独立构建清单。**Agent 会在用户的项目目录中，针对用户已安装的 DOCA 构建清单；pkg-config --modversion doca-mgmt 是事实依据。
• 原始命令操作码目录。doca_mgmt_raw_cmd 的输入负载和输出负载因设备／固件而异；此技能会说明命令类别的范围以及 Agent 应遵循的规范（预先捕获状态、范围阶梯、回滚路径），但不会枚举操作码——这些内容属于供应商／设备文档，应通过 doca-public-knowledge-map/SKILL.md 查找。
• **任何形式的 samples/、bindings/ 或 reference/ 子目录。**此技能目录中的模拟或不完整产物，即使标注为“参考”，也会造成误导：用户会误以为它可以构建。

加载顺序

1. 首先阅读此技能，确认用户的问题属于其涵盖范围。
2. 有关管理上下文对象模型、原始命令范围阶梯、子域接口、版本兼容性、错误分类、可观测性以及针对各类产物的安全附加要求，请参阅能力配套文件。
3. 有关分步工作流——安装、配置、构建、修改、运行、测试、调试和使用——请参阅任务配套文件。

这两个配套文件会相互交叉链接，并在正确答案是“查阅公共文档或已安装的软件包布局”而非“管理专用指引”时，链接到 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-hardware-safety/SKILL.md — 整个套件范围内的硬件安全元策略。由于 doca-mgmt 是 Agent 最常通过编程方式修改设备状态的入口，能力说明中随附的安全叠加层会以关键方式交叉引用该元策略；每当建议执行写入时，Agent 都会遵循硬件安全阶梯。
• doca-telemetry/SKILL.md 和 doca-telemetry-exporter/SKILL.md — 用于从设备流式传输遥测数据的可观测性入口。用户需要实时指标时使用这些工具；用户需要在某个时间点以编程方式查询或修改时使用 doca-mgmt。
• doca-caps/SKILL.md — 用于检查设备功能的只读 CLI。用户需要交互式快照时使用该工具；用户需要通过 C API 在集群工具中获取相同信息时使用 doca-mgmt。
• doca-bench/SKILL.md — 实时性能基准测试工具。不属于 doca-mgmt 的范围；该技能会说明边界。
• doca-pcc/SKILL.md 和 doca-pcc-counters/SKILL.md — 可编程拥塞控制。doca-mgmt 的 doca_mgmt_cc_global_status_* 接口负责全局启用/禁用 + 协议选择控制平面，它建立在 doca-pcc 所负责的更深入的可编程 CC 接口之上。
• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档来源的路由表，以及已安装 DOCA 软件包的磁盘布局。
• doca-setup/SKILL.md — 环境准备、安装验证，以及尚未安装任何内容时使用公开 NGC DOCA 容器的路径。
• doca-programming-guide/SKILL.md — 所有库共用的通用 DOCA 编程模式： 标准的 pkg-config + meson 构建模式、 通用的“先修改随附示例，构建第一个应用”工作流，以及跨库的 DOCA_ERROR_* 分类。此技能在此基础上叠加管理平面的特定内容。
• doca-debug/SKILL.md — 跨领域的调试阶梯。管理相关的调试叠加层建立在其之上。
• doca-version/SKILL.md — 版本检测 / 四方匹配规则，每个工件的 ## Version compatibility 锚点都以此为基础。本技能仅引用管理相关的叠加内容。
• doca-structured-tools-contract/SKILL.md — 面向 Agent 优先使用的结构化辅助工具的 JSON 架构契约；任务配套文档中的 ## Command appendix 会先引用这些契约，然后才回退到手动调用链。