Skills DirectorySearch all skills ↗AI agent skill · by @NVIDIA
Doca Sta
Use this skill when the user is doing hands-on NVMe-over-Fabrics storage-target work on a BlueField DPU or ConnectX NIC with DOCA STA — standing up a doca_sta DOCA Core context that accelerates the target-side NVMe-oF data path over RDMA, defining doca_sta_subsystem targets (NQN + namespaces) backed by local NVMe-PCI backend disks (doca_sta_be), checking device support via doca_sta_cap_is_supported, sizing the per-connection I/O queues, or debugging DOCA_ERROR_* from a STA call. Trigger even when the user does not say "DOCA STA" — typical implicit phrasings include "my NVMe-oF Connect never completes", "Identify Controller times out over RoCE", "16 I/O queues at depth 1024 — does this BlueField support that", "offload the nvmf target onto the DPU", or "DOCA_ERROR_IO_FAILED on an NVMe read". Refuse and route elsewhere for DOCA install, raw RDMA data movement, raw packet I/O, flow-rule programming, or initiator-side / host NVMe stack work — those belong to other skills.
Archived 2026-10-23 · Source updated 2026-09-30 · License: Apache-2.0. Check the original repository for the latest version.
SKILL.md instructions
# DOCA STA (Storage Target Acceleration) **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 [`TASKS.md`](TASKS.md) if the user wants to *do* something (configure / modify / build / run / test / debug); open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what can DOCA STA express* on this version. If the user has not installed DOCA yet, route to [`doca-setup`](../../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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes). ## 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 [`TASKS.md ## configure`](TASKS.md#configure) + [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) 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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) + the discovery step in [`TASKS.md ## configure`](TASKS.md#configure). - **"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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) + the queue-sizing step in [`TASKS.md ## configure`](TASKS.md#configure) 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 [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy) + the env-prep checklist in [`TASKS.md ## configure`](TASKS.md#configure) step 1, which routes the steering side to [`doca-flow`](../doca-flow/SKILL.md) and the RDMA substrate to [`doca-rdma`](../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 [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility), which cross-links the canonical detection chain in [`doca-version`](../../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_IO_FAILED` on a submitted NVMe read I/O against a target I can ping"*. Answered by the STA overlay on the cross-library taxonomy in [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy) + the layered ladder in [`TASKS.md ## debug`](TASKS.md#debug) that escalates to [`doca-debug`](../../doca-debug/SKILL.md). ## 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** — it is absent from the DOCA libraries / extension_libraries sample profiles — so the worked examples in `TASKS.md` 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`](../doca-rdma/SKILL.md)), raw packet I/O on Ethernet queues (use [`doca-eth`](../doca-eth/SKILL.md)), flow-rule programming (use [`doca-flow`](../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`](../../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: - `CAPABILITIES.md` — 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. - `TASKS.md` — 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`](../../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, and STA is absent from the libraries / extension_libraries sample profiles. 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 [`TASKS.md ## modify`](TASKS.md#modify) 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.md` 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 [CAPABILITIES.md](CAPABILITIES.md).** 3. **For step-by-step workflows — configure, modify, build, run, test, debug — see [TASKS.md](TASKS.md).** Both companion files cross-link to each other, [`doca-version`](../../doca-version/SKILL.md) for the canonical version-handling rules, [`doca-rdma`](../doca-rdma/SKILL.md) for the RDMA substrate that NVMe-over-RDMA transport lands on, [`doca-flow`](../doca-flow/SKILL.md) for the steering rules that direct NVMe traffic to STA-managed queues, and [`doca-public-knowledge-map`](../../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`](../../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`](../../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`](../../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`](../../doca-structured-tools-contract/SKILL.md) — the bundle's structured-tools precedence rule (detect / prefer / fall back / report). The Command appendix in [TASKS.md](TASKS.md) honors this contract. - [`doca-programming-guide`](../../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`](../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`](../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`](../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`](../../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.