doca-hardware-safety

# DOCA hardware safety

**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
[`TASKS.md`](TASKS.md) 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 [`CAPABILITIES.md`](CAPABILITIES.md) 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.

## Example questions this skill answers well

The CLASSES of hardware-safety questions this skill is built to
answer, each with one worked example. The agent should treat the
*class* as load-bearing — the worked example is a single instance.

- **"I'm about to apply a hardware-touching change. What do I have to
  capture *before* I touch anything?"** — worked example: *"the
  per-artifact skill told me to flip a firmware-level emulation slot;
  what do I capture first?"*. Answered by the pre-flight inventory
  in [`TASKS.md ## configure`](TASKS.md#configure) plus the
  inventory taxonomy in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes).
- **"This change might drop the link I'm using to manage the
  BlueField. Is that safe?"** — worked example: *"I'm about to flip
  the BlueField between NIC and DPU mode over the same management
  link"*. Answered by the out-of-band access rule in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  plus the OOB-precondition gate in
  [`TASKS.md ## configure`](TASKS.md#configure).
- **"The per-artifact skill said to write an `mlxconfig` parameter,
  then reboot. Is that the right sequence?"** — worked example:
  *"the storage-emulation skill told me to enable a firmware slot
  via `mlxconfig` and then warm-reboot to apply it"*. Answered by
  the `mlxconfig`-class rule in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  plus the apply-with-cold-power-cycle workflow in
  [`TASKS.md ## modify`](TASKS.md#modify).
- **"My deployment plan reflashes the BlueField BFB during business
  hours. Is that OK?"** — worked example: *"I have a one-hour
  window during the day; can I reflash now?"*. Answered by the
  maintenance-window discipline in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  plus the firmware-burn workflow in
  [`TASKS.md ## modify`](TASKS.md#modify).
- **"How do I prove the change works *before* I touch production?"**
  — worked example: *"the change is small; can I skip the lab
  replica"*. Answered by the replica-first rule in
  [`TASKS.md ## test`](TASKS.md#test) plus the
  pre-hardware-validation pattern in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes).
- **"How do I roll back if this change goes wrong?"** — worked
  example: *"I just reflashed the BFB and the host can't see the
  representors anymore"*. Answered by the rollback ladder in
  [`TASKS.md ## debug`](TASKS.md#debug) plus the
  rollback-must-be-documented rule in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy).
- **"This change doesn't have a documented rollback. Should I still
  apply it?"** — worked example: *"the vendor says this firmware
  rev is one-way"*. Answered by the refuse-and-escalate rule in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  plus the escalation path in [`TASKS.md ## debug`](TASKS.md#debug).

## When to load this skill

Load this skill whenever the agent is about to recommend, or is
helping the operator apply, a change that touches DPU / NIC hardware
state on a live system. The decision must be made **before** the
agent composes its first sentence — the activation checklist below
is the same one referenced from
[`AGENTS.md ## Cross-cutting overlay activation triggers`](../../AGENTS.md#cross-cutting-overlay-activation-triggers),
mirrored here so a per-artifact skill that already loaded this skill
has the activation rule at hand.

## Agent activation checklist — load this skill at the START of the answer when any cell below is true

| Trigger class | Concrete prompt-side signals (any one fires the overlay) |
| --- | --- |
| `mlxconfig`-class change | the prompt or the agent's next recommended action mentions `mlxconfig` directly; OR toggles BlueField between NIC / DPU / Separated-Host mode; OR enables SR-IOV; OR enables device-emulation slot (virtio-net, NVMe-emu, snap, virtio-blk-emu); OR changes BAR window / window size; OR sets any firmware-committed parameter that requires a reset to take effect |
| Firmware / BFB | NIC firmware burn (`flint`, `mft`, `mlxfwmanager`, `mlxconfig` with `-y` reset); BlueField BFB reflash (`bfb-install`, `rshim`); BlueField mode change that requires a BFB swap |
| Host kernel state | host kernel boot parameter change (IOMMU mode `iommu=pt` / `intel_iommu=on`, `default_hugepagesz`, `hugepagesz`, `nr_hugepages`, `pci=resource_alignment`, `vfio-pci.ids`); requires host reboot |
| Hugepages | hugepage *reservation* change (`/sys/kernel/mm/hugepages/*/nr_hugepages`, `sysctl vm.nr_hugepages`); hugepage *mount* change (`mount -t hugetlbfs`); this is global state shared with every DOCA / DPDK process on the host |
| PCIe state | PCIe rebind / `echo > /sys/bus/pci/.../{bind,unbind,remove,rescan}`; representor enable/disable; eswitch mode change (`devlink dev eswitch set ... mode {switchdev,