doca-rmax

DOCA Rivermax

示例

• “ST 2110 接收端没有收到帧。” — 如果已安装 Rivermax SDK 和许可证，这属于适用范围。
• “doca_rmax_init 返回 NOT_SUPPORTED。” — 在更改流设置前，先运行 doca_rmax_get_*_supported 查询。

说明

请遵循下文的加载顺序。需要配置 / 流 / 调试方面的帮助时，打开任务配套文件。需要了解 Rivermax 前置条件时，打开功能配套文件。不要打开所有配套文件。

从这里开始： 此技能假设目标 BlueField DPU 上已安装 DOCA（DOCA Rivermax 应用只能在目标 DPU 上运行），并且已安装 Rivermax 库（来自 DOCA 仓库的 doca-sdk-rmax / libdoca-sdk-rmax-dev），且 DPU 上有有效的 Rivermax 许可证。Agent 遇到任何 Rivermax 问题时，首要操作是确认这两项——没有 Rivermax 库和许可证，无论 DOCA 侧代码多么完善，doca-rmax 都无法运行；这是首次使用时最常见的困惑（Rivermax 许可证以及 Rivermax SDK 页面提到的驱动，需从 DOCA 之外单独获取）。如果用户想要执行某项操作（配置 / 构建 / 修改 / 运行 / 测试 / 调试），请打开任务配套文件；如果用户询问此版本及当前 Rivermax 安装能够实现什么，请打开功能配套文件。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md；要安装 Rivermax SDK 和许可证，请转到公开的 DOCA Rivermax 指南（slug DOCA-Rivermax），路径为 doca-public-knowledge-map/SKILL.md。如果用户问的是*“如何让数据包进入 Rivermax 输入流？”，答案分为多个层面：doca-rmax 是Rivermax 集成接口，doca-eth/SKILL.md 是承载数据包的队列接口，而 doca-flow/SKILL.md 是将数据包导向目标位置的转发规则*接口。

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

此技能旨在回答的 DOCA Rivermax 问题类别，每类附有一个经过演练的示例。Agent 应将类别视为核心内容；经过演练的示例只是一个具体实例。

• “我能在这台主机上使用 doca-rmax 吗？” — 经过演练的示例：“公开文档提到了 doca-rmax；无需做其他操作就能使用吗？”。答案来自 ## Safety policy 中的 Rivermax-SDK + 许可证前置条件规则，以及 ## configure step 1 中的环境准备清单；该清单会通过 doca-public-knowledge-map/SKILL.md 将安装相关问题引导至公开的 Rivermax 指南，并拒绝建议仅回退到 doca-eth，以免悄然丢失时序属性。
• “如何设置 SMPTE ST 2110 视频接收流？” — 经过演练的示例：*“在 BlueField 端口的 representor 上配置一个入站 Rivermax 流，以进行首次测试。”*答案来自 ## configure 中的逐流对象生命周期，以及 ## Capabilities and modes 中的输入流能力表。
• “在选择 PTP 时钟或硬件包放置顺序之前，我必须调用哪个 doca_rmax_get_*_supported 查询？” — 经过演练的示例：*“这台设备和这次 Rivermax 安装能否使用 ST 2110-20 序列号放置？”*答案来自 ## Capabilities and modes 中的能力查询规则，以及 ## configure 中的步骤 3。
• “我的流已设置好，但没有数据包到达——为什么？” — 经过演练的示例：*“Rivermax 流对象已成功启动，但没有触发 recv 事件。”*答案来自 ## Safety policy 中的前置条件矩阵，以及 ## configure step 1 中的环境准备清单；该清单会将流量引导问题转至 doca-flow/SKILL.md，将队列问题转至 doca-eth/SKILL.md，并将许可证问题引回 Rivermax 侧的前置条件。
• “这项 Rivermax 集成能力在我的设备、已安装的 DOCA 和 Rivermax SDK 上可用吗？” — 经过演练的示例：“这台设备和这个 Rivermax 版本是否提供我需要的 PTP 时钟或放置模式？”答案来自能力查询规则，以及 ## Version compatibility 中的版本和设备补充规则；后者在 doca-version/SKILL.md 中规范的 DOCA 版本处理流程之上，增加了Rivermax 侧版本是第二个维度这一规则。
• “Rivermax 调用返回的这个 DOCA_ERROR_* 是什么意思？是哪个层导致的？” — 经过演练的示例：*“doca_rmax_init() 返回 DOCA_ERROR_NOT_SUPPORTED。”*答案来自 ## Error taxonomy 中对跨库错误分类的 Rivermax 补充说明，以及 ## debug 中会升级至 doca-debug/SKILL.md 的分层排查流程；同时保留已安装头文件中针对具体调用的映射：初始化时的 _NOT_SUPPORTED 会首先引导至 Rivermax SDK／许可证检查；后续错误则根据确切的失败调用进行解释，而不会一概归结为许可证问题。

适用对象

此技能面向构建应用以使用 DOCA Rivermax 集成的外部开发者，即其代码调用 doca_rmax_*（直接使用 C/C++，或通过其他语言的 FFI/绑定）来驱动时序精确的 IP 媒体流（SMPTE ST 2110、实时市场数据、高吞吐量科学仪器数据流），并在 BlueField 或 ConnectX 主机上运行于单独安装的 NVIDIA Rivermax SDK 之上。此技能不适用于为 DOCA Rivermax 本身做贡献的 NVIDIA 开发者，也不适用于需要尽力而为型数据包 I/O 的用户——此类用户应直接转到 doca-eth/SKILL.md。

语言范围。 DOCA Rivermax 以 C 库的形式提供，其 pkg-config 模块名为 doca-rmax。随附的示例位于 /opt/mellanox/doca/samples/doca_rmax/ 下，使用 C 编写。C 和 C++ 用户是主要适用对象；任务配套材料中的示例也基于这种情况。使用其他语言的用户（Rust、Go、Python 等）通过 FFI 或特定语言的绑定使用同一个 *.so；在这种情况下，此技能的作用是确保关于前置条件（Rivermax SDK 和许可证）、每个流的生命周期、能力发现、权限、调度规范以及错误分类的指导不依赖特定语言，并引导 Agent 将公共 C ABI 作为权威接口，因为任何封装最终都会调用该接口。

何时加载此技能

当用户正在使用 DOCA Rivermax 进行实际操作时，无论使用哪种语言，都应加载此技能。具体包括：

• 在编写任何 DOCA 侧代码之前，确认主机上已安装 NVIDIA Rivermax SDK，且存在有效的 Rivermax 许可证——这是强制前提条件，而不是错误处理路径；如果不满足，回答应是 “无法使用 doca-rmax；请选择其他库”，而不是 “先试试看会出什么问题”。
• 使用 doca_rmax_init() / doca_rmax_release() 初始化全局 DOCA Rivermax 引擎，然后在针对物理端口、representor 或 SF 打开的 doca_dev 上，通过 doca_rmax_in_stream_create() 创建 doca_rmax_in_stream（接收）上下文，并在调用 doca_ctx_start() 之前通过 doca_rmax_in_stream_as_ctx() 将其转换。公开的 DOCA Rivermax API 仅支持接收——没有发送／输出流对象。
• 为 SMPTE ST 2110 IP 音视频、实时市场数据馈送或科学仪器数据流配置 Rivermax 输入流——需注意，PTP 时钟和硬件包放置顺序支持因设备和 Rivermax 而异，且必须通过匹配的 doca_rmax_get_*_supported 查询进行检查。
• 通过 doca_rmax_in_stream_set_* 读取或设置 Rivermax 流属性，并在假定支持 PTP 时钟或硬件包放置顺序之前，通过 doca_rmax_get_*_supported 系列查询设备和 Rivermax 的能力。
• 将 Rivermax 流与承载数据包的 doca-eth 队列接口，以及负责引导数据包的 doca-flow 规则配合使用——Rivermax 本身不会配置流量引导。
• 为流处理线程设计实时调度策略（底层 Rivermax 堆栈要求使用实时优先级，才能将抖动控制在微秒以下；权威调度指南位于通过 doca-public-knowledge-map/SKILL.md 可访问的 Rivermax SDK 文档中）。
• 调试 Rivermax 调用返回的 DOCA_ERROR_*（生命周期、许可证／权限、能力或底层驱动问题）；问题可能出在 DOCA 侧封装、底层 Rivermax 堆栈或许可层。
• 设计或扩展非 C 绑定（Rust、Go、Python 等），以封装 DOCA Rivermax C ABI——封装必须遵守前提条件、生命周期、能力、权限和调度规则。

