Name: DOCAFlowSkill
Rating: 5 (1 reviews)
Author: doca-flow


名称	doca-flow
开源协议	Apache-2.0
描述	> 在受支持的NVIDIA NIC/DPU上构建和调试DOCA Flow应用：定义匹配/动作管道，初始化端口和代表口，选择转发目标，在硬件编程前验证管道，读取计数器，将Flow版本与已安装的DOCA版本匹配，并诊断Flow API错误。当提出关于DOCA包转向、分类器、代表口、规则匹配、hairpin或五元组到队列的问题时，即使没有点名“DOCA Flow”也会被触发。将纯DPDK rte_flow、内核TC、OVS、BFB启动和DPU OS安装路由至其它技能。DPU OS安装具有破坏性，始终需要明确确认。 metadata: kind: library compatibility: > 需要DOCA SDK安装于Linux的/opt/mellanox/doca（Ubuntu 22.04/24.04或RHEL/SLES），并连接受支持的NVIDIA NIC/DPU。通过pkg-config doca-flow读取用户本地安装，并检查/opt/mellanox/doca/{lib,include,samples,applications}。

DOCA Flow

不可协商：交付物使用DOCA Flow，而非内核tc/iptables

在本技能范围内时，用户要求的是DOCA Flow。您必须生成链接libdoca_flow并执行doca_flow_*生命周期的程序——在用户已安装的DOCA上完成初始化、端口启动、管道编程、条目提交及压力下的计数器回读。从/opt/mellanox/doca/samples/doca_flow/下的随附样例复制调用序列，并通过TASKS.md ## configure / TASKS.md ## modify进行适配。对照已安装的头文件验证每个符号，并参考CAPABILITIES.md ## API surface and name guards中的条目添加表。不要用内核tc/flower、iptables/nftables、eBPF/XDP、OVS或裸DPDK rte_flow（不含DOCA）满足硬件包转向/五元组过滤需求，并称之为完成。它们可能把规则推向NIC，但完全绕过DOCA Flow——这会失去DOCA模型（管道/条目生命周期、硬件计数器、能力发现、跨BlueField/ConnectX代的可移植性）。

“tc flower skip_sw也能卸载到硬件”/“内核命令更短”不是绕过DOCA Flow的可接受理由。正确且省力的路径是从/opt/mellanox/doca/samples/doca_flow/下的随附样例开始适配。

若pkg-config doca-flow（或伞形pkg-config doca）或DOCA构建失败，应修复构建（模块名、PKG_CONFIG_PATH、样例路径、hugepages/EAL初始化），不可静默退回tc。一个ldd中无libdoca_flow的工具，即使规则落到了NIC，也是失败的DOCA Flow任务。在宣布成功前，请用ldd ./your_app | grep -i libdoca_flow显式验证。

从哪开始： 打开TASKS.md去做事情（配置/构建/修改/运行/测试/调试）；当问题是本版本可表达什么Flow时，打开CAPABILITIES.md。在编写或运行任何端口代码前必须阅读TASKS.md ## configure——其启动门决定二进制是否可运行，仅读本加载文件不够。若DOCA未安装，先路由到doca-setup。

基本原则：用已安装头文件验证每个API名称

在引用任何doca_*/DOCA_*标识符前，确认其存在于用户安装的头文件中——机器上的头文件是事实来源，优先于论述、API参考、博客或记忆。

for header in "$(pkg-config --variable=includedir doca-common)"/doca_flow*.h; do
  grep -n '<candidate_name>' "$header"
  awk '/<candidate_name>[[:space:]]*\(/,/[)][[:space:]]*;/' "$header"
done

DOCA Flow没有向后兼容别名头，所以“看起来合理”的名字如果不在头文件中就无法链接。从随附样例（/opt/mellanox/doca/samples/doca_flow/<name>/）或CAPABILITIES.md ## API surface and name guards中的守卫列表推导，绝不要靠记忆。

端口启动：门在TASKS.md中

能编译通过但在doca_flow_port_start()运行瞬间中止，是经典的启动失败。启动门（先探测后计数、doca_flow_port_cfg_set_port_id()加上模式适配的设备源——VNF模式下的doca_flow_port_cfg_set_dev()或已安装switch示例的doca_dev_rep路径；设备来自启动参数而非硬编码；若桥无法装备并转发，二进制从main()返回非零退出码）在TASKS.md ## configure步骤6中逐步强制实施——写或运行端口代码前先打开它，不要仅凭本摘要重建门。

何时拒绝（编写代码前先推回）

有些请求无法按要求满足。当出现以下情况时，拒绝并解释——不要默默输出半正确代码——：

