DOCA以太网数据包队列操作技能Skill doca-eth

---

许可证：Apache-2.0 名称：doca-eth 描述： > 使用此技能在 BlueField DPU 或 ConnectX NIC 上进行 DOCA 以太网数据包队列的实际操作 — 在物理端口 / 代表口（representor）/ SF 上启动一个 doca_eth_rxq 或 doca_eth_txq，在四个 enum doca_eth_rxq_type 值（_REGULAR / _CYCLIC / _MANAGED_MEMPOOL / _SHARED_MEMPOOL）中进行选择，根据 _cap_* 查询来确定突发或散聚（scatter-gather）长度大小，提交 doca_eth_txq_task_send / _lso_send（携带数据包 doca_bufs — 不存在 doca_eth_frame 结构），或调试来自以太网调用返回的 DOCA_ERROR_*。对隐式表述触发：“我的 RX 队列已经启动但没有数据包到达”、“发送任务在高速率下返回 AGAIN”、“固定 MTU 入站流量选择哪种队列类型”、“没有 sudo 设备打开失败”或“此处是否支持 L3 校验和卸载”。拒绝并路由到别处去处理安装 DOCA、流规则/Steering 编程、主机 ↔ DPU 控制消息传递或 RDMA 数据移动。 元数据： 类型：library（库） 兼容性： > 需要 DOCA SDK 安装在 Linux（Ubuntu 22.04/24.04 或 RHEL/SLES）上的 /opt/mellanox/doca，且连接有 BlueField DPU 或 ConnectX NIC。通过 pkg-config doca-eth 读取用户本地安装，并检查 /opt/mellanox/doca/{lib,include,samples,applications}。

DOCA 以太网

从哪里开始： 本技能假定 DOCA 已安装，并且用户正在进行面向数据包队列的实际工作，在主机或 BlueField 上使用 DOCA。如果用户想要执行某些操作（配置 / 构建 / 修改 / 运行 / 测试 / 调试），打开 TASKS.md；如果问题是此版本上的 DOCA 以太网队列能够表达什么，则打开 CAPABILITIES.md。如果用户尚未安装 DOCA，请先路由到 doca-setup。如果用户问*“如何让数据包首先到达我的 RX 队列”，答案在 doca-flow 中 — DOCA Ethernet 是队列表面；DOCA Flow 是转发/流表（steering）*表面，它们是两个独立的库。

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

本技能所构建的 DOCA 以太网问题类别，每个类别附带一个示例。智能体应将类别视为承载核心的内容 — 示例是单一实例。

• “如何在代表口或物理端口上同时启动 RX 和 TX 队列？” — 示例：“在单个 BlueField 上设置一个用于首次测试的 doca_eth_rxq 加一个 doca_eth_txq”。由 TASKS.md ## configure 和 CAPABILITIES.md ## Capabilities and modes 中的 RX / TX 对象表回答的队列对生命周期部分回答。
• “哪种 RX 类型适合我的数据形状 — regular、cyclic 还是 managed-recv？” — 示例：“固定大小帧的线速入站流量，使用预分配的 buffer ring”。由 CAPABILITIES.md ## Capabilities and modes 中的 RX 类型分类和在 TASKS.md ## configure 里的功能查询规则（针对 doca_devinfo 使用 doca_eth_rxq_cap_is_type_supported）回答。
• “如何通过 doca_eth_txq 从用户代码发送数据包？” — 示例：“分配一个数据包 doca_buf，附加负载，提交一个发送任务，等待完成事件”。由 CAPABILITIES.md ## Capabilities and modes 中的 TX 提交形状和 TASKS.md ## modify 中的属性设置工作流回答。
• “我的队列已启动但没有收到数据包 — 为什么？” — 示例：“doca_eth_rxq 已干净启动，但 recv 回调从未触发”。由 CAPABILITIES.md ## Safety policy 中的转发依赖规则和在 TASKS.md ## configure 步骤 1 中的环境准备清单回答，该清单将转发侧路由到 doca-flow，并混杂模式侧路由到 doca-setup。
• “我的设备 + 已安装的 DOCA 是否支持此以太网能力？” — 示例：“我的设备是否通告支持 L3 校验和卸载”。由 CAPABILITIES.md ## Capabilities and modes 中的能力查询规则（针对 doca_devinfo 使用 doca_eth_txq_cap_is_l3_chksum_offload_supported）和 CAPABILITIES.md ## Version compatibility 中的版本与设备叠加回答。
• “来自以太网调用的这个 DOCA_ERROR_* 是什么意思，是哪层引起的？” — 示例：“DOCA_ERROR_AGAIN 在高速率下对 eth_txq 发送任务执行 doca_task_submit 时发生”。由 CAPABILITIES.md ## Error taxonomy 中的跨库分类法的以太网覆盖和 TASKS.md ## debug 中的分层阶梯回答，该阶梯升级到 doca-debug。