不要在以下情形加载此技能：一般性了解 DOCA、安装 DOCA 本身、安装 Rivermax SDK 或管理 Rivermax 许可证文件（这些内容位于通过 doca-public-knowledge-map/SKILL.md 可访问的公开 Rivermax SDK 指南中）、无需时序要求的尽力而为型数据包 I/O（直接使用 doca-eth/SKILL.md），或纯粹在主机侧进行不涉及网络的数据处理。关于 DOCA 文档的使用指引，请参阅 doca-public-knowledge-map/SKILL.md。

此技能提供的内容

这是一个轻量加载器。正文仅保留用于确定下一步应查看哪个文件的指引。实质性的 Rivermax 专属内容位于两个配套文件中：

• capabilities 配套文件 — 说明 DOCA Rivermax 在此版本以及此 Rivermax SDK 安装中能够实现什么：Rivermax 是硬依赖的规则、仅接收的 doca_rmax_in_stream 对象模型、能力查询接口（doca_rmax_get_*_supported）、Rivermax 错误分类（映射到跨库的 DOCA_ERROR_* 集合，并在每一行中指出 Rivermax 专属原因）、可观测性接口（每个流的进度引擎事件、能力快照、Rivermax 侧的许可证和驱动程序状态），以及用于约束 Rivermax SDK 已安装／许可证有效／设备可访问／遵守调度规范等前置条件的安全策略。
• tasks 配套文件 — 针对六个适用的 Rivermax 动词，提供分步工作流：configure、build、modify、run、test、debug。此外还包含 Deferred task verbs 区块，将范围外问题（安装 Rivermax、管理许可证、编程配置流量导向、编程配置底层队列）指向正确的下一项技能；以及一个 Command appendix，列出 Agent 常用的命令。

此技能假定主机或 BlueField 上已在标准位置安装 DOCA，NVIDIA Rivermax SDK 已安装在预期位置且许可证有效，并且用户拥有其公开安装配置所需的权限（通常需要 sudo 权限或属于 mlnx 组，才能为端口打开 doca_dev）。此技能不涵盖安装 DOCA — 此流程请参阅 doca-setup/SKILL.md。此技能不涵盖安装 Rivermax 或其许可证 — 此流程请参阅可通过 doca-public-knowledge-map/SKILL.md 找到的公开 Rivermax SDK 指南。

此技能有意不提供的内容

此技能提供的是Agent 指引，而不是示例或模板包。为明确界限，此技能有意不包含以下内容，且不应通过拉取请求添加：

• 任何语言编写的预先编写的 DOCA Rivermax 应用程序源代码。 已验证的 Rivermax 源代码是随附的 C 示例，位于 /opt/mellanox/doca/samples/doca_rmax/<name>/。Agent 的工作是引导用户找到这些文件，并通过 doca-programming-guide/SKILL.md 中的通用修改示例工作流，针对这些文件给出最小差异修改建议，再叠加 ## modify 中 Rivermax 专属的覆盖规则。
• 独立的构建清单（meson.build、CMakeLists.txt、Cargo.toml 等）放在技能目录中。Agent 应在用户的项目目录中，针对用户已安装的 DOCA 构建清单，其中 pkg-config --modversion doca-rmax 是事实依据。
• 超出公共系列模式的带引号的 Rivermax 符号名称（能力发现使用 doca_rmax_get_*_supported，会话对象使用由标准 DOCA Core 上下文生命周期驱动的仅接收 doca_rmax_in_stream）。具体的 Rivermax 符号名称取决于安装内容和 Rivermax SDK 版本；Agent 应从已安装的头文件（位于 $(pkg-config --variable=includedir doca-common)）以及公开 DOCA Rivermax 指南中读取，而不要依赖 Agent 的记忆。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录。 技能目录中的模拟或不完整内容，即使标注为*"参考"*，也会造成误导：用户会以为它可以构建。

