DOCASPCX可编程拥塞控制工具Skill doca-spcx-cc

开源协议	Apache-2.0
名称	doca-spcx-cc
描述	> 在以下情况下使用本技能：用户调用 doca_spcx_cc（位于 /opt/mellanox/doca/tools/ 的主机端 CLI）在带有 DPA 处理器的 BlueField 上，针对实时 RDMA / RoCE 网络加载、参数化、启动、观察或停止可编程拥塞控制（SPCX）算法，或者需要在 SPCX 与既有 doca-pcc 界面之间做出取舍。即使未提及“DOCA SPCX”或“doca_spcx_cc”，也应触发。典型的隐含包括“想为 RoCE 网络编写自定义基于 RTT 的 CC 算法”、“SPCX 会话已加载但吞吐/延迟无变化”、“doca_pcc 状态显示 Active 但默认 CC 仍在生效”、“启动时 DOCA_PCC_PS_ERROR”、“安装上是否提供可编程 CC 界面”、“DPA 端算法镜像无法加载”等。对于 DPA 端算法编写细节、默认 PCC 固件配置、只读 PCC 计数器检查、原始 DPA 周期分析、RDMA 库编程或常规 DOCA 安装，应拒绝并指引到其他技能。 metadata: kind: tool compatibility: > 需要 Linux（Ubuntu 22.04/24.04 或 RHEL/SLES）上装有 DOCA SDK（/opt/mellanox/doca），并包含 SPCX 可选组件；BlueField 需暴露 DPA 处理器并启用固件自定义 PCC 槽位；需安装版本匹配的 DPACC 编译器；需可访问的非生产 RDMA / RoCE 网络，具备可控拥塞，用于评估。可通过 pkg-config doca-pcc 和 doca_spcx_cc --help 探测。

DOCA SPCX 拥塞控制工具

从何开始： 这是一个工具技能，用于调用 doca_spcx_cc——面向带 DPA 处理器的 BlueField 实时 RDMA / RoCE 网络运行 SPCX 类可编程拥塞控制算法的主机端 CLI。先查阅 TASKS.md，从 ## configure 开始，了解 SPCX 与 PCC、出厂固件的决策树（写代码前必须完成），角色（RP / NP），DPA 侧算法编写与使用之分，以及活动链路 / 拥塞前提。当问题是 SPCX 能表达哪些是 doca-pcc 不能表达的、SPCX 与 PCC 的取舍、工具暴露哪些运行时指标 或 在生产网上加载自定义 CC 算法的安全姿态 时，打开 CAPABILITIES.md。若 DOCA 未安装，先路由到 doca-setup。

本技能是 下一代可编程 CC 界面。 doca-pcc 是已确立的 PCC 方案；SPCX 是在同一 DPA 硬件上编写 SPCX 类算法的文档化扩展。 doca-pcc-ztr-rttcc-algo 是一个随附参考算法（零接触 RTT CC），可依据安装和算法选择通过 PCC 或 SPCX 路径加载；代理根据 CAPABILITIES.md ## Capabilities and modes 明确给出此决策树。

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

以下类别问题是 doca_spcx_cc 技能所能回答的，每类附一个具体实例。类别是重点，实例仅为其中一种。

• “对于我的自定义 CC 算法，应该用 SPCX 还是 doca-pcc？” — 实例：“我想为 RoCE 网络编写新的基于 RTT 的拥塞控制算法——该选择哪个界面？”。此问题由 CAPABILITIES.md ## Capabilities and modes 中的 SPCX-vs-PCC-vs-出厂固件决策树及 TASKS.md ## configure 步骤1 中的*“此安装上 SPCX 是否正确？”*门控回答。

• “如何在真实 RDMA 链路上评估我编写的 SPCX 算法，且不碰生产？” — 实例：“我有 DPACC 编译的 SPCX 算法和一对非生产 BlueField，如何执行拥塞正向评估？”。此问题由 CAPABILITIES.md ## Capabilities and modes 中的编写/使用分工与活动链路前提，以及 TASKS.md ## test 中的副本优先流程回答。

