DOCAPCC（可编程拥塞控制）Skill doca-pcc

开源协议	Apache-2.0
名称	doca-pcc
描述	> 当用户在主机端进行DOCA PCC实操工作时，将自定义可编程拥塞控制（PCC）算法加载到BlueField DPU上——为承载RoCE的端口创建每端口doca_pcc上下文，将dpacc编译的doca_pcc_app加载到该端口的doca_dev上，对其进行参数化，执行三轴能力发现（DOCA能力查询 + 支持DPA的BlueField + 固件启用自定义PCC槽位），或调试来自doca_pcc_*的DOCA_ERROR_*。即使没有明确表述“DOCA PCC”也会触发——隐含形式包括“将我自己定制的拥塞控制加载到BF端口”、“算法加载时出现DOCA_ERROR_NOT_PERMITTED”、“附加自定义算法时出现DOCA_ERROR_DRIVER”、“我的自定义速率更新没有影响RoCE流量”，或“加载成功但没有在线变化”。对于DPA侧算法体设计、pcc_countersCLI、ConnectX固件中的默认工厂PCC，或RDMA/RoCE流量设置，应拒绝并路由到其他技能。 metadata: kind: library compatibility: > 需要Linux（Ubuntu 22.04/24.04或RHEL/SLES）上安装了DOCA SDK，位于/opt/mellanox/doca，BlueField DPU的DPA处理器对主机可见，且固件启用了自定义PCC槽位。还需要根据DOCA兼容性策略，安装版本与DOCA匹配的DPACC编译器。通过pkg-config doca-pcc读取用户本地安装，并检查/opt/mellanox/doca/{lib,include,samples,applications}。

DOCA PCC（可编程拥塞控制）

从哪里开始： 本技能假定DOCA已经安装、用户的BlueField具有主机可通过DOCA看到的DPA处理器、BlueField固件已启用自定义PCC槽位，并且用户正在从主机侧进行自定义PCC实操工作——即使用doca-pcc将DPA侧的拥塞控制算法加载到BlueField上，将其附加到承载RDMA/RoCE流量的端口上，并从主机侧对其进行参数化。如果用户想要做某事（配置 / 构建 / 修改 / 运行 / 测试 / 调试），请打开TASKS.md；如果问题是主机侧PCC API在这个版本 + 这个BlueField代际 + 这个固件上能表达什么，请打开CAPABILITIES.md。如果用户尚未安装DOCA，请先路由到doca-setup；如果用户正在询问如何编写DPA侧的拥塞控制算法本身（在DPA处理器上运行、由dpacc编译的代码），那是不同范围——请通过doca-public-knowledge-map路由到公开的DOCA PCC编程指南，并通过doca-dpa了解本技能所依赖的主机侧DPA生命周期。如果用户只想在运行时检查PCC计数器而不编写自定义算法，那是pcc_countersCLI工具——请通过doca-public-knowledge-map ## DOCA tools路由；本技能仅用于自定义算法。

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

本技能构建用于回答的PCC问题类别，每个类别包含一个示例。Agent应将类别视为主要信息——示例只是一个实例。

• “如何将我自己的自定义拥塞控制算法部署到承载RDMA/RoCE流量的BlueField端口上？” — 示例：“加载一个小的DPA侧PCC算法，并将其附加到处理我RoCE流量的BlueField端口”。由CAPABILITIES.md ## Capabilities and modes中的双面程序模型 + 主机侧加载与附加工作流，以及TASKS.md ## configure中的启动步骤回答。
• “这个BlueField + 固件实际上是否允许自定义PCC算法，而且我的DOCA安装暴露了哪些PCC功能？” — 示例：“我的主机有BlueField，默认工厂PCC工作正常；我能否改用自定义算法？”。由CAPABILITIES.md ## Capabilities and modes中的三轴前置条件规则（BlueField代际必须携带DPA、固件必须启用自定义PCC槽位、doca_pcc_cap_*针对活动doca_devinfo必须一致）+ TASKS.md ## configure步骤1中的环境前置检查清单回答。
• “为什么我的自定义PCC立即返回DOCA_ERROR_NOT_PERMITTED，即使我有doca_dev访问权限？” — 示例：“此主机中的BlueField固件禁用了自定义PCC槽位”。由CAPABILITIES.md ## Safety policy中的权限矩阵 + TASKS.md ## configure步骤1中的固件侧环境修复回答。
• “我需要的这个doca-pcc库是合适的工具，还是我想要默认固件PCC或pcc_countersCLI？” — 示例：“我只想读取PCC计数器而不修改算法”。由CAPABILITIES.md ## Capabilities and modes中的路径选择规则 + CAPABILITIES.md ## Deferred topic boundaries中的延迟主题边界回答，这些边界通过doca-public-knowledge-map ## DOCA tools将计数器工具路由。
• “我所阅读的主机侧PCC API是否存在于我安装的DOCA上？” — 示例：“我在文档中看到的主机侧加载辅助程序是否适用于此主机上的DOCA + DPACC版本？”。由CAPABILITIES.md ## Version compatibility中的版本兼容性覆盖回答，该覆盖交叉链接了doca-version中的规范检测链，并从doca-dpa添加了PCC特定的DOCA必须与DPACC匹配覆盖。
• “来自doca_pcc_*调用的DOCA_ERROR_*是什么意思，由哪一层引起？” — 示例：“主机侧算法加载调用出现DOCA_ERROR_DRIVER——是DOCA、固件侧自定义PCC槽位，还是DPACC生成的镜像？”。由CAPABILITIES.md ## Error taxonomy中跨库分类法的PCC覆盖 + TASKS.md ## debug中的分层阶梯回答，该阶梯升级到doca-debug。

受众

本技能服务于从主机侧构建使用DOCA PCC库的应用的外部开发人员——即用户代码从主机C/C++调用doca_pcc_*来构建每个PCC实例的上下文，加载由dpacc从用户DPA侧源码生成的DPA侧PCC算法镜像，将其附加到承载RDMA/RoCE流量的BlueField端口，对算法进行参数化，启动上下文并观察算法返回的运行时报告。它不面向为DOCA PCC本身做贡献的NVIDIA开发人员，也不是学习如何编写DPA侧拥塞控制算法本身的地方（该路径通过公共DOCA PCC编程指南以及通过doca-public-knowledge-map提供的DOCA DPA/DPACC指南）。

语言范围。 DOCA PCC以主机侧C库发布，pkg-config模块名为doca-pcc。主机侧API是C；DPA侧拥塞控制算法是单独的翻译单元，以DPACC编译器接受的语言编写，并由dpacc编译为二进制文件，主机将其打包到可执行文件中作为PCC算法镜像。附带示例位于/opt/mellanox/doca/samples/doca_pcc/，使用C加DPA侧源码（NVIDIA的选择）编写。其他语言消费方在实践上受到限制——DPA侧算法没有FFI逃生舱，因为它必须是dpacc接受的翻译单元——但用Rust/Go/Python编写主机侧包装器来驱动doca_pcc_*设置并加载单独构建的PCC算法镜像仍然有用，本技能保持生命周期、能力发现、环境前置条件和错误分类指导与语言无关。

何时加载本技能

当用户从主机侧为自定义拥塞控制算法进行DOCA PCC实操工作时加载本技能，适用于任何主机语言加由dpacc构建的DPA侧翻译单元。具体如下：

• 针对映射到承载要控制的RDMA/RoCE流量的BlueField端口的doca_dev初始化doca_pcc。
• 将dpacc从用户DPA侧拥塞控制算法源码产生的PCC算法镜像（doca_pcc_app）加载到doca_pcc上下文中。
• 通过算法暴露的主机侧旋钮对已加载算法进行参数化，并启动doca_pcc核心上下文，使算法开始对附加端口上的RDMA/RoCE流量产生影响。
• 通过doca_pcc_cap_*家族检查活动doca_devinfo支持哪些PCC功能——BlueField代际和固件修订版本在是否允许自定义PCC算法方面不同。
• 调试来自doca_pcc_*调用的DOCA_ERROR_*——特别是区分固件级自定义PCC槽位禁用与设备完全不支持自定义PCC与算法镜像与此设备不兼容与标准doca_dev访问被拒绝。
• 用非C语言设计主机侧绑定，驱动单独用dpacc构建的自定义PCC算法镜像——此技能中的环境前置条件和能力发现规则仍然适用。

不要为一般DOCA方向、DOCA或DPACC编译器安装、DPA侧编程模型本身（如何编写在DPA上运行的拥塞控制算法体）、关于ConnectX固件中默认工厂PCC算法的问题（不需要主机侧doca-pcc代码——该路径仅为固件级配置），或pcc_counters诊断CLI等问题加载此技能（通过doca-public-knowledge-map ## DOCA tools路由）。对于所有这些，请通过doca-public-knowledge-map路由到匹配的上游指南。

本技能提供的内容

这是一个薄加载器。正文只保留选择正确下一文件所需的导向信息。PCC特定的实质性内容位于两个附带文件中：

• CAPABILITIES.md——主机侧PCC API在此版本 + 此BlueField代际 + 此固件上能表达什么：每个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版本匹配、算法镜像与主机侧期望一致）。
• TASKS.md——六个范围内的PCC动词的分步工作流：configure、build、modify、run、test、debug。还有一个Deferred task verbs块，将范围外的问题指向正确的下一个技能。

该技能假定主机上DOCA已安装于标准位置，BlueField带DPA处理器物理存在且对主机可见，BlueField固件已启用自定义PCC槽位，DPACC编译器已按DOCA兼容性策略安装了与DOCA安装匹配的版本，并且用户已经知道（至少在草图级别）如何编写dpacc要编译的DPA侧PCC算法。它不涵盖安装DOCA、安装DPACC编译器或切换固件级配置——这些路径通过doca-setup。

