/doca-dpa

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:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - dpa
    - accelerator
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}. The
  validation steps require a live DOCA install.

DOCA DPA

Examples

• **"Run compute on the DPA from my host."** — this is in scope.

Stay on `doca_dpa` + a DPACC-built image; do not rewrite it as host-CPU or GPUNetIO.

• **"DPA kernel hangs, no completion."** — drain

`doca_dpa_completion` and check DOCA/DPACC version skew before changing the kernel.

Instructions

Follow Loading order below. Open the tasks companion for configure / launch / debug. Open the capabilities companion for threads vs kernels and the DPA cap query. Do not open every companion file.

**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 the tasks companion if the user wants to *do* something (configure / build / modify / run / test / debug); open the capabilities companion 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/SKILL.md` 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/SKILL.md` to the public DOCA DPA / DPACC / DPA-Comms / DPA-Verbs guides (this skill does not redefine those DPA-side surfaces).

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/SKILL.md`).

**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 in