/doca-dpdk-bridge

DOCA DPDK Bridge workflows

Where to start: The verbs run configure → build → modify → run → test → debug. Skip ahead only when the user is already past a verb. The ## test verb is an iterative loop (bridge install probe → DPDK preconditions → single-rule smoke → multi- rule run → cross-version), not a one-shot pass — see the eval-loop overlay in ## test below. Every workflow below assumes the interop case: the user has an EXISTING DPDK app and wants to add DOCA libraries on top. If the user is starting fresh (no DPDK code yet), the right answer is not this skill — route to doca-eth and stop here.

Read this file when the loader sent you here from SKILL.md. For the bridge capability surface, bridge-vs-native path selection, port-handover and mbuf-conversion shape, capability-query rules, error taxonomy, observability, and safety policy, see CAPABILITIES.md. For the cross-library DOCA patterns layered under everything below (the universal lifecycle, the cross-library DOCA_ERROR_* taxonomy, the modify-a-shipped-sample workflow), see doca-programming-guide. For the steering library that is the most common reason to use this bridge, see doca-flow. For the matched-pair DPDK ↔ DOCA version coupling that this skill overlays on top of the canonical four-way match, see doca-version.

Each verb below describes the shape of the workflow, not a copy-paste recipe. The agent's job is to walk the user through the steps in order, verifying preconditions before recommending the next call.

configure

