doca-gpi

DOCA GPI

例

• 「CUDA カーネルから GPU メモリ上の RDMA をポストする必要があります。」 — これは対象範囲内です。GPUNetIO の送信／受信インターフェイスではなく、GPI ドメイン／チャネルを使用してください。
• 「GPU ハンドルを CUDA カーネルに渡すにはどうすればよいですか？」 — doca_gpu_gpi_channel* を使用してください。これを DPA 側の RDMI に振り分けないでください。

手順

以下の読み込み順に従ってください。設定／変更／デバッグについてはタスク用の補足ファイルを開きます。GPI と GPUNetIO、RDMI の違いについては機能用の補足ファイルを開きます。すべての補足ファイルを開かないでください。

最初に確認する場所： このスキルは、DOCA がすでにインストールされており、PCIe 経由で到達可能な BlueField／ConnectX デバイスと NVIDIA GPU の両方があるホストで、ユーザーが GPI を実際に操作していることを前提としています。ユーザーが何かを実行（インストール／設定／ビルド／変更／実行／テスト／デバッグ／使用）したい場合は、タスク用の補足ファイルを開いてください。質問が「このバージョンで GPI で表現できること」、つまりドメイン＋チャネルのオブジェクトモデル、GPU 側ハンドルの受け渡し、doca-gpunetio および doca-verbs との関係、属性オブジェクト、安全性のオーバーレイに関するものであれば、機能用の補足ファイルを開いてください。ユーザーがまだ DOCA をインストールしていない場合は、まず doca-setup/SKILL.md に案内してください。

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

このスキルが回答するために作られている GPI の質問のクラスと、それぞれの具体例を示します。エージェントは、具体例は一つの事例にすぎないことを踏まえ、根幹となる要素である クラス に着目してください。

• 「このケースでは doca-gpi と doca-gpunetio のどちらを使うべきですか？」 — 具体例：「CUDA カーネルからリモート DPU のメモリに直接 RDMA 書き込みをポストしたい場合、高レベルの送信／受信インターフェイスと低レベルのチャネル／キューインターフェイスのどちらを使えばよいですか？」。

  Capabilities and modes

  のインターフェイス選択表にある チャネルレベルと送信／受信レベル の選択ルールで回答します。
• 「GPI チャネルを立ち上げ、リモートピアに接続するにはどうすればよいですか？」 — 具体例：「GPI を作成し、ドメインとチャネルの属性サイズを設定してチャネルを作成し、リモートとエンドポイントの接続情報を交換して、エンドポイントを接続する」。

  Capabilities and modes

  のチャネルオブジェクトのライフサイクルと、

  configure

  の設定手順で回答します。
• 「GPU 側のハンドルとは何ですか。また、CUDA カーネルに渡すにはどうすればよいですか？」 — 具体例：「doca_gpi_gpu_channel_get は doca_gpu_gpi_channel* を返します。これを CUDA カーネルの引数リストに渡すにはどうすればよいですか？」。

  Capabilities and modes

  の GPU への受け渡しパターンと、

  run

  の実行時の接続手順で回答し、CUDA 側のプログラミングインターフェイス自体については doca-gpunetio/SKILL.md に相互リンクします。
• 「CUDA、GPU、DOCA のバージョン構成はどのようなものである必要がありますか？」 — 具体例：「BlueField-3 と A100 を使用しています。必要な CUDA Toolkit と DOCA のバージョンを教えてください。」。

  Version compatibility

  のバージョンオーバーレイと、

  install

  のインストール確認で回答します。
• 「使用したいチャネルとワークキューのサイズは、どのように設定すればよいですか？」 — 具体例：「ドメインに 64 個のチャネルを用意し、それぞれに 1024 エントリの送信キューを設けたい場合、どのセッターで指定できますか？」。

  Capabilities and modes

  の属性オブジェクトのサイズ設定ルール（doca_gpi_domain_attr_set_num_channels、 doca_gpi_channel_attr_set_sq_wqe_num）と、

  configure

  のサイズ設定手順で回答します。
