doca-hardware-safety

DOCA 硬件安全

示例

• “启用 SR-IOV 并重启。”——这属于适用范围。先清点，再确认带外可达性，安排维护窗口并进行副本演练，然后再执行。
• “通过 SSH 切换 BlueField 模式。”——如果主机没有带外通道，则拒绝执行。可能导致链路中断的变更若没有 BMC / RShim / 控制台，必须坚决叫停。

快速解答（根据本文件回答）

• 热关机或硬件安全限值。 将其视为硬件事件：先收集只读证据（BMC/Redfish 机箱热传感器和事件日志、带外控制台、dmesg | grep -i mlx5，以及 MFT 中的 mget_temp -d <mst device>）。切勿禁用或提高热保护限值；气流和散热问题应由设施维护解决。任何涉及固件更新、mlxconfig 写入或冷断电重启的修复操作，都必须遵守下方的约定；如果没有根本原因或无法回滚，则拒绝执行并升级至 NVIDIA 支持团队。
• 只读清点或版本相关问题无需使用此技能：指定 doca-version（四来源链）或 doca-caps（doca_caps --list-devs），并据此回答。
• 适用时，指定同级技能（doca-version、doca-setup、doca-structured-tools-contract）；不要为了回答安全问题而打开它们。

说明

遵循下方的加载顺序。应用会触及硬件的变更前，先打开任务配套文件。针对适用的变更类别和拒绝并升级规则，打开能力配套文件。不要打开所有配套文件。

从这里开始： 此技能是此技能包中唯一的事实来源，规定了在运行中的系统上进行任何触及 DPU / NIC 硬件状态的变更时所遵循的规范。操作员准备应用会触及硬件的变更并需要变更应用规范（预检清点 → 带外通道 → 维护窗口 → 应用 → 验证 → 回滚）时，打开任务配套文件。问题涉及硬件安全究竟涵盖什么（适用的变更类别、策略旨在防范的故障模式、变更必须满足的可观测性要求，以及每个具体工件的 ## Safety policy 如何叠加的元策略）时，打开能力配套文件。

技能包中每个建议执行硬件相关操作的工件专属技能（服务、库、工具），都会在此元策略之上叠加工件专属的安全要求。工件专属的 ## Safety policy 锚点不会重新定义跨领域规范，而是在其基础上叠加该工件自身的注意事项。此技能是所有这些策略共同依托的基础层。

mlxconfig 级生产变更的强制应答要求

关于在生产环境应用 mlxconfig 级写入的回答，必须明确说明以下每一道关卡；仅提供配套文件的链接不能代替逐项说明：

1. 在任何应用步骤之前，先说明变更类别，并说明固件存储的值会在下一次冷电源周期时提交，而不是在暖重启时提交。
2. 要求在变更前采集 PCIe 拓扑、链路状态、固件级别、BFB 级别、当前的 mlxconfig 配置，以及主机内核／模块／环境信息。
3. 将此变更视为可能导致链路中断的变更；在明确指定并证明部署专用的 OOB 控制台类别可访问之前，不得执行此变更。绝不能将 mlxconfig 级生产写入描述为本身不会导致链路中断。
4. 要求在应用变更前记录有时限的维护窗口、相关方、回滚决策点、回滚计划和验证关卡。
5. 在生产环境变更前，必须在匹配的非生产副本上演练正向变更和回滚。
6. 在四方版本匹配、每个制品的健康指标以及端到端可观测性路径全部通过之前，必须阻止生产工作负载运行。
7. 明确说明回滚步骤：与已采集的基线比较 → 恢复已采集的值 → 冷电源周期 → 重复清点和四方检查 → 将残留的软件问题交由 doca-debug 处理。
8. 在回答中明确说明拒绝执行和升级处理的要求：如果没有记录在案的回滚方案、无法恢复已采集的基线，或对于可能导致链路中断的变更无法访问 OOB，立即停止并拒绝继续。将问题升级至操作员的变更控制流程、供应商支持或公开的 DOCA Developer Forum；绝不能猜测恢复方法。仅仅提及“拒绝并升级规则”，却不说明此操作和升级渠道，并不满足本要求。绝不能编造参数、地址、版本、端点或恢复值。

副本关卡是强制要求，绝不能仅作为建议：必须说明，只有在代表性副本上成功完成正向变更和回滚后，才能对生产环境进行变更。即使在回答其他位置提到了副本，使用“建议”、“强烈建议”或“如果有条件”等措辞也违反本要求。

相同的要求也适用于固件烧录、BFB 重刷和主机启动参数变更；区别仅在于各自有据可查的提交操作、特定类别的前置条件和回滚机制。

何时加载此技能

只要 Agent 准备建议，或正在协助操作员对运行中的系统执行涉及 DPU／NIC 硬件状态的变更，就应加载此技能。必须在 Agent 撰写第一句话之前作出判断——下方的激活检查清单与 AGENTS.md ## Cross-cutting overlay activation triggers（捆绑文件 AGENTS.md#cross-cutting-overlay-activation-triggers）中引用的清单相同；此处再次列出，以便已加载此技能的单个制品技能随时查阅激活规则。

