doca-pcc-ztr-rttcc-algo

DOCA PCC ZTR RTTCC アルゴリズム

例

• 「マルチパス PCC のバリアントはどのように選べばよいですか？」 — これは対象範囲内です。ビルド時に ZTR RTTCC バリアントを DPACC で選択してください。独自のアルゴリズムを考案しないでください。
• 「アルゴリズムは読み込まれましたが、カウンターの値が変わりません。」 — 書き換える前に、RoCE-v2 トラフィックが実際に流れていることと、パラメーターがホスト側で設定されていることを確認してください。

手順

以下の読み込み順に従ってください。設定／調整／デバッグについてはタスク用コンパニオンを開き、バリアントと FAIL ステータスについては機能用コンパニオンを開いてください。すべてのコンパニオンファイルを開く必要はありません。

開始する前に： このスキルは、DOCA と DPACC がインストール済みであり、BlueField が DPA をホストから認識できる BlueField-3 世代のデバイスであり、ファームウェアのカスタム 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 ガイドを使用してください。このスキルの対象は、DOCA 同梱のリファレンスアルゴリズムに限られます。

このスキルで適切に回答できる質問の例

このスキルで回答できる ZTR RTTCC の質問のクラスと、それぞれの回答例を示します。重要なのはクラスであり、回答例はその一例です。

• 「ZTR RTTCC のリファレンスアルゴリズムは、私のデプロイに適したベースラインですか。それとも独自のアルゴリズムを作成すべきですか？」 — 回答例：「GPU クラスターからの本番 RoCE-v2 トラフィックを処理する BlueField-3 を使っています。付属のアルゴリズムをデフォルトとして使えばよいですか。それとも独自のロジックが必要ですか？」。## 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 のステップ 6 にある切り分けに進み、まずそこから始めてください。CC イベントはアルゴリズムに届いていますか。イベントが届いていない場合、原因は誤ったアルゴリズムスロット、誤ったポートに接続された doca_pcc、または、よくある落とし穴として説明されている「制御対象となる RoCE-v2 トラフィックがそのポートを流れていないこと」です。この場合、アルゴリズムはロードされていますがアイドル状態であり、実行しても何も検証できません。イベントが届いているのに AI / 減算カウンターが変化しない場合に限り、パラメーターやコンパイル済みのバリアントを検討します。最初にパラメーターを調整したり、別のバリアントを再ビルドしたりするのは誤りです。## Safety policy ではこの点を明示しており、切り分け手順は## debug のステップ 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_* は何を意味し、どのレイヤーが原因ですか？」 — 回答例：「初回起動時に init コールバックが DOCA_PCC_DEV_STATUS_FAIL を返します」。ホスト側 PCC のエラー分類に対するアルゴリズム固有の補足を## Error taxonomyで説明し、## debug の段階的な手順では、doca-pcc/SKILL.md と doca-debug/SKILL.md を通じて調査を進めます。

対象ユーザー

このスキルは、RoCE-v2 トラフィックに NVIDIA 提供のリファレンス PCC アルゴリズムをデプロイしたい、または自作を予定しているカスタムアルゴリズムと比較評価したい、BlueField-3 クラスの DPU を運用する外部開発者を対象としています。このアルゴリズムは設計上、ゼロタッチで動作する、設定不要のベースラインです。アルゴリズム自体に貢献する 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 です。これを利用するデバイス側の翻訳単位は、DPACC でコンパイルされる C です。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 の 1 つのみです。各バリアントは、ユーザーがコンパイルする 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 経由で参照）についても対象外です。

このスキルでできること

これは薄いローダーです。本体には、次に参照すべきファイルを選ぶために必要な概要だけが記載されています。アルゴリズム固有の詳細は、2 つの関連ファイルに記載されています。