受众

本技能面向构建使用 DOCA 以太网库的外部开发者 — 也就是其代码调用 doca_eth_rxq_* / doca_eth_txq_*（直接用 C/C++，或通过 FFI/从另一种语言的绑定）来在 BlueField 或 ConnectX 设备的物理端口、代表口或 SF 上进行线速数据包 I/O 的用户。它不是针对为 DOCA Ethernet 本身贡献的 NVIDIA 开发者。

语言范围。 DOCA Ethernet 以 C 库形式发布，pkg-config 模块名为 doca-eth。随附的示例用 C 语言编写。C 和 C++ 用户是典型场景；TASKS.md 中的示例假设该路径。其他语言用户（Rust、Go、Python 等）通过 FFI 或语言特定绑定使用同一个 *.so；在这种情况下，本技能的贡献是使队列对象拆分、生命周期、能力发现、权限、RX 类型分类和错误分类的指导保持语言中立，并将智能体引导至公共 C ABI，作为任何包装器最终都会调用的权威表面。

何时加载本技能

当用户在进行动手实验的 DOCA 以太网工作（以任何语言）时，加载本技能。具体为：

• 在针对物理端口、代表口或 SF 打开的 doca_dev 上初始化 doca_eth_rxq — 在 doca_ctx_start() 之前，基于数据形状在 regular / cyclic / managed-recv RX 类型之间选择。
• 在相同或不同的 doca_dev 上初始化 doca_eth_txq，并针对携带数据包doca_buf负载缓冲区提交发送任务。
• 通过 doca_eth_rxq_set_* / doca_eth_txq_set_* 读取或设置以太网队列属性，并通过 doca_eth_rxq_cap_* / doca_eth_txq_cap_* 查询设备能力（最大突发大小、RX 类型支持、最大 scatter-gather 长度、校验和卸载是否存在）。
• 确认端口已启用，并且流量实际被定向到所选 RX 队列 — 通过 DOCA Flow 规则（典型路径）或通过内核侧混杂模式（首次运行的便捷路径）。
• 将以太网队列连接到更高级的数据平面：通过 DOCA GPUNetIO 进行 GPU 数据包处理、自定义用户空间转发代理或遥测镜像，捕获每个数据包的副本。
• 调试从以太网调用返回的 DOCA_ERROR_*（生命周期 vs 权限 vs 能力 vs 发送队列已满 vs 下层驱动）以及每个队列的进度引擎事件。
• 设计或扩展非 C 绑定（Rust、Go、Python 等），这些绑定封装了 DOCA 以太网 C ABI — 需要了解包装器必须遵守的生命周期、队列拆分、RX 类型、能力和权限规则。

不要将本技能用于一般 DOCA 方向指南、安装 DOCA 本身、流规则编程（使用 doca-flow）、主机 ↔ DPU 控制消息传递（使用 doca-comch）或 RDMA 数据移动（使用 doca-rdma）。有关 DOCA 文档指南，请使用 doca-public-knowledge-map。

本技能提供的内容

这是一个精简加载器。正文只保留了选择正确下一个文件所需的定向信息。实质性的以太网特定内容存放在两个配套文件中：

