doca-spcx-cc

DOCA SPCX 輻輳制御ツール

例

• 「カスタム CC アルゴリズムには SPCX と doca-pcc のどちらを使うべきですか？」 — 対象範囲内です。ライブファブリックで何かをロードする前に、判断フローを確認してください。
• 「SPCX をロードしましたが、スループットが変わりません。」 — パラメーターを再調整する前に、アルゴリズムが制御を担っていることを確認してください。

手順

以下の読み込み順に従ってください。設定／実行については、タスク用コンパニオンを開いてください。SPCX と PCC のトレードオフおよび安全性については、機能用コンパニオンを開いてください。コンパニオンファイルをすべて開く必要はありません。

最初に確認する内容： これは、BlueField の DPA プロセッサーで駆動されるライブ RDMA／RoCE ファブリック上で、SPCX クラスのプログラマブル輻輳制御アルゴリズムを実行する、文書化されたホスト側 CLI doca_spcx_cc を呼び出すためのツールスキルです。タスク用コンパニオンを開き、## configure から始めてください。ここでは、（コードを書く前に必ず確認すべき）SPCX と PCC とファクトリー ファームウェアの判断フロー、役割の選択（RP／NP）、DPA 側でのアルゴリズム作成と利用の切り分け、ライブリンク／競合に関する前提条件を説明しています。質問が「SPCX では doca-pcc にないどのような表現ができますか」、「SPCX と PCC のトレードオフは何ですか」、「このツールでどのランタイムメトリクスを確認できますか」、または「本番ファブリックにカスタム CC アルゴリズムをロードする際の安全性はどうなっていますか」に関する場合は、機能用コンパニオンを開いてください。DOCA がまだインストールされていない場合は、まず doca-setup/SKILL.md に進んでください。

このスキルは、次世代のプログラマブル CC サーフェスです。doca-pcc/SKILL.md は従来の PCC の説明です。SPCX は、同じ DPA ハードウェア基盤上で SPCX クラスのアルゴリズムを作成するための、文書化された拡張機能です。doca-pcc-ztr-rttcc-algo/SKILL.md は、出荷されているリファレンスアルゴリズムの 1 つ（ゼロタッチの RTT ベース CC）です。インストール状況とユーザーのアルゴリズム選択に応じて、PCC または SPCX のいずれの経路でもロードできます。機能用コンパニオンに従い、エージェントはこの判断フローを明示します。

このスキルが得意とする質問の例

このスキルが回答するように設計されている doca_spcx_cc に関する質問のクラスと、それぞれの具体例を示します。重要なのは質問のクラスであり、具体例はその一例です。

• 「カスタム CC アルゴリズムには SPCX と doca-pcc のどちらを使うべきですか？」 — 具体例：「RoCE ファブリック用に新しい RTT ベースの輻輳制御アルゴリズムを書きたいのですが、どのインターフェースを対象にすべきですか？」。capabilities コンパニオンの SPCX と PCC とファクトリーファームウェアの判断ツリー、および tasks コンパニオンのステップ 1 にある 「このインストール環境で SPCX が適切なインターフェースか」 の判定によって回答します。
• 「作成した SPCX アルゴリズムを本番環境に適用する前に、実際の RDMA リンクで評価するにはどうすればよいですか？」 — 具体例：「DPACC でコンパイルした SPCX アルゴリズムと、本番環境ではない BlueField のペアがあります。輻輳が発生する評価を実行するにはどうすればよいですか？」。capabilities コンパニオンの作成と利用の区別、およびライブリンクの前提条件と、tasks コンパニオンのレプリカを先に使う評価フローによって回答します。
• 「SPCX アルゴリズムは問題なくロードされたようですが、リンクのスループット／レイテンシの曲線に変化がありません。何が起きているのでしょうか？」 — 具体例：「ホスト側の doca_pcc --status は Active で安定したセッションを報告していますが、RoCE フローに変化が見られません」。capabilities コンパニオンのライブリンク／輻輳ルール、tasks コンパニオンの 「輻輳がなければアルゴリズムにシグナルはない」 というガイダンス、およびアルゴリズムを疑う前に階層化されたエラー分類をたどる tasks コンパニオンによって回答します。

輻輳なし → シグナルなし → 結論なし。 Active とトラフィック曲線に変化がないことは、アルゴリズムがファクトリー CC から制御を引き継げなかった証拠にはなりません。ファブリックで実際に輻輳が発生していなければ、CC アルゴリズムの動作を観測できません。そのため、リンクがアイドル状態の実行や、輻輳が発生していない実行は、そもそも有益な情報にならず、どちらの方向の判定も裏付けません。何らかの結論を出す前に、実行中に実際に輻輳が発生したことを確認してください。また、そのような実行結果を根拠に、アルゴリズムが壊れているとも安全であるとも決して判断しないでください。capabilities コンパニオンのルール。

