doca-flow-dpa-provider

# DOCA Flow DPA Provider

**Where to start:** This skill assumes DOCA is already
installed, the user has a BlueField with a DPA processor that
the host can see through DOCA, the user already programs DOCA
Flow from the host (`doca-flow`) and already runs DPA kernels
from the host (`doca-dpa` / DPACC compiler), and the user is
doing **hands-on DPA Flow Provider work** — i.e. using
`doca-flow-dpa-provider` to export an existing DOCA Flow pipe
or external resource into the DPA address space so a DPA
kernel can manipulate it inline. 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 provider 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 has not stood up a host-side Flow pipe yet, route to
[`doca-flow`](../doca-flow/SKILL.md) first; if the user has
not stood up host-side DPA execution yet, route to
[`doca-dpa`](../doca-dpa/SKILL.md) first.

## Example questions this skill answers well

The CLASSES of DPA Flow Provider 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.

- **"Is this library even the right tool for what I want?"** —
  worked example: *"I want my DOCA Flow pipe to be readable
  from a DPA kernel, OR I want to do something fancier than
  the host-side `doca-flow` API exposes"*. Answered by the
  decision rule in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  ("three-program model: when this library is the right
  surface vs pure host-side Flow vs pure DPA"). Most
  first-time askers do NOT need this library; the skill's
  first job is to confirm they do.
- **"How do I export an existing DOCA Flow pipe to the DPA
  side?"** — worked example: *"I have a Flow pipe with a
  counter on every entry; I want a DPA kernel to read those
  counters inline and decide what to do next"*. Answered by
  the host-side export sequence in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the bring-up steps in
  [`TASKS.md ## configure`](TASKS.md#configure).
- **"How do I drive the exported pipe from inside the DPA
  kernel?"** — worked example: *"I have the device address of
  an exported hash pipe; how do I disable an entry from the
  DPA, and how do I know the operation completed?"*.
  Answered by the device-side API surface in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  ("DPA-side consumption") + the host-side queue allocation
  + DPA-side polling step in
  [`TASKS.md ## run`](TASKS.md#run).
- **"What does this `DOCA_ERROR_*` from a
  `doca_flow_dpa_*` call mean, and is the bug on the host
  side, on the DPA side, or in the export handshake between
  them?"** — worked example: *"`DOCA_ERROR_BAD_STATE` from
  `doca_flow_dpa_pipe_export`"*. Answered by the provider
  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).
- **"Why did my pipe export *succeed* but my DPA kernel never
  sees entries?"** — worked example: *"I called
  `doca_flow_dpa_pipe_export_prepare` AFTER adding entries to
  the pipe"*. Answered by the lifecycle ordering rule in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  + the staged-export workflow in
  [`TASKS.md ## test`](TASKS.md#test).
- **"Is the host-side / DPA-side provider API I'm reading
  about on my installed DOCA?"** — worked example: *"is the
  three-queue-type `doca_flow_dpa_queues_create` available
  against the DOCA + DPACC versions on this host, or am I
  still on the older `doca_flow_dpa_pipe_queues`-based
  surface?"*. 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
  provider-specific overlay inherited from
  [`doca-dpa`](../doca-dpa/SKILL.md).

## Audience

This skill serves **external developers building applications
that consume the DOCA Flow DPA Provider library** — i.e.,
users who already have a host-side `doca-flow` pipe and a
host-side `doca-dpa` execution context, and who want to wire
the two together so a DPA kernel can read counters from / mutate
entries of / read or write external resources tied to that
Flow pipe inline, instead of round-tripping through the host
CPU. It is *not* for NVIDIA developers contributing to the
provider library itself, nor is it for users who only need
host-side Flow programming (that is `doca-flow`) or who only
need generic DPA compute that has nothing to do with Flow
(that is `doca-dpa`).

**Language scope.** DOCA Flow DPA Provider ships as a *paired*
library: a host-side C library (pkg-config module
`doca-flow-dpa-provider`, header
`doca_flow_dpa_provider.h`) plus a DPA-side device library
that the DPACC compiler links into the DPA-side translation
unit when the kernel includes `doca_flow_dpa_provider_dev.h`.
Both halves are C. The shipped samples (under the installed
DOCA samples tree) include both translation units. Other-
language host-side consumers can FFI the host C library, but
the DPA-side kernel has no FFI escape hatch (the DPACC
compiler accepts a single translation unit per kernel image).
The skill keeps the lifecycle, capability-discovery, env-
precondition, and error-taxonomy guidance language-neutral on
the host side, and points all DPA-side kernel-writing
questions at the public DOCA DPA and DOCA Flow programming
guides via
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKIL