doca-spcx-cc

DOCA SPCX 拥塞控制工具

示例

• “针对自定义 CC 算法，我应该使用 SPCX 还是 doca-pcc？”——这属于本工具的范围。在实时网络上加载任何内容前，请先走完决策树。
• “SPCX 已加载，但吞吐量没有变化。”——调整参数前，请先确认该算法正在生效。

说明

请遵循下文的加载顺序。打开任务配套文档，了解如何配置／运行。打开功能配套文档，了解 SPCX 与 PCC 的权衡及安全性。不要打开所有配套文件。

**从这里开始：**这是一个用于调用 doca_spcx_cc 的工具技能——该命令行界面有文档说明，可在由搭载 DPA 处理器的 BlueField 驱动的实时 RDMA／RoCE 网络上运行 SPCX 类可编程拥塞控制算法。打开任务配套文档，从 ## configure 开始，了解 SPCX、PCC 与出厂固件之间的决策树（这是编写任何代码前必须经过的关键门槛）、角色选择（RP／NP）、DPA 端算法编写与使用的区别，以及实时链路／竞争条件这一前提。如果问题涉及SPCX 能表达哪些 doca-pcc 无法表达的内容、SPCX 与 PCC 的权衡是什么、该工具会提供哪些运行时指标，或在生产网络上加载自定义 CC 算法时应采取何种安全措施，请打开功能配套文档。如果尚未安装 DOCA，请先转到 doca-setup/SKILL.md。

此技能是新一代可编程 CC 接口。doca-pcc/SKILL.md 介绍成熟的 PCC 方案；SPCX 则是在相同 DPA 硬件基础上编写 SPCX 类算法的有文档说明的扩展。doca-pcc-ztr-rttcc-algo/SKILL.md 是一个随附的参考算法（基于 RTT 的零接触 CC），根据安装情况和用户选择的算法，可通过 PCC 或 SPCX 路径加载；Agent 会按照功能配套文档明确展示这一决策树。

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

此技能旨在回答以下 doca_spcx_cc 问题类别，每类都附有一个完整示例。类别是关键所在；完整示例只是其中一个实例。

• “对于自定义 CC 算法，我应该使用 SPCX 还是 doca-pcc？” — 完整示例：“我想为 RoCE 网络编写一种新的、基于 RTT 的拥塞控制算法——应该针对哪个接口？”。答案来自 capabilities 伴随文档中的 SPCX、PCC 与出厂固件决策树，以及 tasks 伴随文档步骤 1 中的 “此安装是否适合使用 SPCX 接口？” 检查。
• “在将我编写的 SPCX 算法用于生产环境之前，如何在真实 RDMA 链路上对其进行评估？” — 完整示例：“我有一个通过 DPACC 编译的 SPCX 算法和一对非生产环境 BlueField 设备；如何运行一次能够产生争用的评估？”。答案来自 capabilities 伴随文档中的编写与使用之分，以及实时链路前提条件，再加上 tasks 伴随文档中的副本优先评估流程。
• “我的 SPCX 算法似乎加载正常，但链路的吞吐量／延迟曲线没有变化——这是怎么回事？” — 完整示例：“主机端的 doca_pcc --status 报告 Active 且会话稳定，但我的 RoCE 流量看起来没有变化。”。答案来自 capabilities 伴随文档中的实时链路／争用规则，以及 tasks 伴随文档中关于 “没有争用时，算法不会产生信号” 的指南，再加上 tasks 伴随文档（先按照分层错误分类法排查，再责怪算法）。

没有争用 → 没有信号 → 无法得出结论。 Active 状态加上流量曲线没有变化，并不能证明算法未能接管出厂 CC。CC 算法在网络中没有实际争用时不会表现出可观察到的行为，因此，链路空闲或没有争用的运行从设计上就无法提供信息——它不支持任何方向的结论。下结论前，先确认运行确实产生了争用；对于这类运行，绝不要断言算法有问题或安全。详见 capabilities 伴随文档中的规则。

