doca-gpunetio

DOCA GPUNetIO

例

• 「NIC からパケットを直接読み取る CUDA カーネル」 — これは対象範囲です。doca_gpu_eth_rxq / _txq と永続カーネルに注目し、ホスト CPU を使った Ethernet 処理に書き換えないでください。
• 「doca_gpu_create で DOCA_ERROR_DRIVER が発生する」 — キューの種類を変更する前に、CUDA デバイスの一致と dmabuf / nvidia-peermem の登録を確認してください。

手順

以下の読み込み順に従ってください。設定／ビルド／実行についてはタスク用コンパニオンファイルを開いてください。GPU とホストのどちらの経路を使うか判断するには、機能用コンパニオンファイルを開いてください。コンパニオンファイルをすべて開く必要はありません。

最初に確認すること： このスキルは、DOCA がすでにインストールされ、CUDA ツールキットがインストール済みで DOCA のインストールとバージョンが一致しており、ユーザーが GPUNetIO を実際に使っている — つまり、NVIDIA GPU 上の CUDA カーネルに DOCA ネットワークキューを接続している — ことを前提としています。ユーザーが何かを実行したい（設定／ビルド／変更／実行／テスト／デバッグ）場合は、タスク用コンパニオンファイルを開いてください。このバージョンと GPU で GPUNetIO を使って何ができるか、という質問の場合は、機能用コンパニオンファイルを開いてください。ユーザーがまだ DOCA をインストールしていない場合は、まず doca-setup/SKILL.md に案内してください。基盤となる Ethernet RX/TX キューをまだ設定していない場合は、DOCA Ethernet に関する質問です — doca-eth/SKILL.md に案内してください。

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

このスキルが回答するために作られた GPUNetIO の質問の種類と、それぞれの実例です。エージェントは、軸となるのは質問の種類であり、実例はその一例にすぎないことを念頭に置いてください。

• 「NIC からパケットを直接受信する CUDA カーネルを使うにはどうすればよいですか？」 — 実例：「1 台の GPU 上の永続カーネルが、representor doca_eth_rxq 上に構築された doca_gpu_eth_rxq からパケットを読み取り、フローごとにカウントする」。## Capabilities and modes の永続カーネルのパターンと、## configure の GPU 側のセットアップ手順で回答します。
• 「この GPU で GPUNetIO を実行できますか？」 — 実例：「ホストに Ampere カードが 1 枚、Turing カードが 1 枚あります。どちらが GPU 起点のネットワーク処理をサポートしますか？」。## Capabilities and modes の 2 つの機能検出ルール（DOCA の機能クエリと、CUDA デバイス ordinal に対する cudaGetDeviceProperties）と、## configure のデバイス列挙手順で回答します。
• 「doca-eth は正常に起動したのに、GPUNetIO のセットアップで DOCA_ERROR_NOT_SUPPORTED が発生するのはなぜですか？」 — 実例：「nvidia_peermem が読み込まれていないため、GPUDirect RDMA を利用できない」。## Safety policy の環境に関する前提条件と、## configure step 1 の環境チェックリストで回答します。
• 「CUDA で割り当てたバッファーと DOCA キューの間でデータを移動するにはどうすればよいですか？」 — 実例：「受信バッファープールに cudaMalloc を使い、コンテキストを開始する前に doca_buf_arr_create_* で DOCA に登録する」。## Safety policy の CUDA アロケーターと DOCA 登録に関する補足、および ## configure step 4 のバッファー準備手順で回答します。
• 「調べている GPUNetIO API は、インストール済みの DOCA と CUDA の組み合わせで使えますか？」 — 実例：「手元の CUDA ツールキットのバージョンで、永続カーネルのヘルパーは利用できますか？」。## Version compatibility のバージョン互換性に関する補足で回答します。これは doca-version/SKILL.md にある標準の検出手順への相互リンクに、GPUNetIO 固有の DOCA と CUDA のバージョンを一致させる必要がある という補足を加えたものです。
• 「GPUNetIO の呼び出しで発生したこの DOCA_ERROR_* は何を意味し、どのレイヤーが原因ですか？」 — 実例：「doca_gpu_*_create で DOCA_ERROR_DRIVER が発生しています — 原因は DOCA、CUDA、それとも基盤の doca-eth キューですか？」。## Error taxonomy の複数ライブラリーにまたがる分類に対する GPUNetIO の補足と、doca-debug/SKILL.md へのエスカレーションを行う ## debug の段階的な手順で回答します。