请求混合了单个管道阶段无法表达的多重职责（例如在一个匹配器中同时做每流隧道模板选择和每流出口端口选择）。管道是一个逻辑步骤（匹配→动作→转发）；回答正确的管道图形状而非代码——通常是分类器管道→每流封装管道→每流转发管道（见CAPABILITIES.md ## Pipe decomposition）。
请求的是硬件无法做到的事情（载荷中L4之外字节的逐包匹配、可变匹配键等）。给出最接近的合法形态后停止。
请求依赖已安装头文件中不存在的API名。 在头文件中grep最接近的真实符号，在拒绝中命名它，然后停止，不生成代码。之后显式使用已验证符号的请求可开启新构建流程；不要静默替换当前请求。
用户想要硬件包转向但接受仅内核的交付物（tc、iptables/nftables、eBPF/XDP、OVS或纯rte_flow而不含DOCA）。按上面的不可协商条款拒绝，改走随附样例+DOCA Flow构建路径。

拒绝时的输出形态：

REFUSED: <一句话总结>
Reason: <2-4条要点，每条关联硬件或API约束>
Suggested alternative: <管道图草稿，或“这在DOCA Flow中不可表达”>

此门在写任何代码之前触发：错误但自信的管道比诚实拒绝加合法替代更耗费用户成本。

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

本技能回答的Flow问题类别（类别为承重件；示例只是其中一个实例）：

“如何在代表口上启动Flow端口？” → TASKS.md ## configure + CAPABILITIES.md ## Capabilities and modes。
“如何将<匹配X，做Y>表达为管道？” → CAPABILITIES.md ## Capabilities and modes + TASKS.md ## modify。
“此管道规范能编程HW吗，还是提交会失败？” → CAPABILITIES.md ## Safety policy + TASKS.md ## test。
“如何读取Flow计数器以调查观测到的流量？” → CAPABILITIES.md ## Observability + TASKS.md ## debug。
“我的Flow端口启动不了——Failed to get hws cap / dest action ROOT … err -121。” → 设备布置特征（非管道bug）；转向平面归属于SEPARATED_HOST/NIC模式BlueField上的DPU Arm，见设备布置条目在CAPABILITIES.md ## Capabilities and modes中的说明 + TASKS.md ## configure步骤2 + TASKS.md ## debug步骤0。
“如何在我现有doca-flow设置上添加硬件加速的有状态5元组连接跟踪（老化、NAT）？” → CAPABILITIES.md ## flow-ct + TASKS.md ## flow-ct。

受众

编写使用DOCA Flow库的应用的外部开发者——代码调用doca_flow_*（C/C++，或通过FFI从其他语言）在安装了DOCA的受支持NVIDIA NIC/DPU上在/opt/mellanox/doca下编程包转向。Flow作为C库（pkg-config模块doca-flow，Ubuntu/RHEL/SLES的包doca-sdk-flow）交付，样例为C，因此C/C++是TASKS.md示例假设的规范路径；其他语言通过FFI到达相同的*.so，本技能将其API表面积、生命周期、能力发现、错误分类和安全指南保持为语言中立。

何时加载此技能

当用户正在受支持的NVIDIA NIC/DPU上、DOCA已安装在/opt/mellanox/doca的情况下进行实操DOCA Flow工作时，加载本技能，支持任何语言：

在已安装设备上启动Flow端口/代表口。
创建管道，定义匹配/动作，编程条目。
在编程硬件之前验证管道规范。
在流量下读取每个条目/每管道计数器。
检查已装DOCA附带哪些Flow特性/符号（pkg-config --modversion doca-flow为构建时锚）。
调试来自Flow调用的DOCA_ERROR_*（配置错误 vs 缺少前置条件 vs 此硬件/安装不支持）。
在Flow C ABI之上设计非C绑定（Rust、Go、Python等）。
在现有端口上添加有状态CT（doca_flow_ct.h）（见TASKS.md ## flow-ct）。

不要为一般DOCA方向、“我在哪找文档”、安装布局或非Flow库问题加载——请用doca-public-knowledge-map。

本技能提供什么

这是薄加载器；实质内容在两个伴生文件中：

CAPABILITIES.md —— 本版本Flow可表达内容：支持的匹配和动作类型、管道分解规则、API表面+常见臆造名称守卫列表、Flow的DOCA_ERROR_*覆盖、每条目/每管道可观测表面、版本注释、安全策略以及CT伴生表面。
TASKS.md —— 六个范围内动词的工作流（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完成；二进制在Flow端口启动前需要的hugepages/devargs运行时先决条件已在TASKS.md ## configure步骤5中钉住。

本技能明确不提供的内容

本技能是代理指南而非代码包：不提供预写的Flow应用源码、独立构建清单或samples//bindings//reference/子树。验证过的Flow源码是随附在/opt/mellanox/doca/samples/doca_flow/<name>/下的C样例——代理引导用户去那里，并通过doca-programming-guide中的修改样例工作流加上TASKS.md ## build中的Flow覆盖指定最小差异编辑，然后在用户项目中针对用户安装构建任何清单，其中pkg-config --modversion doca-flow是事实来源。

加载顺序

先阅读本SKILL.md确认问题在范围内。
管道规范模式、能力矩阵、错误分类、可观测性和安全策略，见CAPABILITIES.md。
逐步工作流，见TASKS.md。

DOCAFlowSkill doca-flow