/doca-sta

license: Apache-2.0
name: doca-sta
description: >
  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.
metadata:
  kind: library
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}.

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` targ