対象読者

このスキルは、DOCA GPUNetIO ライブラリを利用するアプリケーションを開発する外部開発者を対象としています。つまり、ホスト側の C/C++ から doca_gpu_* を呼び出して GPU ごとのコンテキストと GPU から参照可能なキューハンドルを作成し、CUDA カーネル（.cu 翻訳単位）のデバイスコードからそれらのハンドルを使ってパケットを送受信するコードを開発するユーザー向けです。標準的な対象は、GPU Packet Processing のリファレンスアプリケーションのような構成です。NVIDIA GPU 上で CUDA 常駐カーネルを実行し、GPU から参照可能な RX キューをポーリングして、GPU 上でパケットをインプレース処理します。DOCA GPUNetIO 自体に貢献する NVIDIA の開発者向けではありません。

言語の範囲。 DOCA GPUNetIO は、pkg-config のモジュール名が doca-gpunetio の C / CUDA ライブラリとして提供されています。ホスト側 API は C で、デバイス側 API は .cu カーネル内で使用する CUDA C++ です。提供されているサンプルと GPU Packet Processing リファレンスアプリケーションは、C + CUDA C++（NVIDIA の選択）で記述されています。他の言語からの利用には実質的な制限があります。デバイス側 API には FFI による回避策がなく、カーネルは CUDA 翻訳単位である必要があるためです。ただし、ホスト側の doca_gpu_* セットアップを実行し、別途ビルドした CUDA カーネルを起動する Rust / Go / Python のホスト側ラッパーには、依然として有用性があります。そのため、このスキルではライフサイクル、機能の検出、環境の前提条件、エラー分類に関するガイダンスを言語に依存しない形で示します。

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

ユーザーが、ホスト側の言語を問わず CUDA と組み合わせて DOCA GPUNetIO を実際に扱っている場合に、このスキルを読み込みます。具体的には、次のような場合です。

• NVIDIA GPU を 1 基以上搭載したホスト上で、特定の CUDA デバイスの序数に対して doca_gpu を初期化する場合。
• DOCA Ethernet の既存の doca_eth_rxq / doca_eth_txq 上に GPU から参照可能なキューハンドル（doca_gpu_eth_rxq、doca_gpu_eth_txq）を作成し、デバイス側で使用するために CUDA カーネルへ渡す場合。
• GPU から参照可能な RX キューを長時間実行ループで処理する常駐 CUDA カーネル（標準的な GPU Packet Processing 構成）を作成または変更する場合。
• cudaMalloc で GPU バッファーを割り当て、doca_ctx_start() より前に doca_buf_arr_create_* ファミリーを使って DOCA に登録する場合。
• アクティブな doca_devinfo 上でサポートされている GPUNetIO 機能（DOCA の機能照会ファミリー）と、候補となる CUDA デバイス上でサポートされている機能（cudaGetDeviceProperties および CUDA ドライバーのバージョン確認）の両方を調べる場合。
• GPUNetIO の呼び出しから返された DOCA_ERROR_* をデバッグする場合。特に、DOCA の機能不足、CUDA デバイスの世代が古すぎること、nvidia_peermem が読み込まれていないこと、CUDA ドライバーと DOCA のバージョンの不一致を切り分ける場合。
• 別途ビルドした CUDA カーネルを実行する、非 C 言語向けのホスト側バインディングを設計する場合。このスキルに記載された環境の前提条件と機能検出のルールは、引き続き適用されます。