• “我的 SPCX 算法通过了副本测试——将其推进到生产环境之前，还要通过什么关卡？” — 完整示例：“我的 CC 算法在实验室的两对 BlueField 设备上运行正常；可以将它推送到整个机群吗？”。答案来自 capabilities 伴随文档中的安全性叠加要求（大量交叉链接到 doca-hardware-safety/SKILL.md）：生产切换前，必须限制影响范围、证明可观测性关卡已通过、确保 OOB 可访问、演练回退到出厂 PCC，并记录升级路径。
• “我的安装中是否有 doca_spcx_cc，它是否与匹配的 doca-pcc 库和 DPACC 编译器版本配套？” — 完整示例：“我的 DOCA 安装是否提供 SPCX 接口？”。答案来自 capabilities 伴随文档中的版本叠加说明，该说明会引导至规范的 doca-version/SKILL.md 链路，并补充 工具 ↔ doca-pcc 库 ↔ DPACC 编译器 ↔ 固件自定义 PCC 槽位 的匹配规则。
• “我的 SPCX 会话报错了——问题出在工具、算法、设备还是固件？” — 完整示例：“启动时，doca_spcx_cc 退出并返回 DOCA_PCC_PS_ERROR。”。答案来自 capabilities 伴随文档中的分层错误分类法，以及 tasks 伴随文档中的分层排查流程。

适用对象

此技能面向外部开发者、平台运维人员以及 AI Agent：他们在搭载 DPA 处理器的 BlueField 上，针对正在运行的 RDMA / RoCE 网络，编写、加载和评估 SPCX 类可编程拥塞控制算法。具体包括：

• CC 研究人员 / 开发者：已编写 SPCX 类 DPA 侧算法（或者正在使用有文档说明的随附参考算法，例如在安装环境和算法均支持时，通过 SPCX 路径使用基于零接触 RTT 的算法 doca-pcc-ztr-rttcc-algo/SKILL.md），并需要运维侧工具链来加载算法、设置参数、启动、观察和停止算法。
• 平台运维人员：在非生产 RDMA 网络上运行可编程 CC 试点，以便在受控竞争条件下分析算法行为。
• AI Agent：如实给出“这个 SPCX 算法是否可以安全地继续上线”的结论，并提供存在竞争的评估证据、回滚到出厂 PCC 的文档说明，以及明确的影响范围上限，而不是仅凭数据表中的描述猜测。

此技能不适用于调试 doca_spcx_cc 二进制文件本身的用户，不能替代公开的 DOCA SPCX / DOCA PCC 编程指南，不适合查阅 DPA 侧算法编写细节（相关内容请参阅公开的 DOCA SPCX 编程指南，以及 doca-pcc/SKILL.md 和 doca-dpa/SKILL.md 技能），也不适用于配置出厂默认 PCC（无需主机侧库或 SPCX 工具；请参阅 doca-public-knowledge-map/SKILL.md）。

该工具以 CLI 二进制文件的形式随附于 /opt/mellanox/doca/tools/ 下，而不是供你链接的库；它采用与此套件中其他工具相同的 kind: tool 三文件结构。

语言范围

doca_spcx_cc 是一个 C 语言主机侧 CLI，它链接主机侧的 doca-pcc/SKILL.md 库，并加载由 DPACC 编译器构建的 DPA 侧 SPCX 算法镜像。算法主体是一个独立的 DPA 侧翻译单元，使用 DPACC 支持的语言编写。此技能提供与语言无关的工作流指导，并通过 doca-public-knowledge-map/SKILL.md 将特定语言相关问题引导至公开的 DOCA SPCX / DOCA PCC / DPACC 指南。

何时加载此技能

当用户（或 Agent）需要在安装了 DOCA 的真实主机上调用 doca_spcx_cc 时，应加载此技能。该主机需配对一台已启用 DPA 处理器访问且已开启固件自定义 PCC 插槽的 BlueField，并连接到承载存在实际竞争的 RDMA / RoCE 流量的端口。具体情况包括：

