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.
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 inmodify.
- 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".
Related skills
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.
1---2license: Apache-2.03name: doca-eth4description: >5 Use this skill for hands-on DOCA Ethernet packet-queue work on a6 BlueField DPU or ConnectX NIC — bringing up a `doca_eth_rxq` or7 `doca_eth_txq` on a port / representor / SF, picking among the four8 `enum doca_eth_rxq_type` values (`_REGULAR` / `_CYCLIC` /9 `_MANAGED_MEMPOOL` / `_SHARED_MEMPOOL`), sizing burst or10 scatter-gather length against the `_cap_*` queries, submitting11 `doca_eth_txq_task_send` / `_lso_send` (carrying packet `doca_buf`s —12 no `doca_eth_frame` struct exists), or debugging DOCA_ERROR_* from an13 Ethernet call. `doca_eth_rxq` and `doca_eth_txq` are two Core14 contexts; one `doca_ctx_start()` does not cover both. Trigger on15 implicit phrasings: "my RX queue is up but no packets arrive",16 "send-task returns AGAIN at line rate", "which queue type for17 fixed-MTU ingress", "device open fails without sudo", or "is L318 checksum offload available here". Refuse and route elsewhere for19 installing DOCA, flow-rule / steering programming, host↔DPU control20 messaging, or RDMA data movement.21metadata:22 source: https://skillmd.com/skills/nvidia/doca-eth23 author: NVIDIA <doca-feedback@nvidia.com>24 kind: library25 doca_version: "3.5"26 tags:27 - doca28 - ethernet29 - queues30compatibility: >31 Requires DOCA SDK installed at /opt/mellanox/doca on Linux32 (Ubuntu 22.04/24.04 or RHEL/SLES) with a BlueField DPU or33 ConnectX NIC attached. Reads the user's local install via34 `pkg-config doca-eth` and inspects35 /opt/mellanox/doca/{lib,include,samples,applications}.36 The validation steps require a live DOCA install.37---3839# DOCA Ethernet4041## Examples4243- **"My RX queue is up but no packets arrive."** — RX and TX are two44 Core contexts; one `doca_ctx_start()` does not cover both.45- **"Send-task returns AGAIN at line rate."** — size burst against46 the `_cap_*` queries before changing queue type.4748## Instructions4950Follow Loading order below. Open the tasks companion for configure /51build / run. Open the capabilities companion for the RX-type taxonomy52and send surface. Do not open every companion file.5354**Where to start:** This skill assumes DOCA is already installed and55the user is doing **hands-on packet-queue work** on a host or56BlueField with DOCA. Open the tasks companion if the user wants57to *do* something (configure / build / modify / run / test /58debug); open the capabilities companion when the question59is *what can a DOCA Ethernet queue express* on this version. If60the user has not installed DOCA yet, route to61`doca-setup/SKILL.md` first. **RX and TX are62independent Core contexts.** A `doca_eth_rxq` and a `doca_eth_txq`63each get their own `doca_ctx_create` / `_start` / `_stop` /64`_destroy`; one `doca_ctx_start()` does **not** start both sides.65Do not walk a single lifecycle for "the queue pair". If the user is66asking *"how do I get packets to land on my RX queue at all"*, the67answer lives in `doca-flow/SKILL.md` — DOCA68Ethernet is the *queue* surface; DOCA Flow is the *steering*69surface, and they are independent libraries.7071## Example questions this skill answers well7273The CLASSES of DOCA Ethernet questions this skill is built to74answer, each with one worked example. The agent should treat the75*class* as the load-bearing piece — the worked example is a single76instance.7778- **"How do I bring up an RX and TX queue on a representor or79 physical port?"** — worked example: *"set up a `doca_eth_rxq`80 plus a `doca_eth_txq` on a single BlueField representor for81 first-run testing"*. Answered by two independent Core82 contexts (each with its own start) in83 ## configure +84 ## Capabilities and modes85 RX / TX object table.86- **"Which RX type fits my data shape — regular, cyclic, or87 managed-recv?"** — worked example: *"line-rate ingress with88 fixed-size frames into a pre-allocated buffer ring"*. Answered89 by the RX-type taxonomy in90 ## Capabilities and modes91 + the capability-query rule (`doca_eth_rxq_cap_is_type_supported`92 against a `doca_devinfo`) in93 ## configure.94- **"How do I send a packet from user code through `doca_eth_txq`?"**95 — worked example: *"allocate a packet `doca_buf`, attach the96 payload, submit one send-task, wait for the completion event"*.97 Answered by the TX submission shape in98 ## Capabilities and modes99 + the property-set workflow in100 ## modify.101- **"My queue is up but no packets arrive — why?"** — worked102 example: *"`doca_eth_rxq` started cleanly but the recv callback103 never fires"*. Answered by the steering-dependency rule in104 ## Safety policy105 + the env-prep checklist in106 ## configure step 1, which107 routes the steering side to108 `doca-flow/SKILL.md` and the109 promiscuous-mode side to110 `doca-setup/SKILL.md`.111- **"Is this Ethernet capability available on my device + my112 installed DOCA?"** — worked example: *"does this device113 advertise L3 checksum offload"*. Answered by the114 capability-query rule (`doca_eth_txq_cap_is_l3_chksum_offload_supported`115 against a `doca_devinfo`) in116 ## Capabilities and modes117 + the version-and-device overlay in118 ## Version compatibility.119- **"What does this `DOCA_ERROR_*` from an Ethernet call mean and120 which layer caused it?"** — worked example: *"`DOCA_ERROR_AGAIN`121 on `doca_task_submit` for an `eth_txq` send-task at high rate"*.122 Answered by the Ethernet overlay on the cross-library taxonomy123 in124 ## Error taxonomy125 + the layered ladder in126 ## debug that escalates to127 `doca-debug/SKILL.md`.128129**Picking the root-cause layer when several could explain a symptom.**130Walk the layers bottom-up (install → version → build → link → runtime →131program → driver) with the read-only check each layer names in `TASKS.md`132`## debug`. The lowest layer whose check fails is the root cause: fix it,133change one variable at a time, and re-run the same check before moving up.134For a silent RX queue, rule out the three runtime preconditions (device135access, port up, traffic steered to the queue) before any program or driver136cause.137138## Audience139140This skill serves **external developers building applications that141consume the DOCA Ethernet library** — i.e., users whose code calls142`doca_eth_rxq_*` / `doca_eth_txq_*` (directly in C/C++, or through143FFI/bindings from another language) to do line-rate packet I/O on144physical ports, representors, or SFs of a BlueField or ConnectX145device. It is *not* for NVIDIA developers contributing to DOCA146Ethernet itself.147148**Language scope.** DOCA Ethernet ships as a C library with149`pkg-config` module name `doca-eth`. The shipped samples are150written in C. C and C++ consumers are the canonical case; the151worked examples in the tasks companion assume that path. Other-language152consumers (Rust, Go, Python, …) consume the same `*.so` through153FFI or language-specific bindings; the skill's contribution in154that case is to keep the queue-object split, lifecycle,155capability-discovery, permission, RX-type taxonomy, and156error-taxonomy guidance language-neutral, and to route the agent157to the public C ABI as the authoritative surface that any wrapper158will eventually call.159160## When to load this skill161162Load this skill when the user is doing hands-on DOCA Ethernet163work, in any language. Concretely:164165- Initializing a `doca_eth_rxq` on a `doca_dev` opened against a166 physical port, a representor, or an SF — choosing among the167 regular / cyclic / managed-recv RX types based on data shape168 before `doca_ctx_start()`.169- Initializing a `doca_eth_txq` on the same or a different170 `doca_dev` and posting send-tasks against packet `doca_buf`s171 payload buffers.172- Reading or setting Ethernet queue properties via173 `doca_eth_rxq_set_*` / `doca_eth_txq_set_*` and querying device174 capability via `doca_eth_rxq_cap_*` / `doca_eth_txq_cap_*`175 (max burst size, RX-type support, max scatter-gather length,176 checksum-offload presence).177- Confirming the port is up and that traffic is actually steered178 to the chosen RX queue — either via DOCA Flow rules (the179 canonical path) or via kernel-side promiscuous mode (the180 expedient first-run path).181- Wiring an Ethernet queue to a higher-level data plane: GPU182 packet processing via DOCA GPUNetIO, custom user-space183 forwarding agents, or telemetry mirrors that snap a copy of184 every packet.185- Debugging a `DOCA_ERROR_*` returned from an Ethernet call186 (lifecycle vs. permission vs. capability vs. send-queue-full187 vs. driver-below) and the per-queue progress engine events.188- Designing or extending non-C bindings (Rust, Go, Python, …)189 that wrap the DOCA Ethernet C ABI — for the lifecycle, queue190 split, RX-type, capability, and permission rules the wrapper191 must honor.192193Do **not** load this skill for general DOCA orientation, install194of DOCA itself, flow-rule programming (use195`doca-flow/SKILL.md`), host ↔ DPU control196messaging (use `doca-comch/SKILL.md`), or197RDMA data movement (use `doca-rdma/SKILL.md`).198For DOCA documentation orientation, use199`doca-public-knowledge-map/SKILL.md`.200201## What this skill provides202203This is a **thin loader**. The body keeps only the orientation204needed to pick the right next file. The substantive Ethernet-205specific material lives in two companion files:206207- the capabilities companion — what a DOCA Ethernet queue can express on208 this version: the RX / TX object split, the RX-type taxonomy209 (regular / cyclic / managed-recv), the send-task / frame210 submission surface, the capability-query surface211 (`doca_eth_rxq_cap_*` / `doca_eth_txq_cap_*`), the Ethernet212 error taxonomy (mapped onto the cross-library `DOCA_ERROR_*`213 set), the observability surface (per-queue progress engine214 events, capability snapshots), and the safety policy that215 gates the steering / permission / port-state preconditions.216- the tasks companion — step-by-step workflows for the six in-scope217 Ethernet verbs: `configure`, `build`, `modify`, `run`,218 `test`, `debug`. Plus a `Deferred task verbs` block that219 points out-of-scope questions at the right next skill, and a220 `Command appendix` of the recurring commands the agent221 reaches for.222223The skill assumes a host or BlueField where DOCA is already224installed at the standard location and the user has the225privileges their public install profile expects (typically sudo226or `mlnx`-group membership to open a `doca_dev` against a port).227It does not cover installing DOCA — that path goes through228`doca-setup/SKILL.md`.229230## What this skill deliberately does not ship231232This skill is **agent guidance**, not a samples or templates233bundle. To keep the boundary clean, it deliberately does not234contain — and pull requests should not add:235236- **Pre-written DOCA Ethernet application source code, in any237 language.** The verified Ethernet source code is the shipped C238 samples at `/opt/mellanox/doca/samples/doca_eth/<name>/`. The239 agent's job is to route the user to those files and prescribe240 a minimum-diff modification on them via the universal241 modify-a-sample workflow in242 `doca-programming-guide/SKILL.md`,243 layered with the Ethernet-specific overrides in244 ## modify.245- **Standalone build manifests** (`meson.build`,246 `CMakeLists.txt`, `Cargo.toml`, …) parked inside the skill.247 The agent constructs the build manifest *in the user's project248 directory* against the user's installed DOCA, where249 `pkg-config --modversion doca-eth` is the source of truth.250- **A `samples/`, `bindings/`, or `reference/` subtree** of any251 kind. A mock or incomplete artifact in this skill's tree, even252 one labeled "reference", is misleading: users will read it as253 buildable.254255## Loading order2562571. Read this skill first to confirm the user's question is258 in scope.2592. **For the Ethernet capability matrix, RX-type taxonomy, send260 surface, capability-query rules, error taxonomy,261 observability, and safety policy, see262 the capabilities companion.**2633. **For step-by-step workflows — configure, build, modify, run,264 test, debug — see the tasks companion.**265266Both companion files cross-link to each other,267`doca-version/SKILL.md` for the canonical268version-handling rules,269`doca-flow/SKILL.md` for the steering side270that the RX queue depends on, and271`doca-public-knowledge-map/SKILL.md`272whenever the right answer is "look it up in the public docs or273the installed package layout" rather than "Ethernet-specific274guidance".275276## Related skills277278- `doca-public-knowledge-map/SKILL.md` —279 the routing table for every public DOCA documentation source280 and the on-disk layout of an installed DOCA package. The281 Ethernet URL slug is `DOCA-Ethernet`.282- `doca-setup/SKILL.md` — env preparation,283 install verification, port-state checks (`devlink dev show`,284 `ip link`), permission and group-membership requirements for285 opening a `doca_dev`. This skill assumes its preconditions286 are satisfied.287- `doca-version/SKILL.md` — canonical288 DOCA version-handling rules. This skill's `## Version289 compatibility` cross-links the four-way match rule and adds290 only the Ethernet-specific overlay (RX-type availability291 windows, checksum-offload device-conditional support).292- `doca-structured-tools-contract/SKILL.md` —293 the bundle's structured-tools precedence rule (detect / prefer294 / fall back / report). The Command appendix in295 the tasks companion honors this contract.296- `doca-programming-guide/SKILL.md` —297 general DOCA programming patterns shared by every library:298 the canonical `pkg-config` + meson build pattern, the299 universal modify-a-shipped-sample first-app workflow, the300 universal lifecycle, the cross-library `DOCA_ERROR_*`301 taxonomy, and the program-side debug order. This skill layers302 Ethernet specifics on top.303- `doca-flow/SKILL.md` — the steering surface304 that decides which packets land on which `doca_eth_rxq`. DOCA305 Ethernet does *not* program steering itself; an empty RX queue306 almost always means a missing or wrong Flow rule, not an307 Ethernet bug.308- `doca-debug/SKILL.md` — the cross-cutting309 debug ladder (install / version / build / link / runtime /310 program / driver). Ethernet-specific debug (RX-type311 mismatches, send-queue-full retries, steering-empty-queue312 symptoms) overlays on top of that ladder.