Doca Sta

NVIDIAOfficialCreated by NVIDIA

Skill
Tool integration
Software development
Apache-2.0
Medium risk

From the author

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.

— the description by NVIDIA

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

DOCA STA (Storage Target Acceleration) is a library for offloading NVMe-over-Fabrics (NVMe-oF) target-side data paths to NVIDIA BlueField DPUs. This skill provides the necessary context for developers to configure, manage, and debug NVMe-oF targets using the DOCA STA C ABI. It covers the lifecycle of target subsystems, namespace management, backend NVMe-PCI disk integration, and queue-sizing capabilities. The skill is designed to work alongside other DOCA libraries like DOCA Flow and DOCA RDMA, ensuring developers can correctly steer traffic and manage the underlying transport layers.

What it does

Instantiates and configures doca_sta subsystems and namespaces.
Maps local NVMe-PCI disks to target backends via doca_sta_be.
Validates platform support and hardware capabilities for STA.
Provides guidance on sizing I/O queues and managing queue depth.
Decodes DOCA_ERROR_* status codes related to STA operations.
Integrates with DOCA Flow for steering NVMe-oF traffic.

When to use it

When building an NVMe-oF storage target on BlueField hardware.
When configuring target-side subsystems and namespaces.
When troubleshooting connection timeouts or I/O failures in an NVMe-oF target.
When querying device capabilities for queue limits and supported features.
When integrating STA with RDMA transport and flow steering rules.

Advantages

Provides a clear boundary between STA target logic and initiator-side stacks.
Offers structured guidance on error taxonomy and debugging.
Ensures correct usage of DOCA capability-query functions.
Clarifies the relationship between STA and supporting libraries like DOCA Flow.
Focuses on the authoritative C ABI for cross-language binding development.

Usage examples

“How do I define a doca_sta_subsystem with a local NVMe disk?”: The agent will guide you through the target-model-and-lifecycle workflow, explaining how to instantiate the STA context, define the NQN, and attach a local NVMe-PCI disk backend.
“My NVMe-oF target connections are timing out over RoCE, what should I check?”: The agent will direct you to verify the RDMA substrate, check DOCA Flow steering rules, and validate that the device supports the requested queue configuration.
“Does my BlueField DPU support 16 I/O queues at depth 1024?”: The agent will instruct you to use doca_sta_get_max_io_queue_size and related queries to check the hardware limits against your specific DOCA version.
“What does DOCA_ERROR_IO_FAILED mean during an NVMe read?”: The agent will explain that this is typically a transport-level error and guide you to inspect the RDMA connection and link status rather than the STA application code.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/nvidia/doca-sta/download
Unzip it into the cross-client skills folder of your project:
```
mkdir -p .agents/skills && unzip doca-sta.zip -d .agents/skills
```

Documentation by NVIDIA

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

Read this skill first to confirm the user's question is in scope.
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.
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".

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.

Files

ATTRIBUTION.mdAdded by AutoGineer882 B
BENCHMARK.md10.1 KiB
CAPABILITIES.md20.3 KiB
LICENSELicence file added by AutoGineer11.2 KiB
SKILL.md15.8 KiB
SKILLCARD.yaml2.7 KiB
TASKS.md35.2 KiB
evals/evals.json3.2 KiB
skill-card.md5.1 KiB
skill.oms.sig5.1 KiB

CAPABILITIES.md

DOCA STA capabilities, version overlay, errors, observability, safety

Where to start: Pick the H2 anchor that matches your question (target object model / queue-pair shape / RDMA transport / capabilities / errors / safety) and read that section end-to-end. The tables in each section are the load-bearing content; the prose around them is interpretation.

Read this file when the loader sent you here from SKILL.md. For the how of executing each pattern (the verbs configure / modify / build / run / test / debug), jump to TASKS.md. For the canonical DOCA version-handling rules that this skill layers a STA overlay on top of, see doca-version/SKILL.md. For the RDMA substrate that NVMe-over-RDMA transport lands on, see doca-rdma/SKILL.md. For the steering side that decides which NVMe-oF packets land on which STA-managed queue, defer to doca-flow/SKILL.md.

Pattern overview

Every DOCA STA question this skill teaches resolves into one of SIX patterns. The patterns are CLASSES — they apply across every NVMe-over-Fabrics target deployment shape (single-subsystem smoke vs multi-subsystem fan-out, single namespace vs many, one backend disk vs several), not just the worked example shown.

