doca-dpdk-bridge

# 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