Doca Eth

NVIDIAOfficialCreated by NVIDIA

Skill
Tool integration
Software development
Apache-2.0
Medium risk

From the author

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.

— the description by NVIDIA

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides technical guidance for developers working with the DOCA Ethernet library to perform line-rate packet I/O. It covers the lifecycle management of independent RX and TX core contexts, the selection of RX queue types, capability querying, and error handling. The skill is designed to assist with hands-on development tasks, such as configuring queues on physical ports or representors and debugging packet arrival issues, while maintaining a clear separation from steering logic and installation procedures.

What it does

Guides the initialization and lifecycle management of doca_eth_rxq and doca_eth_txq contexts.
Explains the RX-type taxonomy including regular, cyclic, and managed-mempool configurations.
Provides methods for querying device capabilities like L3 checksum offload and burst size limits.
Assists in debugging DOCA_ERROR_* codes and common runtime issues like silent RX queues.
Outlines the submission process for send-tasks using doca_buf structures.
Routes users to appropriate companion skills for steering, installation, or RDMA-related tasks.

When to use it

When implementing packet I/O applications using the DOCA Ethernet C ABI.
When troubleshooting why packets are not arriving at an initialized RX queue.
When determining the correct RX queue type for specific data shapes or performance requirements.
When verifying if a specific Ethernet capability is supported on a target device.
When debugging errors encountered during task submission or queue lifecycle transitions.

Advantages

Clarifies the independent nature of RX and TX core contexts to prevent lifecycle errors.
Provides a structured approach to capability discovery using standard DOCA query patterns.
Helps isolate root causes by distinguishing between Ethernet queue issues and steering configuration.
Maintains a clean separation between library-specific logic and general DOCA programming patterns.

Usage examples

“My RX queue is up but no packets arrive.”: The agent will guide you to verify steering rules in the DOCA Flow library and check runtime preconditions like device access and port state.
“Which RX type fits my data shape for line-rate ingress?”: The agent will explain the RX-type taxonomy and help you select between regular, cyclic, or managed-mempool types based on your buffer requirements.
“How do I send a packet through doca_eth_txq?”: The agent will provide the workflow for allocating a doca_buf, attaching the payload, and submitting a send-task.
“Is L3 checksum offload available on my device?”: The agent will show you how to use the capability-query rule against your doca_devinfo to confirm hardware support.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/nvidia/doca-eth/download
Unzip it into the cross-client skills folder of your project:
```
mkdir -p .agents/skills && unzip doca-eth.zip -d .agents/skills
```

Documentation by NVIDIA

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 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 the tasks companion 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 route the agent to the public C ABI as the authoritative surface that any wrapper will eventually call.

When to load this skill

Load this skill when the user is doing hands-on DOCA Ethernet work, in any language. Concretely:

Initializing a doca_eth_rxq on a doca_dev opened against a physical port, a representor, or an SF — choosing among the regular / cyclic / managed-recv RX types based on data shape before doca_ctx_start().
Initializing a doca_eth_txq on the same or a different doca_dev and posting send-tasks against packet doca_bufs payload buffers.
Reading or setting Ethernet queue properties via doca_eth_rxq_set_* / doca_eth_txq_set_* and querying device capability via doca_eth_rxq_cap_* / doca_eth_txq_cap_* (max burst size, RX-type support, max scatter-gather length, checksum-offload presence).
Confirming the port is up and that traffic is actually steered to the chosen RX queue — either via DOCA Flow rules (the canonical path) or via kernel-side promiscuous mode (the expedient first-run path).
Wiring an Ethernet queue to a higher-level data plane: GPU packet processing via DOCA GPUNetIO, custom user-space forwarding agents, or telemetry mirrors that snap a copy of every packet.
Debugging a DOCA_ERROR_* returned from an Ethernet call (lifecycle vs. permission vs. capability vs. send-queue-full vs. driver-below) and the per-queue progress engine events.
Designing or extending non-C bindings (Rust, Go, Python, …) that wrap the DOCA Ethernet C ABI — for the lifecycle, queue split, RX-type, capability, and permission rules the wrapper must honor.

