/doca-gpi

license: Apache-2.0
name: doca-gpi
description: >
  Use this skill for hands-on DOCA GPI programming
  — wiring a GPU-Packet-Initiator context so a CUDA kernel drives
  RDMA queues directly from GPU memory without host CPU mediation.
  Covers picking GPI vs doca-gpunetio, the doca_gpi / domain /
  channel object model, the GPU-side handle handoff
  (doca_gpu_gpi_channel*), attaching GPU memory to a GPI domain,
  the domain and channel attribute objects, and debugging
  DOCA_ERROR_* from doca_gpi_* calls. Trigger even when the user
  does not explicitly mention "DOCA GPI" — implicit
  phrasings include "my CUDA kernel needs to post RDMA directly
  from GPU memory", "DOCA_ERROR_* from doca_gpi_gpu_channel_get",
  "how do I hand a GPU handle to my CUDA kernel", "how many
  channels can a GPI domain hold", or "GPU kernel driving RDMA
  without the host CPU on the path". Refuse and route elsewhere
  for the doca-gpunetio
  Send/Receive surface, the doca-rdma queue lifecycle, DPA-side
  initiation (doca-rdmi), or the CUDA programming model — 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 or ConnectX NIC
  attached, plus an NVIDIA GPU with CUDA Toolkit installed
  (GPUDirect-style PCIe path between GPU and NIC). Reads the local
  install via `pkg-config doca-gpi` (co-requires doca-gpunetio,
  doca-dpa, doca-verbs) and inspects /opt/mellanox/doca/{lib,include,samples,applications}.

DOCA GPI

**Where to start:** This skill assumes DOCA is already installed and the user is doing **hands-on GPI work** on a host that has both a BlueField / ConnectX device and an NVIDIA GPU reachable over PCIe. Open [`TASKS.md`](TASKS.md) if the user wants to *do* something (install / configure / build / modify / run / test / debug / use); open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what can GPI express on this version* — the domain + channel object model, the GPU-side handle handoff, the relationship to doca-gpunetio and doca-verbs, the attribute objects, and the safety overlay. If the user has not installed DOCA yet, route to [`doca-setup`](../../doca-setup/SKILL.md) first.

Example questions this skill answers well

The CLASSES of GPI 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.

• **"Should I use `doca-gpi` or `doca-gpunetio` for this case?"** —

worked example: *"my CUDA kernel needs to post RDMA writes directly to a remote DPU's memory — do I want the higher-level Send/Receive surface or the lower-level channel/queue surface?"*. Answered by the *channel-level vs Send/Receive-level* selection rule in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) surface-selection table.

• **"How do I bring up a GPI channel and connect it to a remote

peer?"** — worked example: *"create the GPI, set domain + channel attribute sizing, create the channel, exchange endpoint connection info with the remote, connect the endpoint"*. Answered by the channel-object lifecycle in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the configure walk in

[`TASKS.md ## configure`](TASKS.md#configure).

• **"What is the GPU-side handle and how do I hand it to my CUDA

kernel?"** — worked example: *"`doca_gpi_gpu_channel_get` returns a `doca_gpu_gpi_channel*` — how do I get that into my CUDA kernel's argument list?"*. Answered by the GPU-handoff pattern in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the run-side wiring in [`TASKS.md ## run`](TASKS.md#run),

cross-linked into [`doca-gpunetio`](../doca-gpunetio/SKILL.md) for the CUDA-side programming surface itself.

• **"What does my CUDA + GPU + DOCA version stack need to look

like?"** — worked example: *"I have BlueField-3 + A100; which CUDA Toolkit and which DOCA version do I need?"*. Answered by the version-overlay in [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility)

• the install-checks in [`TASKS.md ## install`](TASKS.md#install).
• **"How do I size the channels and work queues I want?"** —

worked example: *"I want 64 channels in a domain, each with a 1024-entry send queue; which setters express that?"*. Answered by the attribute-object sizing rule (`doca_gpi_domain_attr_set_num_channels`, `doca_gpi_channel_attr_set_sq_wqe_num`) in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the sizing step in

[`TASKS.md ## configure`](TASKS.md#configure).

• **"What does this `DOCA_ERROR_*` from a `doca_gpi_*` call

mean?"** — worked example: *"`DOCA_ERROR_*` from `doca_gpi_gpu_channel_get`"*. Answered by the GPI 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).

Audience

This skill serves **external developers building GPU-resident DOCA applications that need to drive RDMA queues directly from CUDA kernels** — i.e., users whose accelerator-side code wants to post RDMA work from GPU memory without round-tripping through the host CPU. The canonical caller is a CUDA kernel that runs on an NVIDIA GPU on the same host as a BlueField / ConnectX device, has GPUDirect-style access to the DPU's RDMA queues through the DOCA GPU-NetIO stack, and uses the GPI channel + queue handle to drive RDMA initiation. This skill is *not* for NVIDIA developers contributing to DOCA GPI itself, and it is not the right surface for the higher-level Send/Receive Ethernet-shaped GPU NetIO API — that belongs to [`doca-gpunetio`](../doca-gpunetio/SKILL.md).

Language scope

D