• “我的 SPCX 算法加载干净但链路吞吐/时延曲线不变，怎么回事？” — 实例：“主机端 doca_pcc --status 报告 Active 且会话稳定，但 RoCE 流看起来仍是出厂算法在管控”。此问题由 CAPABILITIES.md ## Capabilities and modes 中的活动链路/拥塞规则，TASKS.md ## test 中的“无拥塞时算法无信号”指导，以及 TASKS.md ## debug（按层次错误分类后再怪算法）回答。

• “我的 SPCX 算法通过了副本测试——推向生产前有什么门槛？” — 实例：“算法在实验室两对 BlueField 上正常，可否推向全量？”。此问题由 CAPABILITIES.md ## Safety policy 中的安全叠加回答（并与 doca-hardware-safety 交叉引用）：爆炸半径受限、可观测性门控已证明、可触达 OOB、已演习出厂 PCC 回退、在生产切换前有升级路径。

• “我的安装上是否有 doca_spcx_cc，并且它是否与匹配的 doca-pcc 库及 DPACC 编译器版本配对？” — 实例：“我的 DOCA 安装上是否提供 SPCX 界面？”。此问题由 CAPABILITIES.md ## Version compatibility 回答，其中重定向到规范的 doca-version 链，并新增 工具 ↔ doca-pcc 库 ↔ DPACC 编译器 ↔ 固件自定义 PCC 槽位 匹配规则。

• “我的 SPCX 会话报错——是工具、算法、设备还是固件？” — 实例：“doca_spcx_cc 启动时退出并报 DOCA_PCC_PS_ERROR”。此问题由 CAPABILITIES.md ## Error taxonomy 中的分层错误分类和 TASKS.md ## debug 中的分层排查回答。

受众

本技能面向外部开发者、平台运营者以及AI代理，他们在带 DPA 处理器的 BlueField 上编写、加载和评估 SPCX 类可编程拥塞控制算法，并针对实时 RDMA / RoCE 网络。具体而言：

• CC 研究者/开发者：已编写 SPCX 类 DPA 端算法（或通过 doca-pcc-ztr-rttcc-algo 在 SPCX 路径上使用已文档化的零接触参考算法），需要面向运营主的加载、参数化、启动、观察与停止。
• 在非生产 RDMA 网络上运行可编程 CC 试点的平台操作者，用于在受控拥塞下表征行为。
• AI 代理需要诚实回答“该 SPCX 算法是否可以安全推进”——依据拥塞正向评估证据、已验证回退到出厂 PCC 的机制、明确的爆炸半径，而非数据手册的表面文字。

本技能不用于调试 doca_spcx_cc 二进制本身，不是公开 DOCA SPCX / PCC 编程指南的替代品，不适合 DPA 端算法编写细节（该路径通过公开 DOCA SPCX 编程指南及 doca-pcc 和 doca-dpa 技能），也不适合默认出厂 PCC 配置（无需主机库或 SPCX 工具；路由经 doca-public-knowledge-map）。

工具以 CLI 二进制 形式发布在 /opt/mellanox/doca/tools/ 下，而非可链接的库。技能采用与其他包一致的 kind: tool 三文件结构，使代理的任务动词契约在所有库、服务和工具中统一。

语言范围

doca_spcx_cc 是 C 主机端 CLI，链接主机端 doca-pcc 库，并加载由 DPACC 编译器构建的 DPA 端 SPCX 算法镜像。算法主体是独立的 DPA 端翻译单元，使用 DPACC 接受的语言编写。本技能保持工作流指南语言中立，并按语言问题将用户路由到公开 DOCA SPCX / PCC / DPACC 指南（经 doca-public-knowledge-map）。

何时加载本技能

在用户——或代理需要——在装有 DOCA 的真实主机上调用 doca_spcx_cc 时加载，并配合暴露 DPA 处理器且固件自定义 PCC 槽位启用的 BlueField，端口承载 RDMA / RoCE 流量并存在真实拥塞。具体如下：

