/doca-flow-dpa-provider

license: Apache-2.0
name: doca-flow-dpa-provider
description: >
  Use this skill when the user is doing hands-on DOCA Flow DPA
  Provider work — exporting a `doca-flow` pipe or external
  resource (index-selector/memory) into BlueField DPA
  address space so a DPACC-built kernel can read counters, mutate
  hash-pipe entries, and update/read memory or index-selector
  resources inline with Flow. Covers per-port
  `doca_flow_dpa_ctx`, three queue types
  (general/resources-write/resources-read), the order-sensitive
  export handshake (`_export_prepare` → add entries → `_export` →
  `_get_device_addr`), and DPA-side device API. Trigger even
  when the user does not say "DOCA Flow DPA Provider" — implicit
  phrasings include "DPA kernel never sees entries in the exported
  pipe", "BAD_STATE from `_pipe_export`", "how do I disable a hash
  entry from a DPA kernel", "DPA memory read returns no value", or
  "DPA-side post keeps returning AGAIN". Refuse and route
  elsewhere for `doca-flow` pipe construction, generic
  host-side DPA (`doca-dpa`), or DPA-side kernel-writing — 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 exposing
  a DPA processor visible to the host, PLUS the DPACC compiler
  installed at a version matched to DOCA per the DOCA Compatibility
  Policy. Reads the user's local install via `pkg-config
  doca-flow-dpa-provider` (cross-checked with `doca-flow`,
  `doca-dpa`, and installed `dpacc`). ConnectX-only hosts cannot
  use this library.

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).

A