Skip to main content
skill CX Codex

doca-dpdk-bridge — Claude Code skill: layer DOCA capabilities onto DPDK

The doca-dpdk-bridge skill adds DOCA Flow and other DOCA features to an existing DPDK application, binding ports and converting buffers between DPDK and DOCA without rewriting the fastpath.

Apache-2.0 ★ 4,106 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add NVIDIA/skills --skill doca-dpdk-bridge -a claude-code
Open on GitHub

What doca-dpdk-bridge does

doca-dpdk-bridge is NVIDIA's C library that maps DPDK ports to DOCA device objects. It lets you program hardware offload rules with DOCA Flow, translate packets between DPDK buffers (rte_mbuf) and DOCA buffers (doca_buf), and query bridge capabilities. The core workflow binds a DPDK port via doca_dpdk_port_probe or doca_dpdk_port_as_dev, validates the install with pkg-config doca-dpdk-bridge, and calls DOCA APIs from the same process.

The skill runs on Linux (Ubuntu 22.04/24.04, RHEL, SLES) with a BlueField DPU or ConnectX NIC and requires DOCA SDK at /opt/mellanox/doca compatible with your DPDK version. Errors like DOCA_ERROR_NOT_FOUND on port registration often signal a version mismatch — the skill teaches you how to read the error and check the compatibility window.

If you are starting a new project with no DPDK code yet, use doca-eth for native DOCA packet I/O instead. For a fresh DOCA or DPDK install, see doca-setup.

What it helps with

  • bind a DPDK port to a DOCA device and make it visible to DOCA functions
  • add DOCA Flow hardware offload rules to a DPDK application without rewriting the fastpath
  • convert packets between DPDK rte_mbuf and DOCA buffers
  • troubleshoot bridge errors such as DOCA_ERROR_NOT_FOUND during port registration
  • verify the library is installed and DPDK version matches the DOCA release

Example prompts for the agent

  • How do I add DOCA Flow to my existing DPDK app without rewriting the data-plane?
  • Show me how to bind a DPDK port to a DOCA object using doca_dpdk_port_probe.
  • Why does pkg-config --exists doca-dpdk-bridge fail when DPDK is already installed?

How to install doca-dpdk-bridge

1Skills CLI (Vercel)

npx skills add NVIDIA/skills --skill doca-dpdk-bridge -a claude-code

2Manually: put the files in place

~/.claude/skills/doca-dpdk-bridge/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/doca-dpdk-bridge/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about doca-dpdk-bridge

How do I install doca-dpdk-bridge in Claude Code?

Run npx skills add NVIDIA/skills --skill doca-dpdk-bridge -a claude-code, then open ~/.claude/skills/doca-dpdk-bridge/SKILL.md for usage reference.

What does doca-dpdk-bridge do?

It bridges DPDK ports to DOCA device objects, enabling DOCA Flow hardware offload and other DOCA APIs from your DPDK application without rewriting the fastpath. Converts buffers between DPDK and DOCA, validates version compatibility.

Do I need to install DPDK separately, or does it come with DOCA?

DPDK is installed separately. The skill reads your local install via pkg-config libdpdk and checks compatibility with the DOCA SDK at /opt/mellanox/doca. Versions must fall within a matched-pair window; mismatches cause errors like DOCA_ERROR_NOT_FOUND.

Source text

SKILL.md · Apache-2.0
---
license: Apache-2.0
name: doca-dpdk-bridge
description: >
  Use this skill when the user has an existing DPDK application and is
  adding DOCA capabilities in-place — most commonly DOCA Flow hardware
  steering — without rewriting the data-plane in DOCA-native form:
  binding a DPDK port id to a `doca_dev` (`doca_dpdk_port_probe` /
  `doca_dpdk_port_as_dev`), converting `rte_mbuf` ↔ `doca_buf`, querying
  `doca_dpdk_cap_is_rep_port_supported`, or debugging `DOCA_ERROR_*`
  from a bridge call. Trigger even without "DOCA DPDK Bridge": "how do I
  add DOCA Flow to my DPDK app", "make a DPDK port visible to DOCA",
  "the bridge loads but every operation returns errors", "pkg-config
  --exists doca-dpdk-bridge fails", or "DOCA_ERROR_NOT_FOUND on port
  registration". Route elsewhere for fresh DOCA-native packet I/O
  (doca-eth), flow-rule programming (doca-flow), DOCA or DPDK install
  (doca-setup), or RDMA data movement (doca-rdma).
