doca-gpunetio

# DOCA GPUNetIO

**Where to start:** This skill assumes DOCA is already installed,
the CUDA toolkit is installed and matched to the DOCA install, and
the user is doing **hands-on GPUNetIO work** — i.e. wiring a DOCA
network queue into a CUDA kernel on an NVIDIA GPU. Open
[`TASKS.md`](TASKS.md) if the user wants to *do* something
(configure / build / modify / run / test / debug); open
[`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what
can GPUNetIO express* on this version + this GPU. If the user has
not installed DOCA yet, route to
[`doca-setup`](../../doca-setup/SKILL.md) first; if the user has
not set up the underlying Ethernet RX/TX queues yet, that is a
DOCA Ethernet question — route to
[`doca-eth`](../doca-eth/SKILL.md).

## Example questions this skill answers well

The CLASSES of GPUNetIO 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 get a CUDA kernel to receive packets directly from
  the NIC?"** — worked example: *"persistent kernel on one GPU
  reads packets from a `doca_gpu_eth_rxq` built on top of a
  representor `doca_eth_rxq` and counts them per-flow"*. Answered
  by the persistent-kernel pattern in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the GPU-side bring-up workflow in
  [`TASKS.md ## configure`](TASKS.md#configure).
- **"Can I run GPUNetIO on this GPU?"** — worked example: *"my
  host has one Ampere card and one Turing card; which one
  supports GPU-initiated networking?"*. Answered by the dual
  capability-discovery rule (DOCA cap-query AND
  `cudaGetDeviceProperties` against the CUDA device ordinal) in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the device-enumeration step in
  [`TASKS.md ## configure`](TASKS.md#configure).
- **"Why does my GPUNetIO setup fail with
  `DOCA_ERROR_NOT_SUPPORTED` even though doca-eth came up
  fine?"** — worked example: *"`nvidia_peermem` is not loaded so
  GPUDirect RDMA is unavailable"*. Answered by the env preconditions
  in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  + the env checklist in
  [`TASKS.md ## configure`](TASKS.md#configure) step 1.
- **"How do I move data between CUDA-allocated buffers and a DOCA
  queue?"** — worked example: *"use `cudaMalloc` for the receive
  buffer pool and register it with DOCA via `doca_buf_arr_create_*`
  before starting the context"*. Answered by the CUDA-allocator
  + DOCA-registration overlay in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  + the buffer-prep step in
  [`TASKS.md ## configure`](TASKS.md#configure) step 4.
- **"Is the GPUNetIO API I'm reading about on my installed DOCA +
  CUDA combination?"** — worked example: *"is the persistent-kernel
  helper available with the CUDA toolkit version I have?"*.
  Answered by the version-compatibility overlay in
  [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility)
  which cross-links the canonical detection chain in
  [`doca-version`](../../doca-version/SKILL.md) and adds the
  GPUNetIO-specific *DOCA must match CUDA* overlay.
- **"What does this `DOCA_ERROR_*` from a GPUNetIO call mean and
  which layer caused it?"** — worked example: *"`DOCA_ERROR_DRIVER`
  on `doca_gpu_*_create` — is it DOCA, CUDA, or the underlying
  doca-eth queue?"*. Answered by the GPUNetIO 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 applications
that consume the DOCA GPUNetIO library** — i.e., users whose code
calls `doca_gpu_*` from host C/C++ to stand up the per-GPU
context and the GPU-visible queue handles, and whose CUDA kernel
(`.cu` translation unit) uses those handles from device code to
submit / receive packets. The canonical target shape is the GPU
Packet Processing reference application: a CUDA persistent
kernel on an NVIDIA GPU that polls a GPU-visible RX queue and
processes packets in-place on the GPU. It is *not* for NVIDIA
developers contributing to DOCA GPUNetIO itself.

**Language scope.** DOCA GPUNetIO ships as a C / CUDA library
with `pkg-config` module name `doca-gpunetio`. The host-side API
is C; the device-side API is CUDA C++ used inside a `.cu`
kernel. The shipped samples and the GPU Packet Processing
reference application are written in C + CUDA C++ (NVIDIA's
choice). Other-language consumers are limited in practice — the
device-side API has no FFI escape hatch because the kernel must
be a CUDA translation unit — but a Rust / Go / Python host-side
wrapper that drives the host-side `doca_gpu_*` setup and
launches a CUDA kernel 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 GPUNetIO
work, in any host language plus CUDA. Concretely:

- Initializing a `doca_gpu` against a specific CUDA device
  ordinal on a host with one or more NVIDIA GPUs.
- Creating a GPU-visible queue handle (`doca_gpu_eth_rxq`,
  `doca_gpu_eth_txq`) on top of an existing `doca_eth_rxq` /
  `doca_eth_txq` from DOCA Ethernet, and passing the handle into
  a CUDA kernel for device-side use.
- Writing or modifying the persistent CUDA kernel that drains
  the GPU-visible RX queue in a long-running loop (the canonical
  GPU Packet Processing shape).
- Allocating GPU buffers via `cudaMalloc` and registering them
  with DOCA via the `doca_buf_arr_create_*` family before
  `doca_ctx_start()`.
- Checking which GPUNetIO features are supported on the active
  `doca_devinfo` (DOCA cap-query family) AND on the can