doca-pcc

DOCA PCC

示例

• “将我自己的拥塞控制算法加载到 BF 端口。” — 这属于本技能范围。请仅使用主机侧 doca_pcc 和通过 DPACC 构建的 doca_pcc_app；不要在此处重写算法主体。
• “加载算法时出现 DOCA_ERROR_NOT_PERMITTED。” — 更改加载调用前，请检查固件的 custom-PCC 槽位和 DPA 暴露情况。

说明

请遵循下文的加载顺序。若要配置 / 加载 / 调试，请打开任务配套文件。若要查询三轴能力，请打开能力配套文件。不要打开所有配套文件。

从这里开始： 本技能假设 DOCA 已安装，用户的 BlueField 配备了主机可通过 DOCA 访问的 DPA 处理器，BlueField 固件已启用 custom-PCC 槽位，并且用户正在从主机侧手动操作自定义 PCC——即使用 doca-pcc 将 DPA 侧拥塞控制算法加载到 BlueField，将其关联到处理 RDMA / RoCE 流量的端口，并从主机侧设置参数。如果用户想要执行某项操作（配置 / 构建 / 修改 / 运行 / 测试 / 调试），请打开任务配套文件；如果问题是主机侧 PCC API 在此版本 + 此 BlueField 代际 + 此固件上能表达什么，请打开能力配套文件。如果用户尚未安装 DOCA，请先引导至 doca-setup/SKILL.md；如果用户询问如何编写 DPA 侧拥塞控制算法本身（即运行在 DPA 处理器上、由 dpacc 编译的代码），则属于不同范围——请通过 doca-public-knowledge-map/SKILL.md 引导至公开的 DOCA PCC 编程指南，以及本技能所依赖的主机侧 DPA 生命周期文档 doca-dpa/SKILL.md。如果用户只想在运行时查看 PCC 计数器，而不编写自定义算法，则应使用 pcc_counters CLI 工具——请通过 doca-public-knowledge-map ## DOCA tools（doca-public-knowledge-map/SKILL.md#doca-tools）引导；本技能仅适用于自定义算法。

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

此技能旨在回答的 PCC 问题类别，每类都附带一个完整示例。Agent 应将类别视为关键所在；完整示例只是一个具体实例。

• “如何将自定义拥塞控制算法部署到承载 RDMA / RoCE 流量的 BlueField 端口上？” — 完整示例：“加载一个小型 DPA 端 PCC 算法，并将其关联到处理我的 RoCE 流量的 BlueField 端口”。 通过双侧程序模型 + 主机侧加载与关联工作流解答，详见

  功能与模式

  • configure 中的启动步骤。

• “这款 BlueField + 固件是否真的支持自定义 PCC 算法？我的 DOCA 安装提供了哪些 PCC 功能？” — 完整示例：“我的主机有一块 BlueField，默认出厂 PCC 可以正常工作；我能否换用自定义算法？”。通过三轴前提规则解答（BlueField 代际必须搭载 DPA、固件必须启用自定义 PCC 插槽、针对活动 doca_devinfo 的 doca_pcc_cap_* 查询结果必须一致），详见

  功能与模式

  • configure 步骤 1 中的环境前提检查清单。

• “我明明有 doca_dev 访问权限，为什么自定义 PCC 仍因 DOCA_ERROR_NOT_PERMITTED 而失败？” — 完整示例：“这台主机上的 BlueField 固件禁用了自定义 PCC 插槽”。通过

  安全策略 中的权限矩阵解答，

  • configure 步骤 1 中的固件侧环境修复方案解答。

• “doca-pcc 库是我需要的工具吗？还是我应该使用默认固件 PCC 或 pcc_counters CLI？” — 完整示例：“我只想读取 PCC 计数器，不想改动算法”。通过 ## 功能与模式 中的路径选择规则解答，

  • 延后主题边界 中的主题范围说明会引导你前往

  doca-public-knowledge-map ## DOCA tools（doca-public-knowledge-map/SKILL.md#doca-tools） 使用计数器工具。
• “我读到的主机侧 PCC API 在我安装的 DOCA 中可用吗？” — 完整示例：“文档中提到的主机侧加载辅助函数，在这台主机的 DOCA + DPACC 版本中可用吗？”。通过 ## 版本兼容性 中的版本兼容性补充说明解答，其中交叉链接到 doca-version/SKILL.md 中的规范检测流程，并补充了从 doca-dpa/SKILL.md 继承的 PCC 专属补充规则：DOCA 必须与 DPACC 匹配。
• “doca_pcc_* 调用返回的 DOCA_ERROR_* 是什么意思？由哪一层导致？” — 完整示例：“主机侧算法加载调用返回 DOCA_ERROR_DRIVER——是 DOCA、固件侧自定义 PCC 插槽，还是 DPACC 生成的映像导致的？”。通过 ## 错误分类 中针对跨库错误分类的 PCC 补充说明解答，

  • debug 中的分层排查流程会在需要升级处理时引导至

  doca-debug/SKILL.md。

目标读者

