/doca-sta

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.