doca-dpdk-bridge

DOCA DPDK 桥接

示例

• “如何将 DOCA Flow 添加到我的 DPDK 应用中？”——这属于适用范围。使用 doca_dpdk_port_probe 绑定 DPDK 端口；不要将数据平面改写为原生 doca-eth。
• “端口注册时出现 DOCA_ERROR_NOT_FOUND。”——更改 probe 调用前，先检查 DPDK/DOCA 匹配版本窗口。

说明

遵循下方的加载顺序。打开任务配套文件，了解配置／探测／调试。打开功能配套文件，了解端口绑定和 mbuf 转换。不要打开所有配套文件。

从何处开始： 此技能假设 DOCA 和 DPDK 均已安装，用户已有现成的 DPDK 应用，并希望在原地为其添加 DOCA 功能（最常见的是用于硬件转发的 DOCA Flow），而不将数据平面迁移到 DOCA 原生 API。如果用户想要执行某项操作（配置／构建／修改／运行／测试／调试），请打开任务配套文件；如果问题是此版本的桥接能实现什么功能，请打开功能配套文件。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。如果用户是从头开始（还没有 DPDK 代码），只想通过 DOCA 实现线速数据包 I/O，请改为转到 doca-eth/SKILL.md——此桥接适用于互操作场景，而非从头开始的场景。

如何使用此技能。 阅读本文件，然后在配套文件中查找问题所需的 ## <name> 标题，并阅读该完整章节。答案必须完全依据该章节，且只引用其中的符号和命令。不要浏览文档；请使用 doca-public-knowledge-map 中的入口点。将环境检查作为命令提供，让用户在其 DOCA 主机上执行。对于超出范围的请求，指出负责该请求的技能，然后停止。

此技能擅长回答的问题类别

本技能旨在回答以下 DOCA DPDK Bridge 问题类别，每个类别都附有一个示例。Agent 应将类别视为核心内容——示例只是单个实例。

• “我有一个 DPDK 应用——如何在不重写数据平面的情况下为它添加 DOCA Flow 规则？”——示例：“我的数据包处理应用已经通过 rte_eth_* 端口处理 mbuf；我想在这些端口上安装 DOCA Flow 转发规则以进行 HW 卸载。”可通过

  Capabilities and modes

  中的 bridge 与原生方案选择规则，以及

  configure step 3

  中的端口移交工作流来回答。
• “如何让 DOCA 看到一个 DPDK 端口？”——示例：“我从 rte_eth_dev_* 获取了一个 DPDK 端口 ID；DOCA 如何识别它？”可通过

  Capabilities and modes

  中的 DPDK 端口 ID ↔ doca_dev 映射（doca_dpdk_port_probe / doca_dpdk_port_as_dev）和

  configure step 4

  中的绑定工作流来回答。
• “如何在 DPDK mbuf 和 DOCA buf 之间移动数据包？”——示例：“DPDK 将一个 rte_mbuf 交给我的快速路径；我想让 DOCA 库处理其负载。”可通过

  Capabilities and modes

  中的 mbuf ↔ DOCA-buf 转换形式，以及

  modify

  中的转换步骤工作流来回答。
• “bridge 是否已安装？它所用的 DPDK 是否与我的 DOCA 兼容？”——示例：“一台单独安装了 DPDK 的主机上，pkg-config --exists doca-dpdk-bridge 返回失败。”可通过

  Version compatibility

  中的版本耦合规则，以及

  configure step 1

  中的功能检查工作流来回答。
• “我应该使用 doca-dpdk-bridge 还是 doca-eth？”——示例：“新项目；我还没有决定是否使用 DPDK。”可通过

  Capabilities and modes

  中的路径选择表（bridge 与原生方案行），以及

  Deferred task verbs

  中关于 deferred-verbs 的说明来回答。
• “bridge 调用返回的这个 DOCA_ERROR_* 是什么意思？是哪个层导致的？”——示例：“DPDK 端口正常启动后，端口注册调用返回 DOCA_ERROR_NOT_FOUND。”可通过

  Error taxonomy

  中对跨库分类法的 bridge 扩展，以及

  debug

  中的分层排查步骤来回答；如需进一步升级处理，请参阅 doca-debug/SKILL.md。

受众

本技能面向维护基于 DPDK 的数据包处理应用的外部开发者，也就是说，他们的数据平面已经处理 rte_eth_* 端口和 rte_mbuf 缓冲区，并希望通过将 bridge 链接到同一进程中来添加 DOCA 功能（最常见的是通过 DOCA Flow 实现硬件转发）。本技能不适用于从头开始开发 DOCA 原生项目的用户（请转到 doca-eth/SKILL.md），也不适用于不打算使用 DOCA、只运行纯 DPDK 的用户（本工具包中的技能均不适用）。本技能也不面向为 DOCA DPDK Bridge 本身做贡献的 NVIDIA 开发者。

