doca-pcc-counters

DOCA PCC Counters (pcc_counters.sh)

例

• 「このデバイスのPCC診断カウンターを読み取るにはどうすればよいですか？」 — これは対象範囲内です。アームしてからクエリしてください。PCCの アルゴリズム調整として扱わないでください。
• 「スクリプトにERROR: Bad Deviceと表示されました。」 — ファームウェアに 問題があると判断する前に、mstパスを解決してください。

手順

以下の読み込み順に従ってください。実行／ デバッグにはタスクのコンパニオンを開いてください。固定カウンターセットには 機能のコンパニオンを開いてください。コンパニオンファイルを すべて開かないでください。

開始場所： これは、pcc_counters.shを呼び出すためのツールスキルです。mlx5 debugfsのdiag_cntインターフェースを通じて、デバイスの固定されたファームウェア／ハードウェアのPCC診断 カウンター（CNPカウント、RTT-perf、WRED-drop、RTT-gen、処理済みイベント）をアームして読み取る小さなbashスクリプトです。正規のset→query手順についてはタスクのコンパニオンを開き、## runから開始してください。ユーザーから 「ERROR: Bad Device」、「カウンターがゼロのまま」、または*「ダンプが空です」*と報告された場合は、 ## 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の呼び出し方法で回答します。
• 「最小限の有効な呼び出し方は何ですか？」 — 具体例： 「具体的に何を入力すればよいですか？」。タスクのコンパニオンにある 位置引数2つの仕様 （set | queryとmstデバイスパス）で回答します。
• 「スクリプトにERROR: Bad Deviceと表示されました。何が問題ですか？」 — 具体例：「デバイスパスが一致しません」。 機能のコンパニオンにあるデバイス解決レイヤー と、タスクのコンパニオンで回答します。
• 「カウンターがゼロのままです。デバイスがアイドル状態なのか、 カウンターがアームされていないのか、それとも実際にイベントがないのか？」 — 具体例： 「query後もPCC_CNP_COUNTが0を示します」。読み取り前にアームするルールと、タスクのコンパニオンおよび 機能のコンパニオンにある 段階的な診断方法で回答します。
• 「このスクリプトはインストール先にありますか？どこにありますか？」 — 具体例： 「pcc_counters.shがあるか、インストール先はどこか」。機能のコンパニオンにあるインストール時の上書き情報で回答します。 この情報から、正規の doca-version/SKILL.mdのルールに案内されます。

対象読者

このスキルは、ポート上の輻輳制御の動作（CNP の生成、RTT リクエスト／レスポンス、WRED によるドロップ）を把握するために、ConnectX／BlueField デバイスのファームウェア PCC 診断カウンターを読み取る必要があるオペレーター、開発者、AI エージェントを対象としています。具体的には、次のような方が対象です。

• デバイスで輻輳制御イベント（CNP、RTT、WRED によるドロップ）が発生しているかを確認するネットワークオペレーター。
• カスタム doca-pcc アルゴリズムの効果をデバイスレベルの PCC 診断カウンターと照合する開発者（このスクリプトはファームウェアのカウンターを読み取ります。カスタムアルゴリズム自体は別の領域であり、doca-pcc/SKILL.md が対象です）。
• 輻輳制御の調査を裏付ける証拠として、PCC カウンターのスナップショットを作成する AI エージェント。

このスキルは、スクリプト自体の bash をデバッグするユーザー向けではありません。カスタム PCC アルゴリズムの書き方を学ぶ場所でもありません。その対象者には doca-pcc/SKILL.md が該当します。また、工場出荷時のファームウェア PCC アルゴリズムを設定したいユーザー向けの場所でもありません（その場合は doca-public-knowledge-map/SKILL.md を参照してください）。

pcc_counters.sh は、コンパイル済みのバイナリやリンクして使用するライブラリではなく、DOCA ツールディレクトリにインストールされる通常の bash スクリプトです（tools/pcc_counters/meson.build の install_data に従います）。このスキルでは、バンドル内でタスク動詞の契約（configure / build / modify / run / test / debug）を統一するため、kind: tool の 3 ファイル構成（このスキル、機能の補足ファイル、タスクの補足ファイル）を使用しています。

このスキルを読み込むタイミング

ユーザーが、またはエージェントが、mst ツールを利用でき、debugfs がマウントされたホストまたは BlueField Arm 上で、デバイスの PCC 診断カウンターを有効化して読み取る必要がある場合に、このスキルを読み込んでください。具体的には、次のような場合です。

• 対象の 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 を参照してください。

このスキルでできること

これは薄いローダーです。実質的な内容は、次の2つの補助ファイルにあります。

• capabilities 補助ファイル — pcc_counters.sh の動作内容：正確に2つの操作（set は、カウンターIDとパラメーターを debugfs に書き込んでデバイスの診断カウンターを有効にし、query は diag_cnt/dump を読み取って名前付きカウンターを出力します）、このスクリプトが認識する固定のファームウェア／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 にリダイレクトするインストール可用性オーバーレイ、階層化されたエラー分類（スクリプトが存在しない／デバイスが不正／query 前に有効化されていない／debugfs または権限の問題／カウンターがゼロのまま／複合的な問題）、および set を特権が必要な debugfs 書き込みとして扱い、読み取り値に基づく CC チューニングの判断をハイリスクとして扱う安全ポリシー。
• tasks 補助ファイル — 対象となるタスク動詞の手順を示したワークフロー：configure（インストールに誘導し、mst／debugfs／sudo を確認）、build（インストールに誘導。コンパイル対象はなく、これはスクリプトです）、modify（拒否 — 配布されているスクリプトにパッチを適用しない）、run（set の後に query を実行）、test（ダンプに名前付きカウンターが有限値で含まれていることを確認）、debug（階層化された診断手順）。さらに、Deferred task verbs ブロックと Command appendix も含まれます。

このスキルは、DOCA／MFT がすでにインストールされているホストまたは BlueField（mst ツールがあり、debugfs がマウントされ、sudo が利用可能）を前提とし、対象デバイスが mst status -v に表示されることを想定しています。

このスキルに意図的に含めていないもの

このスキルはエージェント向けのガイダンスであり、サンプルやスクリプトのバンドルではありません。範囲を明確に保つため、意図的に次の内容を含めていません。プルリクエストで追加しないでください。

• 存在しないフラグやサブコマンド。 pcc_counters.sh の操作は正確に2つ（set、query）で、位置引数を正確に2つ取ります。また、--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 — ファームウェアの PCC アルゴリズム設定を含む、公開 DOCA／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 プログラミングパターンです。