doca-gpi

# 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

DOCA GPI ships as a C library with the `pkg-config` module name
`doca-gpi`. The library's **host-side** surface (`doca_gpi_*`)
is C; the **GPU-side** surface — the `doca_gpu_gpi_channel*`
handle and the device-side calls a CUDA kernel uses against that
handle — is compiled with `nvcc` against the DOCA GPU NetIO
device-side header set documented in
[`doca-gpunetio`](../doca-gpunetio/SKILL.md). Other-language
consumers (Rust, Go, Python, …) consume the host-side `*.so`
through FFI; the skill's contribution in that case is to keep the
channel / queue lifecycle, the GPU-handle handoff, the version
discipline, and the safety overlay language-neutral, and to route
the agent to the public C ABI as the authoritative surface that
any wrapper will eventually call. The GPU-side surface is *not*
wrappable in another language — it is compiled and linked into
the CUDA binary itself.

## When to load this skill

Load this skill when the user is doing **hands-on DOCA GPI work**
on a host with both a BlueField / ConnectX device and an NVIDIA
GPU. Concretely:

- Deciding between `doca-gpi` (the lower-level channel/queue
  surface) and `doca-gpunetio` (the higher-level Send/Receive
  surface) for a new GPU-initiated RDMA workload.
- Creating a `doca_gpi` on a `doca_dev`, configuring it via the
  `doca_gpi_set_*` family (domain count, GID index, port) and
  sizing domains and channels through the
  `doca_gpi_domain_attr_*` / `doca_gpi_channel_attr_*` setters
  before `doca_gpi_start()`.
- Creating a channel with `doca_gpi_channel_create` and
  re