metadata:
  author: NVIDIA <[email protected]>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - dpdk
    - bridge
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, plus a separate DPDK install whose version falls within the
  bridge's matched-pair window. Reads the user's local install via
  `pkg-config doca-dpdk-bridge` and `pkg-config libdpdk`, and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}. The validation
  steps require a live DOCA install.
---

# DOCA DPDK Bridge

## Examples

- **"How do I add DOCA Flow to my DPDK app?"** — this is in
  scope. Bind the DPDK port with `doca_dpdk_port_probe`; do not
  rewrite the data-plane as native `doca-eth`.
- **"DOCA_ERROR_NOT_FOUND on port registration."** — check the
  DPDK/DOCA matched-pair window before changing the probe call.

## Instructions

Follow Loading order below. Open the tasks companion for configure /
probe / debug. Open the capabilities companion for port binding
and mbuf conversion. Do not open every companion file.

**Where to start:** This skill assumes DOCA is already installed,
DPDK is already installed, the user has an **existing DPDK
application**, and they want to **add DOCA capabilities to it
in-place** (most commonly DOCA Flow for hardware steering)
without migrating the data-plane to DOCA-native APIs. 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
the bridge can express* on this version. If the user has not
installed DOCA yet, route to
`doca-setup/SKILL.md` first. If the user is
**starting fresh** (no DPDK code yet) and just wants line-rate
packet I/O against DOCA, route to
`doca-eth/SKILL.md` instead — the bridge exists
for the interop case, not the start-fresh case.

**How to use this skill.** Read this file, then search the companion file
for the `## <name>` heading the question needs and read that whole section.
Answer completely from it, quoting only its symbols and commands. Do not
browse docs; use the entry points in `doca-public-knowledge-map`. Give
environment checks as commands for the user's DOCA host. For out-of-scope
requests, name the skill that owns them and stop.

## Example questions this skill answers well

The CLASSES of DOCA DPDK Bridge 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.

- **"I have a DPDK app — how do I add DOCA Flow rules to it
  without rewriting the data-plane?"** — worked example: *"my
  packet-processing app already drives mbufs through `rte_eth_*`
  ports; I want to install DOCA Flow steering rules on those
  ports for HW offload"*. Answered by the bridge-vs-native
  selection rule in
  ## Capabilities and modes
  + the port-handover workflow in
  ## configure step 3.
- **"How do I make a DPDK port visible to DOCA?"** — worked
  example: *"I have a DPDK port id from `rte_eth_dev_*`; how does
  DOCA see it"*. Answered by the DPDK-port-id ↔ `doca_dev`
  mapping (`doca_dpdk_port_probe` / `doca_dpdk_port_as_dev`) in
  ## Capabilities and modes
  bridge-objects table + the binding workflow in
  ## configure step 4.
- **"How do I move packets between DPDK mbufs and DOCA bufs?"** —
  worked example: *"DPDK delivers an `rte_mbuf` to my fastpath; I
  want a DOCA library to operate on the payload"*. Answered by
  the mbuf ↔ DOCA-buf conversion shape in
  ## Capabilities and modes
  + the conversion-step workflow in
  ## modify.
- **"Is the bridge even installed and is its DPDK compatible
  with my DOCA?"** — worked example: *"`pkg-config --exists
  doca-dpdk-bridge` returns failure on a host that has DPDK
  separately installed"*. Answered by the version-coupling rule
  in
  ## Version compatibility
  + the cap-check workflow in
  ## configure step 1.
- **"Should I be using `doca-dpdk-bridge` or `doca-eth`?"** —
  worked example: *"new project; I have not committed to DPDK
  yet"*. Answered by the path-selection table in
  ## Capabilities and modes
  bridge-vs-native row + the deferred-verbs note in
  ## Deferred task verbs.
- **"What does this `DOCA_ERROR_*` from a bridge call mean and
  which layer caused it?"** — worked example: *"`DOCA_ERROR_NOT_FOUND`
  on a port-registration call after the DPDK port came up
  cleanly"*. Answered by the bridge overlay on the cross-library
  taxonomy in
  ## Error taxonomy
  + the layered ladder in
  ## debug that escalates to
  `doca-debug/SKILL.md`.

## Audience

