doca-dpa

# 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 the DPA-Comms routing
  rule, primitive families, host-side capability-budget rule,
  and DPA-Comms error overlay in
  [`CAPABILITIES.md ## comms`](CAPABILITIES.md#comms) plus the
  configure / build / modify / run / test / debug overlay in
  [`TASKS.md ## comms`](TASKS.md#comms). Disambiguates the DPA
  device-side comm component from host-side `doca-comch` and
  host-side `doca-rdma`.
- **"How do I do RDMA directly from inside my DPA kernel to a
  remote peer, without round-tripping to the host?"** — worked
  example: *"my DPA kernel needs to fetch the next 4 KiB input
  buffer from a remote node via RDMA read before continuing
  compute; the host round-trip is the measured bottleneck"*.
  Answered by the 4-way RDMA matrix, the host-configures-QP /
  DPA-uses-QP coupling rule, the host-side cap-query rule for
  the specific verb, and the DPA-Verbs error overlay in
  [`CAPABILITIES.md ## verbs`](CAPABILITIES.md#verbs) plus the
  workflow overlay in [`TASKS.md ## verbs`](TASKS.md#verbs).
  Includes the climb-back rule for when the latency-tuning
  premise stops holding.

## Audience

This skill serves **external developers building applications
that consume the DOCA DPA library from the host side** — i.e.,
users whose code calls `doca_dpa_*` from host C / C++ to stand
up the per-DPA-instance context, load a DPA application image
that `dpacc` produced from their DPA-side source, create one or
more DPA threads, launch DPA kernels with arguments, a