• 通过 SPCX 接口将自编写的 SPCX 算法（或有文档说明的随附参考算法）加载到 BlueField、设置参数、启动算法，并观察其对实时链路的影响。
• 在非生产副本上评估 SPCX 算法，然后再进行任何生产环境部署，并留存存在竞争的运行记录作为证据。
• 在同一安装环境中（两种路径均可用时），比较同一算法类别的 SPCX 路径与 doca-pcc 路径，并决定采用哪一种。
• 根据能力配套文档，提供附有文档说明的证据和回滚计划的“可以安全地继续上线”建议；若缺少证据或回滚方案，则拒绝给出建议。
• 根据分层错误分类法，诊断 DOCA_PCC_PS_ERROR 或无声无效的症状。

不要将此技能用于 DOCA 概览、DPA 侧算法编写细节、DPA 原始周期分析、固件随附的出厂 PCC 算法，或 DOCA 安装相关问题。这些内容请分别参阅 doca-public-knowledge-map/SKILL.md、doca-pcc/SKILL.md、doca-dpa/SKILL.md 或 doca-setup/SKILL.md。

此 skill 提供的内容

这是一个精简加载器。实质性内容位于两个配套文件中：

• 能力配套文件——SPCX 能表达而 PCC 不能表达的内容（以及两者界面的重叠之处）、SPCX 与 PCC 与固件的决策树、编写与使用的区分、角色决策（RP / NP）、文档中记录的探测数据包格式维度、实时链路 / 争用前提规则（关键安全不变量——“没有争用时，CC 算法没有信号”）、运行时可观测性界面（按端口 / 按流的跟踪格式，以及主机端状态界面）、三轴前提规则（doca-pcc/SKILL.md：支持 DPA 的 BlueField + 已启用固件自定义 PCC 槽位 + doca_pcc_cap_* 一致性），并扩展了 SPCX 特有的可用性要求；版本覆盖关系（工具 ↔ 库 ↔ DPACC ↔ 固件）、分层错误分类（安装 / 设备绑定 / 固件槽位 / DPA 镜像 / 算法前提 / 实时链路前提 / 运行时 / 版本 / 跨领域）、可观测性界面，以及覆盖范围广泛的安全要求（在生产环境中使用错误的 CC 算法可能导致网络崩溃）。
• 任务配套文件——涵盖范围内任务动词的分步工作流：install（主机端 DOCA 安装 + DPA 前提条件 + 固件自定义 PCC 槽位）、configure（SPCX 与 PCC 的选择 + 角色 + 算法 + 参数 + 探测数据包格式）、build（转到安装——主机端工具随软件提供；DPA 端算法由用户使用 DPACC 构建）、modify（拒绝——不要修补二进制文件；应修改调用方式、算法和参数）、run（准备 → 冒烟测试 → 争用肯定性评估流程）、test（在生产环境前于副本上迭代）、debug（逐项排查错误分类）、use（基于证据、回滚和升级处理，做出*“可以安全地继续推广”*的决定），以及 Deferred task verbs 部分。

此 skill 假定主机上已安装 DOCA；已配备并可检测到带 DPA 处理器且启用了固件级自定义 PCC 槽位的 BlueField；已安装与主机端 DOCA 版本匹配的 DPACC 编译器；用户已了解如何（大致）编写 DPA 端 SPCX 算法（或有随附的参考算法可供使用）；并且有可控争用的非生产环境 RDMA / RoCE 网络可用于评估。

本技能有意不包含的内容

本技能提供的是 Agent 指引，而不是示例或脚本包。为明确划定边界，本技能有意不包含以下内容，拉取请求也不应添加：