语言范围。 DOCA DPDK Bridge 以 C 库形式提供，其 pkg-config 模块名称为 doca-dpdk-bridge（Agent 必须通过用户的安装环境中的 pkg-config --exists doca-dpdk-bridge 确认拼写；某些 DOCA 版本使用略有不同的模块名称，Agent 不得猜测）。随附示例以 C 编写。C 和 C++ 使用者是典型情况；任务配套材料中的示例也基于此路径。其他语言的使用者（Rust、Go、Python 等）通常不会使用此 bridge——DPDK 本身以 C 为基础，非 C 的 DPDK 应用也很少见；如果用户属于这一少数情况，本技能仍会提供与语言无关的端口移交、功能、权限和错误分类指导，并引导他们将公开的 C ABI 作为权威接口。

何时加载此技能

当用户正在实际操作 DOCA DPDK Bridge 时，无论使用哪种语言，都应加载此技能。具体来说：

• 用户已有 DPDK 应用（其数据平面已经驱动 rte_eth_dev_* 端口和 rte_mbuf 缓冲区），并希望在其上叠加 DOCA——添加 DOCA Flow 规则、将数据包送入 DOCA 加速器（Compress、AES-GCM 等），或将 DOCA 服务接入同一进程。
• 用户需要将 DPDK 端口 ID 绑定到 doca_dev（通过 doca_dpdk_port_probe / doca_dpdk_port_as_dev），以便 DOCA Core / DOCA Flow 在同一物理端口上运行。
• 用户需要在数据平面边界转换 DPDK mbuf 和 DOCA-buf，并询问转换辅助函数及其开销。
• 用户正在调试桥接调用返回的 DOCA_ERROR_*（生命周期、权限、功能、DPDK 端口未注册或 mbuf 转换失败），以及底层分层的 DPDK ↔ DOCA 堆栈。
• 用户遇到跨版本问题：其 DPDK 安装与 DOCA 安装并非桥接所要求的配套版本。
• 用户在询问“使用原生 doca-eth 还是 doca-dpdk-bridge？”，而 Agent 需要判断路径选择规则。

对于一般 DOCA 概览、DOCA 本身的安装、全新的 DOCA 原生数据包 I/O（使用 doca-eth/SKILL.md）、单独的流规则编程（使用 doca-flow/SKILL.md）、主机 ↔ DPU 控制消息（使用 doca-comch/SKILL.md）或 RDMA 数据传输（使用 doca-rdma/SKILL.md），不要加载此技能。 DOCA 文档概览请使用 doca-public-knowledge-map/SKILL.md。

此技能提供的内容

这是一个精简加载器。正文仅保留用于选择下一个正确文件的概览信息。桥接专属的实质内容位于两个配套文件中：

• 功能配套文件——介绍此版本的 DOCA DPDK Bridge 能实现什么：桥接与原生方案的选择规则（何时使用 doca-dpdk-bridge，何时使用原生 doca-eth）、桥接对象接口（DPDK 端口 ID ↔ doca_dev 映射、doca_dpdk_mempool 的 mbuf ↔ DOCA-buf 转换）、功能查询接口（唯一的 doca_dpdk_cap_is_rep_port_supported）、桥接错误分类（映射到跨库的 DOCA_ERROR_* 集）、可观测性接口（DPDK 侧计数器 + DOCA 侧 PE 事件），以及安全策略——涵盖配套的 DPDK ↔ DOCA 版本耦合、EAL 必须已启动这一前置条件和 DPDK 侧权限。
• 任务配套文件——针对范围内六种桥接操作动词的分步工作流：configure、build、modify、run、test、debug。此外还包含一个 Deferred task verbs 部分，指出范围外的问题应转到哪个后续技能，以及一个列出 Agent 常用命令的 Command appendix。

此技能假定用户使用的主机或 BlueField 已在标准位置安装 DOCA 和 DPDK，且用户具备其公开安装配置所要求的权限（通常是 DOCA 所需的 sudo 或 mlnx 组成员身份，以及 DPDK 侧挂载大页、绑定 PCIe 端口和打开目标 rte_eth 设备所需的权限）。此技能不涵盖 DOCA 的安装——请通过 doca-setup/SKILL.md 完成；也不涵盖 DPDK 本身的安装或学习——相关内容请参阅上游 DPDK 文档，可通过 doca-public-knowledge-map/SKILL.md 查找。