• capabilities 関連ファイル — このバージョンと BlueField の世代およびファームウェアで提供される ZTR RTTCC アルゴリズムが表現する内容：公開 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 側のコンパイル時に 1 つ選択）、ホスト側の doca-pcc フレームワークとの関係（フレームワークが読み込むアルゴリズム本体です）、doca-pcc-counters ツールとの関係（標準的な検査用インターフェースです）、アルゴリズムのパラメーターとカウンターのサーフェス（RTT ベースの輻輳シグナル、機能ごとのパラメーターブロック）、DOCA_PCC_DEV_STATUS_OK / _FAIL によるエラー分類、安全ポリシー。
• tasks 関連ファイル — 対象範囲内のアルゴリズム操作（install、configure、build、modify、run、test、debug、use）の手順です。さらに、対象範囲外の質問を適切な次のスキルに案内する Deferred task verbs ブロックもあります。

このスキルは、DOCA、DPACC、およびホスト側フレームワークの doca-pcc/SKILL.md がインストール済みであること、BlueField が DPA プロセッサを公開していること、ファームウェアのカスタム PCC スロットが有効であること（doca-pcc ## Safety policy を継承）、そしてアルゴリズムが制御するポートで RoCE-v2 トラフィックが実際に流れていることを前提としています。このアルゴリズムが制御するのは既存のトラフィックです。トラフィックがなければ、実行することはありません。

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

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

• 言語を問わず、アルゴリズム本体。 提供されるアルゴリズムは、対応する DOCA ホストパッケージでインストールされる静的ライブラリ libdoca_pcc_ztr_rttcc_algo_dev.a（およびホスト側ヘルパー）です。エージェントは、インストール済みのライブラリとヘッダー（doca_pcc_dev_ztr_rttcc_algo.h）をユーザーに案内し、提供済みの DOCA PCC アプリケーションのソースをその場で編集する、README に記載された手順を示します。アルゴリズムを作成することはありません。
• 単独で動作する PCC アプリケーション。 このアルゴリズムをホストする DOCA PCC アプリケーションは、/opt/mellanox/doca/applications/pcc/ にある、提供済みの C サンプルです。エージェントは、README に記載された最小限の差分による変更方法を示し、再ビルドの手順を案内します。別のアプリケーションを作成することはありません。
• すべての内部バリアントの動作の説明。 エージェントはバリアントの一覧を示し、このインストール環境で公開シンボルから利用できるものを伝え、アルゴリズム設計に関する質問を doca-public-knowledge-map/SKILL.md 経由で公開 PCC ガイドに案内します。各バリアントの数式を再定義することはありません。
• 輻輳制御のチュートリアル。 CC 理論、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制御ライブラリです。アルゴリズムはDPACCでコンパイルされ、DPA上で実行されます。2サイドプログラムのルールと、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ファームウェアの設定（カスタムPCCスロットの有効化を含む）、および公開NGC DOCAコンテナーを使う「まだインストールしていない」場合の手順を扱います。このスキルでは、それらの前提条件を満たし、DPACCがDOCAと一致し、カスタムPCCスロットが有効になっていることを前提とします。
• doca-version/SKILL.md — DOCAのバージョンを扱う標準的な方法です。## Version compatibilityでは、4者のバージョン一致ルールと、doca-pcc/SKILL.mdから継承されるDOCAとDPACCのバージョン一致に関するオーバーレイを相互参照しています。
• doca-structured-tools-contract/SKILL.md — タスクの補足資料にあるコマンドの付録で遵守する、「検出／優先／フォールバック／報告」の優先順位ルールです。
• doca-programming-guide/SKILL.md — DOCAプログラミングの一般的なパターンです。このスキルでは、共通のビルドワークフローと提供済みサンプルの変更ワークフローに、アルゴリズム固有のオーバーレイを追加します。
• doca-debug/SKILL.md — 横断的なデバッグ手順です。アルゴリズム固有のデバッグ（読み込み済みだがカウンターに変化がない、初期化に失敗する、調整が強すぎる、または弱すぎる）は、その上に追加で適用されます。
• doca-hardware-safety/SKILL.md — 横断的なハードウェア安全性のメタポリシーです。このアルゴリズムは本番環境のRoCE-v2フローを調整するため、このスキルの## Safety policyオーバーレイに基づき、事前確認、レプリカでの先行テスト、ロールバックのルールが適用されます。