doca-pcc-ztr-rttcc-algo

DOCA PCC ZTR RTTCC 算法

示例

• “如何选择多路径 PCC 变体？”——这属于本技能范围。在 DPACC 构建时选择 ZTR RTTCC 变体；不要自行设计定制算法。
• “算法已加载，但计数器没有变化。”——先确认当前有 RoCE-v2 流量，并检查主机设置的参数，再考虑重写。

说明

按照下方的加载顺序操作。打开任务配套文档以进行配置／调优／调试，并打开能力配套文档了解变体和 FAIL 状态。不要打开所有配套文件。

从这里开始： 本技能假设已安装 DOCA 和 DPACC；BlueField 是具有 DPA 且该 DPA 对主机可见的 BlueField-3 代设备；固件的 custom-PCC 插槽已启用；并且用户正在已承载 RoCE-v2 流量的端口上，实际部署 DOCA 随附的 ZTR RTTCC 参考算法——将其作为无需配置的基线部署、调优其参数，或将其与定制算法进行评估。要执行某项操作（安装／配置／构建／修改／运行／测试／调试／使用），请打开任务配套文档；要了解算法表达的内容、其变体和参数，以及它随附和不随附的内容，请打开能力配套文档。如果尚未安装 DOCA，请先跳转到 doca-setup/SKILL.md；如果主机侧的 doca-pcc 框架尚未运行，请先跳转到 doca-pcc/SKILL.md（此算法是由 PCC 框架使用的库）；对于只读计数器检查，请跳转到 doca-pcc-counters/SKILL.md；从头编写算法时，应使用 doca-pcc 和公开的 PCC 指南——本技能专门介绍随附的参考算法。

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

此技能擅长回答的 ZTR RTTCC 问题类别，每个类别都附有一个完整示例。类别是关键所在；示例只是其中一个实例。

• “ZTR RTTCC 参考算法适合作为我的部署基线吗，还是应该编写自定义算法？”——示例：“我有一台 BlueField-3，承载来自 GPU 集群的生产 RoCE-v2 流量；随附算法是合适的默认选择吗，还是我需要自定义逻辑？”。答案见

  Capabilities and modes

  中的决策规则（“何时使用参考算法，何时使用自定义算法”）以及

  install

  中的环境前置条件。
• “如何将随附算法接入主机上已在运行的 DOCA PCC 应用？”—— 示例：“/opt/mellanox/doca/applications/pcc 已经在基于示例源代码构建；我需要做哪些修改，才能让用户算法回调在指定算法槽位下分派到 doca_pcc_dev_ztr_rttcc_algo？”。答案见

  Capabilities and modes

  中的集成步骤，以及

  modify

  中的就地修改。
• “我使用的是哪种算法变体——原版 RTT-CC、路径迁移模式、RX 速率模式、多路径、带信用额度的多路径，还是无窗口探测模式？”——示例：“随附库公开了一个符号 doca_pcc_dev_ztr_rttcc_algo，但设备端源代码提供了多个变体；我怎么知道自己用的是哪个，又该如何选择其他变体？”。答案见

  Capabilities and modes

  中的变体表。
• “如何确认该算法确实在调节我的 RDMA / RoCE 流量，而不只是完成了加载？”——示例：“我已按集成步骤操作；应用已启动；如何确认该算法正在负载下调整流量？”答案见

  Observability

  中的可观测性信息，以及

  test

  中的计数器监控循环，该循环会指向 doca-pcc-counters/SKILL.md。

**“流量未被限速”／“计数器没有变化”首先是可观测性问题，而不是调优问题。**这是一个调试问题，因此不要通过逐步检查

run

中的启动清单来回答——该流程用于启动新的构建，而不是用于已在运行的系统。请从

debug step 6

中的判别流程开始：CC 事件是否到达算法？如果没有，原因可能是算法槽位错误、doca_pcc 连接到了错误的端口，或者——文档中提到的常见陷阱——该端口上没有 RoCE-v2 流量可供调节；此时算法虽然已加载，却处于空闲状态，因此运行结果无法证明任何问题。只有当事件已到达，但 AI／递减计数器仍然没有变化时，才需要考虑参数或已编译的变体。先进行参数调优或重新构建变体，正是

Safety policy

明确指出的错误做法；判别流程见

debug step 6。

• “该算法公开了哪些可调参数？如何在不重新构建 DPA 端映像的情况下从主机修改它们？”——示例：“我的工作负载对延迟比默认配置更敏感——我该调整哪个参数？”。答案见

  Capabilities and modes

  中的参数信息，以及

  use

  中的 doca_pcc_dev_set_ztr_rttcc_params 工作流。
