doca-eth

Files (8)

• BENCHMARK.md
• CAPABILITIES.md
• SKILL.md
• SKILLCARD.yaml
• TASKS.md
• evals.json · evals/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# 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

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills