doca-eth

DOCA Ethernet

示例

• “我的 RX 队列已启动，但没有收到数据包。” — RX 和 TX 是两个 Core 上下文；一次 doca_ctx_start() 并不能同时启动两者。
• “发送任务在达到线速时返回 AGAIN。” — 修改队列类型前，先根据 _cap_* 查询结果确定突发大小。

说明

请遵循下文的加载顺序。打开任务配套文件以了解配置／ 构建／运行。打开能力配套文件以了解 RX 类型分类 和发送接口。不要打开所有配套文件。

从这里开始： 此技能假定 DOCA 已安装， 且用户正在主机或 BlueField 上进行 数据包队列的实际操作。 如果用户想要执行某项操作（配置／构建／修改／运行／ 测试／调试），请打开任务配套文件；如果用户想了解 此版本的 DOCA Ethernet 队列能够表达什么，请打开能力配套文件。如果 用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。RX 和 TX 是 相互独立的 Core 上下文。 doca_eth_rxq 和 doca_eth_txq 各自都需要自己的 doca_ctx_create / _start / _stop / _destroy；一次 doca_ctx_start() 不会同时启动两侧。 不要把“队列对”视为单一生命周期来讲解。如果用户问的是 “如何让数据包进入我的 RX 队列”，答案在 doca-flow/SKILL.md 中 — DOCA Ethernet 是队列接口；DOCA Flow 是流量导向 接口，两者是独立的库。

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

此技能旨在回答的 DOCA Ethernet 问题类别，每类附带一个完整示例。Agent 应将类别视为核心要点——完整示例只是其中一个具体实例。

• “如何在 representor 或物理端口上启动 RX 和 TX 队列？”——完整示例：“在单个 BlueField representor 上设置一个 doca_eth_rxq 和一个 doca_eth_txq，用于首次运行测试”。由两个独立的 Core 上下文（各自有自己的启动步骤）回答，参见

  configure +

  Capabilities and modes

  中的 RX / TX 对象表。
• “哪种 RX 类型适合我的数据形态——常规型、循环型还是 managed-recv？”——完整示例：“将固定大小的帧接收到预分配缓冲区环中，实现线速入口流量”。由

  Capabilities and modes

  中的 RX 类型分类，以及

  configure

  中的能力查询规则（针对 doca_devinfo 调用 doca_eth_rxq_cap_is_type_supported）回答。
• “如何通过 doca_eth_txq 从用户代码发送数据包？” ——完整示例：“分配一个数据包 doca_buf，附加负载，提交一个发送任务，等待完成事件”。 由

  Capabilities and modes

  中的 TX 提交方式，以及

  modify

  中的属性设置工作流回答。
• “队列已启动，但没有数据包到达——为什么？”——完整示例： “doca_eth_rxq 已正常启动，但接收回调始终未触发”。由

  Safety policy

  中的流量转向依赖规则，以及

  configure step 1

  中的环境准备检查清单回答；该清单会将流量转向部分指向 doca-flow/SKILL.md，并将混杂模式部分指向 doca-setup/SKILL.md。
• “我的设备和已安装的 DOCA 是否支持此 Ethernet 能力？”——完整示例：“此设备是否声明支持 L3 校验和卸载”。由

  Capabilities and modes

  中的能力查询规则（针对 doca_devinfo 调用 doca_eth_txq_cap_is_l3_chksum_offload_supported），以及

  Version compatibility

  中的版本和设备补充说明回答。
• “Ethernet 调用返回的这个 DOCA_ERROR_* 是什么意思？是哪个层导致的？”——完整示例：“高数据速率下对 eth_txq 发送任务调用 doca_task_submit 时返回 DOCA_ERROR_AGAIN”。由

  Error taxonomy

  中针对跨库分类的 Ethernet 补充说明，以及

  debug

  中最终指向 doca-debug/SKILL.md 的分层排查路径回答。

