About this skill
---
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:
kind: library
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}.
---
# DOCA DPDK Bridge
**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
[`TASKS.md`](TASKS.md) if the user wants to *do* something
(configure / build / modify / run / test / debug); open
[`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what
the bridge can express* on this version. If the user has not
installed DOCA yet, route to
[`doca-setup`](../../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`](../doca-eth/SKILL.md) instead — the bridge exists
for the interop case, not the start-fresh case.
## 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.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
+ the port-handover workflow in
[`TASKS.md ## configure`](TASKS.md#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.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
bridge-objects table + the binding workflow in
[`TASKS.md ## configure`](TASKS.md#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.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
+ the conversion-step workflow in
[`TASKS.md ## modify`](TASKS.md#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
[`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility)
+ the cap-check workflow in
[`TASKS.md ## configure`](TASKS.md#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.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
bridge-vs-native row + the deferred-verbs note in
[`TASKS.md ## Deferred task verbs`](TASKS.md#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
[`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)
+ the layered ladder in
[`TASKS.md ## debug`](TASKS.md#debug) that escalates to
[`doca-debug`](../../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`](../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 `TASKS.md` 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`](../doca-eth/SKILL.md)), flow-rule programming on
its own (use [`doca-flow`](../doca-flow/SKILL.md)), host ↔ DPU
control messaging (use [`doca-comch`](../doca-comch/SKILL.md)),
or RDMA data movement (use [`doca-rdma`](../doca-rdma/SKILL.md)).
For DOCA documentation orientation, use
[`doca-public-knowledge-map`](../../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:
- `CAPABILITIES.md` — 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.
- `TASKS.md` — 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`](../../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`](../../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`](../../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`](../../doca-programming-guide/SKILL.md),
layered with the bridge-specific overrides in
[`TASKS.md ## modify`](TASKS.md#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.md` 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
[CAPABILITIES.md](CAPABILITIES.md).**
3. **For step-by-step workflows — configure, build, modify, run,
test, debug — see [TASKS.md](TASKS.md).**
Both companion files cross-link to each other,
[`doca-version`](../../doca-version/SKILL.md) for the canonical
DOCA version-handling rules,
[`doca-eth`](../doca-eth/SKILL.md) for the start-fresh path that
is the bridge's deliberate alternative,
[`doca-flow`](../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`](../../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`](../../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`](../../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`](../../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`](../../doca-structured-tools-contract/SKILL.md) —
the bundle's structured-tools precedence rule (detect / prefer
/ fall back / report). The Command appendix in
[TASKS.md](TASKS.md) honors this contract.
- [`doca-programming-guide`](../../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`](../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`](../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`](../../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.