doca-flow

DOCA Flow

示例

• “如何在 representor 上启动 Flow 端口？” — 这属于适用范围。使用已安装的头文件和随附示例；不要编写首个应用的 main.c。
• “匹配 5 元组并发送到队列。” — 将其表示为 Flow 管道。不要退而使用内核 tc 或 iptables。

说明

遵循下文的加载顺序。打开任务配套文档，了解配置／修改／调试。打开功能配套文档，了解管道规范架构和安全策略。 对于连接跟踪，请先阅读任务配套文档的 flow-ct 部分，再启动端口：CT 初始化是进程全局的，必须在端口启动之前完成。向正在运行的端口添加 CT，需要经过批准的中断，并从捕获的配置重建；不能对每个端口调用 doca_ctx_start，也不能重用已失效的管道句柄。

不容妥协：首个应用必须是拉取 NGC 镜像 + 使用随附示例，而不是编写 C 代码

用户刚开始使用 DOCA、拥有 docker、主机上没有 DOCA，或正在询问首个 Flow 应用时，必须在检查主机上的 pkg-config 和列出任何源代码之前执行以下操作：

1. 先提供文档包。 此回答遵循本地 doca-skills 文档包：doca-setup/SKILL.md（Stage 1 与 Stage 2）、doca-programming-guide/SKILL.md（修改随附示例）、本 doca-flow 技能，以及 doca-public-knowledge-map/SKILL.md。 列出这些技能。不要编造其他技能名称。
2. 在执行任何命令之前说明 Stage 1 与 Stage 2。 Stage 1 = 笔记本电脑上的 NGC 容器（编译／学习；没有真实数据包）。Stage 2 = 用于管道运行时的真实 BlueField 或 ConnectX。Docker 只负责编译；不要声称应用完全在 docker 内运行。
3. 路径 0（Stage 1）。 从 https://catalog.ngc.nvidia.com/orgs/nvidia/teams/doca/containers/doca/tags 复制一个标签，使用 如何选择 NGC 标签而不猜测 — 绝不要编造标签，也不要使用 latest。然后运行 docker pull nvcr.io/nvidia/doca/doca:<tag> 和 docker run -it --rm -v $HOME/dev/doca-work:/work nvcr.io/nvidia/doca/doca:<tag> bash（使用空目录，绝不要用 $HOME）。不要编造 Dockerfile，不要构建源代码。
4. 在容器内继续（必须在 docker run 之后执行）： 引用以下交接语 — 即使是完整教程也不要省略：“请粘贴 pkg-config --modversion doca-flow 和 ls /opt/mellanox/doca/samples/doca_flow/ 的输出。”然后：“我会在你提供真实安装信息后，从 doca-programming-guide ## modify 的步骤 1 继续。”列出该目录内容中显示的一个目录；复制它。如果 ls 没有任何输出，就停止 — 不要搭建框架。在该 pkg-config 命令中使用 doca-flow，不要用 doca-common。
5. 绝不输出新的 main.c、Makefile、Dockerfile，也不要手动输入 -l／-L 标志。粘贴 pkg-config --libs doca-flow。

不容妥协：交付内容必须使用 DOCA Flow，而不是内核 tc／iptables

当此技能适用时，用户要的是 DOCA Flow。完成上述随附示例的复制后，构建的二进制文件必须链接 libdoca_flow，并在用户已安装的 DOCA 上使用 doca_flow_* 生命周期 — 初始化、启动端口、编程管道、提交条目，以及在流量下读取计数器。复制 /opt/mellanox/doca/samples/doca_flow/ 下该随附 DOCA Flow 示例中的调用顺序，并通过 ## configure /

modify 进行调整。根据已安装的头文件核实每个符号（见下文的基本规则）以及添加条目表中的内容

API 面及名称防护。

不要用内核 tc/flower、iptables/nftables、eBPF/XDP、 OVS 或裸 DPDK rte_flow（不带 DOCA）来满足硬件数据包转向 / 5 元组过滤请求， 然后就认为任务完成。 这些方式可能会将规则下发到网卡，但会完全绕过 DOCA Flow，从而违背此库的目的，并丢失 DOCA 模型（管道 / 条目的生命周期、硬件计数器、能力发现、 跨 BlueField/ConnectX 代际的可移植性）。

“tc flower skip_sw 也能卸载到硬件” / “内核命令更少”不是绕过 DOCA Flow 的可接受理由。低门槛的正确做法是从 /opt/mellanox/doca/samples/doca_flow/ 下随附的 DOCA Flow 示例开始并加以改造。

如果 pkg-config doca-flow（或总括性的 pkg-config doca）或 DOCA 构建失败，修复构建（模块名称、PKG_CONFIG_PATH、 示例路径、hugepages/EAL 初始化）——不要悄悄退回到 tc。 如果某个工具的 ldd 未显示 libdoca_flow，那么这就是一次失败的 DOCA Flow 任务， 无论规则是否已写入网卡。在宣告成功之前，明确运行 ldd ./your_app | grep -i libdoca_flow 进行验证。

绝不要臆造链接参数行。 对于 undefined reference / 链接 失败，请运行 pkg-config --libs doca-flow，并附上配套的模块 名称（doca-common、doca-argp、doca-dpdk-bridge、 libdpdk），然后粘贴其输出。这些名称只应出现在 pkg-config 命令中； 绝不要把它们改写成手工输入的 -l / -L 参数，或猜测安装路径。 随附示例的 meson.build dependency() 列表就是模块集合；pkg-config 是唯一负责将其转换为链接器参数的工具。

从何处开始： 如果任务是执行某项操作 （配置 / 构建 / 修改 / 运行 / 测试 / 调试），请打开任务配套文档； 如果问题是此版本的 Flow能表达什么，请打开能力配套文档。**编写或运行 任何端口代码之前，必须先打开

configure**——其中的启动门槛决定二进制是否能启动。

如果尚未安装 DOCA，请先转到 doca-setup/SKILL.md。

基本规则：对照已安装的头文件验证每个 API 名称

引用任何 doca_* / DOCA_* 标识符之前，请先确认它存在于用户已安装的头文件中—— 机器上的头文件是事实依据，优先级高于说明文字、API 参考、博客文章或记忆：

for header in "$(pkg-config --variable=includedir doca-common)"/doca_flow*.h; do
  grep -n '<candidate_name>' "$header"
  # For a multi-line function declaration, print through its closing `);`.
  awk '/<candidate_name>[[:space:]]*\(/,/[)][[:space:]]*;/' "$header"
done

DOCA Flow 不提供向后兼容的别名头文件，因此，头文件中不存在的 “看起来合理”的名称根本无法链接。请从随附示例 （/opt/mellanox/doca/samples/doca_flow/<name>/）或 ## API 面及名称防护中的 防护列表重新推导，切勿从说明文字中推导。

端口启动：门槛位于任务配套文档中

端口编译顺利，却在调用 doca_flow_port_start() 时立即中止，是典型的启动失败。启动门槛（计数前先探测、 doca_flow_port_cfg_set_port_id()，加上与模式相符的设备来源——VNF 模式下使用 doca_flow_port_cfg_set_dev()，或使用已安装的交换机示例中的 doca_dev_rep 路径—— 设备从启动参数获取，而非硬编码；如果桥接无法启用并转发，二进制必须从 main() 返回非零退出码）会在

configure 第 6 步中逐步强制执行——编写或运行端口代码之前请先打开该文档；

不要根据此摘要自行还原启动门槛。

何时应拒绝（编写代码前先提出异议）

有些请求无法按要求实现。遇到以下情况时，应拒绝并解释——不要默默输出不完全正确的代码：

1. 请求混合了单个 pipe 阶段无法表达的职责（例如，在一个 matcher 中同时进行逐流 tunnel 模板选择 和 逐流 egress 端口选择）。一个 pipe 是一个逻辑步骤（匹配 → 动作 → 转发）；应给出正确的 pipe 图结构，而不是代码——通常是 classifier pipe → 逐流 encap pipe → 逐流 forward pipe（参见

   Pipe decomposition）。

2. 请求硬件无法实现的功能（例如，逐包匹配 L4 之外的 payload 字节、可变匹配键，等等）。指出最接近的合法结构，然后停止。
3. **请求依赖于已安装头文件中不存在的 API 名称。**在头文件中 grep 最接近的真实符号，在拒绝说明中指出该符号，然后停止，不要生成代码。之后，用户明确要求使用已验证的符号时，可以开始新的构建工作流；不要在当前请求中默默替换。
4. 用户想要硬件包 steering，却接受仅限内核的交付物（tc、iptables/nftables、eBPF/XDP、OVS，或不带 DOCA 的裸 rte_flow）。应依据上文的 Non-negotiable 拒绝；改为引导用户采用已发布示例 + DOCA Flow 的构建路径。

提出异议时的输出格式：

REFUSED: <one-sentence summary>
Reason: <2-4 bullets, each tied to a hardware or API constraint>
Suggested alternative: <pipe-graph sketch, or "this is not expressible in DOCA Flow">

此门槛在编写任何代码之前触发：自信地给出错误的 pipe，比诚实拒绝并提供合法替代方案对用户的损害更大。

此技能擅长回答的问题示例

此技能擅长回答的 Flow 问题类别（关键在于问题的类别；示例只是其中一种情况）：

• “如何在 representor 上启动 Flow 端口？” →

  configure +

  Capabilities and modes。

• “如何将 <匹配 X，执行 Y> 表示为 pipe？” →

  Capabilities and modes

  • modify。

• “这个 pipe 规范会配置 HW，还是会导致 commit 失败？” →

  Safety policy

  • test。

• “如何读取 Flow 计数器，以调查观测到的流量？” →

  Observability

  • debug。