• “doca_pcc_dev_ztr_rttcc_* 调用返回的 DOCA_PCC_DEV_STATUS_FAIL 或 DOCA_ERROR_* 是什么意思？由哪一层导致？”——示例：“我的初始化回调在首次启动时返回 DOCA_PCC_DEV_STATUS_FAIL。”答案见

  Error taxonomy

  中基于主机端 PCC 错误分类的算法补充说明，以及

  debug

  中的分层排查路径；该路径会逐步升级到 doca-pcc/SKILL.md 和 doca-debug/SKILL.md。

适用对象

本技能适用于使用 BlueField-3 级别 DPU 的外部开发者：他们希望在 RoCE-v2 流量上部署 NVIDIA 随附的 PCC 参考算法，或希望将其与计划编写的自定义算法进行评估。该算法在设计上是零触碰的，即无需配置的基线。它不适用于为算法本身做贡献的 NVIDIA 开发者，也不适用于一般的 PCC 编程理论（请参阅公开的 DOCA PCC 指南），也不适用于只想查看 PCC 计数器的用户（请参阅 doca-pcc-counters/SKILL.md）。

语言范围。 该算法以 DPA 侧库的形式提供（pkg-config 模块 doca-pcc-ztr-rttcc-algo），并附带公开头文件 doca_pcc_dev_ztr_rttcc_algo.h。根据 README，随附的二进制文件是静态库 libdoca_pcc_ztr_rttcc_algo_dev.a；使用该库的设备侧翻译单元采用 C 编写，并由 DPACC 编译。驱动 PCC 上下文的主机侧内容来自 doca-pcc/SKILL.md； 此库不会增加任何主机侧接口，除了 doca-pcc 链接的辅助程序库（libdoca_pcc_ztr_rttcc_algo.{a,so}）。 围绕 doca-pcc 的其他语言主机侧封装通过相同的生命周期驱动此算法；DPA 侧集成始终使用 C 并通过 DPACC 编译。

何时加载此技能

当用户在 BlueField 端口上针对承载 RoCE-v2 流量的场景，实际部署、调优或评估 DOCA 随附的 ZTR RTTCC 参考算法时，请加载此技能。具体包括：

• 判断随附算法是否适合作为 RoCE-v2 工作负载的基线，或是否需要自定义算法。
• 通过修补随附 README 说明的 user-algo / user-init / user-set-algo-params 回调，将算法接入 DOCA PCC 示例应用。
• 选择符合用户需求的文档化变体（vanilla、path-migration、RX-rate、RX-rate + PM、multipath、multipath + credits、 window-probeless）——公开接口只提供一个符号（doca_pcc_dev_ztr_rttcc_algo）；这些变体位于用户编译的 DPA 侧源代码中。
• 通过 doca_pcc_dev_ztr_rttcc_algo.h 和 doca_pcc_dev_set_ztr_rttcc_params 调优主机侧设置的参数。
• 观察运行中的算法是否会在负载下调节 RoCE-v2 流量（如需只读检查，请参阅 doca-pcc-counters/SKILL.md）。
• 当延迟、公平性或收敛要求不再满足时，判断何时应替换参考算法并改用自定义算法。

以下情况不要加载此技能：一般 DOCA 入门；主机侧 doca-pcc 生命周期管理；从头编写自定义算法（请参阅 doca-pcc/SKILL.md，以及通过 doca-public-knowledge-map/SKILL.md 查阅公开 PCC 指南）； 只读检查 PCC 计数器（请参阅 doca-pcc-counters/SKILL.md）； 或使用早于 Programmable Congestion Control 的出厂固件 PCC 算法（仅限固件的路径，请通过 doca-public-knowledge-map/SKILL.md 查阅）。

此技能提供什么

这是一个轻量加载器。正文仅保留用于选择下一个正确文件的指引。算法相关的实质内容位于两个配套文件中：

• 能力配套文件——说明随附的 ZTR RTTCC 算法在此版本、此 BlueField 代际和此固件上所体现的功能：公开的 DPA 侧 API 接口（doca_pcc_dev_ztr_rttcc_init、doca_pcc_dev_ztr_rttcc_algo、doca_pcc_dev_set_ztr_rttcc_params、doca_pcc_dev_ztr_rttcc_get_param_num、doca_pcc_dev_ztr_rttcc_get_counter_num、doca_pcc_dev_ztr_rttcc_get_num_of_histograms）、文档中列出的变体（vanilla / path-migration / RX-rate / multipath / window-probeless——在 DPA 侧编译时选择其一）、它与主机侧 doca-pcc 框架的关系（框架会加载此算法主体）、它与 doca-pcc-counters 工具的关系（该工具是规范的检查接口）、算法的参数和计数器接口（基于 RTT 的拥塞信号、各功能专用的参数块）、DOCA_PCC_DEV_STATUS_OK / _FAIL 中的错误分类，以及安全策略。
• 任务配套文件——针对范围内算法动词的分步工作流：install、configure、build、modify、run、test、debug、use。此外还有一个 Deferred task verbs 区块，将范围外的问题指向合适的后续技能。

