doca-pcc-counters

DOCA PCC 计数器（pcc_counters.sh）

示例

• “如何读取此设备上的 PCC 诊断计数器？” — 这是适用范围内的问题。先启用计数器，再查询；不要将其视为 PCC 算法调优。
• “脚本打印了 ERROR: Bad Device。” — 在认定固件损坏之前，先解决 mst 路径问题。

说明

请遵循下文的加载顺序。打开任务配套文件，了解运行 / 调试方法。打开功能配套文件，查看固定的计数器集合。 不要打开所有配套文件。

从这里开始： 这是一个用于调用 pcc_counters.sh 的工具技能 — 这是一个小型 bash 脚本，可通过 mlx5 debugfs diag_cnt 接口启用并读取设备上固定的一组固件 / 硬件 PCC 诊断 计数器（CNP 计数、RTT-perf、WRED-drop、RTT-gen、已处理事件）。打开任务配套文件，从 ## run 开始查看规范的 set 后接 query 流程；如果用户报告 “ERROR: Bad Device”、“计数器卡在 0” 或 “转储内容为空”，则打开 ## debug。如果用户的问题是*“脚本报告哪些计数器，以及如何读取这些计数器”*，请打开功能配套文件。如果用户尚未安装 DOCA / MFT， 请先转到 doca-setup/SKILL.md。

此技能提供的是固件 / HW PCC 计数器读取功能。 它不是用于将自定义拥塞控制内核加载到 DPA 的主机端控制库（该功能位于 doca-pcc/SKILL.md），也不是固件 PCC 算法配置（该路径属于固件配置，应转至 doca-public-knowledge-map/SKILL.md）。 此脚本读取的计数器是设备 / 固件诊断计数器，无论是否正在运行自定义 doca-pcc DPA 内核，它们都存在 — 不要将读取这些计数器的条件设为已加载自定义内核。

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

此技能专门处理 pcc_counters.sh 问题的各个类别，每类都有一个演示示例。类别是关键所在；演示示例只是其中一种情况。

• “如何读取此 设备上的 PCC 诊断计数器？” — 演示示例：“为 /dev/mst/mt41692_pciconf0 启用并转储 CNP / RTT / WRED-drop 计数器”。 通过功能配套文件中的固定计数器集合，以及 任务配套文件中的 set 后接 query 调用方式解答。
• “最精简的合法调用方式是什么？” — 演示 示例：“我具体要输入什么？”。通过任务配套文件中的 两个位置参数约定 （set | query + 一个 mst 设备路径）解答。
• “脚本打印了 ERROR: Bad Device — 哪里出了问题？” — 演示示例：“我的设备路径不匹配”。 通过功能配套文件中的设备解析层，以及 任务配套文件解答。
• “计数器卡在 0 — 是设备空闲、计数器未启用，还是确实没有事件？” — 演示示例：“query 后 PCC_CNP_COUNT 读取值为 0”。通过任务配套文件 + 功能配套文件中的读取前先启用规则和分层诊断解答。
• “我的安装中是否有此脚本，它位于何处？” — 演示示例：“pcc_counters.sh 是否存在，安装会把它放在哪里”。通过功能配套文件中的安装覆盖说明解答， 该说明会转至规范的 doca-version/SKILL.md 规则。

适用对象

本技能面向需要读取 ConnectX / BlueField 设备固件 PCC 诊断计数器，以分析端口拥塞控制行为（CNP 生成、RTT 请求/响应、WRED 丢弃）的运维人员、开发者和 AI Agent。具体包括：

• 网络运维人员：确认设备上是否发生拥塞控制事件（CNP、RTT、WRED 丢弃）。
• 开发者：将自定义 doca-pcc 算法的效果与设备级 PCC 诊断计数器关联起来（此脚本读取固件计数器；自定义算法本身属于另一个领域，由 doca-pcc/SKILL.md 负责）。
• AI Agent：生成 PCC 计数器快照，作为拥塞控制调查的证据。

本技能不适用于调试脚本本身的 bash 代码的用户，也不用于学习如何编写自定义 PCC 算法——相关内容请参阅 doca-pcc/SKILL.md——也不适用于想要配置出厂固件 PCC 算法的用户（请参阅 doca-public-knowledge-map/SKILL.md）。

pcc_counters.sh 以纯 bash 脚本的形式提供，安装在 DOCA 工具目录下（由 tools/pcc_counters/meson.build 中的 install_data 指定），不是编译后的二进制文件，也不是可供链接的库。本技能采用该工具包的 kind: tool 三文件结构（本技能 + 能力说明文件 + 任务说明文件），确保 Agent 在整个工具包中使用统一的任务动词约定（configure / build / modify / run / test / debug）。

何时加载本技能

当用户需要，或 Agent 需要在主机或 BlueField Arm 上启用并读取设备 PCC 诊断计数器，且系统已安装 mst 工具并挂载 debugfs 时，请加载本技能。具体包括：

