--- license: Apache-2.0 name: doca-sta description: > Use this skill when the user builds an NVMe-over-Fabrics storage target on BlueField with DOCA STA — instantiating doca_sta, declaring doca_sta_subsystem NQNs and namespaces over local NVMe disks via doca_sta_be, validating platform support with doca_sta_cap_is_supported, sizing I/O queue depth, or decoding DOCA_ERROR_* statuses such as IO_FAILED on NVMe reads. Also load it for implied asks like "Identify Controller times out over RoCE", "offload the nvmf target", "NVMe-oF Connect never completes", or "16 I/O queues at depth 1024 — supported?". Refuse and route to the proper owner for raw RDMA movement, packet I/O, steering rules, initiator-side NVMe, or SDK install. metadata: author: NVIDIA kind: library doca_version: "3.5" tags: - doca - sta - nvme compatibility: > Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu 22.04/24.04 or RHEL/SLES) with a BlueField DPU or ConnectX NIC attached. Reads the user's local install via `pkg-config doca-sta` (and `pkg-config doca-rdma` for the NVMe-over-RDMA transport) and inspects /opt/mellanox/doca/{lib,include,samples,applications}. The validation steps require a live DOCA install. --- # DOCA STA (Storage Target Acceleration) ## Examples - **"Offload the nvmf target onto the DPU."** — this is in scope. Stand up `doca_sta` + subsystem/namespaces; do not rewrite the initiator stack here. - **"Identify Controller times out over RoCE."** — check `doca_sta_cap_is_supported` and queue sizing before changing backend disks. ## Instructions Follow Loading order below. Open the tasks companion for configure / target / debug. Open the capabilities companion for queue limits and NVMe-oF caps. Do not open every companion file. **Where to start:** This skill assumes DOCA is already installed and the user is doing **hands-on NVMe-over-Fabrics storage-target work** on a BlueField-class device with DOCA. Open the tasks companion if the user wants to *do* something (configure / modify / build / run / test / debug); open the capabilities companion when the question is *what can DOCA STA express* on this version. If the user has not installed DOCA yet, route to `doca-setup/SKILL.md` first. If the user is asking *"is this an NVMe-oF initiator/host transport?"*, the answer is no — doca-sta accelerates the **target** side: it presents NVMe-oF `doca_sta_subsystem` targets backed by local NVMe-PCI disks; the model lives in the capabilities companion. ## Example questions this skill answers well The CLASSES of DOCA STA questions this skill is built to answer, each with one worked example. The agent should treat the *class* as the load-bearing piece — the worked example is a single instance. - **"How do I bring up an NVMe-oF target that uses the BlueField to accelerate the storage data path?"** — worked example: *"define a `doca_sta_subsystem` (NQN) with one namespace backed by a local NVMe-PCI disk (`doca_sta_be`) and accept NVMe-over-RDMA connections from a remote initiator"*. Answered by the target-model-and-lifecycle workflow in the tasks companion + the capabilities companion target-object table. - **"Can this BlueField accelerate an NVMe-oF target at all?"** — worked example: *"my data center is RoCE end-to-end; does this device support DOCA STA target acceleration?"*. STA transport is RDMA-only (there is no NVMe-over-TCP path). Answered by the capability-query rule (`doca_sta_cap_is_supported` against a `doca_devinfo`) in the capabilities companion + the discovery step in the tasks companion. - **"How deep can I size my I/O queues, and how many I/O queues per connection?"** — worked example: *"I want 16 I/O queues at depth 1024 each — does this device support that?"*. Answered by the queue-sizing capability surface in the capabilities companion + the queue-sizing step in the tasks companion which gates on the matching `doca_sta_get_max_*` query (e.g. `doca_sta_get_max_qps`, `doca_sta_get_max_io_queue_size`). - **"Which other DOCA libraries do I need alongside doca-sta?"** — worked example: *"do I need doca-rdma directly, or does doca-sta hide it from me?"*. Answered by the substrate-library rule in the capabilities companion + the env-prep checklist in the tasks companion step 1, which routes the steering side to `doca-flow/SKILL.md` and the RDMA substrate to `doca-rdma/SKILL.md`. - **"Is this STA capability available on my installed DOCA?"** — worked example: *"is STA target acceleration supported on this BlueField + DOCA version?"*. Answered by the version-and-device overlay in the capabilities companion, which cross-links the canonical detection chain in `doca-version/SKILL.md` and adds the STA-specific cap-query rule (`pkg-config --modversion doca-sta` is the build-time anchor; the runtime `doca_sta_cap_is_supported` query is the truth). - **"What does this `DOCA_ERROR_*` from a STA call mean and which layer caused it?"** — worked example: *"`DOCA_ERROR_NOT_PERMITTED` when opening the `doca_dev`"*. Answered by the STA overlay on the cross-library taxonomy in the capabilities companion + the layered ladder in the tasks companion that escalates to `doca-debug/SKILL.md`. > **A Connect handshake that never completes is usually not an STA > bug.** It is the single most common first-app failure, and the > answer is to walk the three preconditions in > the capabilities companion > *before* any code change: the RDMA substrate resolves on the chosen > device, the `doca_dev` was opened with sufficient permission, and — > most often the culprit — a DOCA Flow rule actually steers the > matching NVMe-oF 5-tuples to this instance's queues. The steering > side belongs to `doca-flow/SKILL.md`; route it > rather than inventing a `doca_sta_*` steering call, and do not > start by auditing STA lifecycle or target-side code. The same > applies to an Identify Controller that times out over RoCE. > **`DOCA_ERROR_IO_FAILED` on a per-I/O completion is a transport > error, not a target-side STA bug** — a link drop, RDMA peer > disconnect, firmware fault, or peer controller reset. Being able to > ping the target does not exclude any of these. Do not retry blindly > and do not change STA code first: capture `dmesg` and route to > `doca-rdma/SKILL.md`, per > the tasks companion. ## Audience This skill serves **external developers building NVMe-over-Fabrics storage targets that consume DOCA STA on BlueField** — i.e., users whose code calls `doca_sta_*` (directly in C/C++, or through FFI/bindings from another language) to accelerate the target-side data path of an NVMe-oF target on the BlueField hardware: presenting `doca_sta_subsystem` targets (NQN + namespaces) backed by local NVMe-PCI disks (`doca_sta_be`) to remote initiators over RDMA. The skill is *not* for NVIDIA developers contributing to DOCA STA itself, and it is *not* for initiator/host-side NVMe stacks. **Language scope.** DOCA STA ships as a C library with `pkg-config` module name `doca-sta`. DOCA STA ships **no public samples** — the public packages install no `samples/doca_sta/` directory — so the worked examples in the tasks companion build against the public headers directly rather than modify a shipped sample. C and C++ consumers are the canonical case. Other-language consumers (Rust, Go, Python, …) consume the same `*.so` through FFI or language-specific bindings; the skill's contribution in that case is to keep the target-model, lifecycle, capability-discovery, queue-pair shape, substrate-dependency, and error-taxonomy guidance language-neutral, and to route the agent to the public C ABI as the authoritative surface that any wrapper will eventually call. ## When to load this skill Load this skill when the user is doing hands-on DOCA STA work, in any language. Concretely: - Initializing a `doca_sta` instance on a `doca_dev` opened against a BlueField PF / SF and configuring the NVMe-oF target subsystems before `doca_ctx_start()`. - Defining target resources — `doca_sta_subsystem` (NQN + namespaces) and `doca_sta_be` backend controllers (local NVMe-PCI disks) — and accepting NVMe-oF connections (admin queue plus N I/O queues per connection) on the target side as remote initiators connect over RDMA CM. - Reading or setting STA properties via the `doca_sta_set_*` family, checking device support via `doca_sta_cap_is_supported`, and querying sizing limits via the `doca_sta_get_max_*` family (max I/O queue depth, max number of queue pairs, max I/O size, max subsystems, max namespaces per subsystem, max backends). - Wiring the **NVMe-over-RDMA** transport — STA's only transport; it lands on the `doca-rdma` substrate and uses RDMA CM for connection establishment — for the target's I/O queues. - Wiring DOCA Flow rules so that NVMe-oF traffic actually reaches the STA-managed queues — the steering boundary is `doca-flow`, not `doca-sta`. - Debugging a `DOCA_ERROR_*` returned from a STA call (lifecycle vs. capability vs. transport-layer I/O failure vs. driver-below) and the per-queue events on the DOCA Core progress engine. - Designing or extending non-C bindings (Rust, Go, Python, …) that wrap the DOCA STA C ABI — for the lifecycle, queue-pair, cap-query, and substrate-dependency rules the wrapper must honor. Do **not** load this skill for general DOCA orientation, install of DOCA itself, raw RDMA data movement (use `doca-rdma/SKILL.md`), raw packet I/O on Ethernet queues (use `doca-eth/SKILL.md`), flow-rule programming (use `doca-flow/SKILL.md`), or initiator/host-side NVMe stack development (SPDK or kernel-nvme own that, not this skill). For DOCA documentation orientation, use `doca-public-knowledge-map/SKILL.md`. ## What this skill provides This is a **thin loader**. The body keeps only the orientation needed to pick the right next file. The substantive STA-specific material lives in two companion files: - the capabilities companion — what DOCA STA can express on this version: the target object model (`doca_sta_subsystem` / namespaces / `doca_sta_be` backend NVMe-PCI disks), the NVMe queue-pair shape (admin queue + I/O queues over RDMA), the RDMA-only transport, the capability-query surface (`doca_sta_cap_is_supported` plus the `doca_sta_get_max_*` sizing queries), the STA error taxonomy (mapped onto the cross-library `DOCA_ERROR_*` set), the observability surface (per-queue progress engine events, capability snapshots), and the safety policy that gates substrate-library, permission, and steering preconditions. - the tasks companion — step-by-step workflows for the six in-scope STA verbs: `configure`, `modify`, `build`, `run`, `test`, `debug`. Plus a `Deferred task verbs` block that points out-of-scope questions at the right next skill, and a `Command appendix` of the recurring commands the agent reaches for. The skill assumes a BlueField (with DOCA installed at the standard location) plus a remote NVMe-oF initiator reachable on the fabric to connect into the accelerated target, and one or more local NVMe-PCI disks to back the target's namespaces. It does not cover installing DOCA — that path goes through `doca-setup/SKILL.md`. It does not cover initiator/host-side NVMe stacks (SPDK `bdev_nvme`, kernel `nvme` host) or NVMe protocol semantics above the accelerated target data path — those are out of scope. ## What this skill deliberately does not ship This skill is **agent guidance**, not a samples or templates bundle. To keep the boundary clean, it deliberately does not contain — and pull requests should not add: - **Pre-written DOCA STA application source code, in any language.** DOCA STA ships **no public samples** — there is no `/opt/mellanox/doca/samples/doca_sta/` directory. The authoritative surface is the public headers under $(pkg-config --variable=includedir doca-common) plus the public DOCA STA guide; the agent builds against those directly rather than modifying a shipped sample, per the the tasks companion workflow. - **Initiator/host-side NVMe stack glue.** SPDK `bdev_nvme`, the kernel `nvme` host, and any initiator-side NVMe stack are upstream projects out of scope for this skill — DOCA STA is target-side acceleration, not an initiator transport provider. - **Standalone build manifests** (`meson.build`, `CMakeLists.txt`, `Cargo.toml`, …) parked inside the skill. The agent constructs the build manifest *in the user's project directory* against the user's installed DOCA, where `pkg-config --modversion doca-sta` is the source of truth. - **A `samples/`, `bindings/`, or `reference/` subtree** of any kind. A mock or incomplete artifact in this skill's tree, even one labeled "reference", is misleading: users will read it as buildable. ## Loading order 1. Read this skill first to confirm the user's question is in scope. 2. **For the STA capability matrix, the target object model, queue-pair shape, RDMA-only transport, capability-query rules, error taxonomy, observability, and safety policy, see the capabilities companion.** 3. **For step-by-step workflows — configure, modify, build, run, test, debug — see the tasks companion.** Both companion files cross-link to each other, `doca-version/SKILL.md` for the canonical version-handling rules, `doca-rdma/SKILL.md` for the RDMA substrate that NVMe-over-RDMA transport lands on, `doca-flow/SKILL.md` for the steering rules that direct NVMe traffic to STA-managed queues, and `doca-public-knowledge-map/SKILL.md` whenever the right answer is "look it up in the public docs or the installed package layout" rather than "STA-specific guidance". ## Related skills - `doca-public-knowledge-map/SKILL.md` — the routing table for every public DOCA documentation source and the on-disk layout of an installed DOCA package. The STA URL slug is `DOCA-STA`. - `doca-setup/SKILL.md` — env preparation, install verification, BlueField mode checks, and the permission / group-membership requirements for opening a `doca_dev`. This skill assumes its preconditions are satisfied. - `doca-version/SKILL.md` — canonical DOCA version-handling rules. This skill's `## Version compatibility` cross-links the four-way match rule and adds only the STA-specific overlay (STA target-acceleration availability windows, NVMe-oF feature-set device-conditional support). - `doca-structured-tools-contract/SKILL.md` — the bundle's structured-tools precedence rule (detect / prefer / fall back / report). The Command appendix in the tasks companion honors this contract. - `doca-programming-guide/SKILL.md` — general DOCA programming patterns shared by every library: the canonical `pkg-config` + meson build pattern, the universal modify-a-shipped-sample first-app workflow, the universal lifecycle, the cross-library `DOCA_ERROR_*` taxonomy, and the program-side debug order. This skill layers STA specifics on top. - `doca-rdma/SKILL.md` — the RDMA substrate that NVMe-over-RDMA transport lands on. STA hides most of the RDMA queue-pair details from the consumer, but the user still needs `doca-rdma` linked in and the device's RDMA capabilities discoverable for the NVMe-over-RDMA path to work. - `doca-eth/SKILL.md` — the queue-pair shape that STA's per-connection queue model echoes. Reach here if the user is asking general questions about how DOCA exposes queue-pairs that don't have an STA-specific answer. - `doca-flow/SKILL.md` — the steering surface that decides which NVMe-oF packets land on which STA-managed queue. DOCA STA does *not* program steering itself; an NVMe-oF target whose connections never come up is often a missing or wrong Flow rule, not a STA bug. - `doca-debug/SKILL.md` — the cross-cutting debug ladder (install / version / build / link / runtime / program / driver). STA-specific debug (transport-type mismatches, queue-depth oversize, IO-failed transport errors) overlays on top of that ladder.