/doca-eth

license: Apache-2.0
name: doca-eth
description: >
  Use this skill for hands-on DOCA Ethernet packet-queue work
  on a BlueField DPU or ConnectX NIC — bringing up a
  `doca_eth_rxq` or `doca_eth_txq` on a port / representor /
  SF, picking among the four `enum doca_eth_rxq_type` values
  (`_REGULAR` / `_CYCLIC` / `_MANAGED_MEMPOOL` /
  `_SHARED_MEMPOOL`), sizing burst or scatter-gather length
  against the `_cap_*` queries, submitting
  `doca_eth_txq_task_send` / `_lso_send` (carrying packet
  `doca_buf`s — no `doca_eth_frame` struct exists), or
  debugging DOCA_ERROR_* from an Ethernet call. Trigger on
  implicit phrasings: "my RX queue is up but no packets
  arrive", "send-task returns AGAIN at line rate", "which
  queue type for fixed-MTU ingress", "device open fails
  without sudo", or "is L3 checksum offload available here".
  Refuse and route elsewhere for installing DOCA,
  flow-rule / steering programming, host↔DPU control
  messaging, or RDMA data movement.
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. Reads the user's local install via
  `pkg-config doca-eth` and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}.

DOCA Ethernet

**Where to start:** This skill assumes DOCA is already installed and the user is doing **hands-on packet-queue work** on a host or BlueField with DOCA. 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 a DOCA Ethernet queue express* on this version. If the user has not installed DOCA yet, route to [`doca-setup`](../../doca-setup/SKILL.md) first. If the user is asking *"how do I get packets to land on my RX queue at all"*, the answer lives in [`doca-flow`](../doca-flow/SKILL.md) — DOCA Ethernet is the *queue* surface; DOCA Flow is the *steering* surface, and they are independent libraries.

Example questions this skill answers well

The CLASSES of DOCA Ethernet 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 bring up an RX and TX queue on a representor or

physical port?"** — worked example: *"set up a `doca_eth_rxq` plus a `doca_eth_txq` on a single BlueField representor for first-run testing"*. Answered by the queue-pair lifecycle in [`TASKS.md ## configure`](TASKS.md#configure) + [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) RX / TX object table.

• **"Which RX type fits my data shape — regular, cyclic, or

managed-recv?"** — worked example: *"line-rate ingress with fixed-size frames into a pre-allocated buffer ring"*. Answered by the RX-type taxonomy in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the capability-query rule (`doca_eth_rxq_cap_is_type_supported`

against a `doca_devinfo`) in [`TASKS.md ## configure`](TASKS.md#configure).

• **"How do I send a packet from user code through `doca_eth_txq`?"**

— worked example: *"allocate a packet `doca_buf`, attach the payload, submit one send-task, wait for the completion event"*. Answered by the TX submission shape in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the property-set workflow in

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

• **"My queue is up but no packets arrive — why?"** — worked

example: *"`doca_eth_rxq` started cleanly but the recv callback never fires"*. Answered by the steering-dependency rule in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)

• the env-prep checklist in

[`TASKS.md ## configure`](TASKS.md#configure) step 1, which routes the steering side to [`doca-flow`](../doca-flow/SKILL.md) and the promiscuous-mode side to [`doca-setup`](../../doca-setup/SKILL.md).

• **"Is this Ethernet capability available on my device + my

installed DOCA?"** — worked example: *"does this device advertise L3 checksum offload"*. Answered by the capability-query rule (`doca_eth_txq_cap_is_l3_chksum_offload_supported` against a `doca_devinfo`) in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the version-and-device overlay in

[`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility).

• **"What does this `DOCA_ERROR_*` from an Ethernet call mean and

which layer caused it?"** — worked example: *"`DOCA_ERROR_AGAIN` on `doca_task_submit` for an `eth_txq` send-task at high rate"*. Answered by the Ethernet 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 Ethernet library** — i.e., users whose code calls `doca_eth_rxq_*` / `doca_eth_txq_*` (directly in C/C++, or through FFI/bindings from another language) to do line-rate packet I/O on physical ports, representors, or SFs of a BlueField or ConnectX device. It is *not* for NVIDIA developers contributing to DOCA Ethernet itself.

**Language scope.** DOCA Ethernet ships as a C library with `pkg-config` module name `doca-eth`. The shipped samples are written in C. C and C++ consumers are the canonical case; the worked examples in `TASKS.md` assume that path. Other-language consumers (Rust, Go, Python, …) consume the same `*.so` through FFI or language-specific bindings; the skill's contribution in that case is to keep the queue-object split, lifecycle, capability-discovery, permission, RX-type taxonomy, and error-taxonomy guidance language-neutral, and to r