• 在目标 mst 设备上使用 set 启用诊断计数器。
• 使用 query 读取已启用的计数器，并逐字引用指定的计数器行。
• 获取计数器读数，作为拥塞控制调查的证据。

不要将本技能用于 DOCA 概览、自定义 PCC 算法设计、主机端 doca-pcc 库 API、出厂固件 PCC 算法或 DOCA / MFT 安装。对于这些内容，请参阅 doca-public-knowledge-map/SKILL.md、doca-pcc/SKILL.md 或 doca-setup/SKILL.md。

此技能提供的内容

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

• capabilities 配套文件——说明 pcc_counters.sh 的功能：它仅支持两种操作（set 会将计数器 ID 和参数写入 debugfs，以启用设备的诊断计数器；query 会读取 diag_cnt/dump 并打印具名计数器）；它所支持的 FIXED 固件／HW 计数器集合（PCC_CNP_COUNT、MAD_RTT_PERF_CONT_*、*_EVENT_WRED_DROP 系列、HANDLED_*_EVENTS、DROP_RTT_PORT*／RTT_GEN_PORT* 系列）；它如何将 mst 设备解析为 PCI 地址（mst status -v + lspci），并访问 /sys/kernel/debug/mlx5/<pci>/diag_cnt/；将安装可用性信息重定向到 doca-version/SKILL.md 的覆盖机制；分层错误分类（脚本不存在／设备错误／查询前未启用／debugfs 或权限问题／计数器始终为零／跨层问题）；以及安全策略：将 set 标记为需要特权的 debugfs 写入操作，并将任何基于读数得出的 CC 调优决策标记为高风险。
• tasks 配套文件——针对适用任务动词的分步工作流：configure（转到安装说明，并确认 mst／debugfs／sudo）、build（转到安装说明；无需编译，这是一个脚本）、modify（拒绝——不要修补随附脚本）、run（依次执行 set 和 query）、test（确认转储包含具名计数器且数值有限）、debug（分层诊断流程）；此外还有 Deferred task verbs 区块和 Command appendix。

此技能假设主机或 BlueField 已安装 DOCA／MFT（具备 mst 工具、已挂载 debugfs，并且可用 sudo），且目标设备可通过 mst status -v 查看。

此技能有意不包含的内容

此技能是面向 Agent 的指导，而不是示例或脚本包。为明确划定边界，此技能有意不包含以下内容；也不应在拉取请求中添加：

• 虚构的标志或子命令。 pcc_counters.sh 仅有两种操作（set、query），且恰好接受两个位置参数；它没有 --help、--version、list、snapshot、watch 或 diff。不要虚构任何此类内容。
• 预先编写的计数器示例值。 计数器值因设备、固件和流量状态而异；采集到的值可能会误导使用其他设备的操作人员。
• 包装器、解析器或重写版脚本。 脚本就是约定；修改或重新实现脚本不在范围内。
• 基于计数器读数给出的具体拥塞控制调优建议。 这是一个高风险领域问题——此技能规定如何采集计数器；对于如何将变化量转化为 CC 参数变更，此技能不会代替用户自己的领域分析作出判断。
• samples/ 或 reference/ 子树。 这是用于已文档化脚本的轻量加载器；实质性内容位于脚本和公开的 PCC 文档中。

加载顺序

1. 首先阅读此技能，确认用户的问题属于适用范围（读取设备的固件 PCC 诊断计数器；而非设计或加载自定义算法）。
2. 有关脚本功能、固定计数器集合、debugfs 机制、安装可用性覆盖机制、分层错误范围和安全原则，请参阅 capabilities 配套文件。
3. 有关已文档化的调用方式——configure、build、modify、run、test、debug，以及 Command appendix——请参阅 tasks 配套文件。

相关技能

• doca-pcc/SKILL.md — 用于在主机端编写自定义拥塞控制内核并将其加载到 DPA 的库。这是一个独立的领域：固件 PCC 诊断计数器 pcc_counters.sh 读取的数据独立于任何自定义 doca-pcc 内核而存在，但调优自定义算法的操作员可以读取这些计数器，以观察设备级别的 CC 行为。混淆脚本（固件计数器读取）与库（自定义算法加载／控制），是初次接触 PCC 时最常见的错误。
• doca-public-knowledge-map/SKILL.md — 用于跳转到 DOCA／PCC 公共文档集，包括固件 PCC 算法配置。
• doca-version/SKILL.md — DOCA 版本处理的规范规则。能力补充文档中的 ## Version compatibility 部分是简明的补充说明，指向此处。
• doca-setup/SKILL.md — 环境准备、安装验证、mst 工具、debugfs，以及使用公共 NGC DOCA 容器的尚未安装路径。此技能假设其前置条件均已满足。
• doca-debug/SKILL.md — 跨领域的调试步骤。在提出任何拥塞控制调优建议之前，PCC 计数器读取可作为只读的设备状态证据来源。
• doca-programming-guide/SKILL.md — 适用于整个工具包的通用 DOCA 编程模式。