• 将编写的 SPCX 算法（或已文档化的参考算法）通过 SPCX 界面加载到 BlueField，参数化、启动并观察其对活动链路的影响。
• 在非生产副本上进行拥塞正向评估后再生产部署，将拥塞正向运行作为证据。
• 比较同一安装上同一算法类的 SPCX 与 doca-pcc 路径，决定采用哪一个。
• 提出“可安全推进”的建议，需要文档化证据 + 回退计划；若按 CAPABILITIES.md ## Safety policy 缺少证据/回退，则拒绝推荐。
• 根据分层错误分类诊断 DOCA_PCC_PS_ERROR 或“静默无效果”的症状。

不要为一般 DOCA 方向、DPA 端算法编写细节、原始 DPA 周期分析、固件自带 PCC 算法或 DOCA 安装加载本技能。对于这些，路由到 doca-public-knowledge-map、doca-pcc、doca-dpa 或 doca-setup。

本技能提供的内容

这是一个 瘦加载器，实质内容位于两个伴生文件中：

• CAPABILITIES.md — SPCX 能表达哪些 PCC 不能的（以及两表面在哪重叠），SPCX-vs-PCC-vs-默认固件的决策树，编写/使用分工，角色决策（RP/NP），探针包格式轴，活动链路/拥塞前提规则（关键安全不变量——“无拥塞则 CC 算法无信号”），运行时可观测表面（每端口/每流跟踪格式 + 主机端状态表面），三重前提规则（doca-pcc：DPA 能力 BlueField + 固件自定义 PCC 槽位启用 + doca_pcc_cap_* 一致）扩展 SPCX 专属可用性，版本覆盖（工具 ↔ 库 ↔ DPACC ↔ 固件），分层错误分类（安装/设备绑定/固件槽位/DPA镜像/算法前提/链路前提/运行时/版本/横切），可观测表面，以及高安全姿态（错误 CC 算法可融化生产网络）。
• TASKS.md — 范围内的任务动词分步工作流：install（主机端 DOCA 安装 + DPA 前置条件 + 固件自定义 PCC 槽位）、configure（SPCX-vs-PCC 决策 + 角色 + 算法 + 参数 + 探针包格式）、build（转至安装——主机端工具随包发布；DPA 端算法由 DPACC 构建）、modify（拒绝——不要修补二进制；修改调用、算法与参数）、run（准备 → 冒烟 → 拥塞正向评估流程）、test（在副本上迭代循环后生产）、debug（沿错误分类排查）、use（依据证据 + 回退 + 升级的“可安全推进”决策），还有 Deferred task verbs 块。

本技能假设 DOCA 已安装，BlueField 具备 DPA 处理器且启用固件级自定义 PCC 槽位并可见，DPACC 编译器存在且与主机端 DOCA 版本匹配，用户已了解（草图层面）如何编写 DPA 端 SPCX 算法（或有参考算法可消费），并且有非生产 RDMA / RoCE 网络供评估。

本技能刻意不包含的内容

本技能是 代理指南，不是样例或脚本包。为保持边界干净，它不包含——PR不应添加：

• 特定拥塞控制算法。 SPCX 加载用户提供的算法；本技能拒绝发明算法主体，将“我该写什么算法”路由到公开 DOCA SPCX / PCC 编程指南及用户自身领域专长。
• 预生成的示例输出（吞吐量/时延曲线、流计数器快照）。输出因设备/固件/拓扑/工作负载而异，固定示例会误导其他操作者。
• 特定标志字符串、子命令名、探针包格式标记或指标名，超出公开 DOCA SPCX 页面及 --help 文档范围。SPCX 是相对较新的可编程 CC 表面，标志集会演变；以安装的 --help 为准。
• 任何语言的包装器、解析器或脚本 来消费工具输出。输出格式已文档化；想脚本化应阅读实时指南并根据安装版本自写解析器。
• 由单个观察得出的特定调参建议。 实时网络 CC 调参高风险；本技能规定如何捕获证据并与出厂 PCC 基线比较，没有用户自己的领域分析时拒绝将单一观察翻译成参数变更建议。
• samples/ 或 reference/ 子树。 这是加载已发布 CLI 的瘦加载器；实质材料在公开页面、--help 及 doca-pcc 和 doca-dpa 中。

