/doca-hardware-safety

license: Apache-2.0
name: doca-hardware-safety
description: >
  Use this skill whenever the agent is about to recommend or apply a
  change that touches DPU / NIC hardware state on a live system —
  mlxconfig firmware-parameter write, NIC firmware burn, BFB reflash,
  NIC ↔ DPU mode flip, SR-IOV or device-emulation slot enable, kernel
  boot-parameter change (IOMMU, hugepages, VFIO), PCIe rebind / rescan /
  link-state flip, BlueField cold reboot, or remediation of a BlueField
  thermal shutdown. Wrap the change in
  pre-flight inventory, OOB reachability, a maintenance window, replica
  rehearsal, and rollback. Trigger on implicit phrasing: "flip BlueField
  mode over SSH", "enable SR-IOV and reboot", "burned firmware but
  mlxconfig shows old value", "BlueField thermal shutdown". Not for
  read-only inventory or version queries (doca-version, doca-caps). Refuse
  orientation (doca-public-knowledge-map), install or env debug
  (doca-setup), and program-side debug (doca-debug,
  doca-programming-guide).
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - hardware
    - safety
compatibility: >
  No DOCA install required to read this skill (it is an overlay
  loaded against any DOCA artifact skill); the validation steps
  within DO require a live DOCA install at /opt/mellanox/doca with a
  BlueField DPU or ConnectX NIC, plus out-of-band console
  reachability (BMC, RShim, or operator-managed console) for any
  link-breaking change.

DOCA hardware safety

Examples

• **"Enable SR-IOV and reboot."** — this is in scope. Inventory first,

require out-of-band reachability, a maintenance window, replica rehearsal, then apply.

• **"Flip BlueField mode over SSH."** — refuse if the host has no

out-of-band path. A link-breaking change without BMC / RShim / console is a hard stop.

Quick answers (answer from this file)

• **Thermal shutdown or hardware safety limits.** Treat it as a hardware

event: capture read-only evidence first (BMC/Redfish chassis thermal sensors and event log, the out-of-band console, `dmesg | grep -i mlx5`, and `mget_temp -d <mst device>` from MFT). Never disable or raise thermal protection; airflow and cooling are facility fixes. Any remediation that is a firmware update, an `mlxconfig` write or a cold power cycle goes through the contract below; with no root cause or no rollback, refuse and escalate to NVIDIA support.

• **Read-only inventory or version questions** do not need this skill: name

`doca-version` (four-source chain) or `doca-caps` (`doca_caps --list-devs`) and answer there.

• Name sibling skills (`doca-version`, `doca-setup`,

`doca-structured-tools-contract`) when they apply; do not open them to answer a safety question.

Instructions

Follow Loading order below. Open the tasks companion before applying a hardware-touching change. Open the capabilities companion for the in-scope change class and refuse-and-escalate rules. Do not open every companion file.

**Where to start:** This skill is the bundle's single source of truth for the discipline that wraps every change touching DPU / NIC hardware state on a live system. Open the tasks companion when the operator is about to *apply* a hardware-touching change and needs the change-application discipline (pre-flight inventory → out-of-band path → window → apply → verify → rollback). Open the capabilities companion when the question is *what does hardware-safety even cover* (the class of changes in scope, the failure modes the policy prevents, the observability surface that gates a change, and the meta-policy that every per-artifact `## Safety policy` overlays).

Every per-artifact skill (services, libraries, tools) in the bundle that recommends a hardware-touching action overlays this meta-policy with artifact-specific safety. The per-artifact `## Safety policy` anchors do NOT redefine the cross-cutting discipline — they layer the artifact's own concerns on top of it. This skill is the layer they all build on.

Mandatory answer contract for an `mlxconfig`-class production change

An answer about applying an `mlxconfig`-class write on production MUST state every gate below explicitly; links to companion files do not substitute for walking the gates:

1. Name the change class before any apply step and state that its firmware-stored value commits at the next **cold power cycle**, not a warm reboot. 2. Require a pre-flight capture of PCIe topology, link state, firmware level, BFB level, the current `mlxconfig` configuration, and the host kernel/modules/environment. 3. Treat the change as potentially link-breaking and refuse to issue it until a deployment-specific OOB console class is named and proven reachable. Never describe an `mlxconfig`-class production write as inherently non-link-breaking. 4. Require a time-boxed maintenance window with stakeholders, rollback decision point, rollback plan, and verification gate documented before application. 5. Rehearse both the forward change and the rollback on a matching non-production replica before production. 6. Keep production workload gated until the four-way version match, per-artifact health metric, and end-to-end observability path all pass. 7. Name the rollback ladder: compare with the captured baseline → restore the captured values → cold-power-cycle → repeat inventory and four-way checks → route residual software symptoms to `doca-debug`. 8. Include an explicit refusal and escalation statement in the answer: if no documented rollback exists, the captured baseline cannot be restored, or OOB access is unavailable for a potentially link-breaking change, **stop and refuse to proceed**. Escalate to the operator's change-control process, vendor support, or the public DOCA Developer Forum; never guess at recovery. Merely naming a "refuse-and-escalate rule" without stating this action and route does