doca-pcc

DOCA PCC

例

• 「BF ポートに独自の輻輳制御を読み込む。」 — これは対象範囲内です。ホスト側の doca_pcc と、DPACC でビルドした doca_pcc_app を使用してください。ここでアルゴリズム本体を書き換えないでください。
• 「アルゴリズムの読み込み時に DOCA_ERROR_NOT_PERMITTED が発生する。」 — 読み込み呼び出しを変更する前に、ファームウェアのカスタム PCC スロットと DPA の公開設定を確認してください。

手順

以下の読み込み順序に従ってください。設定／読み込み／デバッグについてはタスク用の補足ドキュメントを開いてください。3 軸の機能クエリについては機能用の補足ドキュメントを開いてください。補足ファイルをすべて開く必要はありません。

最初に確認すること： このスキルは、DOCA がすでにインストールされており、ユーザーの BlueField に、ホストから DOCA 経由で認識できる DPA プロセッサがあり、BlueField ファームウェアでカスタム PCC スロットが有効になっていて、ユーザーがホスト側でカスタム PCC を実際に操作していることを前提としています。つまり、doca-pcc を使って DPA 側の輻輳制御アルゴリズムを BlueField に読み込み、RDMA／RoCE トラフィックを処理するポートに割り当て、ホストからパラメーターを設定している状態です。ユーザーが何かを実行したい（設定／ビルド／変更／実行／テスト／デバッグ）場合はタスク用の補足ドキュメントを開いてください。質問が、このバージョン＋この BlueField 世代＋このファームウェアにおいて、ホスト側 PCC API で何を表現できるかに関するものなら、機能用の補足ドキュメントを開いてください。ユーザーがまだ 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の質問クラスを、 それぞれ1つの実例とともに示します。エージェントは、実例そのものではなく、 土台となる「クラス」を重視してください。実例は、各クラスの一例にすぎません。

• 「RDMA／RoCEトラフィックを流すBlueFieldポートに、独自の輻輳制御アルゴリズムをデプロイするにはどうすればよいですか？」 — 実例：「小規模なDPA側PCCアルゴリズムをロードし、RoCEトラフィックを処理するBlueFieldポートにアタッチしたい」。

  Capabilities and modes

  にある両側プログラムモデルと、ホスト側でのロードおよびアタッチのワークフロー、 さらに

  configure

  にある起動手順で回答します。
• 「このBlueFieldとファームウェアで独自のPCCアルゴリズムは実際に使えますか。また、インストール済みのDOCAでどのPCC機能が利用できますか？」 — 実例：「ホストにはBlueFieldがあり、デフォルトの工場出荷時PCCは動作します。代わりに独自のアルゴリズムを追加できますか？」。doca_pcc_cap_* とアクティブな doca_devinfo の結果が一致すること、ファームウェアで独自PCC用スロットが有効になっていること、BlueFieldの世代がDPAを搭載していること、という3軸の前提条件ルールを

  Capabilities and modes

  で説明し、

  configure step 1

  の環境前提条件チェックリストで回答します。
• 「doca_dev にアクセスできるのに、独自のPCCが DOCA_ERROR_NOT_PERMITTED で失敗するのはなぜですか？」 — 実例：「このホストのBlueFieldファームウェアでは、独自PCC用スロットが無効になっている」。権限マトリクスを

  Safety policy

  で説明し、

  configure step 1

  でファームウェア側の環境修正方法を示して回答します。
• 「この doca-pcc ライブラリは目的に合ったツールですか。それともデフォルトのファームウェアPCCや pcc_counters CLIを使うべきですか？」 — 実例：「アルゴリズムには手を加えず、PCCカウンターだけ読み取りたい」。

  Capabilities and modes

  の選択ルールと

  Deferred topic boundaries

  の対象外トピックの境界を使って、 カウンターツールの doca-public-knowledge-map ## DOCA tools (doca-public-knowledge-map/SKILL.md#doca-tools) に案内します。
• 「調べているホスト側PCC APIは、インストール済みのDOCAで使えますか？」 — 実例：「ドキュメントで見たホスト側ロードヘルパーは、このホストのDOCAとDPACCのバージョンで使えますか？」。

  Version compatibility

  のバージョン互換性オーバーレイを使って回答します。これにより、 doca-version/SKILL.md の標準検出チェーンに相互リンクし、 doca-dpa/SKILL.md から継承した、PCC固有の DOCA must match DPACC オーバーレイを追加します。
• 「doca_pcc_* の呼び出しで返されたこの DOCA_ERROR_* は何を意味し、どのレイヤーが原因ですか？」 — 実例：「ホスト側のアルゴリズムロード呼び出しで DOCA_ERROR_DRIVER が発生しました。原因はDOCA、ファームウェア側の独自PCC用スロット、それともDPACCで生成されたイメージですか？」。

  Error taxonomy

  のライブラリ横断分類に対するPCCオーバーレイと、 doca-debug/SKILL.md に引き継ぐ

  debug

  のレイヤー別手順で回答します。

