doca-sta git:20261028.3d06e7eA

Immutable. This exact content never changes and is served at /api/v1/blob/8463080bef44d584.

---
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 <doca-feedback@nvidia.com>
  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.