Goal: bind an already-running DPDK port id to an opened doca_dev (the bridge's DPDK-port-id ↔ DOCA-device association), with both the DPDK side and the DOCA side aware of their lifecycle responsibilities, before any DOCA library (most commonly DOCA Flow) is asked to operate on that doca_dev.

Steps the agent should walk the user through, in order:

1. Confirm the bridge is installed and the DPDK ↔ DOCA pair is consistent. Per the precondition matrix in CAPABILITIES.md ## Safety policy and the version overlay in CAPABILITIES.md ## Version compatibility, run three pkg-config probes BEFORE writing any code: pkg-config --exists doca-dpdk-bridge (the bridge is present on this DOCA install — if it returns failure, run ls /opt/mellanox/doca/infrastructure/lib/pkgconfig/ | grep -i dpdk before claiming the bridge is missing, because some releases use a slightly different module name); pkg-config --modversion doca-dpdk-bridge agrees with doca_caps --version (no partial-install drift); and pkg-config --modversion libdpdk falls within the compatibility window the bridge expects. Quote all three to the user. Disagreement on the third probe is the canonical "the bridge loads but every operation returns confusing errors" failure mode and must be surfaced before any code change — route to doca-version TASKS.md ## debug layer 2.
2. Confirm this is the interop case, not the migration case. Per the bridge-vs-native path-selection table in CAPABILITIES.md ## Capabilities and modes, the bridge is the right answer only when the user has an EXISTING DPDK app. Ask explicitly: "is there already DPDK code that drives rte_eth_* ports in this codebase?" If the answer is no, stop here and route to doca-eth; the bridge is not the right starting point for fresh DOCA-native packet I/O.
3. Verify the DPDK runtime preconditions on the user's host. Per the precondition matrix in CAPABILITIES.md ## Safety policy, four DPDK-side conditions must already be true before the first bridge call: hugepages are mounted (cat /proc/meminfo | grep Huge reports non-zero free pages); the target PCIe port is bound under DPDK (dpdk-devbind.py --status); rte_eal_init is called by the user's app; and rte_eth_dev_start succeeded on the target port id. The agent does NOT walk DPDK setup itself — defer the env-side fix to upstream DPDK docs reachable via doca-public-knowledge-map and the shared hugepage / mlx5 env preconditions to doca-setup TASKS.md ## configure.
4. Open the DOCA-side device and bind it to the DPDK port. Per the bridge-objects table in CAPABILITIES.md ## Capabilities and modes, open a doca_dev against the same physical device (DOCA-side privileges via sudo or mlnx-group membership), then establish the DPDK-port-id ↔ doca_dev association: if the DPDK port has not been probed yet, call doca_dpdk_port_probe(doca_dev, devargs) to attach it; if the user already has a DPDK port id, call doca_dpdk_port_as_dev(port_id, &dev) to resolve its doca_dev (and doca_dpdk_get_first_port_id() / doca_dpdk_get_port_ids() go from a doca_dev to its DPDK port id(s)). There is no doca_dpdk_port handle — the doca_dev is the DOCA-side identity, and DPDK keeps owning rte_eth_dev start / stop / queue config. The agent must walk doca_dpdk.h under $(pkg-config --variable=includedir doca-common) for the exact signatures on this DOCA release rather than quote them from memory.
5. Run capability discovery against the active doca_devinfo BEFORE requesting representors. Per the capability-query rule in CAPABILITIES.md ## Capabilities and modes, the bridge exposes a single device-capability query: doca_dpdk_cap_is_rep_port_supported() on the active doca_devinfo (call with root privileges) tells you whether the device supports representors for doca_dpdk_port_probe(). There is no doca_dpdk_*_cap_* family — do not invent per-conversion or per-offload cap symbols; doca_dpdk.h itself is the authority on the rest of the surface. Quote the queried value back to the user; do not assume from prior installs.
6. Start the DOCA context that will use the bound device. Pass the doca_dev to the DOCA library that needs it (DOCA Flow is the canonical adopter; see doca-flow TASKS.md ## configure), then call doca_ctx_start() on the DOCA side and progress the PE (doca_pe_progress). The DPDK side stays running throughout — the bridge does not stop the DPDK port. For the canonical DOCA universal lifecycle that underlies the DOCA-side calls, see doca-programming-guide TASKS.md ## configure; this skill adds only the bridge overlay (steps 2-5 above).

build

Goal: compile a bridge-using consumer against the user's installed DOCA AND the user's installed DPDK, with pkg-config as the source of truth for include + link flags on BOTH sides.

The build pattern for any DOCA C/C++ consumer is fully documented in doca-programming-guide TASKS.md ## build. This skill carries only the bridge-specific overlay — note that the bridge is the one library in the bundle where the link line spans TWO independent pkg-config namespaces (DOCA and DPDK), and both must agree with the installed runtime:

For non-C consumers (Rust, Go, Python), DPDK itself is a C-shaped library and a non-C DPDK app is rare; if the user is in that minority, the build-time concern is the same — the FFI wrapper must see both libdoca_dpdk_bridge.so and librte_*.so at the same versions the bridge was built against. The role-split and capability-discovery rules from ## configure still apply per the runtime version rule in doca-version CAPABILITIES.md ## Version compatibility.

modify

Goal: take the closest-fitting shipped DOCA Flow sample that already uses the bridge (or the closest reference application that pairs DPDK + DOCA Flow) and apply a minimum diff to make it match the user's intent, without rewriting from scratch and without inventing a build manifest of your own.

The universal modify-a-shipped-sample workflow is in doca-programming-guide TASKS.md ## modify; this skill provides the bridge-specific slot fill — the slots the agent must elicit from the user before recommending any code-level edit:

The agent's anti-pattern alert: a "clean rewrite" from scratch is almost always slower to first green than a minimum- diff modify on a shipped sample, and removes the user's ability to bisect against a known-good baseline. On this stack the bisection has to cross TWO version surfaces (DOCA AND DPDK), which makes guessing especially expensive — the known-good sample anchors both.

run

Goal: execute the bridge-using program end-to-end and confirm the DPDK port reaches DOCA AND that one trivial DOCA-library operation works on the bound doca_dev, before any production traffic.

Steps the agent should walk the user through:

1. Bring up the DPDK side first. The user's existing DPDK app starts as it normally does — rte_eal_init, port configure, rte_eth_dev_start. Confirm the DPDK port is live BEFORE the DOCA side is started (rte_eth_stats_get on the port or whatever stats path the DPDK app already plumbs reports the port up; rx / tx counters increment under expected traffic). If the DPDK side is not live, the bridge binding may resolve but the first DOCA operation returns DOCA_ERROR_BAD_STATE per the lifecycle row in CAPABILITIES.md ## Error taxonomy.
2. Capture the structured log. Set DOCA_LOG_LEVEL=trace for the first run (see doca-debug CAPABILITIES.md ## Observability); the bridge calls and the underlying DOCA Core lifecycle transitions appear on stderr. For DPDK's own logging surface (rte_log, --log-level), the upstream DPDK docs are the authority — route via doca-public-knowledge-map; the agent must not paraphrase DPDK log knobs.
3. Send one trivial DOCA-library operation through the bridge handle. For the canonical adopter (DOCA Flow): one trivial flow rule that matches a wide pattern (e.g. drop or count all incoming packets on the port) installed on the doca_dev bound to the DPDK port, with verification that the rule is programmed (a Flow-side validate / counter read per doca-flow TASKS.md ## configure). Per the smoke-before-scale-up rule in CAPABILITIES.md ## Safety policy, this single-rule smoke is non-negotiable: a failure here narrows cleanly to DPDK-side, bridge-handover, or DOCA-side; a failure at scale-up without the smoke pass is a much harder bisection across the two version surfaces.
4. Tear down in the right order. Per the lifecycle table in CAPABILITIES.md ## Safety policy, reverse the configure order: stop / destroy the DOCA contexts first, then release the bridge binding, then stop the DPDK port and clean up EAL. Out-of-order teardown surfaces as either DOCA-side DOCA_ERROR_BAD_STATE or DPDK- side errors and masks the next run's first-failure signal.

For the runtime version + LD_LIBRARY_PATH cross-checks that underlie "the program built but does nothing" (especially the DPDK side, which is the under-tested seam on this skill), see doca-version TASKS.md ## run.

test

Goal: prove a bridge consumer is correct end-to-end, on the user's installed DOCA + installed DPDK + device + permissions, before claiming the "add DOCA to my DPDK app" journey is done.

This is a loop, not a one-shot pass. Each iteration narrows either the install / version surface (DOCA-side or DPDK-side), the port-handover, the conversion-site set, or the single-library smoke shape. The loop terminates when either (a) the user's intended DOCA library composes cleanly with the existing DPDK app at the rate they care about, or (b) the agent has narrowed the failure cause to a layer outside the bridge (DPDK app itself, driver, firmware, env) and escalated to the matching skill.

Iteration shape:

1. Install + version re-check. Re-run the three pkg-config probes from ## configure step 1 plus doca_caps --version. The DPDK ↔ DOCA pair is the most common failure mode and the cheapest one to detect — quote all four numbers back. If they disagree, that is the answer; fix the install per doca-version TASKS.md ## debug and re-loop. Do not move to step 2 with a mismatched pair.
2. DPDK-side precondition re-check. Walk the four DPDK-side conditions from ## configure step 3 (hugepages, devbind, EAL up, port started). A silent bridge handle (no error, but the DOCA library never sees packets) is almost always a DPDK-side gap, not a bridge bug — the DPDK-side counters from ## run step 1 are the first thing to read.
3. Single-rule smoke. As in ## run step 3 — one trivial DOCA Flow rule (or one trivial accelerator submission) on the bound doca_dev, with verification. If yes, advance. If no, narrow: a bridge-call DOCA_ERROR_* narrows per ## debug; a DPDK-side counter that stops incrementing after the rule is installed narrows to the steering itself — route to doca-flow TASKS.md ## debug.
4. Multi-rule / multi-conversion run. Once single-rule is green, scale to the user's actual rule set (or actual per-packet conversion shape) and confirm every expected operation completes. Catches sizing / queue-depth gaps that the single-rule smoke does not exercise. The PE (doca_pe_progress) must be driven at the rate of submits per the cross-library rule in doca-programming-guide CAPABILITIES.md ## Capabilities and modes.
5. Cross-version / cross-host run (if the user has multiple installs). Re-run steps 1-4 on each install; quote both the DOCA version AND the DPDK version per doca-version TASKS.md ## test on each host. The bridge fails differently on each pair, so "works on host A, fails on host B" without quoted versions on both sides is an unactionable report.

Eval-loop overlay — why this is a loop, not a one-shot pass:

Loop termination: stop iterating once two consecutive iterations do not change the picture — the cause is below the bridge (DPDK app code, kernel driver, firmware, env). Escalate to doca-debug TASKS.md ## debug with the captured trace + version state (BOTH DOCA and DPDK sides) as evidence.

debug

Goal: when a bridge session fails — whether by DOCA_ERROR_* return, silent DOCA library on top of a working DPDK port, or matched-pair version drift — isolate the cause to a single layer before recommending any code change.

The cross-library debug ladder lives in doca-debug TASKS.md ## debug. Walk through it in order — install → version → build → link → runtime → program → driver. This skill provides the bridge overlay at the version, runtime, and program layers; the DPDK side overlays on all of them and is the under-tested seam.

Layer 2 (version) — bridge overlay.

• The four-way match in doca-version CAPABILITIES.md ## Version compatibility becomes a FIVE-way match on this skill: add pkg-config --modversion libdpdk against the bridge's expected DPDK window per CAPABILITIES.md ## Version compatibility. Disagreement here is the canonical "the bridge loads but every operation returns confusing errors" failure; surface it before any code change.
• pkg-config --exists doca-dpdk-bridge returning failure is not always "the bridge is not installed" — some DOCA releases use a slightly different module name. Confirm via ls /opt/mellanox/doca/infrastructure/lib/pkgconfig/ | grep -i dpdk before claiming the bridge is missing.

Layer 5 (runtime) — bridge overlay.

• A silent bridge binding (resolves cleanly, no DOCA_ERROR_*, but the DOCA library never sees packets) is almost always a DPDK-side precondition gap or a steering / port-attachment gap, not a bridge code issue. Read the DPDK-side counters per ## run step 1 BEFORE any code change. If DPDK counters are zero, the problem is upstream of the bridge (DPDK app, env). If DPDK counters increment but the DOCA library still does not see packets, route the steering side to doca-flow TASKS.md ## debug.
• DOCA_ERROR_NOT_PERMITTED from a bridge create / open call is the inherited DPDK + DOCA privilege set per CAPABILITIES.md ## Error taxonomy. Confirm BOTH id for mlnx-group membership AND the DPDK- side hugepage / devbind preconditions before recommending a code change; route the env fix to doca-setup TASKS.md ## debug.
• DOCA_ERROR_DRIVER from any bridge call that crosses into the kernel mlx5 driver: capture dmesg | tail and mlxconfig -d <pcie> q and route to doca-setup TASKS.md ## debug; the layer below DOCA + DPDK is the suspect, not the bridge program.

Layer 6 (program) — bridge overlay.

• Lifecycle order across the DPDK ↔ DOCA seam (per CAPABILITIES.md ## Safety policy): DPDK side up → DOCA doca_dev opened → bridge port registered → DOCA doca_ctx_start(). Out-of-order returns DOCA_ERROR_BAD_STATE from the DOCA side; the most common case is registering the DPDK port with the bridge before rte_eth_dev_start succeeded. The DPDK side has to be live first.
• DOCA_ERROR_NOT_FOUND on port-registration / handle-acquire is a wrong DPDK port id, a port not bound under DPDK, or a port id from a different EAL instance — NOT a bridge bug. Confirm the user's rte_eth_dev_get_port_by_name or DPDK port enumeration result before modifying any bridge call.
• DOCA_ERROR_NOT_SUPPORTED after the cap query returned true is a strong signal the DPDK ↔ DOCA matched-pair window has drifted at runtime — return to layer 2. Do not invent a code workaround; the cap query is not lying, the matched pair is.

Once the layer is identified, route to the matching debug verb on the matching skill: install / build / link / driver to doca-setup TASKS.md ## debug; version (DOCA side AND DPDK side) to doca-version TASKS.md ## debug; steering to doca-flow TASKS.md ## debug; cross-cutting runtime to doca-debug TASKS.md ## debug; program-layer Core-context patterns to doca-programming-guide TASKS.md ## debug.

Deferred task verbs

The following verbs are out of scope for this skill but are commonly asked in the same conversations. Route them as follows so the agent does not invent guidance:

• install (DOCA side). Installing DOCA, choosing packages, post-install verification, pkg-config wiring — defer to doca-setup and to the install-tree layout in doca-public-knowledge-map ## Layout of an installed DOCA package. This skill assumes DOCA is already installed.
• install / learn DPDK itself. Installing DPDK, mounting hugepages, binding PCIe ports, learning the DPDK programming model, choosing a DPDK release — out of scope. DPDK is its own upstream project; this skill treats DPDK as a precondition and routes the user to upstream DPDK docs via doca-public-knowledge-map.
• migrate to native doca-eth. Rewriting the user's DPDK data-plane to doca_eth_rxq / doca_eth_txq — out of scope here, and almost always the wrong tradeoff for a working DPDK app per the bridge-vs-native rule in CAPABILITIES.md ## Capabilities and modes. For fresh DOCA-native projects with no DPDK lock-in, route to doca-eth.
• deploy. Deploying DPDK + DOCA applications at scale across many hosts / BlueFields, Kubernetes operator workflows for line-rate data planes — out of scope for Phase 1 and reserved for a future platform skill.
• firmware burn / reset / kernel driver install. Installing mlx5_core, burning new ConnectX firmware, modifying mlxconfig parameters that require a reset — out of scope. Route to doca-setup TASKS.md ## debug layer 5 (driver), then to the upstream MLNX OFED / firmware documentation reachable through doca-public-knowledge-map.

Command appendix

Every command below is cross-cutting on DOCA DPDK Bridge — it answers a recurring class of question that comes up in the verbs above. The agent should treat the class as load-bearing; the worked example is a single instance. Run-as user is the unprivileged user unless noted. Sudo is called out per row. The bridge is unusual in this bundle because every row reads BOTH the DOCA side AND the DPDK side; do not skip the DPDK column when reporting back.

Infra-aware preamble (every row below). Per the bundle's detect → prefer → fall back → report contract documented in doca-structured-tools-contract ## The agent behavior contract, the agent should:

1. Probe for the matching structured helper FIRST (doca-env --json for version + devices + libraries + drivers + hugepages in one shot; doca-capability-snapshot for per-device capability flags; version-matrix.json for "available since" lookups).
2. If the probe succeeds, the structured tool's output is the authoritative answer and the agent SHOULD NOT also run the manual command in the row below. Report "using structured <tool>".
3. If the probe fails, fall back to the manual command in the row. Report "falling back to manual chain".
4. The schemas the structured tools emit are defined in doca-structured-tools-contract ## Schemas; the version-handling semantics (four-way match, NGC, headers-win) are owned by doca-version.

For commands shared across libraries (pkg-config --modversion, doca_caps, cat /opt/mellanox/doca/applications/VERSION, DOCA_LOG_LEVEL) the cross-library overlay is in doca-debug TASKS.md ## Command appendix; this table adds the bridge-specific rows (every one of which reads BOTH the DOCA side and the DPDK side) on top.