• “我的 Flow 端口无法启动——Failed to get hws cap / dest action ROOT … err -121。” → 这是设备放置特征（不是 pipe 问题）；在 SEPARATED_HOST / NIC 模式的 BlueField 上，steering plane 属于 DPU Arm。参见

  Capabilities and modes

  中的设备放置要点 +

  configure 步骤 2 + ## debug 中的步骤 0。

• “如何在现有 doca-flow 设置上添加硬件加速的有状态 5 元组连接跟踪（老化、NAT）？” →

  flow-ct +

  flow-ct。

受众

在装有 /opt/mellanox/doca 中 DOCA 的受支持 NVIDIA NIC/DPU 上，编写调用 doca_flow_*（使用 C/C++ 或 FFI）以配置包 steering 的代码的外部开发者。Flow 以 C 库形式提供（pkg-config 模块 doca-flow，软件包 doca-sdk-flow），示例为 C；其他语言的使用者通过 FFI 调用相同的 *.so，此技能不依赖特定语言。

何时加载此技能

当用户在已安装 DOCA 的受支持 NVIDIA NIC/DPU 上进行 DOCA Flow 实操 时加载，DOCA 的安装路径为 /opt/mellanox/doca，语言不限：

• 在已安装的设备上启动 Flow 端口／representor。
• 创建管道、定义匹配项／操作，并编程写入条目。
• 在向硬件编程之前验证管道规范。
• 在有流量时读取每个条目／每条管道的计数器。
• 检查已安装的 DOCA 中包含哪些 Flow 功能／符号（pkg-config --modversion doca-flow 是构建时的基准）。
• 调试 Flow 调用返回的 DOCA_ERROR_*（配置错误、缺少前置条件，或此硬件／安装不支持）。
• 基于 Flow C ABI 设计非 C 语言绑定（Rust、Go、Python，……）。
• 在现有端口上添加有状态 CT（doca_flow_ct.h）（参见 ## flow-ct）。

以下情况不要加载：一般性的 DOCA 介绍、“去哪里找文档”、安装布局问题或非 Flow 库相关问题——请改用 doca-public-knowledge-map/SKILL.md。

此技能提供什么

这是一个轻量加载器；实质性内容位于两个配套文件中：

• 功能配套文件——说明此版本的 Flow 能实现什么：支持的匹配项和操作类型、管道拆分规则、API 范围 + 常见臆造名称的防范清单、Flow 的 DOCA_ERROR_* 补充说明、每个条目／每条管道的可观测性范围、版本说明、安全策略，以及 CT 配套内容。
• 任务配套文件——涵盖六个适用动词（configure、build、modify、run、test、debug）的工作流，以及 ## flow-ct（有状态 CT 补充说明）、## shared-resources（共享封装／解封装／计数器／计量器／RSS／IPsec-SA／PSP 补充说明）、## rollback（管道编辑类别快照）、## Command appendix 和用于转交路由安装／部署问题的 Deferred task verbs。

此技能假设 DOCA 已安装在 /opt/mellanox/doca，且用户可以打开 doca_dev。DOCA 安装、hugepages 设置以及 EAL dv_flow_en devargs 准备工作应使用 doca-setup/SKILL.md；二进制文件启动 Flow 端口前所需的 hugepages／devargs 运行时前置条件列于 ## configure 第 5 步。

此技能有意不包含的内容

此技能提供的是Agent 指南，不是代码包：不包含预先编写的 Flow 应用程序源代码、独立构建清单，也不包含 samples/／bindings/／reference/ 子目录。经过验证的 Flow 源码是随附的 C 示例，位于 /opt/mellanox/doca/samples/doca_flow/<name>/——Agent 会引导用户前往该目录，并通过 doca-programming-guide/SKILL.md 中的修改示例工作流以及 ## build 中的 Flow 覆盖项，提出最小差异修改；任何构建清单都应在用户的项目中基于用户的安装构建，其中 pkg-config --modversion doca-flow 是事实依据。

加载顺序

1. 首先阅读此技能，确认问题属于适用范围。
2. 对于管道规范的架构、功能矩阵、错误分类、可观测性和安全策略，请参阅功能配套文件。
3. 对于分步工作流，请参阅任务配套文件。

相关技能

• doca-public-knowledge-map/SKILL.md — 公共 DOCA 文档的路由表，以及已安装软件包在磁盘上的布局。
• doca-setup/SKILL.md — 环境准备、安装验证，以及通过 NGC DOCA 容器进行的尚未安装流程。
• doca-programming-guide/SKILL.md — 所有库通用的 DOCA 模式：pkg-config + meson 构建模式、先修改随附示例的首个应用工作流、 通用生命周期、跨库 DOCA_ERROR_* 分类， 以及程序端调试顺序。此技能在这些内容之上添加 Flow 专属内容。
• doca-flow-tune/SKILL.md — 已编程状态检查（只读）。
• doca-hardware-safety/SKILL.md — 切换卡模式时必须遵循的补充指南（例如通过 mlxconfig 将 SEPARATED_HOST 改为 EMBEDDED_CPU）。
• doca-debug/SKILL.md — 跨领域调试 阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动程序）。