本技能有意不提供的内容

本技能是Agent 指南，而非示例或模板包。为明确界定范围，本技能有意不包含以下内容，且不应通过拉取请求添加：

• 任何语言编写的预置 DOCA DPDK Bridge 应用程序源代码。 已验证的桥接源代码位于随附的 C 语言 DOCA Flow 示例中，具体是 /opt/mellanox/doca/samples/doca_flow/ 内用于桥接的代码（例如调用 doca_dpdk_port_probe() / doca_dpdk_port_as_dev() 的 flow_common.c），以及将 DPDK 与 DOCA Flow 配合使用的标准参考应用程序（参考应用程序索引见 doca-public-knowledge-map/SKILL.md）。Agent 的任务是引导用户找到这些文件，并通过 doca-programming-guide/SKILL.md 中通用的修改示例工作流，在这些文件上进行最小差异修改，再叠加 ## modify 中针对桥接的覆盖规则。
• 存放在本技能中的独立构建清单（meson.build、CMakeLists.txt、Cargo.toml 等）。Agent 应在用户的项目目录中构建构建清单，并针对用户已安装的 DOCA + DPDK；其中 pkg-config --modversion doca-dpdk-bridge 和 pkg-config --modversion libdpdk 是权威信息来源。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录。 即使标注为“参考”，本技能目录树中的模拟或不完整内容也会造成误导：用户会以为它可以构建。

加载顺序

1. 首先阅读本技能，确认用户的问题在范围内（已有 DPDK 应用，并希望在此基础上使用 DOCA，而非从头开始）。
2. 有关桥接能力矩阵、桥接与原生方案的选择规则、端口移交范围、能力查询规则、错误分类、可观测性和安全策略，请参阅能力配套文档。
3. 有关逐步工作流——配置、构建、修改、运行、测试、调试——请参阅任务配套文档。

这两个配套文件相互交叉引用，还会引用 doca-version/SKILL.md 中的 DOCA 版本处理标准规则，doca-eth/SKILL.md 中作为桥接有意替代方案的从头开始路径，doca-flow/SKILL.md 中通常促使用户使用此桥接的流量转向库，以及 doca-public-knowledge-map/SKILL.md；当正确的做法是“查阅公开文档或已安装的软件包目录结构”而非“查阅桥接专属指南”时，应参阅该文件。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档源的路由表， 以及已安装 DOCA 软件包的磁盘布局。桥接 URL slug 为 DOCA-DPDK-Bridge。结合 DPDK + DOCA Flow 的参考应用（该桥接的 典型采用者）可通过同一知识地图中的参考 应用索引找到。
• doca-setup/SKILL.md — 环境准备、 安装验证、大页挂载（DPDK 要求）、 端口状态检查（devlink dev show、ip link）、打开 doca_dev 以及在 DPDK 下绑定 PCIe 端口所需的权限和组成员资格要求。 本技能假定已满足这些前提条件。
• doca-version/SKILL.md — 规范的 DOCA 版本处理规则。本技能的 ## Version compatibility 部分交叉引用四方匹配规则，并仅添加 桥接特有的补充规则（DPDK ↔ DOCA 配对版本耦合）。
• doca-structured-tools-contract/SKILL.md — 本软件包的结构化工具优先级规则（检测 / 优先使用 / 回退 / 报告）。任务配套文档中的命令附录 遵循此契约。
• doca-programming-guide/SKILL.md — 所有库共用的通用 DOCA 编程模式： 规范的 pkg-config + meson 构建模式、 通用的“修改随附示例”首个应用工作流、通用生命周期、 跨库 DOCA_ERROR_* 分类，以及程序侧调试顺序。本技能在此基础上叠加桥接特定内容。
• doca-eth/SKILL.md — 替代路径， 适用于从零开始的用户：纯 DOCA 原生队列 I/O，通过 doca_eth_rxq / doca_eth_txq 实现， 不涉及 DPDK。此桥接之所以存在，正是因为 将现有 DPDK 应用迁移到 doca-eth 往往并非合适的取舍；对于没有 DPDK 锁定的新项目， doca-eth 才是正确选择。
• doca-flow/SKILL.md — 引导库， 也是 DPDK 应用最常因此采用此 桥接的原因。桥接将 DPDK 端口 ID 绑定到 doca_dev； DOCA Flow 会在该 doca_dev 上编程流引导规则。这两个 库专为组合使用而设计。
• doca-debug/SKILL.md — 跨领域的 调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动）。桥接特定的调试问题（DPDK ↔ DOCA 版本 漂移、端口未注册症状、mbuf 转换失败） 可叠加到该阶梯之上。