• 「SPCX アルゴリズムはレプリカテストに合格しました。本番環境に展開する前の関門は何ですか？」 — 具体例：「ラボにある 2 組の BlueField ペアでは CC アルゴリズムが動作しています。フリートに展開してもよいですか？」。capabilities コンパニオンの安全性に関する補足（doca-hardware-safety/SKILL.md への相互リンクが多数あります）によって回答します。本番環境への切り替え前に、影響範囲の制限、監視可能性の確認、OOB への到達性、ファクトリー PCC へのロールバックのリハーサル、エスカレーション経路の文書化が必要です。
• 「このインストール環境に doca_spcx_cc はあり、対応する doca-pcc ライブラリと DPACC コンパイラのバージョンが組み合わされていますか？」 — 具体例：「自分の DOCA インストール環境で SPCX インターフェースを利用できますか？」。capabilities コンパニオンのバージョンに関する補足によって回答します。これは正規の doca-version/SKILL.md の手順に誘導し、ツール ↔ doca-pcc ライブラリ ↔ DPACC コンパイラ ↔ ファームウェアのカスタム PCC スロットの一致ルールを追加します。
• 「SPCX セッションでエラーが発生しました。原因はツール、アルゴリズム、デバイス、ファームウェアのどれですか？」 — 具体例：「doca_spcx_cc の起動時に DOCA_PCC_PS_ERROR で終了します」。capabilities コンパニオンの階層化されたエラー分類と、tasks コンパニオンの階層的な調査手順によって回答します。

対象読者

このスキルは、DPA プロセッサーを搭載した BlueField 上で、稼働中の RDMA／RoCE ファブリックに対して、SPCX クラスのプログラマブル輻輳制御アルゴリズムを作成、読み込み、評価する外部開発者、プラットフォーム運用者、AI エージェントを対象としています。具体的には、次のとおりです。

• SPCX クラスの DPA 側アルゴリズムを作成した CC 研究者／開発者（または、インストール環境とアルゴリズムが対応している場合に、SPCX 経路で doca-pcc-ztr-rttcc-algo/SKILL.md を介してゼロタッチ RTT ベースのアルゴリズムなど、ドキュメント化された同梱リファレンスを利用する開発者）で、アルゴリズムの読み込み、パラメーター設定、起動、監視、停止に運用者側ハーネスが必要な方。
• 制御された競合状態下でのアルゴリズムの動作を評価するため、非本番の RDMA ファブリックでプログラマブル CC のパイロットを実施するプラットフォーム運用者。
• データシートの記述から推測するのではなく、競合が実際に発生する環境での評価結果、工場出荷時の PCC へのロールバック手順、明示的な影響範囲の上限に基づいて、*「この SPCX アルゴリズムを安全にロールフォワードできるか」*を正直に判断する AI エージェント。

これは、doca_spcx_cc バイナリ自体のデバッグを行うユーザー向けではありません。公開されている DOCA SPCX／DOCA PCC プログラミングガイドの代わりにもなりません。DPA 側アルゴリズムの作成方法を説明する場所としても適していません（その場合は、公開 DOCA SPCX プログラミングガイドと doca-pcc/SKILL.md および doca-dpa/SKILL.md スキルを参照してください）。また、工場出荷時のデフォルト PCC 設定を扱う場所としても適していません（ホスト側ライブラリも SPCX ツールも不要です。doca-public-knowledge-map/SKILL.md を参照してください）。

このツールは、リンクして使用するライブラリではなく、/opt/mellanox/doca/tools/ 配下に CLI バイナリとして同梱されています。バンドル内のほかのものと同じ kind: tool の 3 ファイル構成を使用します。

言語の範囲

doca_spcx_cc は、ホスト側の doca-pcc/SKILL.md ライブラリにリンクし、DPACC コンパイラーでビルドされた DPA 側 SPCX アルゴリズムイメージを読み込む C のホスト側 CLI です。アルゴリズム本体は、DPACC が受け付ける言語で記述された、DPA 側の独立した翻訳単位です。このスキルではワークフローのガイダンスを言語に依存しない形で提供し、言語ごとの質問については doca-public-knowledge-map/SKILL.md を介して公開 DOCA SPCX／DOCA PCC／DPACC ガイドを参照します。

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

ユーザーが、またはエージェントが、DOCA をインストール済みの実ホストで doca_spcx_cc を実行し、DPA プロセッサーが公開され、かつファームウェアのカスタム PCC スロットが有効な BlueField と組み合わせて、実際の競合が発生している RDMA／RoCE トラフィックを運ぶポートに対して使用する場合は、このスキルを読み込んでください。具体的には、次のとおりです。

• 作成した SPCX アルゴリズム（またはドキュメント化された同梱リファレンス）を SPCX インターフェイス経由で BlueField に読み込み、パラメーターを設定して起動し、稼働中のリンクへの影響を観察する場合。
• 本番環境へのロールアウト前に、非本番環境のレプリカで SPCX アルゴリズムを評価し、競合が実際に発生している実行結果を証拠として記録する場合。
• 同じインストール環境で利用可能な場合に、同じアルゴリズムクラスについて SPCX 経路と doca-pcc 経路を比較し、どちらを採用するかを決定する場合。
• 能力に関する補足資料に従って、必要な証拠やロールバック手順が不足している場合は推奨を見送るか、ドキュメント化された証拠とロールバック計画に基づいて、*「安全にロールフォワードできる」*という推奨を作成する場合。
• 階層化されたエラー分類に基づいて、DOCA_PCC_PS_ERROR または何も効果が現れない症状を診断する場合。

DOCA の一般的な概要、DPA 側アルゴリズムの作成方法、DPA の生のサイクルプロファイリング、ファームウェアに同梱されている工場出荷時の PCC アルゴリズム、または DOCA のインストールを行う場合は、このスキルを読み込まないでください。これらについては、doca-public-knowledge-map/SKILL.md、doca-pcc/SKILL.md、doca-dpa/SKILL.md、または doca-setup/SKILL.md を参照してください。

このスキルが提供するもの

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

• 機能に関する補助ファイル — SPCXで表現でき、PCCでは表現できないもの（および両者の機能が重なる部分）、SPCX・PCC・ファクトリーファームウェアの選択フローチャート、作成と利用の区分、役割の選択（RP / NP）、文書化されたプローブパケット形式の軸、ライブリンク／輻輳の前提条件ルール（安全性を支える不変条件 — 「輻輳がなければ、CCアルゴリズムにはシグナルがありません」）、ランタイムの可観測性の範囲（ポート単位／フロー単位のトレース形式とホスト側のステータス画面）、SPCX固有の可用性を加えた3軸の前提条件ルール（doca-pcc/SKILL.md：DPA対応のBlueField + ファームウェアのカスタムPCCスロットが有効 + doca_pcc_cap_*の一致）、バージョンの対応関係（ツール ↔ ライブラリ ↔ DPACC ↔ ファームウェア）、階層化されたエラー分類（インストール／デバイスのバインド／ファームウェアスロット／DPAイメージ／アルゴリズムの前提条件／ライブリンクの前提条件／ランタイム／バージョン／横断的な問題）、可観測性の範囲、そして厳重な安全対策（本番環境で誤ったCCアルゴリズムを使用するとファブリックに深刻な障害を起こす可能性があります）。
• タスクに関する補助ファイル — 対象範囲内のタスク動詞に対するステップごとのワークフロー：install（ホスト側のDOCAインストール + DPAの前提条件 + ファームウェアのカスタムPCCスロット）、configure（SPCXとPCCの選択 + 役割 + アルゴリズム + パラメーター + プローブパケット形式）、build（インストールに誘導 — ホスト側のツールは同梱されており、DPA側のアルゴリズムはユーザーがDPACCでビルドします）、modify（拒否 — バイナリにパッチを適用せず、呼び出し方、アルゴリズム、パラメーターを変更します）、run（準備 → スモークテスト → 輻輳ありの評価という手順）、test（本番環境に移行する前にレプリカ上で反復します）、debug（エラー分類に沿って確認します）、use（証拠 + ロールバック + エスカレーションに基づく「安全に次のバージョンへ進められる」判断）、およびDeferred task verbsブロック。

このスキルでは、DOCAがすでにインストールされているホスト、DPAプロセッサを搭載しファームウェアレベルのカスタムPCCスロットが有効になっているBlueFieldが存在して認識されていること、ホスト側のDOCAとバージョンが一致するDPACCコンパイラーがインストールされていること、ユーザーがDPA側のSPCXアルゴリズムの作成方法を（概要レベルで）すでに理解していること（または同梱のリファレンスアルゴリズムを利用できること）、さらに制御可能な輻輳が発生する、評価用の非本番RDMA / RoCEファブリックが利用可能であることを前提としています。

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

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

• 特定の輻輳制御アルゴリズム。 SPCX はユーザーが用意したアルゴリズムを読み込みます。このスキルはアルゴリズム本体を作り出すことを拒否し、「どのアルゴリズムを書くべきか」という質問は、公開されている DOCA SPCX／DOCA PCC プログラミングガイドと、ユーザー自身のドメイン知識を参照するよう案内します。
• あらかじめ用意された出力例（スループット／レイテンシ曲線、フローごとのカウンタースナップショット）。出力はデバイス、ファームウェア、ファブリックトポロジ、ワークロードによって異なるため、ひとつに固定すると、ほかの環境のオペレーターに誤解を与えます。
• 公開されている DOCA SPCX ページと --help に記載されたもの以外の、フラグ文字列、サブコマンド名、プローブパケット形式のトークン、メトリクス名。 このインターフェースは現在も進化しています。インストール済みの --help が、正式な一覧です。
• ツールの出力を処理するラッパー、パーサー、スクリプト。 形式は文書化されています。実際に使用しているバージョンに合わせて、最新のガイドを参照しながらスクリプトを作成してください。
• 単一の観測結果から導き出したチューニングの推奨事項。 稼働中のファブリックにおける CC のチューニングには重大なリスクが伴います。このスキルでは、証拠を取得し、工場出荷時の PCC ベースラインと比較する方法を案内します。また、ユーザー自身のドメイン分析なしに、単一の観測結果をパラメーター変更に結び付けることは拒否します。
• samples/ または reference/ サブツリー。 これは付属の CLI を読み込むための薄いローダーです。実質的な資料は、公開ページ、--help、および doca-pcc/SKILL.md + doca-dpa/SKILL.md にあります。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内（SPCX 側のカスタム CC 作業）であることを確認します（工場出荷時ファームウェアの PCC、生の DPA サイクルプロファイリング、アルゴリズム作成の詳細は対象外です）。
2. SPCX と PCC の選択ツリー、作成と利用の区別、ライブリンクの前提条件、バージョンオーバーレイ、エラー分類、可観測性の範囲、安全性に関する方針については、機能ガイドを参照してください。
3. 文書化された実行方法と、準備 → スモークテスト → 正の輻輳評価のワークフロー（install、configure、build、modify、run、test、debug、use）については、タスクガイドを参照してください。

関連スキル

• doca-pcc/SKILL.md — SPCX の基盤となり、SPCX がリンクするホスト側のプログラマブル混雑制御ライブラリです。 capabilities の関連資料にある SPCX と PCC の選択ツリーが、重要な振り分けルールです。この 2 つを混同することが、プログラマブル CC に初めて触れる際に最もよくある誤りです。
• doca-pcc-ztr-rttcc-algo/SKILL.md — 出荷されている、ゼロタッチの RTT ベース CC アルゴリズムのリファレンスです。リファレンスアルゴリズムを作成するのではなくデプロイする場合に、このツールのオペレーター側ワークフローと対をなすアルゴリズム側の資料です。
• doca-dpa/SKILL.md — アルゴリズムの DPA 側の実装が基盤とする DPA 制御ライブラリです。カーネル起動モデル、DPACC のビルドフラグ、DPA 側の通信／verbs を扱います。
• doca-rdma/SKILL.md — 制御対象となる RDMA／RoCE のフローです。トラフィックが流れており、かつファブリックで輻輳が発生していなければ、アルゴリズムはシグナルを得られません。評価を始める前に、この前提条件を明示してください。
• doca-pcc-counters/SKILL.md — 読み取り専用の PCC カウンター確認です。SPCX の評価前または評価中に、「このポートで何か起きているか」を低コストで確認する手順です。
• doca-hardware-safety/SKILL.md — このスキルの ## Safety policy が適用する、バンドル全体のハードウェア安全性メタポリシーです。本番ファブリックに誤った CC アルゴリズムをデプロイするケースは、メタポリシーによる停止の対象です。
• doca-public-knowledge-map/SKILL.md — 公開されている SPCX、PCC、DPA／DPACC ガイドへの振り分け先です。
• doca-version/SKILL.md — DOCA バージョンの標準的な取り扱い方法です。capabilities の関連資料にある ## Version compatibility では、ツール ↔ doca-pcc ↔ DPACC ↔ ファームウェアの custom-PCC スロットの照合ルールを追加しています。
• doca-setup/SKILL.md — 環境の準備、インストールと DPACC コンパイラーの検証、BlueField ファームウェアの設定（custom-PCC スロットはファームウェアレベルの設定です）、および公開 NGC DOCA コンテナーを使う「まだインストールしない」手順を扱います。
• doca-debug/SKILL.md — 分野横断的なデバッグ手順です。原因が DOCA より下位の層にある場合は、実行時の証拠とカウンタースナップショットを doca-debug セッションに関連付けてください。
• doca-structured-tools-contract/SKILL.md — タスクの関連資料にあるコマンド付録が従う、「検出 → 優先 → フォールバック → 報告」の契約です。
• doca-programming-guide/SKILL.md — このツールのエラーレイヤーが重ねて適用する、ライブラリ横断の DOCA_ERROR_* 分類など、DOCA 共通のプログラミングパターンを扱います。

ConnectX ファームウェアに組み込まれている工場出荷時の PCC アルゴリズムは、対象範囲外です。これらは doca_spcx_cc なしで動作し、ホスト側 API ではなくファームウェアの設定項目を通じて設定します。doca-public-knowledge-map/SKILL.md を参照してください。