此技能面向从主机侧使用 DOCA PCC 库的外部开发者——他们编写的代码会调用 doca_pcc_* 来建立每端口上下文、加载由 dpacc 生成的 doca_pcc_app 映像、将其关联到承载 RoCE 流量的 BlueField 端口、配置参数、启动算法并观察运行时报告。此技能不适用于为 DOCA PCC 作贡献的 NVIDIA 开发者，也不是学习如何编写 DPA 端算法主体的指南（请通过 doca-public-knowledge-map/SKILL.md 查找公开的 PCC / DPA / DPACC 指南）。

语言范围。 DOCA PCC 以主机侧 C 库的形式提供（pkg-config 模块为 doca-pcc）。DPA 端算法是单独的编译单元，dpacc 会将其编译为 PCC 算法映像——没有 FFI 逃生通道。使用 Rust / Go / Python 编写主机侧封装来驱动 doca_pcc_* 仍然很有用；本技能的指导不依赖特定语言。

适用场景

当用户在主机端亲自进行 DOCA PCC 工作，以实现自定义拥塞控制算法时，加载此技能。具体包括：

• 针对映射到承载待控制 RDMA / RoCE 流量的 BlueField 端口的 doca_dev 初始化 doca_pcc。
• 将 dpacc 生成的 doca_pcc_app 算法映像加载到 doca_pcc 上下文。
• 配置算法参数并启动 doca_pcc Core 上下文，使其开始影响该端口上的 RoCE 流量。
• 通过 doca_pcc_cap_* 检查活动 doca_devinfo 支持哪些 PCC 功能 — 不同的 BlueField 代际和固件版本对自定义 PCC 算法的许可有所不同。
• 排查 doca_pcc_* 返回的 DOCA_ERROR_* — 区分固件禁用了自定义 PCC 插槽、设备不支持自定义 PCC、映像不兼容和普通的 doca_dev 访问被拒绝。
• 设计非 C 语言的主机端绑定，以驱动单独使用 dpacc 构建的算法映像 — 环境前提条件和功能规则仍然适用。

不要将此技能用于常规 DOCA 概览、DOCA / DPACC 安装、DPA 侧编程模型本身、ConnectX 固件中随附的工厂 PCC 算法（仅固件端，不涉及主机端代码），或 pcc_counters 诊断 CLI。对于这些内容，请通过 doca-public-knowledge-map/SKILL.md 转至对应的上游指南。

此技能提供的内容

这是一个轻量加载器。正文只保留了用于选择下一个文件所需的概览信息。PCC 专属的实质内容位于两个配套文件中：

• 功能配套文件 — 介绍此版本 + 此 BlueField 代际 + 此固件下主机端 PCC API 能实现的功能：每个 PCC 实例的 doca_pcc 上下文、由 dpacc 生成并加载的 doca_pcc_app 算法映像、将算法绑定到其所控制的 RDMA / RoCE 流量的端口附加语义、功能查询接口（doca_pcc_cap_*）、映射到跨库 DOCA_ERROR_* 集合的 PCC 错误分类、可观测性接口（主机端报告，以及可通过 doca-public-knowledge-map 访问的公开 PCC 计数器工具），以及用于约束环境前提条件的安全策略（支持 DPA 的 BlueField、在固件层启用自定义 PCC 插槽、DOCA 与 DPACC 版本匹配、算法映像与主机端预期一致）。
• 任务配套文件 — 涵盖六项范围内 PCC 操作的分步工作流：configure、build、modify、run、test、debug。此外，还有一个 Deferred task verbs 部分，指出范围外问题应转向的后续技能。

此技能假设主机已在标准位置安装 DOCA，物理连接了配备 DPA 处理器且主机可见的 BlueField，BlueField 固件已启用自定义 PCC 插槽，DPACC 编译器已安装且版本按照 DOCA Compatibility Policy 与 DOCA 安装版本匹配，并且用户已经知道如何（至少大致了解）编写将由 dpacc 编译的 DPA 侧 PCC 算法。此技能不涉及安装 DOCA、安装 DPACC 编译器或更改固件级配置 — 这些流程请参阅 doca-setup/SKILL.md。

此技能有意不包含的内容

此技能是Agent 指南，而非示例或模板包。为明确界定范围，此技能有意不包含以下内容，也不应通过拉取请求添加：

• 预先编写的 DOCA PCC 应用源代码或 DPA 侧算法源代码（任何语言均不例外）。 经验证的 PCC 源代码是随附的 C + DPA 侧示例，位于 /opt/mellanox/doca/samples/doca_pcc/。Agent 的任务是引导用户找到这些文件，并按照 doca-programming-guide/SKILL.md 中通用的修改示例工作流，指导用户对其进行最小差异修改，再叠加 ## modify 中针对 PCC 的专门覆盖规则。
• 特定的拥塞控制算法。 此库会加载用户提供的算法，但不会定义算法。Agent 必须拒绝编造算法主体，并将任何*"我应该编写什么算法"*的问题引导至公开的 DOCA PCC 编程指南和用户自身的领域专业知识——这是研究问题，而非 API 问题。
• 独立的构建清单（meson.build、CMakeLists.txt，……），放在此技能目录中。Agent 会在用户的项目目录中，针对用户已安装的 DOCA 和 DPACC 编译器构建清单；pkg-config --modversion doca-pcc 和已安装的 dpacc 是两项事实来源。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录。 即使标注为“reference”，只要此技能目录中包含模拟或不完整的文件，就会造成误导：用户会以为它可以构建。
• pcc_counters 工具界面。 该 CLI 是独立的产物（位于 tools/pcc_counters/ 下的 pcc_counters.sh 脚本），有自己的页面；相关引导位于 doca-public-knowledge-map ## DOCA tools（doca-public-knowledge-map/SKILL.md#doca-tools）。将它与该库混为一谈，是 PCC 首个应用设计中最常见的错误。