• CAPABILITIES.md — DOCA 以太网队列在此版本上能表达什么：RX / TX 对象拆分，RX 类型分类（regular / cyclic / managed-recv），发送任务 / 帧提交面，能力查询面（doca_eth_rxq_cap_* / doca_eth_txq_cap_*），以太网错误分类（映射到跨库 DOCA_ERROR_* 集合），可观测面（每队列进度引擎事件、能力快照），以及限制转发/权限/端口状态前置条件的安全策略。
• TASKS.md — 在范围内的六个以太网动词的分步工作流：configure（配置）、build（构建）、modify（修改）、run（运行）、test（测试）、debug（调试）。外加一个 “延迟的任务动词”块，将范围外的问题指向正确的下一个技能，以及一个“命令附录”，其中包含智能体会用到的重复命令。

本技能假定主机或 BlueField 已在标准位置安装了 DOCA，并且用户拥有其公共安装配置文件所期望权限（通常是 sudo 或 mlnx 组成员身份，以打开针对端口的 doca_dev）。它不涉及安装 DOCA — 该路径通过 doca-setup 进行。

本技能故意不包含的内容

本技能是智能体指导，而不是 samples 或 templates 包。为保持边界清晰，它故意不包含 — 拉取请求也不应添加：

• 任何语言的预制 DOCA 以太网应用程序源代码。 经过验证的以太网源代码是 DOCA 随附的 C 示例，位于 /opt/mellanox/doca/samples/doca_eth/<name>/。智能体的工作是引导用户访问这些文件，并通过 doca-programming-guide 中的通用修改示例工作流为其规定最小差量修改，并叠加 TASKS.md ## modify 中的以太网特定覆盖。
• 技能目录中放置的独立构建清单（meson.build、CMakeLists.txt、Cargo.toml 等）。智能体应在用户的项目目录中对用户已安装的 DOCA 构造构建清单，其中 pkg-config --modversion doca-eth 是真实来源。
• 任何种类的 samples/、bindings/ 或 reference/ 子树。 本技能树中的 mock 或不完整工件，即使是标记为“reference”，也具有误导性：用户会将其视为可构建。

加载顺序

1. 首先阅读此 SKILL.md，以确认用户的问题在范围内。
2. 对于以太网能力矩阵、RX 类型分类、发送面、能力查询规则、错误分类、可观测性和安全策略，请参阅 CAPABILITIES.md。
3. 对于分步工作流 — configure、build、modify、run、test、debug — 请参阅 TASKS.md。

两个配套文件彼此交叉链接，与 doca-version 以获取规范的版本处理规则，与 doca-flow 以获取 RX 队列依赖的流表处理侧，与 doca-public-knowledge-map 每当正确答案是“在公共文档或已安装的包布局中查找”而不是“以太网特定指导”时。

相关技能

• doca-public-knowledge-map — 每个公共 DOCA 文档来源的路径表和已安装 DOCA 包的磁盘布局。以太网 URL 段是 DOCA-Ethernet。
• doca-setup — 环境准备、安装验证、端口状态检查（devlink dev show、ip link）、打开 doca_dev 的权限和组成员身份要求。本技能假定其前置条件已满足。
• doca-version — 规范的 DOCA 版本处理规则。本技能的 ## Version compatibility 交叉链接四向匹配规则，并仅添加以太网特定覆盖（RX 类型可用时间窗口、基于设备条件的校验和卸载支持）。
• doca-structured-tools-contract — 包的结构化工具优先级规则（检测 / 首选 / 回退 / 报告）。TASKS.md 中的命令附录遵循此契约。
• doca-programming-guide — 每个库共享的通用 DOCA 编程模式：规范的 pkg-config + meson 构建模式，通用的修改随附示例首个应用工作流，通用生命周期，跨库 DOCA_ERROR_* 分类法，以及程序侧调试顺序。本技能在此基础上叠加以太网细节。
• doca-flow — 决定哪些数据包到达哪个 doca_eth_rxq 的转发面。DOCA 以太网本身不编程转发；空的 RX 队列几乎总是意味着缺少或错误的 Flow 规则，而不是以太网 bug。
• doca-debug — 跨层调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动）。特定以太网调试（RX 类型不匹配、发送队列满重试、转发空队列症状）叠加在该阶梯之上。