DOCA の一般的な概要、DOCA または CUDA Toolkit のインストール、基盤となる DOCA Ethernet キューのセットアップ、または GPUNetIO 以外のライブラリに関する質問には、このスキルを読み込まないでください。そうした質問については、doca-public-knowledge-map/SKILL.md を参照し、該当する上流ガイドへ案内してください。

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

これは薄いローダーです。本文には、次に参照すべきファイルを選ぶために必要な概要だけを記載しています。GPUNetIO 固有の実質的な内容は、次の 2 つの補足ファイルに記載されています。

• 機能に関する補足ファイル — このバージョンと GPU で GPUNetIO が表現できる内容：doca_gpu のデバイスごとのコンテキスト、doca-eth 上に構築される GPU から見える RX / TX キューのハンドル、デフォルトの使用形態となる永続的な CUDA カーネルのパターン、機能クエリのインターフェース（DOCA 側では doca_eth_rxq.h の doca-eth doca_eth_rxq_cap_is_type_supported / doca_eth_rxq_cap_get_* ファミリーと、それに対応する doca_eth_txq_cap_* ファミリー、CUDA 側では cudaGetDeviceProperties）、クロスライブラリの DOCA_ERROR_* セットに対応付けられた GPUNetIO のエラー分類、可観測性のインターフェース（CUDA 側のカウンターと DOCA 側のタスクごとの完了）、および環境の前提条件を適用する安全ポリシー（CUDA と DOCA のバージョン一致、dmabuf または nvidia-peermem による登録）。
• タスクに関する補足ファイル — 対象となる 6 つの GPUNetIO 動詞（configure、build、modify、run、test、debug）のステップごとのワークフロー。さらに、## rollback のオーバーレイ（永続カーネルにドレインを通知し、GPU バッファーを登録と逆の順序で登録解除し、親の doca-eth キューをそのまま残す、GPUNetIO 固有の 5 ステップのティアダウン）と、## debug に追加される 5 フェーズの汎用デバッグループの具体例も含まれます。さらに、対象範囲外の質問を適切な次のスキルに案内する Deferred task verbs ブロックも含まれます。

このスキルは、標準の場所に DOCA がすでにインストールされ、NVIDIA GPU が物理的に搭載され、DOCA Compatibility Policy に従って DOCA のインストールとバージョンが一致する CUDA ツールキットがインストールされ、基盤となる DOCA Ethernet RX/TX キューがすでに構成されているホストを前提としています（このスキルは doca-eth の上位に位置し、その下位ではありません）。DOCA や CUDA ツールキットのインストールは対象外です。その手順については doca-setup/SKILL.md を参照してください。

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

このスキルはサンプルやテンプレートのバンドルではなく、エージェント向けのガイダンスです。範囲を明確にするため、以下は意図的に含めておらず、プルリクエストでも追加しないでください。

• DOCA GPUNetIO アプリケーションのソースコードや CUDA カーネルのソースコードを、言語を問わず事前に記述したもの。 検証済みの GPUNetIO ソースは、提供されている C + CUDA サンプル（/opt/mellanox/doca/samples/doca_gpunetio/）と GPU Packet Processing リファレンスアプリケーションです。エージェントの役割は、ユーザーをこれらのファイルに案内し、doca-programming-guide/SKILL.md にある汎用のサンプル変更ワークフローに GPUNetIO 固有の ## modify のオーバーライドを組み合わせて、最小限の差分で変更するよう指示することです。
• スキル内に置く単独のビルドマニフェスト（meson.build、CMakeLists.txt、…）。エージェントは、ユーザーのプロジェクトディレクトリ内に、ユーザーがインストールした DOCA と CUDA ツールキットに対するビルドマニフェストを作成します。このとき、pkg-config --modversion doca-gpunetio、pkg-config --modversion doca-common、nvcc --version をバージョン判定に使用します。
• いかなる種類の samples/、bindings/、reference/ サブツリー。 「reference」とラベル付けされたものでも、このスキルのツリー内にモックや不完全な成果物を置くと誤解を招きます。ユーザーは、それをビルド可能なものとして受け取るでしょう。