Do not load this skill for general DOCA orientation, install of DOCA itself, flow-rule programming (use doca-flow/SKILL.md), host ↔ DPU control messaging (use doca-comch/SKILL.md), or RDMA data movement (use doca-rdma/SKILL.md). For DOCA documentation orientation, use doca-public-knowledge-map/SKILL.md.

What this skill provides

This is a thin loader. The body keeps only the orientation needed to pick the right next file. The substantive Ethernet- specific material lives in two companion files:

the capabilities companion — what a DOCA Ethernet queue can express on this version: the RX / TX object split, the RX-type taxonomy (regular / cyclic / managed-recv), the send-task / frame submission surface, the capability-query surface (doca_eth_rxq_cap_* / doca_eth_txq_cap_*), the Ethernet error taxonomy (mapped onto the cross-library DOCA_ERROR_* set), the observability surface (per-queue progress engine events, capability snapshots), and the safety policy that gates the steering / permission / port-state preconditions.
the tasks companion — step-by-step workflows for the six in-scope Ethernet verbs: configure, build, modify, run, test, debug. Plus a Deferred task verbs block that points out-of-scope questions at the right next skill, and a Command appendix of the recurring commands the agent reaches for.

The skill assumes a host or BlueField where DOCA is already installed at the standard location and the user has the privileges their public install profile expects (typically sudo or mlnx-group membership to open a doca_dev against a port). It does not cover installing DOCA — that path goes through doca-setup/SKILL.md.

What this skill deliberately does not ship

This skill is agent guidance, not a samples or templates bundle. To keep the boundary clean, it deliberately does not contain — and pull requests should not add:

Pre-written DOCA Ethernet application source code, in any language. The verified Ethernet source code is the shipped C samples at /opt/mellanox/doca/samples/doca_eth/<name>/. The agent's job is to route the user to those files and prescribe a minimum-diff modification on them via the universal modify-a-sample workflow in doca-programming-guide/SKILL.md, layered with the Ethernet-specific overrides in
modify.
Standalone build manifests (meson.build, CMakeLists.txt, Cargo.toml, …) parked inside the skill. The agent constructs the build manifest in the user's project directory against the user's installed DOCA, where pkg-config --modversion doca-eth is the source of truth.
A samples/, bindings/, or reference/ subtree of any kind. A mock or incomplete artifact in this skill's tree, even one labeled "reference", is misleading: users will read it as buildable.

Loading order

Read this skill first to confirm the user's question is in scope.
For the Ethernet capability matrix, RX-type taxonomy, send surface, capability-query rules, error taxonomy, observability, and safety policy, see the capabilities companion.
For step-by-step workflows — configure, build, modify, run, test, debug — see the tasks companion.

Both companion files cross-link to each other, doca-version/SKILL.md for the canonical version-handling rules, doca-flow/SKILL.md for the steering side that the RX queue depends on, and doca-public-knowledge-map/SKILL.md whenever the right answer is "look it up in the public docs or the installed package layout" rather than "Ethernet-specific guidance".

doca-public-knowledge-map/SKILL.md — the routing table for every public DOCA documentation source and the on-disk layout of an installed DOCA package. The Ethernet URL slug is DOCA-Ethernet.
doca-setup/SKILL.md — env preparation, install verification, port-state checks (devlink dev show, ip link), permission and group-membership requirements for opening a doca_dev. This skill assumes its preconditions are satisfied.
doca-version/SKILL.md — canonical DOCA version-handling rules. This skill's ## Version compatibility cross-links the four-way match rule and adds only the Ethernet-specific overlay (RX-type availability windows, checksum-offload device-conditional support).
doca-structured-tools-contract/SKILL.md — the bundle's structured-tools precedence rule (detect / prefer / fall back / report). The Command appendix in the tasks companion honors this contract.
doca-programming-guide/SKILL.md — general DOCA programming patterns shared by every library: the canonical pkg-config + meson build pattern, the universal modify-a-shipped-sample first-app workflow, the universal lifecycle, the cross-library DOCA_ERROR_* taxonomy, and the program-side debug order. This skill layers Ethernet specifics on top.
doca-flow/SKILL.md — the steering surface that decides which packets land on which doca_eth_rxq. DOCA Ethernet does not program steering itself; an empty RX queue almost always means a missing or wrong Flow rule, not an Ethernet bug.
doca-debug/SKILL.md — the cross-cutting debug ladder (install / version / build / link / runtime / program / driver). Ethernet-specific debug (RX-type mismatches, send-queue-full retries, steering-empty-queue symptoms) overlays on top of that ladder.