対象読者

このスキルの対象は、ホスト側からDOCA PCCライブラリを利用する外部開発者です。具体的には、doca_pcc_* を呼び出してポートごとのコンテキストを用意し、dpacc が生成した doca_pcc_app イメージをロードしてRoCEを流すBlueFieldポートにアタッチし、パラメーターを設定して起動し、実行時のレポートを確認するコードを扱う開発者です。NVIDIAでDOCA PCCの開発に携わる開発者向けではなく、DPA側のアルゴリズム本体の記述方法を学ぶ場所でもありません（公開されているPCC／DPA／DPACCガイドについては、doca-public-knowledge-map/SKILL.md を参照してください）。

言語の範囲。 DOCA PCCはホスト側Cライブラリ（pkg-config モジュール doca-pcc）として提供されています。DPA側のアルゴリズムは別の翻訳単位であり、dpacc がコンパイルしてPCCアルゴリズムイメージを生成します。FFIを介した回避策はありません。doca_pcc_* を操作するRust／Go／Pythonのホスト側ラッパーも有用であり、このスキルのガイダンスは言語に依存しない形で提供します。

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

ユーザーがホスト側からカスタム輻輳制御アルゴリズムの DOCA PCC を実際に扱っている場合に、このスキルを読み込んでください。具体的には、次のような作業が対象です。

• 制御対象の RDMA／RoCE トラフィックを運ぶ BlueField ポートに対応する doca_dev に対して、doca_pcc を初期化する。
• dpacc で生成した doca_pcc_app アルゴリズムイメージを doca_pcc コンテキストに読み込む。
• アルゴリズムのパラメーターを設定し、doca_pcc Core コンテキストを開始して、ポート上の RoCE トラフィックに影響させる。
• 有効な doca_devinfo が doca_pcc_cap_* を通じてサポートする PCC 機能を確認する。BlueField の世代やファームウェアのリビジョンによって、カスタム PCC アルゴリズムを使用できるかどうかが異なります。
• doca_pcc_* から返される DOCA_ERROR_* をデバッグする。ファームウェアでカスタム PCC スロットが無効、デバイスがカスタム PCC に対応していない、イメージに互換性がない、通常の doca_dev アクセスが拒否された、のいずれかを切り分けます。
• 別途 dpacc でビルドしたアルゴリズムイメージを操作する、C 以外のホスト側バインディングを設計する。環境の前提条件と機能に関するルールは引き続き適用されます。

一般的な DOCA の概要、DOCA／DPACC のインストール、DPA 側のプログラミングモデルそのもの、ConnectX ファームウェアに同梱されているファクトリー PCC アルゴリズム（ファームウェアのみで、ホスト側コードはありません）、または pcc_counters 診断 CLI を扱う場合は、このスキルを読み込まないでください。これらについては、doca-public-knowledge-map/SKILL.md を参照して、該当するアップストリームガイドに進んでください。

このスキルで提供する内容

これは薄いローダーです。本体には、次に参照すべきファイルを選ぶために必要な概要のみを残しています。PCC 固有の実質的な内容は、2 つの関連ファイルにあります。

• 機能に関する関連ファイル — このバージョン、この 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 操作 6 つ（configure、build、modify、run、test、debug）の手順を説明します。また、対象範囲外の質問を適切な次のスキルに案内する Deferred task verbs ブロックも含まれます。

このスキルは、DOCA が標準の場所にすでにインストールされているホスト、DPA プロセッサを搭載した BlueField が物理的に存在し、ホストから認識できる環境を前提とします。また、BlueField ファームウェアでカスタム PCC スロットが有効になっていること、DOCA Compatibility Policy に従って DOCA のインストールと互換性のあるバージョンの DPACC コンパイラーがインストールされていること、ユーザーが dpacc でコンパイルする DPA 側 PCC アルゴリズムの書き方を（概要レベルでも）すでに把握していることも前提です。DOCA のインストール、DPACC コンパイラーのインストール、ファームウェアレベルの設定変更は扱いません。これらについては doca-setup/SKILL.md を参照してください。

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

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

