Name: DOCA管理Skill
Rating: 5 (1 reviews)
Author: doca-mgmt


开源协议	Apache-2.0
名称	doca-mgmt
描述	> 当用户正在对BlueField / ConnectX设备进行动手的DOCA Management编程时使用此技能 — 建立管理或代表器上下文（doca_mgmt_dev_ctx / doca_mgmt_dev_rep_ctx）、查询设备能力（data-direct、caps-general）、切换拥塞控制全局状态、修改 diagnostics-data、设置ICM配额或通过doca_mgmt_raw_cmd以正确作用域（CONFIGURATION / DEBUG_READ_ONLY / DEBUG_WRITE / DEBUG_WRITE_FULL）发出原始固件命令。即使不提及“DOCA Management”也触发 — 典型隐含说法包括“遍历每个BlueField并读取设备状态的机队工具”、 “在VF上切换data-direct”、“为每个代表器设置ICM配额”、“从C语言发送原始固件命令”、 “raw_cmd中出现DOCA_ERROR_IO_FAILED”或“fwctl ioctl失败”。对于mlxconfig直接操作、BFB / 固件重新刷写、流式遥测、doca_caps CLI快照或DOCA安装本身，拒绝并转至其他技能。 metadata: kind: library compatibility: > 需要DOCA SDK已安装在Linux（Ubuntu 22.04/24.04或RHEL/SLES）上的 /opt/mellanox/doca 中，并带有BlueField DPU或ConnectX NIC。通过 `pkg-config doca-mgmt` + `doca-common` 读取用户的本地安装，并检查 /opt/mellanox/doca/{lib,include,samples,applications}；运行时操作需要root（或设备管理员cap_）以及主机内核暴露的 /dev/fwctl 字符设备。

DOCA 管理

开始之处： 本技能假定 DOCA 已经安装，用户正针对 BlueField/ConnectX 设备进行实际的管理面工作 — 通常是构建机队管理或编排工具，需要以编程方式查询和修改设备级状态。若用户希望做某事（安装/配置/构建/修改/运行/测试/调试/使用），请打开 TASKS.md；当问题是此版本上的 doca-mgmt 可以表达什么 时，请打开 CAPABILITIES.md — 管理上下文模型、原始命令作用域阶梯、子域表面（caps-general、cc-global-status、diagnostics-data、icm-quota）、版本兼容性和安全覆盖。如果用户尚未安装 DOCA，请先转到 doca-setup。

本技能善于回答的示例问题

管理面问题类别，每类带一个工作示例。代理应把类别视为承重部分 — 示例是一个实例。

“doca-mgmt 是正确的表面吗，还是我想要遥测/基准/caps？” — 示例：“我正在构建一个机队库存工具 — 我应该使用 doca-mgmt 查询每个 BlueField 的 data-direct 能力，还是使用 doca-telemetry，或者 doca_caps？” 由 CAPABILITIES.md ## 能力和模式 的管理面 vs 观测平面 vs 只读 CLI 选择规则回答。
“我如何在设备上建立管理上下文（以及代表器）？” — 示例：“在设备上打开 doca_mgmt_dev_ctx，然后在特定 VF 代表器上打开 doca_mgmt_dev_rep_ctx 以进行 caps-general 编程。” 由管理上下文生命周期 + TASKS.md ## 配置 中的配置步骤回答。
“我如何查询设备能力 — 比如它是否支持 data-direct？” — 示例：“创建 caps-general 句柄，在代表器上下文上调用 doca_mgmt_device_caps_general_get，读取 data-direct 标志。” 由能力查询模式 + TASKS.md ## 测试 中的测试步骤回答。
“我如何安全地修改设备级功能标志？” — 示例：“切换代表器上的 data_direct，捕获先前状态、写入、验证、准备回滚。” 由 TASKS.md ## 修改 中的带回滚应用工作流回答，并叠加 CAPABILITIES.md ## 安全策略 引用的全局硬件安全元策略。
“doca_mgmt_raw_cmd 的作用域是什么意思，我应该用哪个？” — 示例：“我有一个供应商文档记录的用于 DEBUG_READ_ONLY 查询的操作码 — 需要什么作用域，影响范围是多少？” 由 CAPABILITIES.md ## 能力和模式 中的命令作用域阶梯 + TASKS.md ## 使用 中的原始命令动词回答。
“doca_mgmt_* 调用返回的 DOCA_ERROR_* 是什么意思，是哪个层引起的？” — 示例：“来自 doca_mgmt_raw_cmd 的 DOCA_ERROR_IO_FAILED”。由 CAPABILITIES.md ## 错误分类 中的 mgmt 覆盖 + TASKS.md ## 调试 中的分层阶梯回答，该阶梯升级到 doca-debug 以及当原因是设备状态更改时的 doca-hardware-safety。

