/doca-dpa

license: Apache-2.0
name: doca-dpa
description: >
  Use this skill when the user is doing hands-on DOCA DPA host-side
  work on a BlueField — creating the `doca_dpa` Core context, loading
  a DPACC-compiled DPA app image (`doca_dpa_app`), creating DPA
  threads, launching kernels via `doca_dpa_kernel_launch_update_*`,
  draining `doca_dpa_completion`, running `doca_dpa_cap_*` discovery,
  choosing between the DPA comm component (inter-DPA messaging) and the
  DPA verbs component (in-kernel RDMA), or debugging `DOCA_ERROR_*`
  from `doca_dpa_*`. Trigger even without "DOCA DPA" or "Data-Path
  Accelerator": "run compute on the DPA from my host", "DPA kernel
  hangs, no completion", "DOCA_ERROR_DRIVER on launch", "DOCA/DPACC
  version skew", or "does this BlueField expose a DPA". Route elsewhere
  for DPA-side kernel programming itself, DPACC compiler internals,
  host↔DPU messaging (doca-comch), host-side RDMA (doca-rdma), and
  GPU-initiated networking (doca-gpunetio).
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 whose
  generation exposes the DPA processor to the host, plus the
  matching DPACC compiler at a version listed compatible by
  the DOCA Compatibility Policy. Reads `pkg-config --modversion
  doca-dpa` and the installed `dpacc` version, and inspects
  /opt/mellanox/doca/{lib,include,samples/doca_dpa,applications}.

DOCA DPA

**Where to start:** This skill assumes DOCA is already installed, the user's BlueField has a DPA processor and the host can see it through DOCA, and the user is doing **hands-on DPA work from the host side** — i.e. using `doca-dpa` to load a DPA application image, launch DPA kernels, and exchange data with the DPA processor. Open [`TASKS.md`](TASKS.md) if the user wants to *do* something (configure / build / modify / run / test / debug); open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what can the host-side DPA API express* on this version + this BlueField generation. If the user has not installed DOCA yet, route to [`doca-setup`](../../doca-setup/SKILL.md) first; if the user is asking how to *write* the DPA-side kernel itself (the code that runs on the DPA processor, compiled by `dpacc`), that is a different scope — route via [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md) to the public DOCA DPA / DPACC / DPA-Comms / DPA-Verbs guides (this skill does not redefine those DPA-side surfaces).

Example questions this skill answers well

The CLASSES of DPA 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 run a piece of compute on the DPA processor from

my host program?"** — worked example: *"load a DPA kernel that counts events in a loop and reports the count back to the host"*. Answered by the two-side-program model + the host-side launch workflow in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the bring-up steps in

[`TASKS.md ## configure`](TASKS.md#configure).

• **"Does this BlueField even have a DPA, and which DPA features

does my DOCA install expose?"** — worked example: *"my host has a BlueField; can I use the DPA on it for a programmable control workload?"*. Answered by the dual-axis capability rule (BlueField-generation axis via `doca_dpa_cap_*` against the active `doca_devinfo` plus the DOCA-install axis via `pkg-config --modversion doca-dpa`) in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the device-enumeration step in

[`TASKS.md ## configure`](TASKS.md#configure).

• **"Why does my host-side DPA setup fail with

`DOCA_ERROR_NOT_SUPPORTED` even though DOCA Core looks healthy?"** — worked example: *"the BlueField generation in this host predates the DPA feature my code uses"*. Answered by the env-precondition matrix in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)

• the env checklist in

[`TASKS.md ## configure`](TASKS.md#configure) step 1.

• **"How do I get arguments and results between my host program

and my DPA kernel?"** — worked example: *"pass a buffer pointer and a length into the DPA kernel as launch arguments; read a completion back when the kernel finishes"*. Answered by the launch-argument + completion overlay in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the launch + drain steps in

[`TASKS.md ## run`](TASKS.md#run).

• **"Is the DPA host-side API I'm reading about on my installed

DOCA?"** — worked example: *"is the host-side launch helper I see in the docs available against the DOCA + DPACC versions on this host?"*. Answered by the version-compatibility 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 DPA-specific *DOCA must match DPACC* overlay.

• **"What does this `DOCA_ERROR_*` from a `doca_dpa_*` call mean

and which layer caused it?"** — worked example: *"`DOCA_ERROR_DRIVER` on a host-side launch call — is it DOCA, the DPACC-produced image, or the DPA processor itself?"*. Answered by the DPA 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).

• **"How does my DPA kernel send a small message to another

DPA thread on the same DPA processor?"** — worked example: *"two DPA threads in the same loaded `doca_dpa_app`; thread A sends a counter value to thread B over a DPA-side comms endpoint and thread B signals the host through `doca_dpa_completion`"*. Answered by