当多个层都可能解释某个症状时，如何选择根因所在层。 从底层向上逐层检查（安装 → 版本 → 构建 → 链接 → 运行时 → 程序 → 驱动），并使用 TASKS.md ## debug 中各层指定的只读检查。检查失败的最低层就是根因：修复问题，每次只更改一个变量，并在继续向上排查前重新运行相同的检查。对于无响应的 RX 队列，在排查程序或驱动原因前，先排除三项运行时前提（设备访问权限、端口已启动、流量已转向该队列）。

受众

此技能面向使用 DOCA Ethernet 库构建应用的外部开发者——也就是通过 doca_eth_rxq_* / doca_eth_txq_*（直接使用 C/C++，或通过其他语言的 FFI/绑定）调用代码，以便在 BlueField 或 ConnectX 设备的物理端口、representor 或 SF 上实现线速数据包 I/O 的用户。此技能不面向为 DOCA Ethernet 本身做贡献的 NVIDIA 开发者。

语言范围。 DOCA Ethernet 以 C 库形式提供，pkg-config 模块名称为 doca-eth。随库提供的示例使用 C 编写。C 和 C++ 消费者是典型用例；任务配套材料中的完整示例均假设采用这种方式。其他语言的消费者（Rust、Go、Python、……）通过 FFI 或特定语言绑定使用相同的 *.so；在这种情况下，此技能的作用是确保队列对象划分、生命周期、能力发现、权限、RX 类型分类和错误分类方面的指导不依赖于语言，并引导 Agent 以公开的 C ABI 作为权威接口，因为任何封装最终都会调用该接口。

何时加载此技能

用户使用任意语言进行 DOCA Ethernet 实操时，加载此技能。具体包括：

• 在针对物理端口、representor 或 SF 打开的 doca_dev 上初始化 doca_eth_rxq——在 doca_ctx_start() 之前，根据数据形态在常规 / 循环 / 托管接收 RX 类型之间选择。
• 在同一个或不同的 doca_dev 上初始化 doca_eth_txq，并针对数据包 doca_buf 载荷缓冲区提交发送任务。
• 通过 doca_eth_rxq_set_* / doca_eth_txq_set_* 读取或设置 Ethernet 队列属性，并通过 doca_eth_rxq_cap_* / doca_eth_txq_cap_* 查询设备能力（最大突发大小、RX 类型支持、最大散布-聚集长度、是否支持校验和卸载）。
• 确认端口已启动，且流量确实被导向所选 RX 队列——通过 DOCA Flow 规则（标准路径）或内核侧混杂模式（便于首次运行的路径）。
• 将 Ethernet 队列连接到更高层的数据平面：通过 DOCA GPUNetIO 处理 GPU 数据包、自定义用户空间转发 Agent，或捕获每个数据包副本的遥测镜像。
• 调试 Ethernet 调用返回的 DOCA_ERROR_*（生命周期、权限、能力、发送队列已满或底层驱动问题），以及每队列进度引擎事件。
• 设计或扩展封装 DOCA Ethernet C ABI 的非 C 绑定（Rust、Go、Python 等）——遵循封装必须遵守的生命周期、队列拆分、RX 类型、能力和权限规则。

不要在以下情况下加载此技能：了解 DOCA 的一般信息、安装 DOCA 本身、编写流规则（使用 doca-flow/SKILL.md）、进行主机 ↔ DPU 控制消息传递（使用 doca-comch/SKILL.md）或 RDMA 数据移动（使用 doca-rdma/SKILL.md）。 了解 DOCA 文档的概况，请使用 doca-public-knowledge-map/SKILL.md。

此技能提供的内容

这是一个轻量级加载器。正文只保留用于选择合适后续文件的概览信息。实质性的 Ethernet 专属内容位于两个配套文件中：

• 能力配套文件——说明此版本的 DOCA Ethernet 队列支持哪些功能：RX / TX 对象拆分、RX 类型分类（常规 / 循环 / 托管接收）、发送任务 / 帧提交接口、能力查询接口（doca_eth_rxq_cap_* / doca_eth_txq_cap_*）、Ethernet 错误分类（映射到跨库的 DOCA_ERROR_* 集合）、可观测性接口（每队列进度引擎事件、能力快照），以及用于约束转向 / 权限 / 端口状态前置条件的安全策略。
• 任务配套文件——针对六种适用的 Ethernet 操作 verb，提供逐步工作流：configure、build、modify、run、test、debug。此外还包括一个 Deferred task verbs 区块，将范围外的问题指向合适的后续技能；以及一个 Command appendix，列出 Agent 经常使用的命令。

