doca-bf3-deployment

---
name: doca-bf3-deployment
description: >
license: Apache-2.0
---

# 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 — the change-application
discipline is meta-policy owned by
[`doca-hardware-safety`](../doca-hardware-safety/SKILL.md), loaded
ALONGSIDE this skill.

## What this skill provides

This is a **thin loader**. Substantive material lives in two
companion files:

- `CAPABILITIES.md` — the BF3 platform-bring-up contract: the
  RShim/BFB transport surface (the userspace RShim daemon, the
  `/dev/rshim*` tree, console-over-rshim, the BFB image as the unit
  of input), the TMFIFO management-channel surface (`tmfifo_net0` /
  `tm-br`, the documented `192.168.100.x` convention, the
  `ip route get`-before-`ping` loopback gotcha), the DPU-mode
  surface (DPU / embedded-function vs separated-host / NIC mode, set
  via `mlxconfig` at BFB-install time — a MUTATING burn routed to
  [`doca-hardware-safety`](../doca-hardware-safety/SKILL.md)), the
  host-side-vs-Arm-side DOCA install distinction, the
  BF3-version overlay on the four-way match owned by
  [`doca-version`](../doca-version/SKILL.md), the cross-cutting error
  taxonomy, the observability surface, and the safety policy
  (overlay on
  [`doca-hardware-safety`](../doca-hardware-safety/SKILL.md)).
- `TASKS.md` — step-by-step workflows for the in-scope BF3
  lifecycle verbs: `configure`, `build` (routing stub), `modify`,
  `run` (the BFB-install + RShim/TMFIFO bring-up sequence), `test`
  (the post-BFB readiness smoke), `debug` (the six-state
  `bluefield-state-classifier`), and the `Deferred task verbs`
  block routing app-launch / container / install / library-API /
  hardware-state-change / BF4 questions out to their owning skills.

The skill assumes a target where:

- a BlueField-3 is physically present and powered, reachable from a
  host that has the RShim daemon and `/dev/rshim*` tree available,
- the operator has a BFB image downloaded from the public DOCA
  Downloads page (route via
  [`doca-public-knowledge-map`](../doca-public-knowledge-map/SKILL.md)),
  and
- the operator has an out-of-band path (BMC console, serial-over-LAN,
  or physical UART) to reach the BF3 if a push breaks the Arm OS.

It does **not** cover installing DOCA on a host from scratch (that
goes through [`doca-setup`](../doca-setup/SKILL.md)), and it does
**not** cover BlueField-4 (that goes through
[`doca-bf4-deployment`](../doca-bf4-deployment/SKILL.md)).

## Loading order

1. Read this `SKILL.md` first to confirm the user's question is in
   scope (BF3 platform bring-up over the RShim/BFB path; NOT BF4,
   NOT app-launch, NOT a library-API question).
2. **For the bring-up contract (RShim/BFB transport, TMFIFO
   channel, DPU-mode surface, host-vs-Arm install distinction,
   BF3-version overlay, error taxonomy, observability surface, BF3
   safety overlay), see [CAPABILITIES.md](CAPABILITIES.md).**
3. **For step-by-step workflows — `configure`, `build` (routing
   stub), `modify`, `run` (BFB install + RShim/TMFIFO bring-up),
   `test` (post-BFB readiness smoke), `debug` (the six-state
   `bluefield-state-classifier`), plus the `Deferred task verbs`
   block — see [TASKS.md](TASKS.md).**

## Example questions this skill answers well

See [`references/details.md`](references/details.md#example-questions-this-skill-answers-well).
## What this skill deliberately does not ship

See [`references/details.md`](references/details.md#what-this-skill-deliberately-does-not-ship).
## Related skills

See [`references/details.md`](references/details.md#related-skills).