• DOCA PCC アプリケーションの事前作成済みソースコード、または DPA 側の アルゴリズムのソースコード（言語を問いません）。 検証済みの PCC ソースは、 /opt/mellanox/doca/samples/doca_pcc/ にある、付属の C + DPA 側サンプルです。 エージェントの役割は、ユーザーをそれらのファイルに案内し、 doca-programming-guide/SKILL.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-public-knowledge-map/SKILL.md#doca-tools）にあります。 これをライブラリと混同することは、PCC の初回アプリケーション設計で 最もよくある誤りです。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内 （ホスト側のカスタム PCC 作業であり、DPA 側のアルゴリズム設計でも カウンターツールでもない）であることを確認します。
2. PCC の機能マトリックス、2 プログラムモデル、インスタンスごとの doca_pcc コンテキスト、読み込み済みの doca_pcc_app アルゴリズム イメージ、ポートへのアタッチのセマンティクス、3 軸の前提条件ルール、 環境変数の前提条件ポリシー、エラーの分類体系、可観測性の範囲、 安全性ポリシーについては、機能の補足資料を参照してください。
3. 設定、ビルド、変更、実行、テスト、デバッグの手順ごとのワークフローに ついては、タスクの補足資料を参照してください。

どちらの補足ファイルも、互いにリンクしています。また、 DOCA のバージョン処理に関する標準ルール（DOCA のバージョンが DPACC コンパイラーと一致する必要があるという PCC 固有の補足を含む）を記載した doca-version/SKILL.md にもリンクしています。さらに、 適切な回答が「PCC のホスト側に固有のガイダンス」ではなく、 「公開されている DOCA PCC プログラミングガイド、公開されている DPA / DPACC ガイド、pcc_counters ツールガイド、またはディスク上の インストールレイアウトを確認する」である場合には、 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 のライフサイクルと同じ形をしています。ユーザーに、PCC がその上に構築される DPA レベルの質問（カーネル起動モデル、DPA 側ライブラリ）がある場合、エージェントはこのスキルと併せて doca-dpa を読み込みます。
• doca-rdma/SKILL.md — カスタム PCC アルゴリズムが制御するトラフィックを扱うライブラリです。カスタム PCC アルゴリズムは、接続された BlueField ポート上の RDMA / RoCE フローに影響します。ユーザーがそのポートで RDMA / RoCE トラフィックをまだセットアップしていない場合、アルゴリズムが作用できる対象はありません。そのトラフィックを立ち上げるのが doca-rdma スキルです。
• doca-setup/SKILL.md — 環境の準備、インストールの検証、DPACC コンパイラーのインストール／検証、BlueField ファームウェアの設定（カスタム PCC スロットの有効化を含む）、および まだ何もインストールしていない場合に公開 NGC DOCA コンテナーを使用する手順です。このスキルでは、前提条件が満たされ、かつ DPACC が DOCA に適合するバージョンでインストールされており、さらにファームウェアレベルのカスタム PCC スロットが有効になっていることを前提とします。
• doca-version/SKILL.md — DOCA のバージョンを扱うための標準ルールです。このスキルの ## Version compatibility では、DOCA Compatibility Policy に基づく 4 者間の一致ルールへの相互リンクを示し、PCC 固有の DOCA と DPACC のバージョンは一致させる必要があるという条件を追加しています（doca-dpa/SKILL.md から継承）。
• doca-structured-tools-contract/SKILL.md — バンドルの構造化ツールに関する優先順位ルール（検出／優先／フォールバック／報告）です。タスク用コンパニオンの Command 付録はこの契約に従います。
• doca-programming-guide/SKILL.md — すべてのライブラリで共有される DOCA プログラミングの一般的なパターンです。標準の pkg-config + meson ビルドパターン、同梱サンプルを変更する普遍的な最初のアプリケーション構築ワークフロー、普遍的な Core コンテキストのライフサイクル、ライブラリ間で共通の DOCA_ERROR_* 分類、プログラム側のデバッグ手順が含まれます。このスキルでは、これらに PCC 固有の内容を重ねます。
• doca-debug/SKILL.md — 横断的な デバッグ手順（インストール／バージョン／ビルド／リンク／ランタイム／プログラム／ドライバー）です。PCC 固有のデバッグ（ファームウェアでカスタム PCC スロットが有効になっていない、DPACC と DOCA のバージョン不一致、デバイスとの互換性がないとしてアルゴリズムイメージが拒否される、doca_pcc_start() が呼び出されていない、または接続されたポートに RoCE トラフィックがないために、読み込まれたアルゴリズムがオンワイヤーの変化を生み出さない）は、この手順に重ねて行います。

「読み込まれるのに、ワイヤー上で何も変わらない」はホスト側の問題です。 読み込みに成功しても、アルゴリズムが稼働中とは限りません。 doca_pcc_start() がポート上でアルゴリズムを稼働させるタイミングであり、PCC が調整するのは、doca_pcc の作成時に指定された doca_dev 上にすでに存在する RoCE トラフィックだけです。ここで両方を解決し、DPA 側のアルゴリズム本体は調査しないでください。そこは doca-dpa/SKILL.md の範囲であり、レポートが発生しているなら本体が動作していることはすでに確認できています。未確認なのは、アルゴリズムがバインドされ、稼働中であることです。順序に沿った確認手順は

debug を参照してください。