doca-bf3-deployment

# 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 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 1. 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). 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 the capabilities companion.** 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 the tasks companion.** ## Example questions this skill answers well ## What this skill deliberately does not ship ## Related skills