doca-bf3-deployment

Files (8)

• BENCHMARK.md
• CAPABILITIES.md
• SKILL.md
• TASKS.md
• evals.json · evals/
• details.md · references/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# DOCA BlueField-3 (BF3) deployment

## Examples

- **"I have a BlueField-3 and a BFB — how do I push it?"** — RShim
  plus bfb-install from the host. Exit 0 is not success until the
  DPU is ready.
- **"bfb-install exited 0 but the DPU never came back."** — start
  at the six-state classifier, not a second burn.

## Instructions

Follow Loading order below. Open the tasks companion for BFB push
and recover. Open the capabilities companion for the RShim/BFB
contract and safety overlay. Do not open every companion file.

**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/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
the tasks companion and start at
`## configure`. If the question is *what shape
does the BF3 platform-bring-up surface even have*, start at
the capabilities companion. Once the BF3 is healthy, this
skill routes **onward** to the deployment skills — running a binary
goes to
`doca-bare-metal-deployment/SKILL.md`;
deploying a service container goes to
`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/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/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/SKILL.md`)
  or *deploy a service container* (route to
  `doca-container-deployment/SKILL.md`),
- fresh-no-hardware users with no DOCA install — route to
  `doca-setup ## 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/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`,
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/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/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

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills