doca-bench-extension

DOCA Bench 拡張機能

例

• 「私のワークロードクラスは、組み込みの doca-bench モードにありません。」 — 組み込みモードに適合するものがないことを確認した後であれば、対象範囲内です。 標準的な RDMA スループット計測の場合は、ここから始めないでください。
• 「doca-bench がカスタム .so を見つけられない、または読み込めません。」 — カーネルを書き換える前に、 検出、soversion、エクスポートされたシンボルを確認してください。

手順

以下の読み込み順に従ってください。設定／ビルド／実行／デバッグについては、タスク用の補助ファイルを開いてください。拡張機能 API の概要については、機能用の補助ファイルを開いてください。補助ファイルをすべて開く必要はありません。

開始する場所： これは、doca-bench/SKILL.md を拡張する拡張機能／プラグインフレームワーク用のツールスキルであり、単独でワークロードの形状を扱うスキルではありません。タスク用の補助ファイルを開き、まず ## configure から始めて、3 つの軸による判断（ワークロードクラスが doca-bench の組み込みモードの対象外である × 拡張機能 API の範囲に適合する × 親ツールとの同時ロードが許容できる）を確定します。次に ## build でカスタム拡張機能のコンパイル方法と配置方法を確認し、続いて ## run で doca-bench が拡張機能を検出して呼び出す方法を確認し、その後 ## test で、新しい拡張機能ごとにエージェントが適用する一括実行前のスモークテスト手順を確認してください。拡張機能で組み込みの doca-bench モードではできないこと、拡張機能 API の概要（公開されているリファレンスで示される DOCA_EXPERIMENTAL の C エントリーポイント）、ビルド／登録／検出の流れ、または拡張機能のライフタイムが親の doca-bench 呼び出しによって制限される仕組みについての質問であれば、機能用の補助ファイルを開いてください。doca-bench 自体についての質問であれば、doca-bench/SKILL.md に案内してください。「どの組み込み doca-bench モードを選べばよいか」という質問も doca-bench/SKILL.md の対象です。拡張機能は、組み込みモードでカバーされないワークロード向けの出口です。

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

• 「私のワークロードクラスは <X> です。doca-bench でネイティブに計測できますか、それとも拡張機能が必要ですか？」 — 拡張機能と組み込み機能のどちらを選ぶかという質問です。エージェントはまず、組み込みモードの一覧がある doca-bench/SKILL.md にユーザーを案内し、該当する組み込みモードがない場合にのみ、拡張機能フレームワークを案内します。
• 「DOCA GPUNetIO の RX キューと TX キューを使用する CUDA／GPU 側のワークロードをベンチマークしたいです。どこから始めればよいですか？コピーできるリファレンス拡張機能はありますか？」 — エージェントは /opt/mellanox/doca/tools/bench_extension/doca_bench_cuda/ にある公開済みの doca_bench_cuda 拡張機能をリファレンスとして示し、その API の範囲とビルド形式を順を追って説明します。
• 「doca-bench は、実行時にカスタム拡張機能をどのように検出して読み込むのですか？バージョン管理された共有ライブラリですか？エントリーポイントはどのような形式にすればよいですか？」 — ビルド／登録／検出の流れに関する質問です。エージェントは Meson でビルドされた共有ライブラリの形式、バージョン管理、親ツールによる実行時の検出経路を説明します（エージェントはこれを記憶から作り上げるのではなく、公開済み拡張機能の meson.build と docs.nvidia.com の DOCA Bench 公開ドキュメントを信頼できる情報源とします）。
• 「手元にある API ヘッダーには DOCA_EXPERIMENTAL と記載されています。DOCA のリリース間で、拡張機能の安定性にはどのような影響がありますか？リリースのたびに再ビルドが必要になりますか？」 — 実験的な API の範囲と、バージョン互換性に関する質問です。
• 「拡張機能をビルドした後、実際のワークロードに使う前に実行できる、最小限のスモークテストは何ですか？doca-bench が実際に拡張機能を読み込み、呼び出し、親ツールが期待するデータを呼び出しから返したことは、どうすれば確認できますか？」 — 一括実行前のスモークテストに関する質問です。
• 「カスタム拡張機能はビルドできますが、doca-bench が見つけられない／読み込めない／呼び出せないと言っています。最初にどこを確認すればよいですか？」 — ビルドの失敗、読み込みの失敗、登録の不一致、実行時の呼び出しの失敗を切り分ける、段階的なデバッグに関する質問です。

対象読者

doca-bench/SKILL.md で組み込みのワークロードモードをすでに使用しており、組み込みモードでは対応できないワークロードクラスを扱う、経験豊富な AI エージェントおよびプラットフォーム／パフォーマンスエンジニアを対象としています。読者は、ネイティブビルドシステム（このコードベースでは Meson）、Linux での共有ライブラリのパッケージング、および DOCA_EXPERIMENTAL API の安定性に関する契約に精通していることが前提です。ユーザーが同梱のリファレンス拡張機能 doca_bench_cuda を使った GPU 側のベンチマークについて尋ねる場合、読者は DOCA GPUNetIO と CUDA ツールチェーンの基本にも精通していることが前提です。これらの領域は独自のスキルで扱うものであり、ここでは扱いません。

このスキルは、次の方を対象としていません。

• doca-bench の組み込みモードのいずれかでワークロードを表現できるオペレーター。該当するのは doca-bench/SKILL.md です。
• 別の DOCA プリミティブ（Flow、Comch、RMAX）を、そのプリミティブ独自の測定ツールでベンチマークしたいオペレーター。そのツールを案内してください。
• ツリー内の拡張機能そのものを作成または変更するコントリビューター。このスキルはフレームワークを利用する外部のオペレーター向けであり、DOCA の内部コントリビューター向けではありません。

対象範囲

doca-bench 拡張機能は、次の要素で構成されます。

1. Linux 上のバージョン管理された共有ライブラリ（DOCA リリースに一致する soversion を持つ .so）。同梱の /opt/mellanox/doca/tools/bench_extension/meson.build にある doca-bench-extension Meson ルールと、拡張機能ごとのサブディレクトリ（リファレンスとなる実例は doca_bench_cuda/）を使ってビルドします。
2. 親の doca-bench が呼び出す、DOCA_EXPERIMENTAL としてマークされた少数の C エントリーポイント。つまり、拡張機能のヘッダーファイルで宣言される API サーフェスです。同梱の doca_bench_cuda/doca_bench_cuda.h は、実際の API サーフェスの形を示すリファレンスです（*_init、*_device_query、*_device_synchronize、および *_start_nop_kernel、*_start_eth_recv_kernel、*_start_eth_send_kernel、*_start_eth_bidir_kernel など、ワークロードごとのカーネル起動エントリーポイント）。
3. 親が渡す、ワークロードごとの設定構造体一式。たとえば、リファレンスとなる実例の doca_bench_cuda_kernel_settings、doca_bench_cuda_eth_rx_kernel_settings、doca_bench_cuda_eth_tx_kernel_settings、doca_bench_cuda_eth_bidir_kernel_settings には、ブロック数、ブロックあたりのスレッド数、RX／TX キュー、バッファーのアドレス／mkey／サイズ、停止フラグ、統計情報へのポインターが含まれます。

このスキル自体は Markdown で記述されています。ユーザーの拡張機能のソースコードには、ワークロードに必要な言語（リファレンスの場合は C／C++／CUDA）が使われます。エージェントは、同梱のリファレンスで示されている範囲を超えて、使用言語を指定しません。

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

次のいずれかに該当する場合は、doca-bench-extension を読み込んでください。

• ユーザーが doca-bench-extension、doca_bench_cuda リファレンス拡張、doca_bench_cuda_impl 共有ライブラリ、またはいずれかの DOCA_EXPERIMENTAL 拡張エントリーポイントに明示的に言及している。
• ユーザーが（doca-bench/SKILL.md を通じて）、測定したいクラスに該当する doca-bench 組み込みワークロードモードがなく、拡張が代替手段となることを確認している。
• ユーザーが、同梱されている doca_bench_cuda リファレンスをコピーまたは拡張して、カスタムの GPU 側ワークロード拡張を作成したい。
• ユーザーが、自作のカスタム拡張を doca-bench が検出、読み込み、または呼び出せない理由をデバッグしている。