此技能假设主机或 BlueField 已在标准位置安装 DOCA，且用户拥有其公开安装配置要求的权限（通常需要 sudo 权限或属于 mlnx 组，才能针对端口打开 doca_dev）。 此技能不涵盖安装 DOCA——请参阅 doca-setup/SKILL.md。

本技能有意不包含的内容

本技能是Agent 指南，而非示例或模板合集。为明确边界，本技能有意不包含以下内容，拉取请求也不应添加：

• 任何语言编写的预先编写好的 DOCA Ethernet 应用源代码。 已验证的 Ethernet 源代码是随附的 C 示例，位于 /opt/mellanox/doca/samples/doca_eth/<name>/。Agent 的任务是引导用户找到这些文件，并按照 doca-programming-guide/SKILL.md 中的通用修改示例工作流，对其进行最小差异修改，再叠加 ## modify 中针对 Ethernet 的专属覆盖规则。
• 单独的构建清单（meson.build、CMakeLists.txt、Cargo.toml 等），不得放在本技能中。Agent 会在用户的项目目录中，针对用户已安装的 DOCA 构建清单；pkg-config --modversion doca-eth 是唯一可信依据。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录。 即使标注为“reference”，本技能目录树中的模拟或不完整文件也会造成误导：用户会以为它们可以构建。

加载顺序

1. 首先阅读本技能，确认用户的问题属于其涵盖范围。
2. 有关 Ethernet 能力矩阵、RX 类型分类、发送接口、能力查询规则、错误分类、可观测性和安全策略，请参阅能力配套文档。
3. 有关分步工作流——配置、构建、修改、运行、测试、调试——请参阅任务配套文档。

这两个配套文件彼此交叉链接，还会链接到 doca-version/SKILL.md（其中包含规范的版本处理规则）、doca-flow/SKILL.md（其中包含 RX 队列所依赖的流量引导部分），以及 doca-public-knowledge-map/SKILL.md；当正确答案是“查阅公开文档或已安装的软件包布局”，而不是“Ethernet 专属指南”时，应参阅后者。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档来源的路由表，以及已安装 DOCA 软件包的磁盘布局。Ethernet 的 URL 路径段是 DOCA-Ethernet。
• doca-setup/SKILL.md — 环境准备、安装验证、端口状态检查（devlink dev show、ip link），以及打开 doca_dev 所需的权限和组成员资格要求。本技能假定这些前置条件已满足。
• doca-version/SKILL.md — DOCA 版本处理的规范规则。本技能的 ## Version compatibility 交叉链接到四方匹配规则，并且只补充 Ethernet 专属的覆盖内容（RX 类型可用性时间窗口、依赖设备的校验和卸载支持）。
• doca-structured-tools-contract/SKILL.md — 此工具包的结构化工具优先级规则（检测／优先使用／回退／报告）。任务配套文档中的命令附录遵循此约定。
• doca-programming-guide/SKILL.md — 各库通用的 DOCA 编程模式：规范的 pkg-config + meson 构建模式、通用的“先修改随附示例”首个应用工作流、通用生命周期、跨库 DOCA_ERROR_* 分类，以及程序端调试顺序。本技能在此基础上叠加 Ethernet 专属内容。
• doca-flow/SKILL.md — 决定哪些数据包进入哪个 doca_eth_rxq 的流量引导接口。DOCA Ethernet 不会自行配置流量引导；RX 队列为空几乎总是意味着缺少 Flow 规则或规则有误，而不是 Ethernet 的问题。
• doca-debug/SKILL.md — 通用调试阶梯（安装／版本／构建／链接／运行时／程序／驱动程序）。Ethernet 专属调试问题（RX 类型不匹配、发送队列已满时的重试、流量引导导致队列为空的症状）会叠加在该阶梯之上。