Agent 激活检查清单 — 如果以下任一单元格为真，请在回答开头加载此技能

触发类别	提示词中的具体信号（任一信号触发此覆盖规则）
mlxconfig 类变更	提示词或 Agent 接下来建议的操作直接提及 mlxconfig；或在 NIC / DPU / Separated-Host 模式之间切换 BlueField；或启用 SR-IOV；或启用设备仿真插槽（virtio-net、NVMe-emu、snap、virtio-blk-emu）；或更改 BAR 窗口 / 窗口大小；或设置任何需要重置才能生效的固件提交参数
固件 / BFB	刷写 NIC 固件（flint、mft、mlxfwmanager、带 -y reset 的 mlxconfig）；重新刷写 BlueField BFB（bfb-install、rshim）；需要更换 BFB 的 BlueField 模式变更
主机内核状态	更改主机内核启动参数（IOMMU 模式 iommu=pt / intel_iommu=on、default_hugepagesz、hugepagesz、nr_hugepages、pci=resource_alignment、vfio-pci.ids）；需要重启主机
大页	更改大页预留（/sys/kernel/mm/hugepages/*/nr_hugepages、sysctl vm.nr_hugepages）；更改大页挂载（mount -t hugetlbfs）；这是与主机上每个 DOCA / DPDK 进程共享的全局状态
PCIe 状态	PCIe 重新绑定 / echo > /sys/bus/pci/.../{bind,unbind,remove,rescan}；启用 / 禁用 representor；更改 eswitch 模式（devlink dev eswitch set ... mode {switchdev,legacy}）；对当前承载流量的端口执行链路关闭 / 启用
BlueField 重启类别	BlueField 冷重启、为应用 mlxconfig 而对 BlueField 执行热重启；打开除 misc 以外的任何 RShim 节点（即使执行 cat /dev/rshimN/boot 也会启动引导周期并重置 BlueField；只读取 /dev/rshimN/misc）；任何影响范围为*"此 DPU 上托管的所有服务都会重启"*的变更
按制品交叉链接	任何按制品划分的技能在 ## Safety policy 中交叉链接至此处，以引用跨领域规则正文

当以上任一单元格触发时，Agent 必须在撰写回答的第一句话之前加载此技能。对于生产环境，必须按以下顺序遵循变更应用流程：

configure（计划） →

## test（代表性副本变更 + 回滚演练）→ ## modify（应用到生产环境）→ ## run（生产环境验证）→ ## debug（调试 / 回滚）。回答中必须明确说明激活原因（例如：“由于此操作涉及 mlxconfig，回答将遵循 doca-hardware-safety 流程……”），以便用户审核推理过程。

激活是**强制要求，而非建议。**此覆盖规则要防止的最常见故障是：*"Agent 建议更改 mlxconfig，却没有维护时段、带外访问路径，也未说明回滚方案；用户应用更改后，管理链路中断，设备无法恢复，只能通过物理控制台操作。"*一次无必要的激活（回答多出几段文字）造成的代价，与一次漏掉激活相比微不足道。

拒绝并升级处理是硬性规则

如果满足以下任一条件，Agent MUST 停止并拒绝推荐此变更——不得弱化警告，不得以“这有风险，但可以这样做”的方式继续，也不得把回滚问题推给用户，让他们“自行考虑”：

1. 此变更没有记录在案的回滚路径，且用户无法提供回滚路径。（根据 ## Safety policy 的 rollback-must-be-documented 规则。）
2. 此变更会导致链接中断，且主机没有带外访问路径。（根据 ## Safety policy 的 out-of-band-precondition 规则。）
3. 此变更涉及硬件状态，且用户尚未确认明确且有时间限制的维护窗口。（根据

   Safety policy

   的 maintenance-window 规则。）
4. 在此变更及其回滚方案通过代表性非生产环境副本上的测试之前，就计划应用于生产环境。此拒绝基于意图：适用于会导致计划、建议或后续操作过早触及生产环境的情况，不仅限于用户明确要求“直接应用”的情况。如果副本在所需硬件、固件、内核、模块或功能拓扑方面不匹配，则不符合此门槛；应获取有代表性的副本，否则拒绝并升级处理。（根据 ## test 的 replica-first 规则。）

在上述每种情况下，正确的回答形式都是：“此变更需要 X（原因如下）；没有 X，本套件拒绝推荐此变更；获取 X 的途径如下”——既不能沉默，也不能临时编造办法。拒绝并升级处理规则让本套件的硬件安全指南值得生产环境操作人员信赖。

对于一般性的 DOCA 概览，请勿加载此技能（使用 doca-public-knowledge-map/SKILL.md）； 对于首次安装或环境类别调试，请勿加载此技能（使用 doca-setup/SKILL.md）； 对于完全在程序侧进行且不涉及硬件状态的调试，请勿加载此技能（使用 doca-debug/SKILL.md 或 doca-programming-guide/SKILL.md）。

此技能提供的内容

这是一个轻量加载器。正文仅保留用于选择下一个文件所需的概览信息。实质性内容位于两个配套文件中：

• 能力配套文件——元策略层面：涵盖的变更类别（飞行前清单分类法、mlxconfig 类／固件烧录／内核启动参数分组）、适用于每个工件 ## Safety policy 覆盖层的跨领域安全策略、该策略所防止的故障模式（链路瘫痪、烧录失控、模式悄然变更、缺少回滚方案）、操作人员在任何工作负载迁移之前必须满足的可观测性门槛，以及指向 doca-version/SKILL.md 的轻量版本兼容性覆盖层。
• 任务配套文件——变更应用工作流：## configure（飞行前清单＋带外访问＋维护窗口计划）、## build（路由占位内容——涉及硬件的变更不会生成构建产物）、## modify（应用变更的规范，包括 mlxconfig 的冷断电重启规则和固件烧录规范）、## run（变更后的验证门槛）、## test（副本优先的冒烟测试）、## debug（回滚阶梯＋拒绝并升级处理的应急机制），以及 ## Deferred task verbs 块。

加载顺序

1. 首先阅读此技能，以确认用户的问题在范围内（Agent 即将建议一项会影响运行中系统硬件状态的更改）。
2. 对于范围内的更改类别，元安全策略、故障模式分类、可观测性门槛和版本覆盖重定向，请参阅能力配套文档。
3. 对于应用更改工作流——变更前清点 → 带外操作 → 维护窗口 → 应用 → 验证 → 回滚——请参阅任务配套文档。
4. 每种工件的具体信息（要切换的确切固件槽位、操作员需要的确切内核参数、操作员必须回滚到的确切容器标签）都位于匹配的每工件技能的 ## Safety policy 覆盖部分中。此技能不会列出这些具体信息；满足元策略后，Agent 会通过路由返回每工件技能来获取这些信息。

相关技能

• doca-version/SKILL.md — 四方匹配规则，以及主机 ↔ BlueField BFB ↔ 容器标签的配对关系。每项涉及硬件的更改都有版本维度；此技能中的 ## Version compatibility 覆盖部分会用 3-5 行将正文内容重定向至 doca-version。
• doca-setup/SKILL.md — 涉及硬件的更改的环境类别前置检查（大页、IOMMU 模式、pkg-config、代表端口可见性）。此技能中 ## configure 的变更前清点会交叉链接到 doca-setup，以涵盖清点中的环境类别部分。
• doca-debug/SKILL.md — 跨层调试阶梯。当涉及硬件的更改出错时，此技能中 ## debug 的回滚阶梯会在回滚恢复已知状态且症状现于软件层后，移交给 doca-debug。
• doca-structured-tools-contract/SKILL.md — 存在时 Agent 优先使用的 JSON 模式。collect-host-state / collect-dpu-state 模式是此技能中变更前清点的结构化形式；当主机安装了辅助工具时，Agent 会将其用作一次性答复。
• doca-container-deployment/SKILL.md — 各 DOCA 服务共享的规范容器部署方案。多项涉及硬件的更改（BlueField 冷重启、重新刷写 BFB）会中断 BlueField 上运行的所有服务容器；回滚路径会引用 doca-container-deployment 的重新部署方式。
• doca-programming-guide/SKILL.md — 程序侧前置条件（能力发现、提交前验证）。此技能中 ## run 的更改后验证门槛会交叉链接到该指南，以获取生产工作负载迁移前必须可见的程序侧可观测性界面。
• 每项捆绑内服务 / 库 / 工具技能中的每工件 ## Safety policy 锚点——例如 doca-argus/SKILL.md、doca-dms/SKILL.md、doca-firefly/SKILL.md、doca-urom-svc/SKILL.md 中的固件槽位前置条件；涉及设备的库（doca-flow/SKILL.md、doca-rdma/SKILL.md、doca-eth/SKILL.md、doca-pcc/SKILL.md、doca-rmax/SKILL.md）；以及涉及硬件的工具（例如 doca-spcx-cc/SKILL.md、doca-pcc-counters/SKILL.md）。 每项捆绑内工件技能的 ## Safety policy 都会将此元策略与工件专属安全要求叠加。交叉链接特意设为双向：每工件技能会在此处链接至元策略；此技能则在 ## Safety policy 中列出叠加此元策略的技能。产品化的外部同类项（doca-virtio-net、doca-snap、doca-hbn、BlueMan、DPF）不是捆绑内技能——其安全策略位于产品文档中，可通过 doca-public-knowledge-map ## Externally-productized DOCA software 找到（doca-public-knowledge-map/SKILL.md#externally-productized-doca-software--not-in-this-bundle-but-here-is-where-to-route）。