This skill serves **external developers who already maintain a
DPDK-based packet-processing application** — i.e., users whose
data-plane already drives `rte_eth_*` ports and `rte_mbuf`
buffers — and who want to **add DOCA capabilities** (most
commonly hardware steering via DOCA Flow) by linking the bridge
into the same process. It is *not* for users starting a fresh
DOCA-native project (route to `doca-eth/SKILL.md`)
and *not* for users running pure DPDK with no interest in DOCA
(no skill in this bundle applies). It is also not for NVIDIA
developers contributing to DOCA DPDK Bridge itself.

**Language scope.** DOCA DPDK Bridge ships as a C library with
`pkg-config` module name `doca-dpdk-bridge` (the agent must
confirm the spelling against the user's install via
`pkg-config --exists doca-dpdk-bridge`; some DOCA releases use a
slightly different module name and the agent must not guess).
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, …)
typically do not use this bridge — DPDK itself is C-shaped, and
a non-C DPDK app is rare; if the user is in that minority, the
skill's contribution is to keep the port-handover, capability,
permission, and error-taxonomy guidance language-neutral and
route them to the public C ABI as the authoritative surface.

## When to load this skill

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

- The user has an EXISTING DPDK application (their data-plane
  already drives `rte_eth_dev_*` ports and `rte_mbuf` buffers),
  and they want to layer DOCA on top — adding DOCA Flow rules,
  feeding packets into a DOCA accelerator (Compress, AES-GCM, …),
  or wiring a DOCA service into the same process.
- The user needs to bind a DPDK port id to a `doca_dev` (via
  `doca_dpdk_port_probe` / `doca_dpdk_port_as_dev`) so DOCA Core
  / DOCA Flow can operate on the same physical port.
- The user needs to convert between DPDK mbufs and DOCA-bufs at
  the data-plane boundary, and is asking about the conversion
  helpers and their cost.
- The user is debugging a `DOCA_ERROR_*` returned from a bridge
  call (lifecycle vs. permission vs. capability vs. DPDK-port-not-
  registered vs. mbuf-conversion-failed) and the layered DPDK ↔
  DOCA stack underneath.
- The user is hitting cross-version pain: their DPDK install and
  their DOCA install are not the matched pair the bridge expects.
- The user is asking *"native `doca-eth` or `doca-dpdk-bridge`?"*
  and the agent needs the path-selection rule.

