doca-bf3-deployment

# DOCA BlueField-3 (BF3) deployment

**Where to start:** This skill is the bundle's home for **BlueField-3
day-1 platform bring-up** — taking a BF3 from "powered card in the
slot" (or a card that just came back broken from a BFB push) to
"Arm OS healthy, TMFIFO up, host PFs bound, four-way version match
closed, ready to run a workload". It owns the **classic RShim/BFB
path** that BF3 uses today; the newer BMC-Redfish provisioning path
is the sibling skill
[`doca-bf4-deployment`](../doca-bf4-deployment/SKILL.md) (the BF4
equivalent). If the user has a BF3 and needs to push a BFB, recover
a DPU that did not come back, or verify the install, open
[`TASKS.md`](TASKS.md) and start at
[`## configure`](TASKS.md#configure). If the question is *what shape
does the BF3 platform-bring-up surface even have*, start at
[`CAPABILITIES.md`](CAPABILITIES.md). Once the BF3 is healthy, this
skill routes **onward** to the deployment skills — running a binary
goes to
[`doca-bare-metal-deployment`](../doca-bare-metal-deployment/SKILL.md);
deploying a service container goes to
[`doca-container-deployment`](../doca-container-deployment/SKILL.md).

Every **mutating** burn invoked from a bring-up step — the BFB
reflash itself, any `mlxconfig set` (including a DPU/separated-host
mode flip), a firmware burn, or a kernel-boot-parameter change — is
governed by the change-application meta-policy in
[`doca-hardware-safety`](../doca-hardware-safety/SKILL.md), which
the agent loads ALONGSIDE this skill. This skill adds only the
**BF3-specific operational sequencing** on top; it does NOT redefine
the preflight / OOB-console / maintenance-window / rollback
discipline that meta-policy owns.

## Audience

This skill serves **external DOCA operators bringing up a real
BlueField-3** — i.e. people who already have:

- a physical BlueField-3 in a host (or a standalone BF3 they can
  reach over its console / management network),
- host-side RShim access to the DPU (the RShim userspace daemon and
  the `/dev/rshim*` character-device tree present over the PCIe or
  USB RShim interface), and
- a matching DOCA-Host install on the host plus a BlueField bundle
  (BFB) image downloaded from the public DOCA Downloads page.

It is **not** for:

- BlueField-4 bring-up (the BMC-Redfish provisioning path) — route
  to [`doca-bf4-deployment`](../doca-bf4-deployment/SKILL.md), the
  BF4 equivalent of this skill,
- kernel-driver or BlueField-OS developers contributing to `mlx5_*`
  or the BFB image itself (that is internal-tree work, not a
  field deployment),
- operators who already have a healthy BF3 and just want to *run a
  binary* (route to
  [`doca-bare-metal-deployment`](../doca-bare-metal-deployment/SKILL.md))
  or *deploy a service container* (route to
  [`doca-container-deployment`](../doca-container-deployment/SKILL.md)),
- fresh-no-hardware users with no DOCA install — route to
  [`doca-setup ## no-install`](../doca-setup/TASKS.md#no-install).

The skill teaches the agent the BF3 bring-up *procedure* and the
rules for quoting documented commands from the public BlueField
Platform Software Manual, the public DOCA Installation Guide, and
the MFT manual via
[`doca-public-knowledge-map`](../doca-public-knowledge-map/SKILL.md);
it does **not** invent `bfb-install` flag sets, BFB image filenames,
RShim character-device paths, `bf.cfg` schema keys, `mlxconfig`
parameter names, or TMFIFO subnets from memory. Where a fact is
already vetted in
[`doca-bare-metal-deployment ## bluefield-lifecycle`](../doca-bare-metal-deployment/TASKS.md#bluefield-lifecycle),
this skill reuses that exact fact rather than restating a new one.

## When to load this skill

Load this skill when the user is doing **hands-on BlueField-3
platform bring-up over the RShim/BFB path**, or asking a
cross-cutting BF3 lifecycle question that is not specific to one
library's API. Concretely:

- Pushing a BFB image to a BF3 for the first time (or re-pushing
  after a failed install), from the host over the RShim interface
  with `bfb-install`.
- Bringing up or recovering the host-to-DPU TMFIFO management
  channel (`tmfifo_net0`, the documented `192.168.100.x`
  convention) and the RShim console.
- Confirming RShim driver/daemon state on the host (the userspace
  `rshim` daemon and the `/dev/rshim*` tree) before any push or
  console capture.
- Deciding (and routing) a DPU-mode change — DPU / embedded-function
  mode vs separated-host / NIC mode — knowing the actual `mlxconfig
  set` burn leaves this skill for
  [`doca-hardware-safety`](../doca-hardware-safety/SKILL.md).
- Recovering a BF3 that did not come back after a BFB push:
  `bfb-install` exited 0 but the DPU never reached the documented
  `DPU is ready` marker; `ping 192.168.100.2` works but SSH refuses;
  host PFs are present in `lspci -d 15b3:` but their netdevs are
  gone.
- Verifying a BF3 install — `cat /etc/mlnx-release` on the Arm side,
  the four-way version match per
  [`doca-version`](../doca-version/SKILL.md) — and distinguishing
  the host-side DOCA install from the BlueField-Arm-side DOCA
  install.
- Cross-cutting questions: *"is DOCA on the host or on the Arm
  side, and which one do I install?"*, *"my BF3 was fine last week
  and after a BFB push it never came back — where do I start?"*,
  *"how do I tell which `/dev/rshim<N>` is which BlueField on a
  multi-DPU host?"*.

Do **not** load this skill for: BlueField-4 bring-up (route to
[`doca-bf4-deployment`](../doca-bf4-deployment/SKILL.md), the BF4
equivalent); running a DOCA-linked binary on a healthy BF3 (route to
[`doca-bare-metal-deployment`](../doca-bare-metal-deployment/SKILL.md));
deploying a DOCA service container (route to
[`doca-container-deployment`](../doca-container-deployment/SKILL.md));
env-preparation including hugepages, IOMMU, pkg-config, and devlink
mode flips (use [`doca-setup`](../doca-setup/SKILL.md)); the body of
the version-match rule (use [`doca-version`](../doca-version/SKILL.md));
or any hardware-state-changing burn itself — t