• 特定的拥塞控制算法。 SPCX 加载 用户提供的算法；本技能不会臆造算法实现，并会将任何关于 “我应该编写什么算法” 的问题引导至公开的 DOCA SPCX / DOCA PCC 编程指南，以及用户自身的领域专业知识。
• 预先制作的示例输出（吞吐量 / 延迟曲线、逐流计数器快照）。输出因设备、固件、网络拓扑和工作负载而异；固定一种输出会误导其他环境中的运维人员。
• 公开的 DOCA SPCX 页面和 --help 之外的标志字符串、子命令名称、探测数据包格式标记或指标名称。 这些内容仍在演进；已安装版本中的 --help 是权威清单。
• 用于处理工具输出的包装器、解析器或脚本。 格式已有文档说明；请使用实时指南，针对已安装的版本编写脚本。
• 根据单次观察得出的调优建议。 在运行中的网络上调优 CC 风险很高：本技能规定如何 收集证据并与出厂 PCC 基线比较，但不会在缺少用户自身领域分析的情况下，将单次观察转化为参数变更。
• samples/ 或 reference/ 子目录。 本技能是已发布 CLI 的轻量加载器；实质性内容位于公开页面、--help 以及 doca-pcc/SKILL.md + doca-dpa/SKILL.md 中。

加载顺序

1. 首先阅读本技能，确认用户的问题属于适用范围（SPCX 侧的自定义 CC 工作，而非出厂固件 PCC、原始 DPA 周期分析或算法编写细节）。
2. 关于 SPCX 与 PCC 的决策树、编写与使用的区分、实时链接前提条件、版本差异覆盖、错误分类、可观测性范围和安全原则，请参阅配套的 capabilities 文档。
3. 关于已记录的调用方式，以及 prepare → smoke → contention-positive 评估工作流——install、configure、build、modify、run、test、debug、use——请参阅配套的 tasks 文档。

相关技能

• doca-pcc/SKILL.md — SPCX 所依赖并链接的主机端可编程拥塞控制库。 能力配套文档中的 SPCX 与 PCC 决策树是关键路由规则；混淆二者是首次接触可编程拥塞控制时最常见的错误。
• doca-pcc-ztr-rttcc-algo/SKILL.md — 已提供的参考零接触式 RTT 拥塞控制算法；部署参考算法而非编写算法时，它是本工具操作端工作流的算法端配套技能。
• doca-dpa/SKILL.md — 算法 DPA 端主体所依赖的 DPA 控制库：内核启动模型、DPACC 构建标志、DPA 端通信／verbs。
• doca-rdma/SKILL.md — 受控的 RDMA／RoCE 流量。若没有正在传输的流量，且 fabric 上没有争用，算法就没有信号；评估前务必明确这一前置条件。
• doca-pcc-counters/SKILL.md — 只读 PCC 计数器检查；在 SPCX 评估前或评估期间，先用这个成本更低的步骤确认“该端口上是否有活动”。
• doca-hardware-safety/SKILL.md — 本技能的 ## Safety policy 所依托的整个工具包硬件安全元政策。在生产 fabric 上部署错误的 CC 算法属于元政策要求停止的情况。
• doca-public-knowledge-map/SKILL.md — 引导至公开的 SPCX、PCC 和 DPA／DPACC 指南。
• doca-version/SKILL.md — DOCA 版本处理的权威规范。能力配套文档中的 ## Version compatibility 补充了工具 ↔ doca-pcc ↔ DPACC ↔ 固件自定义 PCC 插槽的匹配规则。
• doca-setup/SKILL.md — 环境准备、安装与 DPACC 编译器验证、BlueField 固件配置（自定义 PCC 插槽是固件级设置），以及通过公开 NGC DOCA 容器实现的暂不安装路径。
• doca-debug/SKILL.md — 跨领域的调试阶梯。若根因位于 DOCA 以下层，请将运行时证据和计数器快照交叉关联到 doca-debug 会话中。
• doca-structured-tools-contract/SKILL.md — 任务配套文档中的命令附录遵循 detect → prefer → fall back → report 合约。
• doca-programming-guide/SKILL.md — 通用 DOCA 编程模式，包括本工具错误层所叠加的跨库 DOCA_ERROR_* 分类体系。

ConnectX 固件中的工厂 PCC 算法不在范围内：它们无需 doca_spcx_cc 即可运行，并通过固件旋钮而非主机端 API 进行配置。请通过 doca-public-knowledge-map/SKILL.md 路由。