受众

本技能服务于正在构建机队管理、编排或设备管理工具的外部开发者，这些工具以编程方式查询和修改 BlueField/ConnectX 设备级状态 — 即用户的代码调用 doca_mgmt_*（直接用 C/C++，或通过其他语言的 FFI/绑定）来检查设备能力、切换设备功能标志、查询诊断计数器、设置 ICM 配额，或发出原始固件控制命令。典型调用者是遍历数据中心每个 BlueField 并应用期望状态差异的机队管理代理。本技能不用于为 DOCA Management 本身做贡献的 NVIDIA 开发者，也不适合实时性能基准测试或基于流的可观测性 — 后者应分别使用 doca-bench、doca-telemetry 和 doca-telemetry-exporter。

语言范围

DOCA Management 是一个 C 库，pkg-config 模块名为 doca-mgmt。库的接口是 C；在真实安装上提供的示例（如果存在）是 C。C 和 C++ 消费者是典型情况，TASKS.md 中的工作流假定该路径。其他语言消费者（Rust、Go、Python 等）通过 FFI 或语言特定绑定消费同一个 *.so 库；在这种情况下，技能的作用是保持管理上下文生命周期、命令作用域阶梯、能力查询模式、版本处理规则和安全覆盖语言中立，并将代理路由到公共 C ABI 作为任何包装器最终调用的权威接口。技能不编写任何语言的包装器。

何时加载此技能

当用户在有 BlueField/ConnectX 设备的主机上进行实际的 DOCA Management 工作时加载本技能。具体来说：

在 doca_dev 上建立 doca_mgmt_dev_ctx 以检查或修改设备级状态。
在 doca_dev_rep（或当代表器不可用时通过 doca_mgmt_dev_rep_ctx_create_by_pci_addr）上建立 doca_mgmt_dev_rep_ctx 以检查或修改 VF/功能级配置。
通过 doca_mgmt_device_caps_general_* 查询设备的通用能力（data-direct 支持和类似设备级属性）。
通过相同的 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、doca-setup、doca-bench 和 doca-telemetry。

本技能提供什么

这是一个精简加载器。正文仅保留选择正确下一个文件所需的导向。与具体管理相关的实质材料位于两个伴随文件中：

CAPABILITIES.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 覆盖、可观测性表面（前状态捕获 + 写后重新查询），以及每制品对全局硬件安全元策略的安全覆盖。
TASKS.md — 八个范围内动词的分步工作流：install、configure、build、modify、run、test、debug、use。外加一个“延迟任务动词”块，将越界问题指向正确的下一个技能。

技能假定在标准位置已经安装 DOCA 的主机/BlueField 上运行，用户具有其公共安装配置文件所期望的权限（管理面操作通常需要 root 或等效的设备管理能力）。它不覆盖安装 DOCA — 该路径通过 doca-setup 进行。

本技能刻意不包含的内容

本技能是代理指南，不是示例或模板捆绑包。为保持边界清晰，它刻意不包含 — 且拉取请求不应添加：

任何语言的预写 DOCA Management 应用程序源代码。 管理面代码接触设备状态，错误的写入可能使设备离线；根据文档散文（尤其针对实验性符号集，其形状在版本之间可能更改）来创作它被本技能禁止。代理的工作是将用户引导到经过验证的参考代码（已安装包集中附带的 DOCA 示例是规范的工作示例），并通过 doca-programming-guide 中的通用修改示例工作流推荐最小差异修改。
技能内部存放的独立构建清单。 代理在用户的项目目录中，根据用户安装的 DOCA 构建清单，其中 pkg-config --modversion doca-mgmt 是事实来源。
原始命令操作码目录。 doca_mgmt_raw_cmd 中的有效载荷和输出载荷是设备/固件特定；技能只命名命令类的作用域和代理应用的纪律（前状态捕获、作用域阶梯、回滚路径），但不枚举操作码 — 这些是供应商/设备文档，通过 doca-public-knowledge-map 查找。
任何类型的 samples/、bindings/ 或 reference/ 子树。 此技能树中的模拟或不完整制品（即使标记为“reference”）会误导：用户会将其视为可构建。

加载顺序

首先阅读本 SKILL.md 来确认用户的问题在范围内。
关于管理上下文对象模型、原始命令作用域阶梯、子域表面、版本兼容性、错误分类、可观测性以及每制品安全覆盖，请参阅 CAPABILITIES.md。
关于逐步工作流 — 安装、配置、构建、修改、运行、测试、调试、使用 — 请参阅 TASKS.md。

两个伴随文件互相链接，以及当正确答案是“在公共文档或已安装包布局中查找”而不是“mgmt 特定指南”时，指向 doca-public-knowledge-map。

DOCA管理Skill doca-mgmt