Pattern	When it applies (class shape)	Where the substance lives
1. Define the target object model	Lay out the NVMe-oF target: one or more `doca_sta_subsystem` (NQN) resources, their namespaces, and the `doca_sta_be` backend controllers (local NVMe-PCI disks) that back them; doca-sta accelerates the target data path	`## Capabilities and modes` target-object table + TASKS.md ## configure step 1
2. Stand up the `doca_sta` context	DOCA Core lifecycle: create → configure (add devices, queue-pair sizing, subsystems/namespaces/backends) → start → use → stop → destroy, on the underlying `doca_dev`	TASKS.md ## configure + `doca-programming-guide CAPABILITIES.md ## Capabilities and modes` (`doca-programming-guide/CAPABILITIES.md#capabilities-and-modes`) for the universal lifecycle
3. Confirm device support (RDMA transport)	STA transport is RDMA-only (RDMA CM); the single capability gate is `doca_sta_cap_is_supported` against the active `doca_devinfo`, which is the only authority on whether this device can accelerate an STA target at all	`## Capabilities and modes` transport section + TASKS.md ## configure step 3
4. Shape the NVMe queue pair	One admin queue plus N I/O queues per NVMe-oF connection; size N (number of queue pairs), the depth per queue, and the I/O size against what the `doca_sta_get_max_*` queries report	`## Capabilities and modes` queue-pair table + TASKS.md ## configure step 4
5. Honor substrate and steering preconditions	The RDMA transport needs `doca-rdma` discoverable and the RDMA cap surface non-empty on the chosen device; NVMe-oF traffic only reaches the STA-managed queues when DOCA Flow rules (or the env-side equivalent) steer it there	`## Safety policy` precondition matrix + TASKS.md ## configure step 1
6. Diagnose a STA error	Map symptom (`DOCA_ERROR_BAD_STATE`, `_NOT_SUPPORTED`, `_INVALID_VALUE`, `_AGAIN`, `_IO_FAILED`, `_NOT_PERMITTED`) to root cause without leaving the STA layer prematurely	`## Error taxonomy` + TASKS.md ## debug

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

doca-sta is target-side acceleration, not an initiator stack. doca-sta presents NVMe-oF target subsystems (NQN + namespaces) backed by local NVMe-PCI disks and accelerates the target-side data path over RDMA; it does not implement an NVMe-oF initiator / host, and the remote initiator (SPDK bdev_nvme, kernel nvme host, …) is out of scope. An agent that recommends doca-sta as an initiator transport provider is misleading the user.
Discover the version-installed surface, do not assume. Every pattern above gates on pkg-config --modversion doca-sta, on the doca_sta_cap_is_supported device check, and on the doca_sta_get_max_* sizing queries against the active doca_devinfo. Quoting an I/O queue depth, a queue count, or an NVMe-oF sizing value without checking is the most common hallucination failure mode.

Capabilities and modes

