/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. `doca_eth_rxq` and `doca_eth_txq` are two Core
  contexts; one `doca_ctx_start()` does not cover both. 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:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - ethernet
    - queues
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}.
  The validation steps require a live DOCA install.

DOCA Ethernet

Examples

• **"My RX queue is up but no packets arrive."** — RX and TX are two

Core contexts; one `doca_ctx_start()` does not cover both.

• **"Send-task returns AGAIN at line rate."** — size burst against

the `_cap_*` queries before changing queue type.

Instructions

Follow Loading order below. Open the tasks companion for configure / build / run. Open the capabilities companion for the RX-type taxonomy and send surface. Do not open every companion file.

**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 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 a DOCA Ethernet queue express* on this version. If the user has not installed DOCA yet, route to `doca-setup/SKILL.md` first. **RX and TX are independent Core contexts.** A `doca_eth_rxq` and a `doca_eth_txq` each get their own `doca_ctx_create` / `_start` / `_stop` / `_destroy`; one `doca_ctx_start()` does **not** start both sides. Do not walk a single lifecycle for "the queue pair". If the user is asking *"how do I get packets to land on my RX queue at all"*, the answer lives in `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 two independent Core contexts (each with its own start) in

configure +

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 and modes

• the capability-query rule (`doca_eth_rxq_cap_is_type_supported`

against a `doca_devinfo`) in

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 and modes

• the property-set workflow in

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

Safety policy

• the env-prep checklist in

configure step 1, which

routes the steering side to `doca-flow/SKILL.md` and the promiscuous-mode side to `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 and modes

• the version-and-device overlay in

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

Error taxonomy

• the layered ladder in

debug that escalates to

`doca-debug/SKILL.md`.

**Picking the root-cause layer when several could explain a symptom.** Walk the layers bottom-up (install → version → build → link → runtime → program → driver) with the read-only check each layer names in `TASKS.md` `## debug`. The lowest layer whose check fails is the root cause: fix it, change one variable at a time, and re-run the same check before moving up. For a silent RX queue, rule out the three runtime preconditions (device access, port up, traffic steered to the queue) before any program or driver cause.

Audience

This skill serves **external developers building application