加载顺序

1. 首先阅读此技能，确认用户的问题 属于适用范围，并且已考虑 Rivermax-SDK + 许可证 前置条件。
2. 有关 Rivermax 能力矩阵、仅接收的输入 流模型、能力查询规则、错误分类、 可观测性和安全策略，请参阅 capabilities companion。
3. 有关分步工作流——配置、构建、修改、 运行、测试、调试——请参阅 tasks companion。

这两个配套文件会彼此交叉链接， doca-version/SKILL.md，用于了解权威的 DOCA 版本处理规则（Rivermax 在此基础上 额外增加 Rivermax-SDK 版本这一维度）， doca-eth/SKILL.md，用于了解承载数据包的队列 接口， doca-flow/SKILL.md，用于了解决定哪些数据包进入哪个队列的 流量导向接口，以及 doca-public-knowledge-map/SKILL.md， 当正确答案是“查阅公开的 Rivermax SDK 指南或已安装的软件包布局”，而不是 “Rivermax 集成专属指导”时。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档来源和已安装 DOCA 软件包磁盘布局的 路由表。Rivermax 的 URL slug 是 DOCA-Rivermax；当用户询问如何安装 Rivermax 或其 许可证时，可从同一张路由表访问公开的 Rivermax SDK 指南（独立产品）。
• doca-setup/SKILL.md — 环境准备、 安装验证、端口状态检查（devlink dev show、 ip link）、打开 doca_dev 所需的权限和组成员资格要求。此技能假定其 前置条件已满足；Rivermax-SDK + 许可证前置条件 则在此基础上叠加。
• doca-version/SKILL.md — 权威的 DOCA 版本处理规则。此技能的 ## Version compatibility 交叉链接了四方匹配规则，并增加了 Rivermax 专属的补充规则（Rivermax SDK 版本是 第二个维度；此主机上的能力集是 DOCA 侧能力查询结果与 Rivermax 侧能力的交集）。
• doca-structured-tools-contract/SKILL.md — 本套件的结构化工具优先级规则（检测 / 优先使用 / 回退 / 报告）。tasks companion 中的 Command 附录遵循此约定。
• doca-programming-guide/SKILL.md — 各库通用的 DOCA 编程模式： 权威的 pkg-config + meson 构建模式、 通用的“先修改已提供的示例”首次应用工作流、通用生命周期、跨库的 DOCA_ERROR_* 错误分类，以及程序侧的调试顺序。此技能在此基础上叠加 Rivermax 专属内容。
• doca-eth/SKILL.md — 承载 Rivermax 流生成或 消费的数据包的队列接口。DOCA Rivermax 不会编程底层 队列；它会与通过 doca-eth 编程的队列集成。两种技能的生命周期相互独立。
• doca-flow/SKILL.md — 决定哪些数据包进入哪个队列的流量 导向接口。DOCA Rivermax 不会自行编程流量导向；Rivermax 输入流为空，几乎总是意味着缺少或错误的 Flow 规则（或缺少 Rivermax 许可证），而不是 Rivermax 错误。
• doca-debug/SKILL.md — 跨领域的调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动）。Rivermax 专属调试内容 （许可证前置条件缺失、流类型 / 数据包速率 能力不匹配、调度策略导致的抖动 症状）叠加在此阶梯之上。