次のスキルと併せて読み込んでください。

• doca-bench/SKILL.md（親ツール。必ず併せて読み込みます。拡張は doca-bench のプラグインとしてのみ意味があります）。
• doca-version/SKILL.md（DOCA_EXPERIMENTAL の仕様は DOCA とともにバージョン管理されます。拡張の soversion は DOCA の soversion であり、4 つのバージョンの一致が適用されます）。
• 拡張が GPU 側であり、リファレンス例と同様に GPUNetIO の RX／TX キューを使用する場合は、doca-gpunetio/SKILL.md（GPUNetIO のセマンティクスはこちらに振り分け、このスキルでは扱いません）。
• 環境側のデバッグ手順（ドライバー、ファームウェア、CUDA ツールキット、動的リンカー）には、doca-debug/SKILL.md と doca-setup/SKILL.md。

ユーザーのワークロードが doca-bench の組み込みモードに適合する場合は、このスキルを読み込まないでください。拡張にはコスト（ビルドツールチェーン、バージョンの変動、実験的な仕様の制約）が伴います。まずは必ず組み込みモードを試してください。

このスキルの内容

このディレクトリには、異なる質問の種類をそれぞれ担当する 3 つの関連ファイルがあります。

• このスキル — このファイルです。対象読者、対象範囲、読み込み順序、関連スキルを説明し、それ以外のすべてを振り分けます。
• 機能に関する関連ファイル — 拡張でできる、組み込みモードではできないこと、API の概要、ビルド／登録／検出の流れ、対応するバージョン（doca-version に重ねて適用される DOCA_EXPERIMENTAL の安定性に関する補足を含む）、階層化されたエラー分類、可観測性、安全性ポリシーの補足を説明します。
• タスクに関する関連ファイル — 手順を表す動詞（configure、build、run、test、debug など）に加えて、doca-bench-extension 固有のコマンド補足と、拡張の実行結果を利用するエージェント側の use ワークフローを説明します。

これらのスキルを組み合わせることで、AI エージェントが doca-bench の「拡張を作成して組み込む」種類の質問に対応できるようになります。拡張が本当に必要かを確認し、同梱のリファレンス例（/opt/mellanox/doca/tools/bench_extension/doca_bench_cuda/）を見つけ、そのビルドと API の構成を模倣し、DOCA リリースに適合するバージョン付き共有ライブラリをビルドし、親ツールである doca-bench が実際に読み込むことを簡易テストし、読み込めない場合は階層化された障害を診断します。

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

• doca-bench に組み込まれたワークロードモードの一覧。 これは doca-bench/SKILL.md の担当です。 このスキルは、組み込みモードで対応できない内容への 次の手段を示すものであり、親スキルのモード一覧を 重複して記載しません。
• 配布されているリファレンスで宣言されている範囲を超えて 独自に作成した DOCA_EXPERIMENTAL エントリーポイント名。 ユーザーのインストール環境にある配布済みの doca_bench_cuda/doca_bench_cuda.h が、API の 形状を確認するためのリファレンスです。エージェントは、 特定のシグネチャを持つ他の拡張機能が存在すると断言しません。
• 標準的な「正しい」拡張機能のレイアウト。 配布済みの doca_bench_cuda リファレンスが標準的なレイアウト そのものです。ここで書き直すと、信頼できる情報源との 差異が生じます。エージェントは配布済みのツリーを参照する ようオペレーターに案内し、それを適応する手順を示します。
• エージェントが独自に考案した、文書化済みの実行時検出の仕組み。 doca-bench が拡張機能を検索して読み込む正確な仕組み （検索パス、命名規則、登録呼び出し）は、docs.nvidia.com にある公開 DOCA Bench ドキュメントと、インストール済みの doca-bench バイナリに記載されています。エージェントは 記憶をもとに仕組みを断言せず、オペレーターをそれらの情報源に 案内します。
• DOCA GPUNetIO のプログラミング詳細。 拡張機能が GPU 側で動作する場合（リファレンス例も同様です）、 GPUNetIO の RX / TX キューのセマンティクスは doca-gpunetio/SKILL.md に記載されています。 このスキルでは重複して記載せず、相互参照します。
• CUDA ツールチェーンのインストール方法。 docs.nvidia.com にある公開 NVIDIA CUDA Toolkit ドキュメントを参照してください。 このスキルでは重複して記載しません。
• 拡張機能とは関係のない、ライブラリ内部での doca-bench の呼び出し詳細。 親スキルの CLI フラグ、 パイプラインの形状、組み込みワークロードクラスは doca-bench/SKILL.md の担当です。