• 「doca_gpi_* の呼び出しで返されたこの DOCA_ERROR_* は何を意味しますか？」 — 具体例：「doca_gpi_gpu_channel_get からの DOCA_ERROR_*」。

  Error taxonomy

  の複数ライブラリにまたがる分類に対する GPI のオーバーレイと、

  debug

  の段階的な手順で回答し、必要に応じて doca-debug/SKILL.md に案内します。

対象読者

このスキルは、RDMA キューを CUDA カーネルから直接操作する必要がある、GPU 上に常駐する DOCA アプリケーションを開発している外部の開発者を対象としています。つまり、ホスト CPU を経由せずに GPU メモリから RDMA の処理を投入したいユーザー向けです。想定される呼び出し元は、BlueField／ConnectX デバイスと同じホスト上の NVIDIA GPU で実行される CUDA カーネルです。このカーネルは、DOCA GPU-NetIO スタックを通じて DPU の RDMA キューに GPUDirect 形式でアクセスし、GPI チャネルとキューハンドルを使って RDMA の開始を制御します。このスキルは、DOCA GPI 自体に貢献する NVIDIA の開発者向けではありません。また、より高レベルで Send／Receive によるイーサネット形式の GPU NetIO API を扱うものでもありません。それについては doca-gpunetio/SKILL.md を参照してください。

対象言語

DOCA GPI は、doca-gpi という pkg-config モジュール名の C ライブラリとして提供されています。ライブラリのホスト側インターフェイス（doca_gpi_*）は C です。一方、GPU 側インターフェイス（doca_gpu_gpi_channel* ハンドル、および CUDA カーネルがそのハンドルに対して使用するデバイス側呼び出し）は、doca-gpunetio/SKILL.md に記載されている DOCA GPU NetIO のデバイス側ヘッダーを使用し、nvcc でコンパイルされます。その他の言語（Rust、Go、Python など）を使う場合は、FFI を介してホスト側の *.so を利用します。その場合、このスキルではチャネル／キューのライフサイクル、GPU ハンドルの受け渡し、バージョン管理、安全性に関する補足を言語に依存しない形で扱い、最終的にあらゆるラッパーが呼び出すことになる、正式なインターフェイスとして公開 C ABI を案内します。GPU 側インターフェイスは、CUDA バイナリ自体にコンパイルおよびリンクされるため、別の言語からラップすることはできません。

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

BlueField／ConnectX デバイスと NVIDIA GPU の両方を備えたホストで、ユーザーがDOCA GPI を実際に操作しているときに、このスキルを読み込んでください。具体的には、次のような場合です。

• GPU から開始する新しい RDMA ワークロードで、doca-gpi（低レベルのチャネル／キューインターフェイス）と doca-gpunetio（高レベルの Send／Receive インターフェイス）のどちらを使うか判断するとき。
• doca_dev 上に doca_gpi を作成し、doca_gpi_set_* ファミリーで設定（ドメイン数、GID インデックス、ポート）したうえで、doca_gpi_start() を呼び出す前に doca_gpi_domain_attr_*／doca_gpi_channel_attr_* セッターを使ってドメインとチャネルのサイズを設定するとき。
• doca_gpi_channel_create でチャネルを作成し、doca_gpi_gpu_channel_get で GPU 側ハンドルを取得してから、そのハンドルを CUDA カーネルに渡すとき。
• doca_gpi_channel_ep_conn_info_create／doca_gpi_channel_ep_connect を使ってリモートピアとエンドポイント接続情報を交換し、GPU が制御するチャネルをエンドツーエンドで確立するとき。
• doca_gpi_domain_attach_local_mmap／doca_gpi_domain_attach_remote_mmap を使って GPI ドメインにメモリー領域を追加するとき（それぞれ、アプリケーションが作成した doca_mmap に基づきます）。
• doca_gpi_* の呼び出しから返された DOCA_ERROR_* をデバッグし、原因がライフサイクルの順序の誤り、GPU データパスへの割り当てミス、CUDA バージョンの不一致、または DOCA より下位のレイヤーにあるかを判断するとき。