加载顺序

1. 首先阅读此技能，确认用户的问题属于适用范围（主机侧自定义 PCC 工作，而非 DPA 侧算法设计，也非计数器工具）。
2. 有关 PCC 能力矩阵、双侧程序模型、doca_pcc 每实例上下文、已加载的 doca_pcc_app 算法映像、附加到端口的语义、三轴前置条件规则、环境变量前置条件策略、错误分类、可观测性界面和安全策略，请参阅能力配套文档。
3. 有关分步工作流——配置、构建、修改、运行、测试、调试——请参阅任务配套文档。

这两个配套文件会相互链接；还会链接到 doca-version/SKILL.md，以查阅规范的 DOCA 版本处理规则（其中包含 DOCA 必须与 DPACC 编译器版本匹配的 PCC 覆盖规则）；并在正确答案应是“查阅公开的 DOCA PCC 编程指南、公开的 DPA / DPACC 指南、pcc_counters 工具指南或磁盘上的安装布局”，而非“PCC 主机侧专属指南”时，链接到 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档源的路由表，以及已安装 DOCA 软件包在磁盘上的布局。 PCC 公开指南位于 https://docs.nvidia.com/doca/sdk/DOCA-PCC/index.html；pcc_counters 诊断 CLI 属于 DOCA Tools 范畴，是一种配套入口，而不是在此处重新定义的 工件。
• doca-dpa/SKILL.md — PCC 在概念上依赖的主机端 DPA 控制库：自定义 PCC 算法本身是 DPA 端代码，由 DPACC 编译器编译；主机端 doca-pcc Core 生命周期与 doca-dpa Core 生命周期遵循相同的模式。当用户提出 DPA 层面的问题（内核启动模型、DPA 端库）时，Agent 会同时加载 doca-dpa 和本技能；PCC 就构建在 DPA 之上。
• doca-rdma/SKILL.md — 自定义 PCC 算法所控制流量的 库。自定义 PCC 算法会影响所连接 BlueField 端口上的 RDMA / RoCE 流量；如果用户尚未在该端口上 设置 RDMA / RoCE 流量，算法就无事可做，而 doca-rdma 是负责启动这些流量的技能。
• doca-setup/SKILL.md — 环境准备、 安装验证、DPACC 编译器安装 / 验证、BlueField 固件配置（包括启用 custom-PCC 插槽），以及尚未安装任何内容时使用公开 NGC DOCA 容器的路径。本技能假定其 前提条件均已满足，且 DPACC 已安装并与 DOCA 版本匹配，同时固件级 custom-PCC 插槽已启用。
• doca-version/SKILL.md — DOCA 版本处理的规范 规则。本技能的 ## Version compatibility 会交叉引用四方匹配规则，并根据 DOCA 兼容性政策添加 PCC 专属的 DOCA 与 DPACC 必须匹配补充规则（继承自 doca-dpa/SKILL.md）。
• doca-structured-tools-contract/SKILL.md — 本套件结构化工具的优先级规则（检测 / 优先使用 / 回退 / 报告）。任务配套文档中的命令附录遵循此约定。
• doca-programming-guide/SKILL.md — 所有库共用的 DOCA 通用编程模式： 规范的 pkg-config + meson 构建模式、通用的“先修改已提供示例，再创建首个应用”工作流、通用 Core 上下文生命周期、跨库的 DOCA_ERROR_* 错误分类，以及程序端调试顺序。 本技能在此基础上叠加 PCC 特有内容。
• doca-debug/SKILL.md — 跨领域的 调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动）。PCC 专属调试（固件中未启用 custom-PCC 插槽、DPACC 与 DOCA 版本不一致、 算法映像被拒绝，原因是与设备不兼容、已加载的算法未造成线路上的变化，原因是 从未调用 doca_pcc_start() 或所连接端口没有 RoCE 流量）都在此阶梯之上进行。

“已加载，但线路上毫无变化”是一个主机端问题。 成功加载并不意味着算法已运行： doca_pcc_start() 才是算法在端口上开始运行的时刻，而且 PCC 只会调节 创建 doca_pcc 时所针对的 doca_dev 上已有的 RoCE 流量。请在此处解决这两个问题， 不要检查 DPA 端算法主体：那属于 doca-dpa/SKILL.md 的范畴；报告已触发就已经证明主体在运行——尚未证实的是它 已绑定并处于运行状态。请按顺序检查

debug。