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

if the user wants to *do* something (configure / build /

modify / run / test / debug); open

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 first; if

the user has not stood up a host-side Flow pipe yet, route to

doca-flow first; if the user has

not stood up host-side DPA execution yet, route to

doca-dpa 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

("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

+ the bring-up steps in

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

("DPA-side consumption") + the host-side queue allocation

+ DPA-side polling step in

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

+ the layered ladder in

TASKS.md ## debug that escalates to

doca-debug.

• **"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

+ the staged-export workflow in

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

which cross-links the canonical detection chain in

doca-version and adds the

provider-specific overlay inherited from

doca-dpa.

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.

When to load this skill

Load this skill when the user is doing hands-on DOCA Flow DPA

Provider work, in any host language plus a DPA-side

translation unit built by dpacc. Concretely:

• Initializing a doca_flow_dpa_ctx against a flexio_process

that maps to a BlueField with a DPA processor visible to

the host AND a host-side doca-flow port already brought

up against the same device.

• Allocating the three DPA-side queue types (general /

entries, resources-write, resources-read) for a port via

doca_flow_dpa_queues_create.

• Exporting a host-side doca_flow_pipe to the DPA address

space via the

doca_flow_dpa_pipe_export_prepare → _pipe_export →

_pipe_get_device_addr sequence, BEFORE any entry is added

to the pipe.

• Exporting an external Flow resource (index-selector

resource, memory resource) to the DPA via the matching

doca_flow_dpa_external_resource_* family.

• Handing the resulting doca_flow_dpa_addr device pointer to

the DPA-side kernel so the kernel can call

doca_flow_pipe_hash_* / doca_flow_external_resource_*

/ doca_flow_queue_poll_completion on it.

• Debugging a DOCA_ERROR_* from a doca_flow_dpa_* call —

in particular disambiguating *export called too late in the

pipe lifecycle* from *queues not yet created* from *DPA-

side queue full and not drained*.

• Designing host-side bindings in a non-C language that drive

the provider's host-side setup and hand the device address

off to a DPA application image built separately with

dpacc.

Do not load this skill for general DOCA Flow programming

(use doca-flow), generic host-side

DPA work (use doca-dpa), or DPA-

side kernel-writing itself (route via

doca-public-knowledge-map

to the public DOCA DPA / DPACC / Flow programming guides).

What this skill provides

This is a thin loader. The body keeps only the orientation

needed to pick the right next file. The substantive

provider-specific material lives in two companion files:

• CAPABILITIES.md — what the host-side and DPA-side provider

API can express on this version + this BlueField

generation: the per-port doca_flow_dpa_ctx context, the

three queue types (DOCA_FLOW_DPA_QUEUE_TYPE_GENERAL /

_RESOURCES_WRITE / _RESOURCES_READ), the

pipe-export handshake (prepare → export → get-device-addr),

the parallel external-resource-export handshake, the DPA-

side device API for hash-pipe entry manipulation

(doca_flow_pipe_hash_enable_index /

_hash_disable_index / _hash_replace_index), the DPA-

side device API for external resources

(doca_flow_external_resource_index_selector_modify*,

doca_flow_external_resource_memory_update,

doca_flow_external_resource_memory_read*), the

completion-queue polling

(doca_flow_queue_poll_completion), the

three-program-model rule (host-side doca-flow + host-side

doca-dpa + DPA-side kernel), the error taxonomy mapped

onto the cross-library DOCA_ERROR_* set, the

observability surface, and the safety policy that gates the

export lifecycle.

• TASKS.md — step-by-step workflows for the in-scope

provider verbs: install, configure, build, modify,

run, test, debug, use. Plus a Deferred task verbs

block that points out-of-scope questions at the right next

skill.

The skill assumes a host where DOCA is already installed at

the standard location, a BlueField with a DPA processor is

physically present and visible to the host, the DPACC

compiler is installed at a version matched to the DOCA

install per the DOCA Compatibility Policy, the user already

knows how to bring up a doca-flow port and create a

host-side doca_dpa (or its FlexIO equivalent) for kernel

execution, and the user has at least a sketch of the DPA-side

kernel that will consume the exported pipe device address.

What this skill deliberately does not ship

This skill is agent guidance, not a samples or templates

bundle. To keep the boundary clean, it deliberately does not

contain — and pull requests should not add:

• **Pre-written DOCA Flow DPA Provider application source

code or DPA-side kernel source, in any language.** The

verified provider source is the shipped C + DPA-side

samples under the installed DOCA samples tree (route via

doca-public-knowledge-map

for the per-install sample tree path). The agent's job is

to route the user to those files and prescribe a

minimum-diff modification on them via the universal

modify-a-sample workflow in

doca-programming-guide,

layered with the provider-specific overrides in

TASKS.md ## modify.

• Standalone build manifests (meson.build,

CMakeLists.txt, …) parked inside the skill. The agent

constructs the build manifest *in the user's project

directory* against the user's installed DOCA + DPACC

compiler, where `pkg-config --modversion

doca-flow-dpa-provider (alongside doca-flow` and

doca-dpa) and the installed dpacc are the joint sources