読み込み順序

doca-bench-extension に関する質問を受けた場合：

1. DOCA がインストールされており、ユーザーの環境で doca-bench にアクセスできることを確認します。そうでない 場合は doca-setup/SKILL.md を案内します。
2. doca-bench の組み込みモードのいずれでも ワークロードの種類に対応できないことを確認します。 対応できるモードがある場合は doca-bench/SKILL.md に 案内して終了します。拡張機能は次の手段であり、最初に 提案するものではありません。
3. capabilities の補助資料を読み、3 軸の判断基準を確認して、 リファレンス例の API の形状を説明します。
4. tasks の補助資料を読み、 ## configure → ## build → ## run → ## test → ## debug の順に進めます。ビルド前の手順を飛ばして ## run から始めてはいけません。

関連スキル

相互リンクの規約は、tools/<X>/ を起点とするバンドルの相対パスの ルールに従います。

• doca-bench/SKILL.md — 親ツールです。 常に一緒に読み込まれます。 拡張機能は doca-bench のプラグインであり、置き換えるものではありません。また、単独の CLI を持たず、親ツールから呼び出されない限り何も測定しません。このスキルに 関する質問はすべて、親ツールがあることを前提とします。
• doca-version/SKILL.md — DOCA_EXPERIMENTAL の インターフェースは DOCA とともにバージョン管理されます。拡張機能の soversion は、同梱の meson.build に従って DOCA のリリースと一致します。 4つのバージョンを一致させる必要があります。DOCA のアップグレード時に拡張機能を 再ビルドするのは例外ではなく、原則です。
• doca-gpunetio/SKILL.md — 参照実装の doca_bench_cuda のように、拡張機能が GPU 側にあり、 GPUNetIO の RX／TX キューを使用する場合に参照します。GPUNetIO のセマンティクスは こちらで扱います。
• doca-setup/SKILL.md — DOCA のインストール状況 （doca-bench が存在するか、doca_bench_cuda_impl の参照ライブラリが 存在するか、必要に応じて CUDA ツールチェーンがインストールされているか）。
• doca-debug/SKILL.md — 環境側の問題 （動的リンカー、ライブラリ検索パス、CUDA ドライバー／ツールキット、 ファームウェア）を横断するデバッグ手順です。
• doca-public-knowledge-map/SKILL.md — docs.nvidia.com の DOCA Bench／DOCA GPUNetIO の公開ページと、 文書化された拡張機能のライフサイクル／検出メカニズムに関するリリースノートへの 案内です。
• doca-structured-tools-contract/SKILL.md — ビルド／ロードの前提条件が依存する構造化ヘルパー （doca-env --json、doca-capability-snapshot、 version-matrix.json）について、エージェントが検出 → 優先 → フォールバック → 報告するための規約です。
• doca-hardware-safety/SKILL.md — capabilities companion が適用する、ハードウェア安全性に関する標準の メタポリシーです。拡張機能は doca-bench に読み込まれる外部コードです。 データプレーン／デバイスに触れるベンチマークに実験的なコードを読み込むことには、 現実的な安全上の影響があります。

このスキルでは、ユーザーが Linux 上で共有ライブラリをビルドした経験があり、 Meson ビルドについて理解していることを前提とします。これらのトピックの 背景情報は、このスキルではなくツールチェーンのドキュメントに記載します。