Files

ATTRIBUTION.mdAdded by AutoGineer882 B
BENCHMARK.md9.7 KiB
CAPABILITIES.md20.2 KiB
LICENSELicence file added by AutoGineer11.2 KiB
SKILL.md13.8 KiB
SKILLCARD.yaml2.6 KiB
TASKS.md24.2 KiB
evals/evals.json3.1 KiB
skill-card.md5.1 KiB
skill.oms.sig5.1 KiB

CAPABILITIES.md

DOCA Ethernet capabilities, version overlay, errors, observability, safety

Where to start: Pick the H2 anchor that matches your question (queue objects / RX-type taxonomy / TX submission / capabilities / errors / safety) and read that section end-to-end. The tables in each section are the load-bearing content; the prose around them is interpretation.

Read this file when the loader sent you here from SKILL.md. For the how of executing each pattern (the verbs configure / build / modify / run / test / debug), jump to TASKS.md. For the canonical DOCA version-handling rules that this skill layers an Ethernet overlay on top of, see doca-version/SKILL.md. For the steering side (which Flow rule sends which packet to which RX queue), defer to doca-flow/SKILL.md; DOCA Ethernet is the queue surface, not the steering surface.

Pattern overview

Every DOCA Ethernet question this skill teaches resolves into one of FIVE patterns. The patterns are CLASSES — they apply across every Ethernet release and every host / BlueField pair.

Pattern	When it applies (class shape)	Where the substance lives
1. Pick the queue side	Decide whether the user needs RX, TX, or both; instantiate as separate `doca_eth_rxq` and `doca_eth_txq` contexts (each with its own DOCA Core lifecycle)	`## Capabilities and modes` RX / TX object table + TASKS.md ## configure step 2
2. Pick the RX type	Choose one of the four real `enum doca_eth_rxq_type` values — `DOCA_ETH_RXQ_TYPE_CYCLIC`, `_MANAGED_MEMPOOL`, `_REGULAR`, `_SHARED_MEMPOOL` — based on per-packet vs ring-buffer vs library-managed vs library-shared-pool data shape; cap-query before assuming the chosen type works on this device	`## Capabilities and modes` RX-type taxonomy + TASKS.md ## configure step 3
3. Discover capabilities	Query `doca_eth_rxq_cap_` / `doca_eth_txq_cap_` for max burst size, supported RX types, scatter-gather depth, and checksum-offload presence — against the active `doca_devinfo`	`## Capabilities and modes` capability-query rule + TASKS.md ## configure step 3
4. Honor preconditions	Verify the device opens under the user's access (sudo or `mlnx` group), the port reports linkup, and traffic is steered to the RX queue (via DOCA Flow or kernel promiscuous mode)	`## Safety policy` precondition matrix + TASKS.md ## configure step 1
5. Diagnose an Ethernet error	Map symptom (`DOCA_ERROR_BAD_STATE`, `_AGAIN`, `_NOT_PERMITTED`, `_NOT_SUPPORTED`, `_NO_MEMORY`, `_DRIVER`) to root cause without leaving the Ethernet layer prematurely	`## Error taxonomy` + TASKS.md ## debug

Two cross-cutting rules that apply to every pattern above:

RX and TX are independent contexts. A doca_eth_rxq and a doca_eth_txq are two separate DOCA Core contexts with two separate lifecycles; they share nothing except the underlying doca_dev. Conflating them — sizing TX queues from RX cap queries, or expecting one doca_ctx_start() to cover both — is the most common first-app design error and the cleanest place to fail fast.
An RX queue without steering is silent, not broken. Bringing a doca_eth_rxq to STARTED state does not by itself cause packets to arrive. The user must either program a DOCA Flow rule that steers matching packets to this queue, or enable kernel-side promiscuous mode on the underlying interface so every packet on the wire reaches the queue. The agent must surface this before any code change when the user reports "no packets arriving".