DOCA STA is a DOCA Core context. Every STA instance follows the universal cfg-create → cfg-set-* → init → start → use → stop → destroy lifecycle (see doca-programming-guide CAPABILITIES.md ## Capabilities and modes (doca-programming-guide/CAPABILITIES.md#capabilities-and-modes)). On top of that lifecycle, STA layers a target object model, the RDMA transport, and a queue-pair shape.

Target object model — what doca-sta presents. doca-sta is target-side acceleration: the BlueField presents one or more NVMe-oF target subsystems, backed by local NVMe-PCI disks, to remote initiators over RDMA. The single most important framing the agent should surface before any code:

Object	Created by	What it is
`doca_sta` context	`doca_sta_create()` on a `doca_dev`	The STA engine instance; additional devices are added with `doca_sta_add_dev()`
`doca_sta_subsystem`	`doca_sta_subsystem_create()` (takes an NQN)	An NVMe subsystem — the target identity remote initiators connect to; holds namespaces and is bound to one or more network devices
Namespace	`doca_sta_subsystem_add_ns()`	A namespace exposed by a subsystem, with a logical block size validated by `doca_sta_is_logical_block_size_supported()`
`doca_sta_be` backend controller	`doca_sta_be_create()`	An abstraction of a backend device — a local NVMe-PCI disk that stores the namespace data
`doca_sta_io` + IO QP	the STA IO QP API (`doca_sta_io_qp.h`)	A per-EU IO context carrying the RDMA queue pairs that remote initiators connect into

The remote initiator (the NVMe-oF host) and its NVMe stack are out of scope: doca-sta does not implement initiator logic, and there is no NVMe-over-TCP path — the only transport is RDMA.

Transport — RDMA only. STA's transport is NVMe-over-RDMA on the doca-rdma substrate; connections are established through RDMA CM (the IO QP is moved to connected on the RDMA_CM_EVENT_ESTABLISHED event via doca_sta_io_qp_connect_established(), per doca_sta_io_qp.h). There is no NVMe-over-TCP transport in the public API. The single device gate is doca_sta_cap_is_supported.

The agent's rule: never promise STA acceleration without naming the cap check. Run doca_sta_cap_is_supported against the active doca_devinfo; quote the queried result. Do not assume from the docs page.

NVMe queue-pair shape. Each NVMe-oF connection (initiator ↔ target pair) carries:

Queue	Count per connection	What it carries
Admin queue	exactly 1	NVMe admin commands (Identify, Set/Get Features, Connect, Discovery, …) plus the NVMe-oF Connect handshake itself
I/O queue	configurable, up to the device cap	NVMe Read / Write / Flush / Dataset Management I/O commands

Sizing inputs (each gates on the matching doca_sta_get_max_* query — these are distinct from the single doca_sta_cap_is_supported device check):

Sizing input	Query	Why the agent must ask
Number of queue pairs (connections)	`doca_sta_get_max_qps`	Oversize fails at start; under-size limits fan-out
I/O queue depth (NVMeoF QP depth)	`doca_sta_get_max_io_queue_size`	Per-queue depth is device-bound; assuming 1024 works everywhere is wrong
Maximum NVMeoF I/O size	`doca_sta_get_max_io_size`	I/O larger than the reported max is rejected
Number of IO contexts (IO threads)	`doca_sta_set_max_sta_io` / `doca_sta_get_max_sta_io` / `doca_sta_get_max_io_threads`	The IO-thread count is bounded by the library maximum
Subsystems / namespaces / backends	`doca_sta_get_max_subsys` / `doca_sta_get_max_ns_per_subs` / `doca_sta_get_max_be`	The target topology is bounded; oversize fails at create

The agent SHOULD verify the exact spelling of these doca_sta_get_max_* queries and the single doca_sta_cap_is_supported device check against the headers shipped on the user's install ($(pkg-config --variable=includedir doca-common) doca_sta*.h) or in the public DOCA STA guide reachable via doca-public-knowledge-map/SKILL.md. Do not invent a multi-query doca_sta_cap_* family — only doca_sta_cap_is_supported exists; everything else is a doca_sta_get_max_* getter.

Configuration shape. Mandatory configurations before doca_ctx_start(): the underlying doca_dev opened against a device that passes doca_sta_cap_is_supported; the devices added via doca_sta_add_dev(); the IO-context count set with doca_sta_set_max_sta_io() at or below the library maximum; the target subsystems, namespaces, and backends defined within the reported doca_sta_get_max_* bounds. The queue-pair depth and count must stay at or below the doca_sta_get_max_* reported values.

Version compatibility

For the canonical DOCA version-detection chain, the four-way match rule, NGC container semantics, and the headers-win-over-docs rule, see doca-version/SKILL.md. The body lives there; this skill does not duplicate it.

The STA-specific overlay is:

doca_sta_cap_is_supported and the doca_sta_get_max_* queries are the runtime authority, not the public docs. Per the cross-cutting cap-query rule in doca-version CAPABILITIES.md ## Observability (doca-version/CAPABILITIES.md#observability), the agent must call doca_sta_cap_is_supported against the active doca_devinfo before promising the user that STA target acceleration is on this device + DOCA version, and must call the matching doca_sta_get_max_* query before promising any queue depth, queue count, or topology size. Quoting a sizing value from memory is the canonical hallucination failure mode for this library.
doca-sta.pc and doca-common.pc must both match doca_caps --version at the four-way-match check (per doca-version CAPABILITIES.md ## Version compatibility (doca-version/CAPABILITIES.md#version-compatibility)). Use pkg-config --modversion doca-sta as the build-time anchor; disagreement with doca_caps --version is a partial-install hazard and must be routed to doca-version TASKS.md ## debug (doca-version/TASKS.md#debug) layer 2 before any STA-layer diagnosis.
Substrate-library version match. Because STA's transport is RDMA, doca-rdma.pc must also match the same doca_caps --version line — a STA install that compiles against one DOCA RDMA major and runs against another is a partial-install hazard. Route to doca-rdma CAPABILITIES.md ## Version compatibility (doca-rdma/CAPABILITIES.md#version-compatibility) for the RDMA-side overlay.

Error taxonomy

STA-specific overlays on the cross-library DOCA_ERROR_* taxonomy. The cross-library taxonomy itself lives in doca-programming-guide CAPABILITIES.md ## Error taxonomy (doca-programming-guide/CAPABILITIES.md#error-taxonomy); the rows below are the STA surface meaning that the agent must disambiguate before falling back to the cross-library response.

Error	DOCA STA context where it shows up	STA-specific cause
`DOCA_ERROR_BAD_STATE`	Any call after `doca_ctx_stop()` or before `doca_ctx_start()`; submitting an I/O on a queue pair that has not completed the NVMe-oF Connect handshake; reconfiguring subsystems / backends after start	Lifecycle violation on either the `doca_sta` context itself or the per-connection queue-pair state machine. Walk the call sequence against the universal lifecycle in `doca-programming-guide CAPABILITIES.md ## Capabilities and modes` (`doca-programming-guide/CAPABILITIES.md#capabilities-and-modes`); the most common case is submitting before the queue-pair reports CONNECTED.
`DOCA_ERROR_NOT_SUPPORTED`	Opening / using a device that does not pass `doca_sta_cap_is_supported`; a logical block size the device does not support; oversized queue count or depth	Re-run `doca_sta_cap_is_supported` against the active `doca_devinfo` (the device gate) and the matching `doca_sta_get_max_*` query (the sizing gate); if the device is unsupported or a getter returns a smaller bound, that is the answer — the user's device or DOCA version does not support the request.
`DOCA_ERROR_INVALID_VALUE`	`doca_sta_set_` with a queue depth or count outside the `doca_sta_get_max_` bound; a namespace block size rejected by `doca_sta_is_logical_block_size_supported()`	The fix is to re-read the relevant `doca_sta_get_max_*` value, lower the requested value, and re-run configure. Quote the queried value, not a value the user remembered.
`DOCA_ERROR_AGAIN`	I/O submission on a per-queue path when the in-flight budget is full	The I/O queue is full. This is not a hardware error; the program must drain completions via `doca_pe_progress()` before re-submitting, or raise the queue depth within the `doca_sta_get_max_io_queue_size` bound. Same as the cross-library "would-block, retry after progress" pattern.
`DOCA_ERROR_IO_FAILED`	Per-IO completion event reports failure; transport-layer error during the NVMe-oF Connect handshake	A transport-layer I/O error. Likely causes: link drop, RDMA peer disconnect, firmware fault, peer-side controller reset. Do not retry blindly — capture `dmesg
`DOCA_ERROR_NOT_PERMITTED`	`doca_dev_open` for a device the user has no access to; STA context create after a permission downgrade	The device was not opened with the required access. Confirm sudo or the appropriate group membership per `## Safety policy`; do not modify the program.
`DOCA_ERROR_DRIVER`	Any submit / completion call	The layer below DOCA reported failure. Capture state (`dmesg

The agent's rule: never recommend a retry loop on DOCA_ERROR_* without first identifying which of the rows above is the cause. _AGAIN is the only one that wants a retry (after doca_pe_progress()); the others want investigation, not retry. And "the connection won't establish" is rarely a _BAD_STATE on the STA side — it is more often a steering / fabric / peer issue and the agent should walk the precondition matrix in ## Safety policy before any code change.

Observability

The DOCA Core progress engine (PE) is the single source of observability for STA: every queue-pair state transition and every I/O completion (success or failure) arrives as an event on the PE that the doca_sta context is registered against. STA does not maintain per-connection counters of its own; its observability surface is event-driven, with one add-on signal (capability snapshot at configure time).

Three primary signals the agent should reach for:

Per-queue I/O completion events on the PE. Each submitted I/O produces a completion event when it finishes (or errors) on the matching queue. The completion carries the doca_error_t if it failed; the agent must inspect the per-IO completion, not the submit-call return value alone. Absence of completions on a queue with submitted IOs is always either a missing doca_pe_progress() call or a transport-layer stall; route to ## Error taxonomy _AGAIN / _IO_FAILED rows.
Queue-pair state transitions. The NVMe-oF queue pair transitions from CREATED → CONNECTED (after the NVMe-oF Connect handshake) → DISCONNECTED. The agent must wire and inspect the transition events; submitting an I/O before CONNECTED returns DOCA_ERROR_BAD_STATE, and a session that seems up but never moves past CREATED is a fabric or peer-side problem, not a STA bug.
Capability snapshot at configure time. The output of the doca_sta_cap_is_supported device check plus the doca_sta_get_max_* queries is a snapshot of what the library said was possible before any I/O was submitted. Save it as the baseline; if an I/O later returns DOCA_ERROR_NOT_SUPPORTED or _INVALID_VALUE the diff against this snapshot is the bug.

For the cross-cutting debug-time observability primitives (DOCA_LOG_LEVEL=trace, --sdk-log-level, the trace build flavor) see doca-debug CAPABILITIES.md ## Observability (doca-debug/CAPABILITIES.md#observability). For the env-side observability primitives (link state, RDMA device enumeration) defer to doca-setup CAPABILITIES.md ## Observability (doca-setup/CAPABILITIES.md#observability).

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.

DOCA STA's safety surface is substrate-library presence, device access, and steering. The single most common first-app failure for an NVMe-over-RDMA target is "the initiator's Connect handshake never completes" — and the agent's job is to verify the three preconditions before any code change, not after the first DOCA_ERROR_*.

The precondition matrix the agent must walk for any new DOCA STA setup:

Precondition	What must be true before `doca_ctx_start()`	How the agent verifies	Where to fix
Substrate library present	STA's transport is RDMA-only: `doca-rdma.pc` resolves and `doca_rdma_cap_*` reports a non-empty surface on the chosen device	`pkg-config --modversion doca-rdma`; the matching cap-query call as documented in `doca-rdma CAPABILITIES.md ## Capabilities and modes` (`doca-rdma/CAPABILITIES.md#capabilities-and-modes`); `mlxconfig -d <pcie> q` for the firmware view	`doca-setup/SKILL.md` for the env-side; do not modify the program
Device access	The `doca_dev` was opened against a BlueField PF / SF the user has permission to use (typically requires sudo or the appropriate group membership)	`id` for group membership; the open call failing with `DOCA_ERROR_NOT_PERMITTED` is the runtime symptom	`doca-setup/SKILL.md` for the env-side; do not modify the program
NVMe-oF traffic actually reaches the STA-managed queue	Either a DOCA Flow rule (or the env-side equivalent) steers matching NVMe-oF 5-tuples to this STA instance's queues	Inspect the Flow rule programmed for this NVMe-oF connection (or the absence of one); confirm via the steering-rule listing on the user's setup	`doca-flow/SKILL.md` for the steering side; do not invent a `doca_sta_*` steering call

The initiator side is out of scope. The agent must surface — early in any recommendation — that doca-sta accelerates the NVMe-oF target data path only. The remote initiator / host NVMe stack (SPDK bdev_nvme, kernel nvme host) is a separate peer on the fabric and is not programmed through doca-sta. The skill does NOT prescribe the initiator's deployment — that's the remote peer's decision — but it must ensure the user knows doca-sta is target-side acceleration, not an initiator transport provider.

Smoke before scale-up. Before driving production workloads, the agent must walk the user through a single-IO smoke (one NVMe admin command — typically Identify Controller — over the admin queue, then one NVMe Read over a single I/O queue). Read is the default smoke. A Write is permitted only after the user explicitly confirms that the namespace is disposable and supplies a safe test LBA or LBA range whose existing data may be overwritten. Without both confirmations, the agent must not recommend a Write or invent an LBA. A failure here narrows cleanly: admin-queue side, fabric, or I/O-queue side. A failure at production scale without the single-IO smoke pass is a much harder bisection.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

The author says: 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.

Security

What our scanner noticed· Medium risk

Large base64-encoded blobs

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

NVIDIA

Publisher

NVIDIA (Official)

Source

NVIDIA/skills · skills/doca-sta · commit fce3cca

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE-APACHE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download doca-sta.zip