本技能刻意不提供的内容

本技能是代理指导，不是示例或模板包。为保持边界清晰，它刻意不包含——同时PR不应添加：

• 任何语言的预写DOCA PCC应用程序源码或DPA侧算法源码。 经验证的PCC源码是/opt/mellanox/doca/samples/doca_pcc/中提供的C+DPA侧示例。代理的工作是将用户路由到这些文件，并通过在doca-programming-guide中的通用修改示例工作流规定最小差异修改，同时应用TASKS.md ## modify中的PCC特定覆盖。
• 特定的拥塞控制算法。 此库加载用户提供的算法；它不定义算法。代理必须拒绝发明算法体，并且必须将任何*“我应该编写什么算法”*问题路由到公共DOCA PCC编程指南和用户自身的领域专业知识——这是一个研究问题，不是API问题。
• 停放在技能内的独立构建清单（meson.build、CMakeLists.txt等）。代理在用户项目目录中根据用户安装的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-pcc库混为一谈是PCC首次应用设计中最常见的错误。

加载顺序

1. 先阅读此SKILL.md，确认用户的问题在范围内（主机侧自定义PCC工作，不是DPA侧算法设计和不是计数器工具）。
2. 有关PCC能力矩阵、双面程序模型、doca_pcc每实例上下文、已加载doca_pcc_app算法镜像、端口附加语义、三轴前置条件规则、环境前置条件策略、错误分类、可观察性表面和安全策略，请参阅CAPABILITIES.md。
3. 有关逐步工作流——configure、build、modify、run、test、debug——请参阅TASKS.md。

两个附带文件都相互交叉链接，doca-version用于规范的DOCA版本处理规则（并带有DOCA必须与DPACC编译器匹配的PCC覆盖），doca-public-knowledge-map在正确答案是“在公共DOCA PCC编程指南、公共DPA/DPACC指南、pcc_counters工具指南或磁盘安装布局中查找”而不是“PCC主机侧特定指导”时使用。

相关技能

• doca-public-knowledge-map——每个公共DOCA文档来源和已安装DOCA包的磁盘布局的路由表。PCC公共指南位于https://docs.nvidia.com/doca/sdk/DOCA-PCC/index.html；pcc_counters诊断CLI作为伴随表面存在于DOCA Tools伞下，而不是在此处重新定义的工件。
• doca-dpa——PCC在概念上依赖的主机侧DPA控制库：自定义PCC算法就是 DPA侧代码，由DPACC编译器编译，主机侧doca-pcc Core生命周期遵循与doca-dpa Core生命周期相同的形状。当用户有PCC所依赖的DPA级问题（内核启动模型、DPA侧库）时，代理将此技能与doca-dpa一起加载。
• doca-rdma——自定义PCC算法正在控制其流量的库。自定义PCC算法影响附加的BlueField端口上的RDMA/RoCE流；如果用户尚未在该端口上设置RDMA/RoCE流量，则算法无可作用对象，而doca-rdma是让该流量启动的技能。
• doca-setup——环境准备、安装验证、DPACC编译器安装/验证、BlueField固件配置（包括自定义PCC槽启用），以及我没有安装路径，包含公共NGC DOCA容器。本技能假定其前置条件满足，并且DPACC以与DOCA匹配的版本安装，并且固件级自定义PCC槽位已启用。
• doca-version——规范DOCA版本处理规则。本技能的## Version compatibility交叉链接四路匹配规则，并根据DOCA兼容性策略（继承自doca-dpa）添加PCC特定的DOCA和DPACC必须匹配覆盖。
• doca-structured-tools-contract——捆绑包的结构化工具优先级规则（检测/偏好/回退/报告）。TASKS.md中的命令附录遵守此契约。
• doca-programming-guide——每个库共享的通用DOCA编程模式：规范pkg-config + meson构建模式、通用修改附带示例首次应用工作流、通用Core上下文生命周期、跨库DOCA_ERROR_*分类和程序侧调试顺序。本技能在其上叠加PCC特定内容。
• doca-debug——跨领域调试阶梯（安装/版本/构建/链接/运行时/程序/驱动）。PCC特定调试（固件中未启用自定义PCC槽位、DPACC + DOCA版本偏差、算法镜像因不兼容设备被拒绝、附加端口上的流量未被影响是因为算法体没有效果路径）在此阶梯之上叠加。

ConnectX固件中默认工厂PCC算法不在本技能范围内——它们无需doca-pcc工作，并通过固件级旋钮而不是任何主机侧库API配置。pcc_counters诊断CLI也不在范围内——它是用于检查运行时PCC计数器的独立工件，存在于公共DOCA Tools伞下。将两者任一与doca-pcc库混为一谈是PCC首次应用设计中最常见的错误。