一般的な DOCA の概要、DOCA 自体のインストール、ホスト CPU が開始する RDMA、または高レベルの GPU NetIO による Send／Receive イーサネット形式 API を扱う場合、このスキルは読み込まないでください。それぞれ doca-public-knowledge-map/SKILL.md、doca-setup/SKILL.md、doca-rdma/SKILL.md、doca-gpunetio/SKILL.md を使用してください。1 つの質問が GPI チャネルのライフサイクルと CUDA 側の GPU NetIO 動作の両方にまたがる場合は、両方のスキルを読み込んでください。このスキルでは GPI オブジェクトの作成、接続、解放を扱い、doca-gpunetio ではカーネルの起動とデバイス側の実行を扱います。両方の範囲を読んでも境界が曖昧なままの場合は、どちらかを暗黙に選ばず、どちら側で問題が起きているかを確認してください。

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

これは薄いローダーです。本体には、次に読むべきファイルを選ぶために必要な案内だけを残しています。GPI 固有の実質的な内容は、次の 2 つの関連ファイルに記載されています。

• capabilities 関連ファイル — このバージョンで GPI が表現できる内容：doca_gpi／doca_gpi_domain／doca_gpi_channel オブジェクトモデル、GPU 側のハンドル受け渡し、doca-gpunetio/SKILL.md（GPU 側の doca_gpu_gpi_channel* デバイスインターフェイスを担当）および doca-verbs/SKILL.md と doca-dpa/SKILL.md（GPI が基盤とするトランスポート層と DPA 層）との関係、ドメインおよびチャネルの属性オブジェクト、成熟度に関する説明（すべての doca_gpi_* シンボルは DOCA_EXPERIMENTAL）、ライブラリ間で共通の DOCA_ERROR_* 分類における GPI 固有の追加項目、可観測性インターフェイス（CUDA 側でのチャネルポーリング、mmap アタッチ交換）、GPU 側からの RDMA 開始を制御する安全ポリシー。
• tasks 関連ファイル — 対象となる 8 つの動詞（install、configure、build、modify、run、test、debug、use）について、手順を追ったワークフローを説明しています。さらに、対象外の質問を適切な次のスキルに案内する Deferred task verbs ブロックもあります。

このスキルでは、DOCA が標準の場所にすでにインストールされており、インストール済みの DOCA と互換性のある CUDA Toolkit が存在し、ユーザーが自身の公開インストールプロファイルで想定される権限を持つホストを前提としています。DOCA のインストールは対象外です。その手順については doca-setup/SKILL.md を参照してください。

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

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

• いずれの言語でも、DOCA GPI アプリケーションのソースコードをあらかじめ記述したもの。 エージェントの役割は、検証済みのリファレンスコード（インストール済みパッケージに含まれる DOCA GPU-NetIO サンプルが、GPU 側の受け渡しに関する正式な実例です）へユーザーを案内し、doca-programming-guide/SKILL.md にある汎用のサンプル変更ワークフローに沿って、差分を最小限に抑えた変更を指示することです。すべての GPI シンボルは公開ヘッダーで DOCA_EXPERIMENTAL とタグ付けされているため、このスキルではドキュメントの説明文をもとに GPI ソースを作成しません。
• スキル内に置く単独のビルドマニフェスト（meson.build、CMakeLists.txt、Cargo.toml、…）。エージェントは、ユーザーのプロジェクトディレクトリで、インストール済みの DOCA を対象にビルドマニフェストを作成します。その際、正しい情報源となるのは pkg-config --modversion doca-gpi です。
• CUDA カーネルテンプレート。 CUDA 側のインターフェイスは doca-gpunetio/SKILL.md が担当します。GPI の GPU 側ハンドルは、そこで説明されている CUDA プログラミングモデルによって使用されます。このスキルでは GPI 固有の受け渡し（doca_gpu_gpi_channel* 型、チャネル接続呼び出し）について説明しますが、CUDA カーネルは作成しません。
• いかなる種類の samples/、bindings/、reference/ サブツリー。 「reference」と表示されていても、このスキルのツリー内にある模造品や不完全な成果物は誤解を招きます。ユーザーがビルド可能なものとして受け取ってしまうためです。