of truth.

• A samples/, bindings/, or reference/ subtree of

any kind. A mock or incomplete artifact in this skill's

tree, even one labeled "reference", is misleading: users

will read it as buildable.

• Host-side doca-flow pipe-spec content. That is

doca-flow's scope; this skill

*exports* an already-constructed pipe and does not redefine

how to construct it.

• DPA-side kernel programming generalities. Writing the

DPA-side function body, allocating DPA memory inside the

kernel, intrinsics, DPA-side libraries like

doca-dpa-comms and doca-dpa-verbs — out of scope. Route

to the public DOCA DPA / DPACC guides via

doca-public-knowledge-map.

Loading order

• Read this SKILL.md first to confirm the user's question

is in scope (Flow-pipe-exported-to-DPA work, not pure

doca-flow work and not generic doca-dpa work).

• **For the provider capability matrix, the three-program

model, the per-port doca_flow_dpa_ctx, the three queue

types, the pipe-export and external-resource-export

handshakes, the DPA-side device API surface, the

completion model, the error taxonomy, the observability

surface, and the safety policy, see

CAPABILITIES.md.**

• **For step-by-step workflows — install, configure, build,

modify, run, test, debug, use — see

TASKS.md.**

Both companion files cross-link to each other,

doca-flow and

doca-dpa for the host-side

surfaces this library bridges,

doca-version for the

canonical DOCA version-handling rules (with the

DOCA-and-DPACC overlay inherited from

doca-dpa), and

doca-public-knowledge-map

whenever the right answer is "look it up in the public DOCA

Flow / DOCA DPA / DPACC programming guides, or in the on-disk

install layout" rather than "provider-specific guidance".

Related skills

• doca-flow — the canonical

host-side Flow programming skill. The Flow pipe this

library exports MUST be brought up against

doca-flow CAPABILITIES.md ## Capabilities and modes

first; this skill only adds the DPA-export layer on top.

• doca-dpa — the host-side DPA

control library. The DPA kernel that consumes the

exported device address is loaded and launched through

doca-dpa (or its FlexIO-process equivalent); this skill

inherits the two-side-program model, the DPACC-and-DOCA

version-match rule, and the env-precondition matrix from

there.

• doca-public-knowledge-map —

routing table for every public DOCA documentation source

(DOCA Flow guide at

<https://docs.nvidia.com/doca/sdk/doca-flow/index.html>;

DOCA DPA guide at

<https://docs.nvidia.com/doca/sdk/doca-dpa/index.html>;

DPACC compiler guide and DPA Tools umbrella reachable from

the same routing table) and the on-disk layout of an

installed DOCA package.

• doca-setup — env preparation,

install verification, DPACC compiler install /

verification, and the *I have no install yet* path with

the public NGC DOCA container. This skill assumes its

preconditions are satisfied AND that DPACC is installed at

a version that matches DOCA.

• doca-version — canonical

DOCA version-handling rules. This skill's `## Version

compatibility` cross-links the four-way match rule and adds

the provider-specific *DOCA-and-DPACC must match* overlay

per the DOCA Compatibility Policy (inherited from

doca-dpa).

• doca-structured-tools-contract —

the bundle's structured-tools precedence rule (detect /

prefer / fall back / report). The Command appendix in

TASKS.md honors this contract.

• doca-programming-guide —

general DOCA programming patterns: the canonical

pkg-config + meson build pattern, the universal

modify-a-shipped-sample first-app workflow, the universal

Core-context lifecycle, the cross-library DOCA_ERROR_*

taxonomy, and the program-side debug order. This skill

layers provider specifics on top.

• doca-debug — the cross-cutting

debug ladder (install / version / build / link / runtime /

program / driver). Provider-specific debug (lifecycle-

ordering between Flow pipe creation, queue creation, export

prepare, entry add, export; queue-full on DPA-side polling;

pipe device address handed to a kernel that targets a

different doca_flow_dpa_ctx) overlays on top.

• doca-hardware-safety —

cross-cutting hardware-safety meta-policy that this

skill's ## Safety policy overlays. Because the exported

pipe is mutated inline by DPA-side kernel code, the

validate-before-commit discipline from doca-flow plus the

two-side-program rebuild discipline from doca-dpa BOTH

apply, and the meta-policy provides the cross-cutting

framing.