license: Apache-2.0 name: doca-dpa description: > Use this skill when the user is doing hands-on DOCA DPA host-side work on a BlueField — creating the doca_dpa Core context, loading a DPACC-compiled DPA app image (doca_dpa_app), creating DPA threads, launching kernels via doca_dpa_kernel_launch_update_*, draining doca_dpa_completion, running doca_dpa_cap_* discovery, choosing between the DPA comm component (inter-DPA messaging) and the DPA verbs component (in-kernel RDMA), or debugging DOCA_ERROR_* from doca_dpa_*. Trigger even without "DOCA DPA" or "Data-Path Accelerator": "run compute on the DPA from my host", "DPA kernel hangs, no completion", "DOCA_ERROR_DRIVER on launch", "DOCA/DPACC version skew", or "does this BlueField expose a DPA". Route elsewhere for DPA-side kernel programming itself, DPACC compiler internals, host↔DPU messaging (doca-comch), host-side RDMA (doca-rdma), and GPU-initiated networking (doca-gpunetio). 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 whose generation exposes the DPA processor to the host, plus the matching DPACC compiler at a version listed compatible by the DOCA Compatibility Policy. Reads pkg-config --modversion doca-dpa and the installed dpacc version, and inspects /opt/mellanox/doca/{lib,include,samples/doca_dpa,applications}.

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 if the user wants to do something (configure / build / modify / run / test / debug); open 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 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 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
  • the bring-up steps in 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
  • the device-enumeration step in 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
  • the env checklist in 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
  • the launch + drain steps in 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 which cross-links the canonical detection chain in doca-version 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
  • the layered ladder in TASKS.md ## debug that escalates to doca-debug.
• "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 plus the configure / build / modify / run / test / debug overlay in 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 plus the workflow overlay in 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, and drain completions. It is not for NVIDIA developers contributing to DOCA DPA itself, nor is it the place to learn how to write the DPA-side kernel code (that path goes through the public DOCA DPA, DPACC, DPA-Comms, and DPA-Verbs guides via doca-public-knowledge-map).

Language scope. DOCA DPA ships as a host-side C library with pkg-config module name doca-dpa. The host-side API is C; the DPA-side kernel is a separate translation unit written in the language the DPACC compiler accepts and compiled by dpacc into a binary that the host packages into the executable as the DPA application image. The shipped samples under /opt/mellanox/doca/samples/doca_dpa/ are written in C plus DPA-side source (NVIDIA's choice). Other-language consumers are limited in practice — the DPA-side kernel has no FFI escape hatch because it must be a translation unit dpacc accepts — but a Rust / Go / Python host-side wrapper that drives doca_dpa_* setup and launches a DPA kernel image built separately is still useful, and the skill keeps the lifecycle, capability-discovery, env-precondition, and error-taxonomy guidance language-neutral.

When to load this skill

Load this skill when the user is doing hands-on DOCA DPA work from the host side, in any host language plus a DPA-side translation unit built by dpacc. Concretely:

• Initializing a doca_dpa against a doca_dev that maps to a BlueField with a DPA processor visible to the host.
• Loading a DPA application image (doca_dpa_app) that dpacc produced from the user's DPA-side source, into the doca_dpa context.
• Creating one or more DPA execution contexts (doca_dpa_thread) so DPA kernels have somewhere to run on the DPA processor.
• Launching a DPA kernel function with arguments from the host via the doca_dpa_kernel_launch_update_* family, and reasoning about which argument shape is supported on this install.
• Attaching a doca_dpa_completion to observe when async DPA work finishes, and draining it from the host side.
• Checking which DPA features are supported on the active doca_devinfo via the doca_dpa_cap_* family — BlueField generations differ in DPA hardware support.
• Debugging a DOCA_ERROR_* returned from a doca_dpa_* call — in particular disambiguating DPA not present on this BlueField from DPA feature too new for this hardware generation from DPACC-produced image mismatched against the host-side DOCA install from DPA driver layer reporting failure.
• Designing host-side bindings in a non-C language that drive a DPA application image they built separately with dpacc — the env-precondition and capability-discovery rules in this skill still apply.
• Writing DPA-side kernel code that calls the DPA device-side comm component libdoca_dpa_dev_comm.a (header doca_dpa_dev_comch_msgq.h) — for inter-DPA-thread messaging or coordination signals between DPA threads on the same doca_dpa_app. The DPA-Comms routing rule, primitive families, capability rule (there is no per-primitive host cap-query family — host-side DPA discovery is only doca_dpa_cap_is_supported / doca_dpa_cap_get_max_kernel_time_alive_supported), error overlay (_AGAIN → kernel must yield; _BAD_STATE disambiguation from the parent's host-side _BAD_STATE), and the configure / build / modify / run / test / debug overlay live in CAPABILITIES.md ## comms and TASKS.md ## comms under this same skill.
• Writing DPA-side kernel code that calls the DPA device-side verbs component libdoca_dpa_dev_verbs.a (header doca_dpa_dev_verbs.h) — for RDMA from inside the DPA kernel to a remote peer when the host round-trip is the measured latency bottleneck. The 4-way RDMA matrix, the host-configures-QP / DPA-uses-QP coupling rule, the capability rule (no per-verb host cap-query family exists; verb availability follows the BlueField generation + matched DOCA/DPACC install, read from doca_dpa_dev_verbs.h and the shipped sample), the IO_FAILED → CQE-inspection overlay, and the climb-back rule live in CAPABILITIES.md ## verbs and TASKS.md ## verbs under this same skill.

Do not load this skill for general DOCA orientation, install of DOCA or the DPACC compiler, the DPA-side programming model itself (how to write a DPA kernel; the DPA device-side comm and verbs compo