読み込み順序

1. ユーザーの質問が対象範囲内であることを確認するため、まずこのスキルを読みます。
2. GPI オブジェクトモデル、GPU 側の受け渡しパターン、ドメインおよびチャネルの属性オブジェクト、バージョン互換性の規則、エラー分類、可観測性、安全ポリシーについては、capabilities 関連ファイルを参照してください。
3. 手順を追ったワークフロー（install、configure、build、modify、run、test、debug、use）については、tasks 関連ファイルを参照してください。

どちらが適切な回答かを判断する際に「GPI 固有のガイダンス」ではなく「公開ドキュメントまたはインストール済みパッケージの構成を確認する」となる場合は、2 つの関連ファイルはいずれも doca-public-knowledge-map/SKILL.md への相互リンクを含みます。

関連スキル

• doca-gpunetio/SKILL.md — CUDA カーネル向けに Send/Receive 形式のイーサネット I/O を提供する GPU NetIO ライブラリです。GPI が引き継ぐ GPU 側のデバイスインターフェイスを所有しています。doca_gpu_gpi_channel* 型とデバイス側の .cuh API は doca-gpunetio にあり、doca_gpi.h は doca_gpunetio.h をインクルードします。両方を同じアプリケーション内で共存させることができます。

  Capabilities and modes

  の選択表は、判断に欠かせない資料です。
• doca-verbs/SKILL.md と doca-dpa/SKILL.md — GPI が基盤とするトランスポート層と DPA 層です。dependencies/meson.build には doca-dpa、doca-gpunetio、doca-verbs（および libmlx5／libibverbs 外部ライブラリ）が列挙されています。doca_gpi_get_dpa は、DPA 属性を調整するための GPI 所有の doca_dpa* を返します。RDMA トランスポートの種類、GID／ポートの選択、権限のセマンティクスは verbs 層にあり、GPI は doca-rdma キューにバインドするのではなく、これを利用します。
• doca-rdmi/SKILL.md — 姉妹となる DPA 側のイニシエーターインターフェイスです。GPI と RDMI はどちらも「データパスにホスト CPU を介さず、アクセラレーターから RDMA の開始を駆動する」ためのもので、GPU の場合は GPI、DPA の場合は RDMI を使用します。
• doca-public-knowledge-map/SKILL.md — 公開されているすべての DOCA ドキュメントソースへのルーティングテーブルと、インストール済み DOCA パッケージのディスク上の構成です。
• doca-setup/SKILL.md — 環境の準備、インストールの検証、および公開 NGC DOCA コンテナーを使った まだ何もインストールしていない場合 の手順です。
• doca-programming-guide/SKILL.md — すべてのライブラリで共有される一般的な DOCA プログラミングパターンです。標準的な pkg-config と meson によるビルドパターン、提供されているサンプルを変更して最初のアプリケーションを作る共通ワークフロー、共通の Core コンテキストのライフサイクル、ライブラリ間で共通する DOCA_ERROR_* の分類体系が含まれます。このスキルでは、これらに GPI 固有の内容を重ねています。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／実行時／プログラム／ドライバーにまたがる、共通のデバッグ手順です。GPI 固有のデバッグ内容はその上に重ねています。
• doca-hardware-safety/SKILL.md — バンドル全体に適用されるハードウェア安全性のメタポリシーです。機能の補足資料にある ## Safety policy の項目から相互参照されています。
• doca-version/SKILL.md — 各アーティファクトの ## Version compatibility アンカーが前提とする、バージョンの検出と四者照合のルールです。このスキルで引用しているのは GPI 固有の補足のみです（DOCA 側の .pc に加え、CUDA Toolkit の軸も対象です）。
• doca-structured-tools-contract/SKILL.md — エージェントが優先的に使用する構造化ヘルパーの JSON スキーマ契約です。タスクの補足資料にある ## Command appendix では、手動の手順に進む前にこれらを参照します。