# Evaluation Report

Evaluation of the `doca-bf3-deployment` skill before publication through Skill Evaluator.

This benchmark summarizes 3-Tier Evaluation from Skill Evaluator results for the skill. The goal is to document whether the skill is safe, discoverable, effective, and useful for agents before it is published for broader workflow use.

## Evaluation Summary

- Skill: `doca-bf3-deployment`
- Evaluation date: 2026-07-26
- Environment: `k8s-sandbox`
- Dataset: 3 evaluation tasks
- Attempts per task: 1
- Pass threshold: 50%
- Overall verdict: PASS

## Agents Used

- Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`)
- Codex (`openai/openai/gpt-5.5`)

## Metrics Used

Reported benchmark dimensions:

- Security: checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access.
- Correctness: checks whether the agent follows the expected workflow and produces the correct final output.
- Discoverability: checks whether the agent loads the skill when relevant and avoids using it when irrelevant.
- Effectiveness: checks whether the agent performs measurably better with the skill than without it.
- Efficiency: checks whether the agent uses fewer tokens and avoids redundant work.

Underlying evaluation signals used in this run:

- `security` (Security): checks for unsafe operations, secret leakage, and unauthorized access.
- `skill_execution` (Skill Execution): verifies that the agent loaded the expected skill and workflow.
- `skill_efficiency` (Efficiency): checks routing quality, decoy avoidance, and redundant tool usage.
- `accuracy` (Accuracy): grades final-answer correctness against the reference answer.
- `goal_accuracy` (Goal Accuracy): checks whether the overall user task completed successfully.
- `behavior_check` (Behavior Check): verifies expected behavior steps, including safety expectations.

## Test Tasks

The benchmark dataset contained 3 evaluation tasks:

- Positive tasks: 2 tasks where the skill was expected to activate.
- Negative tasks: 1 tasks where no skill was expected.
- Unlabeled tasks: 0 tasks where positive/negative intent could not be inferred.

Task composition is derived from the evaluation dataset when possible. Entries with `expected_skill` set are treated as positive skill-activation cases, while entries with `expected_skill: null` are treated as negative activation cases.

## Results

| Dimension | Num | Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`) | Codex (`openai/openai/gpt-5.5`) |
|---|---:|---:|---:|
| Security | 3 | 100% (+0%) | 100% (+0%) |
| Correctness | 3 | 100% (+53%) | 100% (+33%) |
| Discoverability | 3 | 100% (+50%) | 90% (+40%) |
| Effectiveness | 3 | 91% (+40%) | 98% (+54%) |
| Efficiency | 3 | 92% (+42%) | 98% (+64%) |

Score values show skill-assisted performance. Values in parentheses show uplift versus the no-skill baseline when baseline data is available.

## Tier 1: Static Validation Summary

Tier 1 validation passed with observations. Skill Evaluator ran 1 checks and found 5 total findings.

Top findings:

- MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Instructions' (`skills/doca-bf3-deployment/SKILL.md`)
- MEDIUM SCHEMA/body_recommended_section: Missing recommended section: '## Examples' (`skills/doca-bf3-deployment/SKILL.md`)
- MEDIUM SCHEMA/author_missing: Author not specified in metadata (`skills/doca-bf3-deployment/SKILL.md`)
- LOW SCHEMA/unexpected_file: Unexpected 'CAPABILITIES.md' in skill root (`skills/doca-bf3-deployment/CAPABILITIES.md`)
- LOW SCHEMA/unexpected_file: Unexpected 'TASKS.md' in skill root (`skills/doca-bf3-deployment/TASKS.md`)

## Tier 2: Deduplication Summary

This tier was not run or did not produce findings in this report.

## Publication Recommendation

The skill is suitable to proceed toward Skill Evaluator publication based on this benchmark. Skill owners should keep this file with the skill and refresh it when the evaluation dataset, skill behavior, or target agents materially change.

# DOCA BlueField-3 (BF3) deployment — Capabilities

**Where to start:** The pattern overview below names the recurring
BF3 platform-bring-up patterns the agent walks for any BlueField-3.
Pick the pattern first, then drill into the H2 that owns the
substance. For the *how* of executing each pattern, jump to
[TASKS.md](TASKS.md). For the BF4 counterpart of the same lifecycle
(the BMC-Redfish provisioning path), see the sibling skill
[`doca-bf4-deployment`](../doca-bf4-deployment/SKILL.md) — the BF4
equivalent. For the cross-cutting safety meta-policy this skill
overlays (and which owns every mutating burn named below), see
[`doca-hardware-safety`](../doca-hardware-safety/SKILL.md).