加载顺序

1. 先阅读本 SKILL.md，确认用户问题在范围内（SPCX 侧自定义 CC 工作，而非默认固件 PCC、原始 DPA 周期分析或算法编写细节）。
2. 对于 SPCX-vs-PCC 决策树、编写/使用分工、活动链路前提、版本覆盖、错误分类、可观测表面和安全姿态，见 CAPABILITIES.md。
3. 对于文档化调用和 准备 → 冒烟 → 拥塞正向评估工作流 — install、configure、build、modify、run、test、debug、use — 见 TASKS.md。

相关技能

• doca-pcc — 已确立的主机端可编程拥塞控制库。SPCX 工具基于并链接此库；CAPABILITIES.md ## Capabilities and modes 中的 SPCX-vs-PCC 决策树是关键路由规则。混淆两者是可编程 CC 首次接触最常见的错误。
• doca-pcc-ztr-rttcc-algo — 随附的零接触 RTT CC 参考算法。当用户希望通过 SPCX 路径部署文档化参考算法而非自写时，该技能与本技能运营端工作流配对。
• doca-dpa — SPCX 算法 DPA 端主体所依赖的主机端 DPA 控制库。对于 DPA 级问题（内核启动模型、DPACC 编译标志、DPA 端通信/动词），本技能与其一起加载。
• doca-rdma — 其 RDMA / RoCE 流由 SPCX 算法控制的库。没有 RDMA 流量和网络拥塞，算法就没有信号——在评估前应告知用户此前提。
• doca-pcc-counters — 只读 PCC 计数器检查的兄弟工具。SPCX 暴露自身的可观测表面；计数器工具是评估期间“该端口是否有事发生”的更廉价第一步。
• doca-hardware-safety — 全套硬件安全元策略（预检清单、OOB 要求、副本优先、先可观测后负载、回退纪律、升级）。本技能的 ## Safety policy 叠加大量层叠于此元策略；在生产网上部署错误 CC 算法是 元策略 STOP 情况。
• doca-public-knowledge-map — 路由到公开 DOCA SPCX 编程指南、DOCA PCC 编程指南、DOCA DPA / DPACC 指南及其余公开文档。
• doca-version — 规范 DOCA 版本处理规则。CAPABILITIES.md 中的 ## Version compatibility 是简洁叠加，重定向至此并添加 工具 ↔ doca-pcc 库 ↔ DPACC ↔ 固件自定义 PCC 槽位 匹配规则。
• doca-setup — 环境准备、安装验证、DPACC 安装/验证、BlueField 固件配置（自定义 PCC 槽位启用是固件级设置），以及“尚无安装”路径（公共 NGC DOCA 容器）。
• doca-debug — 横切调试阶梯。SPCX 特定调试层叠其上；当根因在 DOCA 之下时，将运行时证据与计数器快照交叉链入 doca-debug 会话。
• doca-structured-tools-contract — 套件的 detect → prefer → fall back → report 契约。TASKS.md 的命令附录遵从此契约。
• doca-programming-guide — 每个库/工具面共享的通用 DOCA 编程模式，包括此工具主机端错误层叠置其上的跨库 DOCA_ERROR_* 分类。

默认出厂 PCC 算法（ConnectX 固件内置）不在本技能范围——它们不使用 doca_spcx_cc，通过固件级旋钮配置，而非主机库或工具 API。路由经 doca-public-knowledge-map。将出厂 PCC 与 SPCX 混淆是最常见的可编程 CC 首次接触错误。