Capabilities and modes

The two orthogonal selection axes for any DOCA Ethernet design are queue side (RX vs TX) and, for RX, RX type (regular vs cyclic vs managed-recv vs shared-mempool). Choose both before writing any code, then drill into the relevant capability-query.

Queue object split — RX vs TX. Each is its own DOCA Core context.

Object	What it does	Key calls	Sizing inputs
`doca_eth_rxq`	Receive queue on a physical port, representor, or SF; surfaces inbound packets to user code as DOCA tasks or library-managed buffers depending on RX type	`doca_eth_rxq_create`, `_set_type`, `_set_max_burst_size`, `_set_cqe_format`, `_set_shared_mempool`, `doca_ctx_start`	`doca_eth_rxq_cap_get_max_burst_size(devinfo)`; `doca_eth_rxq_cap_is_type_supported(devinfo, type)`; `doca_eth_rxq_cap_is_cqe_format_supported(devinfo, format)`
`doca_eth_txq`	Transmit queue on the same device class; user submits send-tasks (`doca_eth_txq_task_send` for regular packets, `doca_eth_txq_task_lso_send` for LSO) that carry a packet `doca_buf` (`doca_eth_txq_task_send_set_pkt`) or a payload `doca_buf` + headers `struct doca_gather_list` (`doca_eth_txq_task_lso_send_set_pkt_payload` + `_set_headers`; headers are a gather list, not a `doca_buf`) plus the target queue	`doca_eth_txq_create`, `_set_max_send_buf_list_len`, `_set_max_inline_data_size`, `doca_ctx_start`, send-task allocator + submit	`doca_eth_txq_cap_get_max_send_buf_list_len(devinfo)`; `doca_eth_txq_cap_is_l3_chksum_offload_supported(devinfo)`; `doca_eth_txq_cap_get_max_inline_data_size(devinfo)`
Packet payload	The shipped public surface carries packet bytes as a plain `doca_buf ` (LSO headers as a `struct doca_gather_list `) attached to the send-task via the setters above. There is no `doca_eth_frame` struct family in the public header — do not invent one.	`doca_buf_*` allocators + `doca_eth_txq_task_send_set_pkt` (or `_lso_send_set_pkt_payload` + `_set_headers`)	— (sized by the user's MTU and scatter-gather plan)

RX-type taxonomy. Picking the right type is data-shape-dependent; the cap query is the only authority on what the device supports.

RX type (`enum doca_eth_rxq_type`)	What the user sees	Right shape for	Wrong shape for
`DOCA_ETH_RXQ_TYPE_REGULAR` (the default)	One DOCA task per inbound packet; the user posts a recv buffer per packet via the recv-task allocator	Small fan-out, per-packet user logic, debug-friendly first-run path	Line-rate ingress — per-packet task overhead dominates
`DOCA_ETH_RXQ_TYPE_CYCLIC`	A ring of fixed-size buffers preallocated by the user; the library writes packets in order; the user reads the ring head	Max packet-rate ingress with fixed-MTU traffic; GPU packet-processing on a pre-pinned buffer	Variable-sized packets bigger than the ring slot, or workloads that need per-packet completion semantics
`DOCA_ETH_RXQ_TYPE_MANAGED_MEMPOOL`	The library allocates and reclaims the receive buffers from an internal mempool; the user just consumes completion events	Hands-off line-rate ingress with no preallocated buffer plan; lowest-friction first app	Workloads that need to control buffer placement (GPU pinned memory, NUMA-affinity, registered memory regions for downstream RDMA)
`DOCA_ETH_RXQ_TYPE_SHARED_MEMPOOL`	The library manages a shared memory pool across multiple RX queues / consumers; receive buffers are drawn from the shared pool.	Multi-queue ingress where memory must be shared across RX queues; the appropriate type when several `doca_eth_rxq` instances on the same device want a unified buffer plan. See `doca_eth_rxq_shared_mempool.h` for the shared-mempool surface.	Single-queue ingress (use `_REGULAR` / `_CYCLIC` / `_MANAGED_MEMPOOL` instead)

CQE format selection. The public API exposes the DOCA_ETH_RXQ_CQE_FORMAT_* constant family (regular and compressed variants) in doca_eth_rxq.h. Query support with doca_eth_rxq_cap_is_cqe_format_supported(devinfo, format) and select the format with doca_eth_rxq_set_cqe_format(eth_rxq, format). The agent must not assume a compressed format is available; the capability query is the only authority.

TX submission shape. A doca_eth_txq submission is always one send-task = one packet doca_buf. The doca_buf wraps the packet payload; the send-task carries it onto the queue. The agent should not invent scatter-gather "list" submission beyond what doca_eth_txq_cap_get_max_send_buf_list_len(devinfo) reports — that cap is the only authority on whether and how deep scatter-gather works on the active device.

Capability discovery — the only rule. Before sizing any queue, picking any RX type, or assuming any offload feature, call the matching doca_eth_<side>_cap_* query against the active doca_devinfo:

Capability	Query	Why the agent must ask
Maximum RX burst size	`doca_eth_rxq_cap_get_max_burst_size(devinfo)`	Device-dependent; oversizing returns `DOCA_ERROR_NOT_SUPPORTED` at `doca_ctx_start()`
RX type supported on this device	`doca_eth_rxq_cap_is_type_supported(devinfo, type)`	Not every device supports every RX type; agent must not silently assume managed-recv or cyclic is present
CQE format supported on this RX queue	`doca_eth_rxq_cap_is_cqe_format_supported(devinfo, format)`	Not every device supports every CQE format; agent must not assume compressed formats are present
Maximum send scatter-gather list length	`doca_eth_txq_cap_get_max_send_buf_list_len(devinfo)`	Used to size the scatter-gather plan; assuming "1" works everywhere but "N" does not
Maximum TX inline data size	`doca_eth_txq_cap_get_max_inline_data_size(devinfo)`	Device-dependent; setting above the cap fails at start
L3 checksum offload presence	`doca_eth_txq_cap_is_l3_chksum_offload_supported(devinfo)`	Offload is device-conditional; requesting it on a device that does not advertise it fails at start

Configuration shape. Mandatory configurations before doca_ctx_start(): an RX queue needs its type set via doca_eth_rxq_set_type() plus a burst size at or below the cap, and either a recv-task allocator (regular type), the appropriate buffer wiring per the chosen type (cyclic or managed-mempool), or doca_eth_rxq_set_shared_mempool() for shared-mempool type; a TX queue needs its send-task configuration plus, if used, a scatter-gather length at or below the cap. Optional configurations (checksum offload, advanced flow-tag fields, RSS, CQE format, TX max inline data size) gate on the matching _cap_* query and use the matching _set_* setter.

Version compatibility

For the canonical DOCA version-detection chain, the four-way match rule, NGC container semantics, and the headers-win-over-docs rule, see doca-version/SKILL.md. The body lives there; this skill does not duplicate it.

The Ethernet-specific overlay is:

RX-type availability and doca_eth_*_cap_* are the runtime authority, not the public docs. Per the cross-cutting cap-query rule in doca-version CAPABILITIES.md ## Observability (doca-version/CAPABILITIES.md#observability), the agent must call doca_eth_rxq_cap_is_type_supported(devinfo, type) before promising the user that managed-recv or cyclic is on this device + DOCA version; checksum offload likewise gates on doca_eth_txq_cap_is_l3_chksum_offload_supported(devinfo). Quoting an RX-type or offload from memory is the canonical hallucination failure mode for this library.
doca-eth.pc and doca-common.pc must both match doca_caps --version at the four-way-match check (per doca-version CAPABILITIES.md ## Version compatibility (doca-version/CAPABILITIES.md#version-compatibility)). Use pkg-config --modversion doca-eth as the build-time anchor; disagreement with doca_caps --version is a partial-install hazard and must be routed to doca-version TASKS.md ## debug (doca-version/TASKS.md#debug) layer 2 before any Ethernet-layer diagnosis.
DOCA 3.5 added shared-mempool RXQ, CQE format selection, and TX max inline data size APIs; earlier releases do not provide them. The agent must call doca_eth_rxq_cap_is_cqe_format_supported(devinfo, format) with the desired format from the DOCA_ETH_RXQ_CQE_FORMAT_* family before promising a CQE format, doca_eth_rxq_cap_is_type_supported(devinfo, type) with the shared-mempool RXQ type from the DOCA_ETH_RXQ_TYPE_* family before promising shared-mempool RXQ, and doca_eth_txq_cap_get_max_inline_data_size(devinfo, &max_inline_data_size) before promising TX inline data size. See the public DOCA Ethernet header for the constant families. Quoting these from memory is the same hallucination failure mode.

Error taxonomy

Ethernet-specific overlays on the cross-library DOCA_ERROR_* taxonomy. The cross-library taxonomy itself lives in doca-programming-guide CAPABILITIES.md ## Error taxonomy (doca-programming-guide/CAPABILITIES.md#error-taxonomy); the rows below are the Ethernet surface meaning that the agent must disambiguate before falling back to the cross-library response.

Error	DOCA Ethernet context where it shows up	Ethernet-specific cause
`DOCA_ERROR_BAD_STATE`	Any call after `doca_ctx_stop()` or before `doca_ctx_start()`; submitting a send-task on a `doca_eth_txq` that is not STARTED; posting a recv buffer on a `doca_eth_rxq` of the wrong type	Lifecycle violation. Walk the queue's own state against the universal lifecycle in `doca-programming-guide CAPABILITIES.md ## Capabilities and modes` (`doca-programming-guide/CAPABILITIES.md#capabilities-and-modes`); the most common case is treating RX and TX as one context.
`DOCA_ERROR_NOT_SUPPORTED`	`doca_eth_rxq_set_type` with a type the device does not advertise; `doca_eth_txq_set_*` for L3 checksum offload on a device that does not support it; oversized burst	Re-run the matching `doca_eth_<side>_cap_*` query against the active `doca_devinfo`; if the cap query says false, that is the answer — the user's device or DOCA version does not support the request.
`DOCA_ERROR_NOT_PERMITTED`	`doca_dev_open` for a port or representor that the user has no access to; queue create after a permission downgrade	The device was not opened with the required access. Confirm sudo or `mlnx`-group membership per `## Safety policy`; do not modify the program.
`DOCA_ERROR_AGAIN`	`doca_task_submit` for a TX send-task when the queue is full	The send queue is full. This is not a hardware error; drain completions via `doca_pe_progress()` before re-submitting. Same as the cross-library "would-block, retry after progress" pattern.
`DOCA_ERROR_NO_MEMORY`	RX recv-task allocator or managed-recv internal buffer pool; large TX scatter-gather attempts	The descriptor or buffer pool is exhausted. The fix is to raise queue / pool sizing (within the cap) or to drain inbound completions faster, not to retry the allocation in a tight loop.
`DOCA_ERROR_DRIVER`	Any submit / completion call	The layer below DOCA reported failure. Capture state (`dmesg

The agent's rule: never recommend a retry loop on DOCA_ERROR_* without first identifying which of the rows above is the cause. _AGAIN is the only one that wants a retry (after doca_pe_progress()); the others want investigation, not retry. And "no packets arriving" is never a DOCA_ERROR_* — it is the steering side; route to doca-flow/SKILL.md or to the promiscuous-mode workaround in doca-setup/SKILL.md, not to the Ethernet error taxonomy.

Observability

The DOCA Core progress engine (PE) is the single source of observability for each Ethernet queue: every recv-task or send-task completion (success or failure) arrives as an event on the PE that the queue's context is registered against. DOCA Ethernet does not maintain per-queue counters of its own; its observability surface is event-driven, not poll-driven, with two add-on signals (capability snapshot + port-state).

Three primary signals the agent should reach for:

Per-queue task completion events on the PE. Each RX queue produces a completion event on every received packet (regular type) or per ring-buffer slot consumed (cyclic / managed-recv, shape-specific). Each TX queue produces a completion event on every send-task that finishes (success or error). Absence of completions on a started queue is always either a missing doca_pe_progress() call or — for RX — a steering / port- state precondition gap. Route to ## Safety policy first.
Capability snapshot at configure time. The output of every doca_eth_rxq_cap_* / doca_eth_txq_cap_* query is a snapshot of what the library said was possible before any task was submitted. Save it as the baseline; if a task later returns DOCA_ERROR_NOT_SUPPORTED the diff against this snapshot is the bug.
Port and link state from the env side. devlink dev show, ip -j link show <dev>, and ethtool <dev> together tell the agent whether the port the user opened is up at the driver layer at all. A linkdown port is a silent ingress queue; the agent must check it before any Ethernet-layer diagnosis. Defer to doca-setup CAPABILITIES.md ## Observability (doca-setup/CAPABILITIES.md#observability) for the env-side observability primitives.

For the cross-library debug-time observability (DOCA_LOG_LEVEL=trace, --sdk-log-level, the trace build flavor) see doca-debug CAPABILITIES.md ## Observability (doca-debug/CAPABILITIES.md#observability).

Safety policy

Overlay on the bundle-wide hardware-safety meta-policy. The rules below are this skill's per-artifact overlay on the cross-cutting rules in doca-hardware-safety CAPABILITIES.md ## Safety policy (doca-hardware-safety/CAPABILITIES.md#safety-policy) (specifically ### Per-artifact overlay pattern (doca-hardware-safety/CAPABILITIES.md#per-artifact-overlay-pattern)). When the two layers disagree, the stricter wins; when either layer says STOP, the agent stops.

DOCA Ethernet's safety surface is access, port state, and steering. The single most common first-app failure is "my queue is up but no packets arrive" — and the agent's job is to verify the three preconditions before any code change, not after the first DOCA_ERROR_* (because there often is no error; an empty RX queue is silent).

The precondition matrix the agent must walk for any new DOCA Ethernet setup:

Precondition	What must be true before `doca_ctx_start()`	How the agent verifies	Where to fix
Device access	The `doca_dev` was opened against a port / representor / SF the user has permission to use (typically requires sudo or `mlnx`-group membership)	`id` for group membership; the open call failing with `DOCA_ERROR_NOT_PERMITTED` is the runtime symptom	`doca-setup/SKILL.md` for the env-side; do not modify the program
Port up	The underlying port reports linkup at the driver layer (`devlink dev show` reports `state: PORT_ACTIVE`; `ip link` shows the device `UP,LOWER_UP`)	`devlink dev show`; `ip -j link show <dev>`; `ethtool <dev>`	`doca-setup CAPABILITIES.md ## Capabilities and modes` (`doca-setup/CAPABILITIES.md#capabilities-and-modes`) port-bring-up; do not modify the program
Traffic actually reaches the RX queue	Either a DOCA Flow rule steers matching packets to this `doca_eth_rxq`, OR the underlying interface is in promiscuous mode at the kernel layer so every packet on the wire reaches the queue	Inspect the flow rule programmed for this queue (or the absence of one); `ip link show <dev>` reports the `PROMISC` flag if promiscuous mode is on	`doca-flow/SKILL.md` for the steering side (canonical); `doca-setup/SKILL.md` for the promiscuous-mode workaround (expedient first-run path only)

RX and TX queues are independent — do not share lifecycles. A doca_eth_rxq and a doca_eth_txq each have their own doca_ctx_* lifecycle. Treating them as one context (one start, one stop) is caught by the runtime as DOCA_ERROR_BAD_STATE on whichever side was skipped; the user-visible symptom does not name the conflation.

Smoke before scale-up. Before driving traffic at line rate, the agent must walk the user through a single-packet smoke (one TX submission → loopback or external echo → one RX completion). A failure here narrows cleanly: TX-side, network, or RX-side. A failure at scale-up without the smoke pass is a much harder bisection.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

The author says: 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.

Security

What our scanner noticed· Medium risk

Large base64-encoded blobs

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

NVIDIA

Publisher

NVIDIA (Official)

Source

NVIDIA/skills · skills/doca-eth · commit fce3cca

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE-APACHE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by NVIDIA or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download doca-eth.zip