This file enumerates the BF3 platform-bring-up contract as described
in the public **BlueField Platform Software Manual**, the public
**DOCA Installation Guide**, and the public **MFT manual** (`flint`,
`mlxconfig`, `mlxfwmanager`) — all reachable through
[`doca-public-knowledge-map`](../doca-public-knowledge-map/SKILL.md)
— plus the standard Linux primitives the RShim/TMFIFO path inherits
(`modprobe(8)`, `lspci(8)`, `ip-route(8)`). Treat this file as a
*map of what is documented*, not a substitute for reading the live
manuals against the operator's BF3. The BF3 lifecycle facts here are
the same facts vetted in
[`doca-bare-metal-deployment ## bluefield-lifecycle`](../doca-bare-metal-deployment/TASKS.md#bluefield-lifecycle);
this skill is their consolidated BF3 home, not a re-derivation.

## Pattern overview

Every BF3-bring-up question this skill teaches resolves into one of
SIX patterns. The patterns are CLASSES — they apply to any
BlueField-3 regardless of which DOCA release the operator is
landing.

| BF3 bring-up pattern | Class shape | Where the substance lives |
| --- | --- | --- |
| 1. Recognise the install side — host-side DOCA-Host vs Arm-side BlueField-OS DOCA | Which package the operator installs where; which side `pkg-config --modversion doca-common` is read on; which side the binary will eventually run | [`## Capabilities and modes`](#capabilities-and-modes) install-side table |
| 2. Push a BFB over RShim | `bfb-install` streams the BFB to the DPU over the RShim PCIe/USB interface; the Arm side reboots through UEFI to Linux up to first-boot init | [`## Capabilities and modes`](#capabilities-and-modes) RShim/BFB surface |
| 3. Bring up / recover the TMFIFO channel | `tmfifo_net0` (or the `tm-br` bridge), the documented `192.168.100.x` convention, the `ip route get`-before-`ping` loopback gotcha | [`## Capabilities and modes`](#capabilities-and-modes) TMFIFO surface |
| 4. Select the DPU mode | DPU / embedded-function vs separated-host / NIC mode, set via `mlxconfig` at BFB-install time — a MUTATING burn | [`## Safety policy`](#safety-policy) + [`doca-hardware-safety`](../doca-hardware-safety/SKILL.md) |
| 5. Map a not-yet-healthy BF3 back to its state | installer-running → uefi-only → linux-up-tmfifo-down → tmfifo-up-ssh-down → arm-ok-host-pfs-unbound → host-bf-version-mismatch | [`## Error taxonomy`](#error-taxonomy) six-state classifier |
| 6. Verify before declaring healthy | readiness markers (not a timer), `cat /etc/mlnx-release`, host PF rebind, the four-way version match re-close | [`## Observability`](#observability) + [`## Version compatibility`](#version-compatibility) |

Two cross-cutting rules apply to *every* pattern above:

- **Operate the documented path; do not invent one.** `bfb-install`
  flags, the BFB image filename, the `/dev/rshim<N>` path, the
  `bf.cfg` schema keys, the `mlxconfig` mode parameters, and the
  TMFIFO subnet all come from the public BlueField Platform Software
  Manual, the MFT manual, or `--help` on the installed tool.
  Inferring them from generic Linux intuition or from a previous
  BF2's behaviour is the most common hallucination failure for this
  skill.
- **Every mutating burn is governed by the meta-policy alongside this
  skill.** The
  BFB reflash itself, any `mlxconfig set` (including a DPU-mode
  flip), a firmware burn, and any kernel-boot-parameter change are
  owned by
  [`doca-hardware-safety`](../doca-hardware-safety/SKILL.md) for the
  preflight / OOB-console / maintenance-window / rollback
  discipline. Keep this skill loaded for BF3-specific *sequencing*;
  `doca-hardware-safety ## modify` owns whether and how the mutation
  may proceed.

## Capabilities and modes

### Install side — host-side DOCA-Host vs Arm-side BlueField-OS DOCA

A BlueField-3 deployment has DOCA on TWO distinct sides, and the
operator must be explicit about which one a given step touches.

| Property | Host-side (DOCA-Host) | Arm-side (BlueField-OS DOCA) |
| --- | --- | --- |
| What is installed | The DOCA-Host packages on the host x86/Arm OS, per the public DOCA Installation Guide host-side path (reached through [`doca-public-knowledge-map`](../doca-public-knowledge-map/SKILL.md)) | The DOCA userland baked into the BFB image, landed on the BF3 Arm cores by the BFB push |
| How it lands | `apt` / `dnf` install on the host, routed via [`doca-setup`](../doca-setup/SKILL.md) | `bfb-install` pushing the BFB over RShim (this skill, [`TASKS.md ## run`](TASKS.md#run)) |
| Version read with | `pkg-config --modversion doca-common` + `doca_caps --version` on the host | `cat /etc/mlnx-release` + `bfver` on the BF3 Arm console |
| What runs there | Host-side binaries/containers talking to the BF3 NIC over PCIe | Arm-side binaries/containers running on the DPU cores directly |
| Routes onward to | [`doca-bare-metal-deployment`](../doca-bare-metal-deployment/SKILL.md) / [`doca-container-deployment`](../doca-container-deployment/SKILL.md) once healthy | the same two deployment skills, Arm-side leg |

The load-bearing recognition: *"is DOCA on the host or on the Arm
side?"* is the FIRST question for any BF3 deploy. The agent confirms
which side a step touches before walking it; conflating them ("just
install DOCA") is the canonical BF3 first-contact failure.

### RShim / BFB transport surface

RShim is the host-side surface that exposes the BF3 Arm console
(`/dev/rshim<N>/console`) AND the host-side endpoint of the TMFIFO
recovery interface. The BFB (BlueField bundle) is the unit of input:
`bfb-install` streams it to the DPU over the RShim PCIe (or USB)
interface, and the Arm side reboots through UEFI to Linux up to
first-boot init. On DOCA 3.3+ hosts the RShim surface ships as a
**userspace daemon** (`/usr/sbin/rshim` started by `rshim.service`);
the legacy in-tree kernel module is no longer shipped, so
`lsmod | grep rshim` being empty is EXPECTED, not failure evidence.
On a multi-DPU host the agent disambiguates which `/dev/rshim<N>`
maps to which BF3 (via the `DEV_NAME` field of each `misc` file,
cross-matched against `lspci -d 15b3: -nn`) BEFORE any per-DPU
`bfb-install` — skipping it is the #1 cause of *"I flashed the wrong
DPU"* incidents. The agent does NOT fabricate the `bfb-install` flag
set, the BFB filename, or the `/dev/rshim<N>` path; all come from
`--help` and the BSP manual.

### TMFIFO management-channel surface

The TMFIFO interface is the host-to-DPU *recovery* path when the
BF3's normal management network is broken; it is NOT a primary data
path. Factory defaults per the BlueField Platform Software Manual:
host-side address `192.168.100.1/30`, BlueField-side address
`192.168.100.2/30` (the agent does NOT fabricate the subnet). The
host-side interface is `tmfifo_net0`, or `tm-br` on BSP/DOCA-host
installs that bridge `tmfifo_net0` into a `tm-br` bridge. The
load-bearing gotcha: a `ping 192.168.100.2` that "works" can be
pinging the HOST, not the BF3, when the BlueField-side address has
been bound locally; the agent ALWAYS runs `ip route get
<bf-tmfifo-address>` first and accepts `dev tmfifo_net0` OR `dev
tm-br` as healthy egress, while `dev lo` / `local <bf-addr> dev lo`
is the broken local-loopback signature.

### DPU-mode surface (MUTATING — routed out)

A BF3 boots in one of two operating modes: **DPU / embedded-function
mode** (the Arm cores own the data path; the host sees a managed
function) or **separated-host / NIC mode** (the host owns the ports
directly; the Arm side is out of the data path). The mode is
selected via `mlxconfig` NV-config parameters, typically applied
from a `bfb_modify_os()` hook in `bf.cfg` at BFB-install time;
reconfiguring the same modes after install typically requires
another BFB push. Because `mlxconfig set` is a hardware-state change,
the agent quotes the `bf.cfg`/`mlxconfig` parameter keys from the
public schema but routes the actual set/burn to
[`doca-hardware-safety`](../doca-hardware-safety/SKILL.md) — this
skill names the *sequencing* (mode decision belongs at BFB-install
time, not after), the meta-policy owns the burn.

## Version compatibility

For the canonical DOCA version-detection chain, the four-way match
rule (host package ↔ binary build ↔ BlueField firmware ↔
DOCA-version policy), and the headers-win-over-docs rule, see
[`doca-version`](../doca-version/SKILL.md). The body lives there;
this skill does not duplicate it.

**The BF3-bring-up-specific overlay** is:

- **The BF3 has THREE independent version legs, read on different
  sides.** (i) The host-side DOCA-Host install version
  (`pkg-config --modversion doca-common` + `doca_caps --version` on
  the host). (ii) The BFB-image DOCA version on the Arm side
  (`cat /etc/mlnx-release` + `bfver` on the BF3 Arm console — this
  is the DOCA userland inside the BFB). (iii) The NIC-side firmware
  version (`flint -d <bdf> q`, the `FW Version:` line — NOT
  `mlxconfig -d <bdf> q`, which returns the firmware *configuration*
  dump, not the version). A mismatch among any two is the canonical
  *"the docs say this should work but it does not"* trap.
- **`cat /etc/mlnx-release` is the BF3 install-verification anchor.**
  After a BFB push, this is the first read that confirms which BFB
  landed; it is the Arm-side leg of the four-way match and the
  rollback baseline for any subsequent re-push.
- **Push the BFB and the host-side DOCA-Host install together.** A
  BFB push that is not accompanied by a matching host-side
  DOCA-Host alignment lands the `host-bf-version-mismatch` state in
  [`## Error taxonomy`](#error-taxonomy); resolve any
  `/etc/apt/sources.list.d/doca.list` repo-pin drift per
  [`doca-version TASKS.md ## apt-source consistency`](../doca-version/TASKS.md#apt-source-consistency)
  BEFORE installing anything new, and route any host-side reinstall
  through [`doca-setup`](../doca-setup/SKILL.md).
- **Do NOT substitute `mlxconfig -d <bdf> q` for the FW-version
  leg, and do NOT invent `bfb-info`** (not a real
  NVIDIA-documented tool) for the BFB-image leg — both are common
  hallucinations banned in
  [`doca-version CAPABILITIES.md ## Version compatibility`](../doca-version/CAPABILITIES.md#version-compatibility).
  Capture per-device (`flint -d <bdf> q`), not globally — two BF3s
  from different procurement waves on the same host are independent
  silicon with independent FW levels.

## Error taxonomy

A BF3 that has had a BFB push, a soft-reset, or a host PF rebind and
is *not yet* confirmed healthy is classified by the six-state
`bluefield-state-classifier`, walked IN ORDER in
[`TASKS.md ## debug`](TASKS.md#debug). The states are the SAME six
vetted in
[`doca-bare-metal-deployment ### bluefield-state-classifier`](../doca-bare-metal-deployment/TASKS.md#bluefield-state-classifier);
this skill is their BF3 home.

1. **`installer-still-running`.** `bfb-install` still resident on
   the host AND the RShim console buffer still emitting documented
   installer progress lines. Root cause class: install in flight,
   not failure. Recovery: WAIT — aborting a first-flash push
   mid-write is what *creates* the next state down.
2. **`uefi-only`.** The RShim console reports the documented
   UEFI-exit marker but never reaches the documented `Linux up`
   marker. Root cause class: kernel did not hand off to userspace —
   common after a partial BFB-install whose firmware-update sub-step
   silently failed. Recovery: capture the full console buffer and
   host `dmesg`, do a documented cold power cycle (via BMC, not
   `reboot` from the dead Arm side) BEFORE re-pushing.
3. **`linux-up-tmfifo-down`.** Documented `Linux up` marker present,
   BUT the TMFIFO probe returns no host-side address. Root cause
   class: TMFIFO interface never came up (driver / udev / link
   state). Recovery: re-check the host RShim daemon, run the
   documented TMFIFO bring-up, THEN re-run the `ip route get`
   loopback check.
4. **`tmfifo-up-ssh-down`.** TMFIFO probe passes (and `ip route get`
   confirms the route goes to the BF3, not local loopback), BUT SSH
   to the documented Arm-side endpoint refuses or hangs. Root cause
   class: Arm-side `sshd` not yet listening, OR the operator's
   `authorized_keys` / password was not in the `bf.cfg`. Recovery:
   wait the documented `sshd`-ready bound, else fall through to the
   RShim console and re-seed credentials there.
5. **`arm-ok-host-pfs-unbound`.** Arm-side SSH alive and OS healthy,
   BUT host-side enumeration is broken — `lspci -d 15b3:` shows the
   PFs, `ip link show` does NOT show the netdevs, `ibv_devinfo` is
   empty, DOCA programs cannot attach by representor name. Root
   cause class: stale host `mlx5` driver-binding state post-push.
   Recovery: route the documented PF-rebind sequence through
   [`doca-hardware-safety ## modify`](../doca-hardware-safety/TASKS.md#modify),
   then return to the identical readiness smoke in
   [`TASKS.md ## test`](TASKS.md#test); do NOT launch any DOCA
   binary in this state.
6. **`host-bf-version-mismatch`.** Everything above looks healthy,
   but the four-way version match owned by
   [`doca-version`](../doca-version/SKILL.md) does not close.
   Recovery: walk [`doca-version TASKS.md`](../doca-version/TASKS.md)
   in full, resolve apt-source / repo-pin drift first, route any
   host-side reinstall through [`doca-setup`](../doca-setup/SKILL.md).

Three cross-cutting rules: **evaluate all six states and report every
match before selecting a recovery**; **recover in dependency order**
(installer → boot/Arm → TMFIFO → SSH → PF binding → version); and
**never declare healthy from absence of evidence** (a TMFIFO `ping`
without `ip route get`, an SSH connect without `uptime`/`dmesg`, an
`lspci` listing without a usable netdev are each NOT proof). Each
recovery is followed by the identical readiness-smoke tuple defined
in `TASKS.md ## test`, so before/after evidence remains comparable.

## Observability

Documented observability surfaces for BF3 bring-up, in the order the
agent reaches for them. Healthy means all of them agree; a wall-clock
sleep is never a substitute for a documented readiness marker.

- **RShim console buffer (FIRST).** The Arm-side boot story lives in
  `/dev/rshim<N>/console`. The agent watches for the documented
  `Linux up` and `DPU is ready` markers (per the BSP manual) and for
  any `[MISC]` / `[ERR]` line containing a failure verb ("failed",
  "error", "abort") — the canonical partial-install signature is
  *"Ubuntu installation completed"* followed by an
  `INFO[MISC]: NIC firmware update failed` line while `bfb-install`
  still exits 0. Exit code 0 alone is NOT proof of success.
- **TMFIFO reachability (SECOND).** `ip addr show tmfifo_net0` (or
  the `tm-br` bridge) on the host, then `ip route get
  <bf-tmfifo-address>` BEFORE any `ping` — the `dev lo` /
  `local <bf-addr> dev lo` output is the local-loopback failure that
  makes `ping` lie.
- **Host PF enumeration (THIRD).** `lspci -d 15b3:` lists the BF3
  PFs; `ip link show` enumerates their netdevs; `ibv_devinfo`
  enumerates the RDMA devices; `devlink dev show` lists the devlink
  instance. PFs present in `lspci` but absent from `ip link` is the
  `arm-ok-host-pfs-unbound` state.
- **Install verification (FOURTH).** `cat /etc/mlnx-release` +
  `bfver` on the Arm side confirm which BFB landed;
  `mlxconfig -d <pci> query` (QUERY only) reads the firmware
  configuration; `flint -d <bdf> q` reads the FW version. Any
  `mlxconfig set` is a hardware-state change owned by
  [`doca-hardware-safety`](../doca-hardware-safety/SKILL.md).

Cross-cutting host-side debug (kernel version, driver loaded/not,
PCIe link state, `dmesg`) lives in
[`doca-debug TASKS.md ## debug`](../doca-debug/TASKS.md#debug); this
skill names only the BF3-bring-up-specific surfaces.

## Safety policy

> **Overlay on the bundle-wide hardware-safety meta-policy.** The
> rules below are this skill's per-artifact overlay on the
> cross-cutting rules in
> [`doca-hardware-safety` CAPABILITIES.md ## Safety policy](../doca-hardware-safety/CAPABILITIES.md#safety-policy)
> (specifically
> [### Per-artifact overlay pattern](../doca-hardware-safety/CAPABILITIES.md#per-artifact-overlay-pattern)).
> When the two layers disagree, the stricter wins; when either layer
> says STOP, the agent stops.

- **Every mutating burn loads the safety meta-policy alongside.** A
  BFB reflash, any
  `mlxconfig set` (including a DPU/separated-host mode flip), a
  firmware burn, and any kernel-boot-parameter change are
  hardware-state changes. The agent hands the change-application
  discipline (preflight inventory, OOB console, maintenance window,
  rollback) to
  [`doca-hardware-safety ## modify`](../doca-hardware-safety/TASKS.md#modify)
  while retaining this skill for BF3 sequencing. Continue the BF3
  workflow only after that change is complete and verified. This
  skill owns the *sequencing*, never the burn discipline.
- **An OOB path is a precondition, not a nicety.** Before any BFB
  push the operator must have a BMC console / serial-over-LAN /
  physical UART path to reach the BF3 if the push breaks the Arm OS.
  Without one, the bar to proceed is "stop, escalate" per the
  meta-policy.
- **Never declare healthy from `bfb-install` exit 0 alone.** Parse
  the console / log output for the documented `Linux up` / `DPU is
  ready` markers and for any failure-verb line, and run the
  post-BFB readiness smoke in [`TASKS.md ## test`](TASKS.md#test)
  before re-declaring the BF3 ready. Do NOT invent `bfb-install`
  flags, BFB filenames, `/dev/rshim<N>` paths, `bf.cfg` keys, or the
  TMFIFO subnet from memory — quote the live `--help` and the BSP
  manual.

## Public-source pointer

The canonical public sources for BF3 platform bring-up are:

- The **BlueField Platform Software Manual** on `docs.nvidia.com`,
  reachable through
  [`doca-public-knowledge-map ## Public documentation entry points`](../doca-public-knowledge-map/SKILL.md#public-documentation-entry-points),
  for `bfb-install`, the `bf.cfg` schema, RShim/TMFIFO, and the
  readiness markers.
- The **DOCA Installation Guide** on `docs.nvidia.com`, reachable
  through the same routing table, for the host-side DOCA-Host
  install path and the BFB download location (the public DOCA
  Downloads page).
- The **MFT manual** (`flint`, `mlxconfig`, `mlxfwmanager`) for the
  firmware-query and NV-config surfaces.

Verify that the version of each manual matches the operator's DOCA
release and BFB image per
[`## Version compatibility`](#version-compatibility) — flag names,
`bf.cfg` keys, and readiness markers evolve, so anything quoted from
memory is suspect.

## Description: <br>
Guides BlueField-3 (BF3) day-1 platform bring-up via the classic RShim/BFB path: pushing a BlueField bundle to the DPU over RShim with bfb-install from the host, managing the TMFIFO channel, DPU mode selection, post-BFB recovery, and install verification. <br>

This skill is ready for commercial/non-commercial use. <br>

## Owner
NVIDIA <br>

### License/Terms of Use: <br>
Apache 2.0 AND CC-BY-4.0 <br>
## Use Case: <br>
Developers and engineers performing hands-on BlueField-3 platform bring-up, including pushing BFB images over RShim, recovering DPUs that fail to come back after a push, verifying installs, and managing DPU mode selection. <br>

### Deployment Geography for Use: <br>
Global <br>

## Requirements / Dependencies: <br>
**Requires API Key or External Credential:** [Not Specified] <br>
**Credential Type(s):** [None identified] <br>

Do not include secrets in prompts/logs/output; use least-privilege credentials; rotate keys as appropriate. <br>

## Known Risks and Mitigations: <br>
Risk: Review before execution as proposals could introduce incorrect or misleading guidance into skills. <br>
Mitigation: Review and scan skill before deployment. <br>

## Reference(s): <br>
- [NVIDIA DOCA SDK Documentation](https://docs.nvidia.com/doca/sdk/index.html) <br>
- [DOCA Samples (GitHub)](https://github.com/NVIDIA-DOCA/doca-samples) <br>
- [DOCA Platform Framework (GitHub)](https://github.com/NVIDIA/doca-platform) <br>
- [details.md](references/details.md) <br>


## Skill Output: <br>
**Output Type(s):** [Shell commands, Configuration instructions, Analysis] <br>
**Output Format:** [Markdown with inline bash code blocks] <br>
**Output Parameters:** [1D] <br>
**Other Properties Related to Output:** [None] <br>

## Evaluation Agents Used: <br>
- Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`) <br>
- Codex (`openai/openai/gpt-5.5`) <br>



## Evaluation Tasks: <br>
Evaluated against 3 evaluation tasks (2 positive skill-activation, 1 negative) in a k8s-sandbox environment. <br>

## Evaluation Metrics Used: <br>
Reported benchmark dimensions: <br>
- Security: Checks whether skill-assisted execution avoids unsafe behavior such as secret leakage, destructive commands, or unauthorized access. <br>
- Correctness: Checks whether the agent follows the expected workflow and produces the correct final output. <br>
- Discoverability: Checks whether the agent loads the skill when relevant and avoids using it when irrelevant. <br>
- Effectiveness: Checks whether the agent performs measurably better with the skill than without it. <br>
- Efficiency: Checks whether the agent uses fewer tokens and avoids redundant work. <br>

Underlying evaluation signals used in this run: <br>
- `security`: Checks for unsafe operations, secret leakage, and unauthorized access. <br>
- `skill_execution`: Verifies that the agent loaded the expected skill and workflow. <br>
- `skill_efficiency`: Checks routing quality, decoy avoidance, and redundant tool usage. <br>
- `accuracy`: Grades final-answer correctness against the reference answer. <br>
- `goal_accuracy`: Checks whether the overall user task completed successfully. <br>
- `behavior_check`: Verifies expected behavior steps, including safety expectations. <br>



## Evaluation Results: <br>
| Dimension | Num | Claude Code (`aws/anthropic/bedrock-claude-opus-4-8`) | Codex (`openai/openai/gpt-5.5`) |
|---|---:|---:|---:|
| Security | 3 | 100% (+0%) | 100% (+0%) |
| Correctness | 3 | 100% (+53%) | 100% (+33%) |
| Discoverability | 3 | 100% (+50%) | 90% (+40%) |
| Effectiveness | 3 | 91% (+40%) | 98% (+54%) |
| Efficiency | 3 | 92% (+42%) | 98% (+64%) |

## Skill Version(s): <br>
18a69be (source: git SHA, committed 2026-07-26) <br>

## Ethical Considerations: <br>
NVIDIA believes Trustworthy AI is a shared responsibility and we have established policies and practices to enable development for a wide array of AI applications. When downloaded or used in accordance with our terms of service, developers should work with their internal team to ensure this skill meets requirements for the relevant industry and use case and addresses unforeseen product misuse. <br>

(For Release on NVIDIA Platforms Only) <br>
Please report quality, risk, security vulnerabilities or NVIDIA AI Concerns [here](https://app.intigriti.com/programs/nvidia/nvidiavdp/detail). <br>

---
license: Apache-2.0
name: doca-bf3-deployment
description: >
  Use this skill for BlueField-3 (BF3) day-1 platform bring-up via
  the classic RShim/BFB path: pushing a BlueField bundle (BFB) to
  the DPU over RShim with bfb-install from the host, the host-to-DPU
  TMFIFO management channel (tmfifo_net0, the 192.168.100.x
  convention), RShim daemon state and console-over-rshim, DPU mode
  selection (DPU/embedded-function vs separated-host/NIC mode) via
  mlxconfig, post-BFB recovery, a six-state BlueField-state
  classifier, and verifying the install (cat /etc/mlnx-release plus
  version checks). Trigger even when the user does not say "BF3" —
  typical phrasings include {push a BFB to my BlueField-3},
  {bfb-install exited 0 but the DPU never came back}, {ping
  192.168.100.2 works but ssh fails}, or {is DOCA on the host or
  the Arm side?}. BFB reflash, mlxconfig set, mode changes, and
  firmware burns are destructive: require explicit target-bound
  confirmation and load doca-hardware-safety. App launch, container
  deploy, env install, and the BF4 BMC-Redfish path route elsewhere.
metadata:
  kind: library
compatibility: >
  No DOCA install required to read this skill (it is a
  platform-lifecycle overlay loaded against BF3 hardware); the
  bring-up and validation steps within DO require a real
  BlueField-3, host-side RShim access (PCIe or USB), the matching
  DOCA-Host install, and a BlueField bundle (BFB) image downloaded
  from the public DOCA Downloads page.
---

# 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).

# DOCA BlueField-3 (BF3) deployment — Tasks

**Where to start:** The verb order is `configure → build → modify →
run → test → debug`. For BF3 platform bring-up, `build` is a
*routing stub* — there is no application or BFB artifact to build
inside this skill (building a DOCA-linked binary lives in
[`doca-programming-guide`](../doca-programming-guide/SKILL.md);
building the BFB image itself is internal-tree work, out of scope).
This skill owns taking a real BF3 from "powered card" to "Arm OS
healthy, host PFs bound, version match closed". The `## run` verb is
the BFB-install + RShim/TMFIFO bring-up sequence; `## test` is the
post-BFB readiness smoke; `## debug` is the six-state classifier.

Every step assumes the operator has consulted the live public
BlueField Platform Software Manual, the public DOCA Installation
Guide, and the MFT manual (all reachable through
[`doca-public-knowledge-map ## Public documentation entry points`](../doca-public-knowledge-map/SKILL.md#public-documentation-entry-points))
and is using them as the authoritative reference; this file
prescribes the *order* and *what to look up where*, not a copy-paste
runbook. If the release-matched live manual or installed tool
`--help` is unavailable, STOP rather than using remembered flags,
paths, keys, subnets, or timeout values. Every mutating burn (BFB reflash, `mlxconfig set`, firmware
burn, kernel-boot-parameter change) STILL routes through
[`doca-hardware-safety`](../doca-hardware-safety/SKILL.md) for the
meta-policy — this file adds only the BF3-specific sequencing. These
operations are destructive: verify the exact target and require explicit
target-bound confirmation before issuing any command.

## configure

Preparing the BF3 bring-up, confirming every precondition the push
will rely on, and recognizing the install side BEFORE any BFB is
pushed.

1. **Recognise the install side.** Confirm with the operator which
   side the work touches — host-side DOCA-Host on the host OS, OR
   Arm-side DOCA baked into the BFB landing on the DPU cores. Per
   the install-side table in
   [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes),
   this is the FIRST question for any BF3 deploy. If the operator is
   ambiguous, derive it from where the install lives
   (`/opt/mellanox/doca` on the host vs on the BF3 Arm). Do NOT
   guess.
2. **Confirm the BF3 and host prerequisites are present.** Confirm
   `lspci -d 15b3:` identifies the intended physical BF3 and
   `pkg-config --modversion doca-common` identifies the host-side
   DOCA-Host install, then run all of:
   `dpkg -s rshim` / `rpm -q rshim` (userspace package installed),
   `systemctl status rshim` (daemon `active (running)`), and
   `ls /dev/rshim*` (character-device tree present), per the BSP
   manual. On DOCA 3.3+ `lsmod | grep rshim` is EXPECTED empty (the
   in-tree module is gone) and is NOT failure evidence. If the
   daemon or `/dev/rshim*` tree is missing, the host has no path to
   push.
3. **Disambiguate which `/dev/rshim<N>` is which BF3.** On a
   multi-DPU host, read the `DEV_NAME` field of each
   `/dev/rshim*/misc` file and cross-match against
   `lspci -d 15b3: -nn` (the canonical one-liner is in
   [`doca-bare-metal-deployment CAPABILITIES.md`](../doca-bare-metal-deployment/CAPABILITIES.md#rshim-instance--bluefield-disambiguation-canonical-one-liner)).
   This is the precondition for every per-DPU `bfb-install`;
   skipping it is the #1 cause of *"I flashed the wrong DPU"*.
4. **Confirm the OOB path exists.** A BMC console-over-Redfish,
   BMC IPMI serial-over-LAN, or physical UART to reach the BF3 if
   the push breaks the Arm OS — per the safety precondition in
   [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy).
   Without one, the bar to proceed is "stop, escalate" per
   [`doca-hardware-safety`](../doca-hardware-safety/SKILL.md).
5. **Verify the BFB image.** Confirm the BFB image SHA matches the
   SHA the operator downloaded from the documented public DOCA
   Downloads page (route via
   [`doca-public-knowledge-map ## Public documentation entry points`](../doca-public-knowledge-map/SKILL.md#public-documentation-entry-points))
   — pushing a corrupted BFB is the load-bearing first-run failure.
   If the published SHA is unavailable or the values differ, STOP;
   do not push. Do NOT invent the BFB filename.
6. **Capture the BEFORE version anchors.** Per
   [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility),
   record (read-only): the host-side DOCA-Host version
   (`pkg-config --modversion doca-common`), the current Arm-side BFB
   (`cat /etc/mlnx-release` + `bfver`), and the per-device NIC
   firmware (`flint -d <bdf> q`). This capture is the rollback
   anchor — without a BEFORE state, "rollback" is a phrase, not a
   thing the operator can do. Close the four-way match per
   [`doca-version TASKS.md ## configure`](../doca-version/TASKS.md#configure).
7. **Decide the DPU mode BEFORE the push.** If the BF3 must boot in
   a specific mode (DPU / embedded-function vs separated-host / NIC
   mode), that decision belongs at BFB-install time — the
   `mlxconfig` set is applied from a `bfb_modify_os()` hook in
   `bf.cfg`, and reconfiguring after install typically needs another
   push. The mode-set burn itself routes to
   [`doca-hardware-safety`](../doca-hardware-safety/SKILL.md); this
   step only records the decision so the `bf.cfg` authored in
   [`## run`](#run) carries it.

## build

BF3 platform bring-up is the *deploy-the-platform* path; there is no
application or BFB artifact for the operator to build inside this
skill.

- If the user is asking how to build a DOCA-linked binary they want
  to run on the healthy BF3, hand off to
  [`doca-programming-guide ## build`](../doca-programming-guide/TASKS.md#build)
  (the canonical `pkg-config doca-<library>` + meson pattern). Once
  the BF3 is healthy, control routes onward to
  [`doca-bare-metal-deployment`](../doca-bare-metal-deployment/SKILL.md).
- If the user is asking how to build the **BFB image** itself, that
  is internal BlueField-OS tree work — out of scope for this bundle;
  route to the public BlueField Platform Software documentation via
  [`doca-public-knowledge-map`](../doca-public-knowledge-map/SKILL.md).
- If the user is asking how to author `bf.cfg`, that is composed
  against the live BSP-manual schema at push time, not built ahead;
  see [`## run`](#run) step 1.
- The `bf.cfg` `bfb_modify_os()` hook is the documented mechanism
  for seeding post-install state; the agent quotes its parameter
  keys from the public schema and does NOT invent key names.

## modify

BF3 bring-up does not have a *modify a sample program* workflow; the
platform-side analog of "modify" is **re-walk the bring-up after the
BFB, the `bf.cfg`, or the underlying mode/version state changes**.

1. **A BFB change is a bring-up event.** Pushing a different BFB
   re-opens the readiness smoke in [`## test`](#test) — the new BFB
   may land a different Arm-side DOCA version, a different host PF
   layout, or a different mode. Re-walk [`## configure`](#configure)
   step 6 (version anchors), then [`## run`](#run), then
   [`## test`](#test).
2. **A `bf.cfg` change is a bring-up event.** Editing the password,
   the `authorized_keys` hook, or the mode-set hook changes the
   post-install state; treat each edit as a fresh push and re-walk
   [`## run`](#run) step 1 (author `bf.cfg`) and [`## test`](#test).
3. **A host-side change is a bring-up event.** A host-side DOCA-Host
   reinstall, an apt-source repo-pin change, or an `LD_LIBRARY_PATH`
   change re-opens the four-way match; re-walk
   [`## configure`](#configure) step 6 and route the host reinstall
   through [`doca-setup`](../doca-setup/SKILL.md).
4. **A mode flip or firmware burn leaves this verb entirely.** Any
   `mlxconfig set` (DPU/separated-host mode flip), firmware burn, or
   BFB reflash is owned by
   [`doca-hardware-safety ## modify`](../doca-hardware-safety/TASKS.md#modify);
   this skill does NOT walk that burn. Control returns here at
   [`## configure`](#configure) step 6 once the change is complete
   and verified per the meta-policy.

The anti-pattern alert: re-pushing a BFB or editing a `bf.cfg`
without re-running the readiness smoke is the canonical *"the DPU
came back wrong and I did not notice"* failure. Treat every
platform-side change as a fresh bring-up.

## run

The BFB-install + RShim/TMFIFO bring-up sequence — pushing the BFB
and getting the host-to-DPU channel healthy. Every step assumes the
preconditions in [`## configure`](#configure) are done.

1. **Author `bf.cfg` from the documented schema.** The BFB-install
   path takes an installer configuration file (`bf.cfg`) controlling
   post-install Arm-side state. Two operator-relevant rules: (a) for
   passwordless SSH to survive the install, set the documented
   password parameter AND seed the SSH public key via a
   `bfb_modify_os()` hook that writes the to-be-installed rootfs
   (mounted under `/mnt` during install per the BSP manual) — the
   default BFB install rewrites the home `.ssh/`, so a pre-existing
   key is GONE unless reseeded; there is NO top-level
   `authorized_keys` `bf.cfg` parameter, the mechanism is the hook.
   (b) for a specific DPU mode, the required `mlxconfig set`
   invocations run from a `bfb_modify_os()` hook (decision recorded
   in [`## configure`](#configure) step 7; the burn routes to
   [`doca-hardware-safety`](../doca-hardware-safety/SKILL.md)). Quote
   the `bf.cfg` keys from the public schema; do NOT invent them.
2. **Push the BFB over RShim.** Run the host-side `bfb-install`
   invocation per its `--help` and the BSP manual, targeting the
   `/dev/rshim<N>` disambiguated in [`## configure`](#configure)
   step 3. The push streams the BFB to the BF3 over RShim/PCIe; the
   Arm side reboots through UEFI to Linux up to first-boot init. The
   BFB reflash is a mutating change — load
   [`doca-hardware-safety`](../doca-hardware-safety/SKILL.md)
   ALONGSIDE for the preflight / OOB / rollback discipline.
3. **Do NOT trust `bfb-install` exit code 0 alone.** This is the
   single most expensive failure mode. `bfb-install` has been
   observed to exit 0 while the Arm-side flow only partially
   completed — the canonical field signature is *"Ubuntu
   installation completed"* followed by an `INFO[MISC]: NIC firmware
   update failed` line. Parse the actual console / log output for:
   (a) any `[MISC]` / `[ERR]` line with a failure verb, (b) the
   documented `Linux up` marker, (c) the documented `DPU is ready`
   marker. If (a) is present or (b)/(c) are absent, the install is
   **partial** — advance to [`## debug`](#debug) instead of
   declaring success.
4. **Verify the RShim console and TMFIFO channel.** Watch
   `/dev/rshim<N>/console` for the documented boot markers, then
   bring up TMFIFO: `ip addr show tmfifo_net0` (or the `tm-br`
   bridge) on the host, and — CRITICALLY — `ip route get
   <bf-tmfifo-address>` BEFORE any `ping`. Accept `dev tmfifo_net0`
   OR `dev tm-br` as healthy egress; `dev lo` / `local <bf-addr>
   dev lo` is the local-loopback failure that makes `ping` lie. The
   factory subnet (`192.168.100.1/30` host, `192.168.100.2/30` BF)
   comes from the BSP manual; do NOT fabricate it.
5. **Hand off to the readiness smoke.** "BFB install completed"
   means the installer's I/O is done; it does NOT mean the Arm OS
   is up, TMFIFO is reachable, SSH is live, or host PFs are bound.
   Always run [`## test`](#test) before re-declaring the BF3
   healthy.

## test

BF3 bring-up has no *compile-and-unit-test* workflow — testing is
the operational post-BFB readiness smoke against real hardware.

**`## test` is an iterative loop, not a one-shot pass.** Every push,
every `bf.cfg` edit, every mode/version change re-opens the smoke.
Skipping the re-run after a mutation is the failure mode this loop
replaces.

1. **Wait for documented readiness markers, not a timer.** Poll the
   RShim console buffer for `Linux up` / `DPU is ready` (per the BSP
   manual), AND the Arm-side SSH endpoint responding, AND (where
   present) the BMC health endpoint reporting `OK`. If any never
   reports ready within the manual's documented bound, the BF3 is
   partial — advance to [`## debug`](#debug). If the release-matched
   manual provides no bound, do not wait indefinitely or invent one:
   stop the poll, preserve the console evidence, and escalate for a
   release-specific bound before classifying readiness.
2. **Route the host PF rebind if netdevs are missing.** A
   push can leave the host `mlx5` driver stale: PFs present in
   `lspci -d 15b3:` but `ip link show` shows no netdevs and
   `ibv_devinfo` is empty. A sysfs PF bind/unbind is a disruptive
   PCIe mutation: capture the current BF3 BDF-to-driver mapping and
   rollback path, then hand that evidence and the documented rebind
   procedure to
   [`doca-hardware-safety ## modify`](../doca-hardware-safety/TASKS.md#modify)
   for quiescing, OOB/maintenance applicability, apply/rollback, and
   post-change inventory. Return here only to re-verify with
   `ip link show` / `ibv_devinfo` / `devlink dev show`. The BDF
   strings come from the pre-flight `lspci -d 15b3:` capture, NOT
   from memory; never emit an `echo .../bind` directly from this
   skill.
3. **Verify the install landed.** `cat /etc/mlnx-release` + `bfver`
   on the Arm side confirm which BFB landed; `flint -d <bdf> q`
   reads the per-device FW version. These are the Arm-side and NIC
   legs of the four-way match.
4. **Check the `/home/ubuntu` ownership gotcha.** On certain BFB
   images `/home/ubuntu` ships owned by `root`, breaking the normal
   pattern of the `ubuntu` user writing under their own home. Check
   `stat -c '%U:%G' /home/ubuntu` after first SSH. Before proposing
   a recursive ownership change, verify the shell is on the BF3 Arm
   side (not the host), resolve the target with `readlink -f`, require
   it to be exactly `/home/ubuntu`, and record the current owner. If
   it is `root:root`, propose the documented `chown -R
   ubuntu:ubuntu /home/ubuntu` fix (per the BSP manual) BEFORE
   pasting any script that writes there.
5. **Re-close the four-way version match.** Once Arm OS is healthy
   and host PFs are bound, walk the four-way match owned by
   [`doca-version TASKS.md`](../doca-version/TASKS.md) against the
   new BF3 state BEFORE handing onward to a deployment skill. A
   skipped re-close after a push is the most common cause of "ran
   fine yesterday, breaks today".

**Identical smoke and evidence rule.** Before and after each
recovery, run the same readiness smoke and preserve the same tuple:
RShim markers and failure lines; TMFIFO address plus `ip route get`;
Arm SSH plus `uptime`/relevant `dmesg`; host PF outputs from `lspci`,
`ip link`, `ibv_devinfo`, and `devlink`; Arm BFB/FW anchors; and the
four-way match. A changed command set is not comparable evidence.

Loop termination: "same kind" means the same failing check category
(readiness markers, PF binding, install verification, ownership, or
version match); "change nothing" means the identical smoke fails
with a materially identical captured evidence tuple. Stop after two
consecutive smokes meet both conditions — that means the cause is
below the platform layer (BFB image, host OS, silicon). Escalate to
[`doca-debug TASKS.md ## debug`](../doca-debug/TASKS.md#debug) with
the captured evidence. Once the smoke is green, hand off — running a
binary to
[`doca-bare-metal-deployment ## run`](../doca-bare-metal-deployment/TASKS.md#run),
a service container to
[`doca-container-deployment ## run`](../doca-container-deployment/TASKS.md#run).

## debug

The six-state `bluefield-state-classifier`. When a BFB push, a
soft-reset, or a host PF rebind has been done and the BF3 is *not
yet* confirmed healthy, evaluate all six states against one captured
evidence tuple, IN ORDER, before choosing a recovery. Report every
match (an Arm OS can be "Linux up" AND "host PFs unbound"
simultaneously); never stop classification at the first match. Apply
recoveries in this priority order: `installer-still-running` →
`uefi-only` → `linux-up-tmfifo-down` → `tmfifo-up-ssh-down` →
`arm-ok-host-pfs-unbound` → `host-bf-version-mismatch`. The full state
evidence/recovery detail is in
[`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy);
this is the evaluation order. Mutating recovery steps leave this
skill for [`doca-hardware-safety ## modify`](../doca-hardware-safety/TASKS.md#modify);
this skill owns only BF3-specific ordering and the identical
post-recovery smoke.

1. **`installer-still-running`.** `bfb-install` resident + console
   still emitting progress lines → WAIT, do not abort. Aborting a
   first-flash push mid-write creates the next state down.
2. **`uefi-only`.** UEFI-exit marker present but no `Linux up` →
   capture console + host `dmesg`, do a documented cold power cycle
   (via BMC, not `reboot` from the dead Arm side) BEFORE re-pushing.
3. **`linux-up-tmfifo-down`.** `Linux up` present but the TMFIFO
   probe returns no host-side address → re-check the host RShim
   daemon, run the documented TMFIFO bring-up, THEN re-run the
   `ip route get` loopback check (a freshly-bound TMFIFO can land in
   the loopback failure mode and look like it works).
4. **`tmfifo-up-ssh-down`.** TMFIFO route confirmed to the BF3 (not
   loopback) but SSH refuses/hangs → wait the documented
   `sshd`-ready bound; else fall through to the RShim console for a
   userspace prompt and re-seed credentials; put `authorized_keys`
   in the `bf.cfg` on the next push. If the release-matched manual
   gives no bound, do not invent one or wait indefinitely: preserve
   the console and route evidence and escalate for the
   release-specific bound.
5. **`arm-ok-host-pfs-unbound`.** Arm SSH alive + OS healthy but
   host enumeration broken (`lspci` shows PFs, `ip link` does not
   show netdevs, `ibv_devinfo` empty) → route the documented PF
   rebind through [`doca-hardware-safety ## modify`](../doca-hardware-safety/TASKS.md#modify),
   then return to the identical smoke in [`## test`](#test). Do NOT
   launch any DOCA binary in this state — every device-open fails
   with a misleading error.
6. **`host-bf-version-mismatch`.** Everything above healthy but the
   four-way match does not close → walk
   [`doca-version TASKS.md`](../doca-version/TASKS.md) in full,
   resolve apt-source / repo-pin drift per
   [`doca-version TASKS.md ## apt-source consistency`](../doca-version/TASKS.md#apt-source-consistency)
   BEFORE installing anything, and route any host reinstall through
   [`doca-setup`](../doca-setup/SKILL.md).

After all six are evaluated, recover in dependency order: first
protect an in-flight installer; then restore boot/Arm reachability
(`uefi-only`); then TMFIFO; then SSH; then host PF binding; finally
host/BFB version alignment. Apply one recovery at a time and re-run
the identical smoke/evidence tuple after each. If two consecutive
post-recovery tuples are identical, stop and escalate rather than
repeating the same recovery.

Cross-cutting host-layer issues (kernel version, driver state, PCIe
link state, hugepage health) that survive a healthy classifier walk
drop to
[`doca-debug TASKS.md ## debug`](../doca-debug/TASKS.md#debug). Never
declare the BF3 healthy from absence of evidence — a TMFIFO `ping`
without `ip route get`, an SSH connect without `uptime`/`dmesg`, an
`lspci` listing without a usable netdev are each NOT proof.

## Deferred task verbs

- **BlueField-4 bring-up** (the BMC-Redfish provisioning path) — out
  of scope here. Route to
  [`doca-bf4-deployment`](../doca-bf4-deployment/SKILL.md), the BF4
  equivalent of this skill.
- **Running a DOCA-linked binary on a healthy BF3** (launch mode,
  PCI/NUMA/CPU binding, per-tenant isolation, the binary error
  taxonomy) — out of scope here. Route to
  [`doca-bare-metal-deployment`](../doca-bare-metal-deployment/SKILL.md)
  once the BF3 is healthy.
- **Deploying a DOCA service container on the BF3** (kubelet
  standalone, static-pod manifests directory, pod-spec YAML,
  image-pull from NGC) — out of scope here. Route to
  [`doca-container-deployment`](../doca-container-deployment/SKILL.md).
- **Env-preparation / host install** (installing DOCA-Host on a
  fresh host, hugepages, IOMMU, `PKG_CONFIG_PATH` /
  `LD_LIBRARY_PATH`, devlink mode flips) — out of scope here. Route
  to [`doca-setup`](../doca-setup/SKILL.md); BF3 bring-up assumes
  the host RShim surface is already in place.
- **Hardware-state changes** (`mlxconfig set` including DPU/
  separated-host mode flips, firmware burn, BFB reflash,
  kernel-boot-parameter changes) — the *change-application
  discipline* (preflight, OOB console, maintenance window, rollback)
  is meta-policy owned by
  [`doca-hardware-safety ## modify`](../doca-hardware-safety/TASKS.md#modify);
  this skill loads it ALONGSIDE whenever a mutating burn is on the
  table and adds only the BF3-specific sequencing.
- **Library-API and cross-library programming questions** (building
  a DOCA-Flow pipe, an RDMA queue pair, the cross-library
  `DOCA_ERROR_*` taxonomy) — out of scope here. Route to
  [`doca-programming-guide`](../doca-programming-guide/SKILL.md) and
  the matching `libs/<library>` skill via
  [`doca-public-knowledge-map ## Library- and module-specific guides`](../doca-public-knowledge-map/SKILL.md#library--and-module-specific-guides).
- **The version-match body** (four-way match rule, NGC semantics,
  headers-win) — out of scope here. Route to
  [`doca-version`](../doca-version/SKILL.md); this skill carries
  only the BF3 three-leg overlay.