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 (outside the scope of
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
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/SKILL.md, the BF4
equivalent); running a DOCA-linked binary on a healthy BF3 (route to
doca-bare-metal-deployment/SKILL.md);
deploying a DOCA service container (route to
doca-container-deployment/SKILL.md);
env-preparation including hugepages, IOMMU, pkg-config, and devlink
mode flips (use doca-setup/SKILL.md); the body of
the version-match rule (use doca-version/SKILL.md);
or any hardware-state-changing burn itself — the change-application
discipline is meta-policy owned by
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:
- the capabilities companion — 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/SKILL.md), the
host-side-vs-Arm-side DOCA install distinction, the
BF3-version overlay on the four-way match owned by
doca-version/SKILL.md, the cross-cutting error
taxonomy, the observability surface, and the safety policy
(overlay on
doca-hardware-safety/SKILL.md).
- the tasks companion — 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/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/SKILL.md), and it does
not cover BlueField-4 (that goes through
doca-bf4-deployment/SKILL.md).
Loading order
- Read this skill 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).
- 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 the capabilities companion.
- 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 the tasks companion.
Example questions this skill answers well
What this skill deliberately does not ship
Related skills
1---2license: Apache-2.03name: doca-bf3-deployment4description: >5 Use this skill for BlueField-3 (BF3) day-1 platform bring-up via the6 classic RShim/BFB path: pushing a BlueField bundle (BFB) to the DPU7 over RShim with bfb-install from the host, the host-to-DPU TMFIFO8 management channel (tmfifo_net0, the 192.168.100.x convention), RShim9 daemon state and console-over-rshim, DPU mode selection10 (DPU/embedded-function vs separated-host/NIC mode) via mlxconfig,11 post-BFB recovery, a six-state BlueField-state classifier, and12 verifying the install (cat /etc/mlnx-release plus version checks).13 Trigger even when the user does not say "BF3" — typical phrasings14 include {push a BFB to my BlueField-3}, {bfb-install exited 0 but the15 DPU never came back}, {ping 192.168.100.2 works but ssh fails}, or {is16 DOCA on the host or the Arm side?}. BFB reflash, mlxconfig set, mode17 changes, and firmware burns are destructive: require explicit18 target-bound confirmation and load doca-hardware-safety. App launch,19 container deploy, env install, and the BF4 BMC-Redfish path route20 elsewhere.21metadata:22 source: https://skillmd.com/skills/nvidia/doca-bf3-deployment23 author: NVIDIA <doca-feedback@nvidia.com>24 kind: library25 doca_version: "3.5"26 tags:27 - doca28 - bluefield-329 - deployment30compatibility: >31 No DOCA install required to read this skill (it is a32 platform-lifecycle overlay loaded against BF3 hardware); the33 bring-up and validation steps within DO require a real34 BlueField-3, host-side RShim access (PCIe or USB), the matching35 DOCA-Host install, and a BlueField bundle (BFB) image downloaded36 from the public DOCA Downloads page.37 The validation steps require a live DOCA install.38---3940# DOCA BlueField-3 (BF3) deployment4142## Examples4344- **"I have a BlueField-3 and a BFB — how do I push it?"** — RShim45 plus bfb-install from the host. Exit 0 is not success until the46 DPU is ready.47- **"bfb-install exited 0 but the DPU never came back."** — start48 at the six-state classifier, not a second burn.4950## Instructions5152Follow Loading order below. Open the tasks companion for BFB push53and recover. Open the capabilities companion for the RShim/BFB54contract and safety overlay. Do not open every companion file.5556**Where to start:** This skill is the bundle's home for **BlueField-357day-1 platform bring-up** — taking a BF3 from "powered card in the58slot" (or a card that just came back broken from a BFB push) to59"Arm OS healthy, TMFIFO up, host PFs bound, four-way version match60closed, ready to run a workload". It owns the **classic RShim/BFB61path** that BF3 uses today; the newer BMC-Redfish provisioning path62is the sibling skill63`doca-bf4-deployment/SKILL.md` (the BF464equivalent). If the user has a BF3 and needs to push a BFB, recover65a DPU that did not come back, or verify the install, open66the tasks companion and start at67`## configure`. If the question is *what shape68does the BF3 platform-bring-up surface even have*, start at69the capabilities companion. Once the BF3 is healthy, this70skill routes **onward** to the deployment skills — running a binary71goes to72`doca-bare-metal-deployment/SKILL.md`;73deploying a service container goes to74`doca-container-deployment/SKILL.md`.7576Every **mutating** burn invoked from a bring-up step — the BFB77reflash itself, any `mlxconfig set` (including a DPU/separated-host78mode flip), a firmware burn, or a kernel-boot-parameter change — is79governed by the change-application meta-policy in80`doca-hardware-safety/SKILL.md`, which81the agent loads ALONGSIDE this skill. This skill adds only the82**BF3-specific operational sequencing** on top; it does NOT redefine83the preflight / OOB-console / maintenance-window / rollback84discipline that meta-policy owns.8586## Audience8788This skill serves **external DOCA operators bringing up a real89BlueField-3** — i.e. people who already have:9091- a physical BlueField-3 in a host (or a standalone BF3 they can92 reach over its console / management network),93- host-side RShim access to the DPU (the RShim userspace daemon and94 the `/dev/rshim*` character-device tree present over the PCIe or95 USB RShim interface), and96- a matching DOCA-Host install on the host plus a BlueField bundle97 (BFB) image downloaded from the public DOCA Downloads page.9899It is **not** for:100101- BlueField-4 bring-up (the BMC-Redfish provisioning path) — route102 to `doca-bf4-deployment/SKILL.md`, the103 BF4 equivalent of this skill,104- kernel-driver or BlueField-OS developers contributing to `mlx5_*`105 or the BFB image itself (outside the scope of106 field deployment),107- operators who already have a healthy BF3 and just want to *run a108 binary* (route to109 `doca-bare-metal-deployment/SKILL.md`)110 or *deploy a service container* (route to111 `doca-container-deployment/SKILL.md`),112- fresh-no-hardware users with no DOCA install — route to113 `doca-setup ## no-install`.114115The skill teaches the agent the BF3 bring-up *procedure* and the116rules for quoting documented commands from the public BlueField117Platform Software Manual, the public DOCA Installation Guide, and118the MFT manual via119`doca-public-knowledge-map/SKILL.md`;120it does **not** invent `bfb-install` flag sets, BFB image filenames,121RShim character-device paths, `bf.cfg` schema keys, `mlxconfig`122parameter names, or TMFIFO subnets from memory. Where a fact is123already vetted in124`doca-bare-metal-deployment ## bluefield-lifecycle`,125this skill reuses that exact fact rather than restating a new one.126127## When to load this skill128129Load this skill when the user is doing **hands-on BlueField-3130platform bring-up over the RShim/BFB path**, or asking a131cross-cutting BF3 lifecycle question that is not specific to one132library's API. Concretely:133134- Pushing a BFB image to a BF3 for the first time (or re-pushing135 after a failed install), from the host over the RShim interface136 with `bfb-install`.137- Bringing up or recovering the host-to-DPU TMFIFO management138 channel (`tmfifo_net0`, the documented `192.168.100.x`139 convention) and the RShim console.140- Confirming RShim driver/daemon state on the host (the userspace141 `rshim` daemon and the `/dev/rshim*` tree) before any push or142 console capture.143- Deciding (and routing) a DPU-mode change — DPU / embedded-function144 mode vs separated-host / NIC mode — knowing the actual `mlxconfig145 set` burn leaves this skill for146 `doca-hardware-safety/SKILL.md`.147- Recovering a BF3 that did not come back after a BFB push:148 `bfb-install` exited 0 but the DPU never reached the documented149 `DPU is ready` marker; `ping 192.168.100.2` works but SSH refuses;150 host PFs are present in `lspci -d 15b3:` but their netdevs are151 gone.152- Verifying a BF3 install — `cat /etc/mlnx-release` on the Arm side,153 the four-way version match per154 `doca-version/SKILL.md` — and distinguishing155 the host-side DOCA install from the BlueField-Arm-side DOCA156 install.157- Cross-cutting questions: *"is DOCA on the host or on the Arm158 side, and which one do I install?"*, *"my BF3 was fine last week159 and after a BFB push it never came back — where do I start?"*,160 *"how do I tell which `/dev/rshim<N>` is which BlueField on a161 multi-DPU host?"*.162163Do **not** load this skill for: BlueField-4 bring-up (route to164`doca-bf4-deployment/SKILL.md`, the BF4165equivalent); running a DOCA-linked binary on a healthy BF3 (route to166`doca-bare-metal-deployment/SKILL.md`);167deploying a DOCA service container (route to168`doca-container-deployment/SKILL.md`);169env-preparation including hugepages, IOMMU, pkg-config, and devlink170mode flips (use `doca-setup/SKILL.md`); the body of171the version-match rule (use `doca-version/SKILL.md`);172or any hardware-state-changing burn itself — the change-application173discipline is meta-policy owned by174`doca-hardware-safety/SKILL.md`, loaded175ALONGSIDE this skill.176177## What this skill provides178179This is a **thin loader**. Substantive material lives in two180companion files:181182- the capabilities companion — the BF3 platform-bring-up contract: the183 RShim/BFB transport surface (the userspace RShim daemon, the184 `/dev/rshim*` tree, console-over-rshim, the BFB image as the unit185 of input), the TMFIFO management-channel surface (`tmfifo_net0` /186 `tm-br`, the documented `192.168.100.x` convention, the187 `ip route get`-before-`ping` loopback gotcha), the DPU-mode188 surface (DPU / embedded-function vs separated-host / NIC mode, set189 via `mlxconfig` at BFB-install time — a MUTATING burn routed to190 `doca-hardware-safety/SKILL.md`), the191 host-side-vs-Arm-side DOCA install distinction, the192 BF3-version overlay on the four-way match owned by193 `doca-version/SKILL.md`, the cross-cutting error194 taxonomy, the observability surface, and the safety policy195 (overlay on196 `doca-hardware-safety/SKILL.md`).197- the tasks companion — step-by-step workflows for the in-scope BF3198 lifecycle verbs: `configure`, `build` (routing stub), `modify`,199 `run` (the BFB-install + RShim/TMFIFO bring-up sequence), `test`200 (the post-BFB readiness smoke), `debug` (the six-state201 `bluefield-state-classifier`), and the `Deferred task verbs`202 block routing app-launch / container / install / library-API /203 hardware-state-change / BF4 questions out to their owning skills.204205The skill assumes a target where:206207- a BlueField-3 is physically present and powered, reachable from a208 host that has the RShim daemon and `/dev/rshim*` tree available,209- the operator has a BFB image downloaded from the public DOCA210 Downloads page (route via211 `doca-public-knowledge-map/SKILL.md`),212 and213- the operator has an out-of-band path (BMC console, serial-over-LAN,214 or physical UART) to reach the BF3 if a push breaks the Arm OS.215216It does **not** cover installing DOCA on a host from scratch (that217goes through `doca-setup/SKILL.md`), and it does218**not** cover BlueField-4 (that goes through219`doca-bf4-deployment/SKILL.md`).220221## Loading order2222231. Read this skill first to confirm the user's question is in224 scope (BF3 platform bring-up over the RShim/BFB path; NOT BF4,225 NOT app-launch, NOT a library-API question).2262. **For the bring-up contract (RShim/BFB transport, TMFIFO227 channel, DPU-mode surface, host-vs-Arm install distinction,228 BF3-version overlay, error taxonomy, observability surface, BF3229 safety overlay), see the capabilities companion.**2303. **For step-by-step workflows — `configure`, `build` (routing231 stub), `modify`, `run` (BFB install + RShim/TMFIFO bring-up),232 `test` (post-BFB readiness smoke), `debug` (the six-state233 `bluefield-state-classifier`), plus the `Deferred task verbs`234 block — see the tasks companion.**235236## Example questions this skill answers well237238## What this skill deliberately does not ship239240## Related skills241