読み込み順

1. ユーザーの質問が対象範囲内であることを確認するため、まずこのスキルを読みます。
2. GPUNetIO の機能マトリクス、デバイスごとの doca_gpu コンテキスト、永続カーネルのパターン、二重の機能クエリ、環境前提条件のポリシー、エラー分類、可観測性の範囲、安全性のポリシーについては、機能の補足資料を参照してください。
3. 設定、ビルド、変更、実行、テスト、デバッグの手順については、タスクの補足資料を参照してください。

どちらの補足ファイルからも、DOCA の正式なバージョン処理ルール（GPUNetIO のオーバーレイでは DOCA と CUDA のバージョンを一致させる必要があります）を記載した doca-version/SKILL.mdと、 適切な回答が「GPUNetIO 固有のガイダンス」ではなく、「公開されている DOCA GPUNetIO ガイド、DOCA Compatibility Policy、CUDA ツールキットのドキュメント、またはディスク上のインストールレイアウトを参照する」である場合に参照する doca-public-knowledge-map/SKILL.md へ相互リンクしています。

関連スキル

• doca-public-knowledge-map/SKILL.md — 公開されているすべての DOCA ドキュメントソースと、インストール済み DOCA パッケージのディスク上のレイアウトを示すルーティング表です。GPUNetIO の公開ガイドは https://docs.nvidia.com/doca/sdk/DOCA-GPUNetIO/index.html にあります。GPU Packet Processing のリファレンスアプリケーションにも、ここからアクセスできます。CUDA ツールキットと DOCA Compatibility Policy へのリンクも、同じルーティング表にあります。
• doca-setup/SKILL.md — 環境の準備、インストールの確認、CUDA ツールキットのインストール／確認、および公開 NGC DOCA コンテナを使う「まだインストールしていない場合」の手順について説明します。このスキルでは、前提条件が満たされており、CUDA が DOCA とバージョンの一致する状態でインストールされていることを前提とします。
• doca-version/SKILL.md — DOCA の正式なバージョン処理ルールを説明します。このスキルの ## Version compatibility では、4 要素の一致ルールへの相互リンクに加え、DOCA Compatibility Policy に基づく GPUNetIO 固有の「DOCA と CUDA のバージョンを一致させる必要がある」というオーバーレイを追加しています。
• doca-structured-tools-contract/SKILL.md — バンドルの構造化ツールに関する優先順位ルール（検出／優先／フォールバック／報告）を説明します。タスクの補足資料にあるコマンドの付録は、この契約に従います。
• doca-programming-guide/SKILL.md — すべてのライブラリに共通する一般的な DOCA プログラミングパターンを説明します。具体的には、標準の pkg-config と meson によるビルドパターン、同梱サンプルを変更して最初のアプリケーションを作る標準ワークフロー、共通のライフサイクル、ライブラリ間で共通する DOCA_ERROR_* のエラー分類、プログラム側のデバッグ順序です。このスキルでは、その上に GPUNetIO 固有の内容を追加します。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／実行時／プログラム／ドライバーを横断するデバッグ手順を説明します。GPUNetIO 固有のデバッグ（CUDA と DOCA のバージョン不一致、nvidia_peermem の欠落、永続カーネルの無言ハング、CUDA アロケーターと DOCA 登録の不一致）も、この手順に重ねて説明します。

DOCA Ethernet は、GPUNetIO に必須の併用ライブラリです。GPU から可視な RX／TX キューハンドルは、DOCA Ethernet の doca_eth_rxq／doca_eth_txq の上に構築されます。基盤となるキューのセットアップについては、doca-eth/SKILL.mdを参照してください。