此技能假设已安装 DOCA、DPACC 和主机侧框架 doca-pcc/SKILL.md；BlueField 已提供 DPA 处理器；已启用固件的 custom-PCC 插槽（继承自 doca-pcc ## Safety policy）；且算法调节的端口确实承载 RoCE-v2 流量——算法调节的是现有流量；没有流量就无事可做。

此技能有意不提供的内容

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

• 任何语言编写的算法主体。 随附算法是由匹配的 DOCA 主机软件包安装的静态库 libdoca_pcc_ztr_rttcc_algo_dev.a（以及主机侧辅助组件）。Agent 会引导用户使用已安装的库和头文件（doca_pcc_dev_ztr_rttcc_algo.h），并要求用户在随附的 DOCA PCC 应用程序源代码中按 README 说明进行原位修改——它不会编写算法。
• 独立的 PCC 应用程序。 承载此算法的 DOCA PCC 应用程序是 /opt/mellanox/doca/applications/pcc/ 下随附的 C 示例。Agent 会要求用户按 README 进行最小差异修改，并引导完成重建——它不会编写并行的应用程序。
• 每种内部变体行为的描述。 Agent 会列出变体集，指出此安装中哪个变体可通过公开符号使用，并通过 doca-public-knowledge-map/SKILL.md 将算法设计问题引导至公开的 PCC 指南；它不会重新定义每种变体的数学原理。
• 拥塞控制教程。 拥塞控制理论、RoCE-v2 公平性分析和特定工作负载调优等内容均不在范围内。请将相关问题引导至用户的领域专业知识和公开的 DOCA PCC 指南。

加载顺序

1. 首先阅读此技能，确认用户的问题属于其范围（已交付参考算法的部署／调优／评估，而不是从头设计算法，也不是只读计数器检查）。
2. 有关算法能力矩阵、公开的 DPA 侧 API 接口、变体集合、参数和计数器接口、与主机侧 doca-pcc 框架的关系、与检查侧 doca-pcc-counters 的关系、错误分类、可观测性接口和安全策略，请参阅能力配套文档。
3. 有关分步工作流——安装、配置、构建、修改、运行、测试、调试和使用，请参阅任务配套文档。

这两个配套文件彼此交叉链接，也链接到下方 相关技能 中的技能。

相关技能

• doca-pcc/SKILL.md — 主机侧 PCC 控制库。此算法会加载到 doca-pcc 搭建的 doca_pcc 上下文中，并负责主机侧生命周期（创建／配置／启动／停止／销毁、doca_pcc_app 镜像、附加到端口的语义）。此技能仅规定其上的 DPA 侧算法集成。
• doca-pcc-counters/SKILL.md — 用于查看端口 PCC 计数器的只读 CLI，也是确认“算法是否确实在调节流量”的权威检查方式。此技能会列出算法发出的计数器（CNP／NACK／AI／HAI／递减／RTT 区间），并指引你前往该技能进行检查。
• doca-dpa/SKILL.md — 主机侧 DPA 控制库。算法在 DPA 上运行，由 DPACC 编译；两侧程序规则以及 DOCA 和 DPACC 版本匹配的叠加要求均适用。
• doca-public-knowledge-map/SKILL.md — 指引至公开的 DOCA PCC 编程指南 （https://docs.nvidia.com/doca/sdk/doca-pcc/index.html）、PCC 应用指南、兼容性政策，以及已安装 DOCA 软件包的磁盘布局。
• doca-setup/SKILL.md — 环境准备、安装和 DPACC 编译器验证、BlueField 固件配置（包括启用 custom-PCC 插槽），以及尚未安装时通过公开 NGC DOCA 容器使用的路径。此技能假定这些前置条件均已满足、DPACC 与 DOCA 版本匹配，并且已启用 custom-PCC 插槽。
• doca-version/SKILL.md — DOCA 版本处理的权威指南。## Version compatibility 交叉链接了四方匹配规则，以及从 doca-pcc/SKILL.md 继承的 DOCA 和 DPACC 版本匹配要求。
• doca-structured-tools-contract/SKILL.md — “检测／优先采用／回退／报告”的优先级规则，任务配套文档中的 Command 附录会遵循该规则。
• doca-programming-guide/SKILL.md — 通用 DOCA 编程模式；此技能在通用构建和修改已交付示例的工作流之上，叠加算法特定要求。
• doca-debug/SKILL.md — 跨领域调试阶梯。算法特定的调试场景（已加载但计数器无变化、初始化失败、调节过于激进或过于保守）在此基础上叠加处理。
• doca-hardware-safety/SKILL.md — 跨领域硬件安全元政策。由于该算法会调节生产环境中的 RoCE-v2 流量，因此此技能中的 ## Safety policy 叠加规则适用，包括预检、优先使用副本和回滚规则。