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.