Do **not** load this skill for general DOCA orientation, install
of DOCA itself, fresh DOCA-native packet I/O (use
`doca-eth/SKILL.md`), flow-rule programming on
its own (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 bridge-
specific material lives in two companion files:

- the capabilities companion — what the DOCA DPDK Bridge can express on
  this version: the bridge-vs-native selection rule (when to
  use `doca-dpdk-bridge` vs native `doca-eth`), the
  bridge-object surface (DPDK-port-id ↔ `doca_dev` mapping, the
  `doca_dpdk_mempool` mbuf ↔ DOCA-buf conversion), the
  capability-query surface (the single
  `doca_dpdk_cap_is_rep_port_supported`), the bridge error taxonomy
  (mapped onto the cross-library `DOCA_ERROR_*` set), the
  observability surface (DPDK-side counters + DOCA-side PE
  events), and the safety policy that gates the matched-pair
  DPDK ↔ DOCA version coupling, the EAL-must-be-up
  precondition, and DPDK-side privileges.
- the tasks companion — step-by-step workflows for the six in-scope
  bridge 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 AND DPDK are
already installed at the standard locations and the user has the
privileges their public install profile expects (typically sudo
or `mlnx`-group membership for DOCA, plus the DPDK-side
privileges to mount hugepages, bind PCIe ports, and open the
target `rte_eth` device). It does not cover installing DOCA —
that path goes through `doca-setup/SKILL.md`;
it does not cover installing or learning DPDK itself — that
belongs in upstream DPDK documentation reachable via
`doca-public-knowledge-map/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 DPDK Bridge application source code, in any
  language.** The verified bridge source code is the bridge
  usage inside the shipped C DOCA Flow samples at
  `/opt/mellanox/doca/samples/doca_flow/` (e.g. `flow_common.c`,
  which calls `doca_dpdk_port_probe()` / `doca_dpdk_port_as_dev()`),
  plus the canonical reference applications that pair DPDK +
  DOCA Flow (see
  `doca-public-knowledge-map/SKILL.md`
  for the reference-applications index). 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 bridge-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 + DPDK, where
  `pkg-config --modversion doca-dpdk-bridge` and
  `pkg-config --modversion libdpdk` are 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

1. Read this skill first to confirm the user's question is
   in scope (existing DPDK app + wants DOCA on top — not fresh).
2. **For the bridge capability matrix, the bridge-vs-native
   selection rule, port-handover surface, capability-query rules,
   error taxonomy, observability, and safety policy, see
   the capabilities companion.**
3. **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
DOCA version-handling rules,
`doca-eth/SKILL.md` for the start-fresh path that
is the bridge's deliberate alternative,
`doca-flow/SKILL.md` for the steering library
that is the most common reason to use this bridge in the first
place, 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 "bridge-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
  bridge URL slug is `DOCA-DPDK-Bridge`. Reference applications
  that pair DPDK + DOCA Flow (the canonical adopters of this
  bridge) are reachable from the same map's reference-
  applications index.
- `doca-setup/SKILL.md` — env preparation,
  install verification, hugepage mounts (DPDK requirement),
  port-state checks (`devlink dev show`, `ip link`), permission
  and group-membership requirements for opening a `doca_dev`
  AND for binding PCIe ports under DPDK. 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 bridge-specific overlay (DPDK ↔ DOCA matched-pair
  coupling).
- `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
  bridge specifics on top.
- `doca-eth/SKILL.md` — the **alternative path**
  for users starting fresh: pure DOCA-native queue I/O via
  `doca_eth_rxq` / `doca_eth_txq` with no DPDK in the picture.
  The bridge exists *because* migrating an existing DPDK app to
  `doca-eth` is often the wrong tradeoff; for a new project
  with no DPDK lock-in, `doca-eth` is the right choice.
- `doca-flow/SKILL.md` — the steering library
  that is the most common reason a DPDK app reaches for this
  bridge. The bridge binds a DPDK port id to a `doca_dev`;
  DOCA Flow programs steering rules onto that `doca_dev`. The two
  libraries are designed to compose.
- `doca-debug/SKILL.md` — the cross-cutting
  debug ladder (install / version / build / link / runtime /
  program / driver). Bridge-specific debug (DPDK ↔ DOCA version
  drift, port-not-registered symptoms, mbuf-conversion failures)
  overlays on top of that ladder.

© NVIDIA · Apache-2.0 · NVIDIA/skills

Similar skills

All skills for Backend and APIs →

From the same set312

The whole set →
doca-upgrade The doca-upgrade skill checks the installed DOCA release, reports the gap to a target, and waits for explicit approval before guiding a change. It also covers rollbacks and interrupted upgrades. CX Codex +1 ★ 4,106repo stars doca-telemetry-utils Runs doca_telemetry_utils on a host with DOCA to track where telemetry metrics disappear between exporter and collector. CX Codex +1 ★ 4,106repo stars doca-socket-relay Bridges host socket traffic onto a BlueField DPU via DOCA Socket Relay without rewriting applications. CX Codex +1 ★ 4,106repo stars nvshmem-troubleshoot-and-report-bugs nvshmem-troubleshoot-and-report-bugs uses launch details and per-PE logs to investigate NVSHMEM runtime failures and draft a bug report. Its diagnosis workflow is read-only. CX Codex +1 ★ 4,106repo stars doca-dts doca-dts is a Claude Code skill that deploys and configures NVIDIA DOCA Telemetry Service on BlueField DPUs, Docker hosts, and DPF clusters. It covers DTS setup across these environments. CX Codex +1 ★ 4,106repo stars doca-structured-tools-contract The doca-structured-tools-contract skill guides an agent through gathering DOCA environment and device details with a structured helper or manual commands. It also covers pre-commit validation and host-versus-DPU checks. CX Codex +1 ★ 4,106repo stars nemo-fabric-build-adapter nemo-fabric-build-adapter is a skill for developing and validating NVIDIA NeMo Fabric adapters against the platform contract, from descriptors and configuration mapping to lifecycle implementation and spec checks. CX Codex +1 ★ 4,106repo stars doca-setup doca-setup is a Claude Code skill that validates and configures NVIDIA DOCA environments for BlueField DPUs, checking library paths, hugepages, and devlink before network workloads run. CX Codex +1 ★ 4,106repo stars

Project sponsors

Companies that keep this analytics open