doca-dpa

DOCA DPA

例

• 「ホストから DPA で計算を実行する。」 — これは対象範囲です。 doca_dpa と DPACC でビルドしたイメージを使用してください。ホスト CPU や GPUNetIO を使う形に書き換えないでください。
• 「DPA カーネルがハングし、完了しない。」 — カーネルを変更する前に、 doca_dpa_completion をドレインし、DOCA／DPACC のバージョンの不一致を確認してください。

手順

以下の読み込み順に従ってください。構成／起動／デバッグについてはタスク用の補足ファイルを開いてください。スレッドとカーネル、および DPA の機能クエリについては、機能用の補足ファイルを開いてください。補足ファイルをすべて開く必要はありません。

最初に確認すること： このスキルは、DOCA がすでにインストールされており、ユーザーの BlueField に DPA プロセッサーが搭載され、ホストから DOCA 経由で認識できること、またユーザーがホスト側から DPA を直接操作していることを前提としています。つまり、doca-dpa を使って DPA アプリケーションイメージを読み込み、DPA カーネルを起動し、DPA プロセッサーとデータを交換していることを前提とします。ユーザーが何かを実行したい（構成／ビルド／変更／実行／テスト／デバッグ）場合は、タスク用の補足ファイルを開いてください。このバージョンと BlueField の世代で、ホスト側の DPA API が何を表現できるかという質問の場合は、機能用の補足ファイルを開いてください。ユーザーがまだ DOCA をインストールしていない場合は、まず doca-setup/SKILL.md に案内してください。DPA 側のカーネル自体、つまり DPA プロセッサー上で実行され、dpacc でコンパイルされるコードの書き方を尋ねている場合は対象範囲が異なります。その場合は doca-public-knowledge-map/SKILL.md を経由して、公開されている DOCA DPA／DPACC／DPA-Comms／DPA-Verbs ガイドに案内してください。このスキルでは、そうした DPA 側のインターフェースは再定義しません。

対象読者

このスキルは、ホスト側から DOCA DPA ライブラリを利用するアプリケーションを開発する外部開発者を対象としています。つまり、ホストの C／C++ から doca_dpa_* を呼び出し、DPA インスタンスごとのコンテキストを用意し、DPA 側のソースから dpacc が生成した DPA アプリケーションイメージを読み込み、1 つ以上の DPA スレッドを作成し、引数を指定して DPA カーネルを起動し、完了をドレインするコードを作成するユーザーです。NVIDIA の開発者が DOCA DPA 自体に貢献するためのものではなく、DPA 側のカーネルコードの書き方を学ぶための場所でもありません。その手順については、doca-public-knowledge-map/SKILL.md 経由で公開されている DOCA DPA、DPACC、DPA-Comms、DPA-Verbs のガイドを参照してください。

言語の対象範囲。 DOCA DPA は、pkg-config モジュール名が doca-dpa のホスト側 C ライブラリとして提供されています。ホスト側 API は C です。DPA 側のカーネルは、DPACC コンパイラーが受け付ける言語で記述し、dpacc でコンパイルする別個の翻訳単位です。コンパイルされたバイナリは、ホスト側で DPA アプリケーションイメージとして実行ファイルにパッケージ化します。/opt/mellanox/doca/samples/doca_dpa/ にあるサンプルは、C と DPA 側ソースで記述されています（これは NVIDIA の選択です）。実際には、他の言語からの利用には制限があります。DPA 側カーネルは dpacc が受け付ける翻訳単位でなければならないため、FFI による回避策はありません。ただし、別途ビルドした DPA カーネルイメージを使って doca_dpa_* のセットアップや起動を行う Rust／Go／Python のホスト側ラッパーには、依然として有用性があります。そのため、このスキルではライフサイクル、機能検出、環境の事前条件、エラー分類に関するガイダンスを言語に依存しない形で扱います。

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

ユーザーが dpacc でビルドした DPA 側の翻訳単位と、任意のホスト言語を使用して、ホスト側から DOCA DPA を直接操作しているときに、このスキルを読み込んでください。具体的には、次のような場合です。

• ホストから見える DPA プロセッサーを備えた BlueField に対応する doca_dev に対して、doca_dpa を初期化する。
• ユーザーの DPA 側ソースから dpacc が生成した DPA アプリケーションイメージ（doca_dpa_app）を、doca_dpa コンテキストに読み込む。
• DPA カーネルを DPA プロセッサー上で実行できるように、1 つ以上の DPA 実行コンテキスト（doca_dpa_thread）を作成する。
• doca_dpa_kernel_launch_update_* ファミリーを介して、ホストから引数を指定して DPA カーネル関数を起動し、このインストール環境でどの引数形式がサポートされているかを判断する。
• doca_dpa_completion を関連付けて非同期の DPA 処理の完了を監視し、ホスト側で完了を回収する。
• doca_dpa_cap_* ファミリーを使って、アクティブな doca_devinfo でサポートされている DPA 機能を確認する。BlueField の世代によって DPA ハードウェアのサポート状況は異なります。
• doca_dpa_* 呼び出しから返された DOCA_ERROR_* をデバッグする。特に、この BlueField に DPA が搭載されていない場合、このハードウェア世代では DPA 機能が新しすぎる場合、DPACC が生成したイメージとホスト側の DOCA インストールが一致しない場合、DPA ドライバー層が失敗を報告している場合を区別する。
• dpacc で別途ビルドした DPA アプリケーションイメージを操作する、C 以外の言語でのホスト側バインディングを設計する。このスキルに記載されている環境の前提条件と機能検出のルールも引き続き適用されます。

「DPA カーネルがハングし、完了通知が一度も届かない」という場合は、まずホスト側の問題として調べます。 起動呼び出しは非同期なので、成功が意味するのは投入済みであって、完了済みではありません。カーネルコードを調べる前に、ホストが完了を実際に監視できる状態にあることを確認してください。つまり、doca_dpa_completion が関連付けられており、実行中の起動処理と並行してホストが doca_pe_progress を実行している必要があります。処理を投入した後、PE を進行させずにブロックするホストは完了通知を受け取れず、誤って*「DPA がハングしている」*と判断します。カーネルはすでに完了している可能性があります。これを除外して初めて、終了しないカーネル本体が疑わしくなります。両方の手順と順序は ## run steps 2-3 に記載されています。

• DPA デバイス側の通信コンポーネント libdoca_dpa_dev_comm.a（ヘッダー doca_dpa_dev_comch_msgq.h）を呼び出す DPA 側カーネルコードを書く。同じ doca_dpa_app 内の DPA スレッド間で、メッセージをやり取りしたり、同期シグナルを送ったりする場合に使用します。DPA-Comms のルーティングルール、プリミティブの各ファミリー、機能に関するルール（プリミティブごとのホスト側機能照会ファミリーはありません。ホスト側の DPA 検出方法は doca_dpa_cap_is_supported / doca_dpa_cap_get_max_kernel_time_alive_supported のみです）、エラーの補足説明（_AGAIN → カーネルは yield する必要があります。_BAD_STATE は親側のホストから返る _BAD_STATE と区別します）、および configure / build / modify / run / test / debug に関する補足説明は、このスキル内の ## comms と ## comms に記載されています。
• DPA デバイス側の verbs コンポーネント libdoca_dpa_dev_verbs.a（ヘッダー doca_dpa_dev_verbs.h）を呼び出す DPA 側カーネルコードを書く。ホストの往復が計測対象のレイテンシのボトルネックとなる場合に、DPA カーネル内部からリモートピアへ RDMA を行います。RDMA の 4 方向マトリックス、ホストで QP を設定し DPA で QP を使用する連携ルール、機能に関するルール（verb ごとのホスト側機能照会ファミリーはありません。verb の利用可否は BlueField の世代と一致する DOCA/DPACC インストールに依存し、doca_dpa_dev_verbs.h および付属サンプルで確認します）、IO_FAILED → CQE の検査に関する補足説明、および上位レイヤーに戻るルールは、このスキル内の ## verbs と ## verbs に記載されています。

一般的な DOCA の概要、DOCA または DPACC コンパイラーのインストール、DPA 側のプログラミングモデルそのもの（DPA カーネルの書き方、DPA カーネル内部で実行される DPA デバイス側の通信コンポーネントと verbs コンポーネント（libdoca_dpa_dev_comm.a / libdoca_dpa_dev_verbs.a））、または DPA 以外のライブラリーに関する質問では、このスキルを読み込まないでください。 これらについては、 doca-public-knowledge-map/SKILL.md を介して、該当する上流ガイドに案内してください。

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

これは薄いローダーです。本文には、次に適切なファイルを選ぶために必要な概要だけを残しています。DPA 固有の実質的な内容は、次の 2 つの補助ファイルにあります。

• capabilities 補助ファイル — このバージョンと BlueField の世代で、ホスト側の DPA API が表現できる内容です。DPA インスタンスごとの doca_dpa コンテキスト、dpacc が生成するロード済みの doca_dpa_app イメージ、doca_dpa_thread 実行コンテキスト、 ホスト起点のカーネル起動インターフェイス （doca_dpa_kernel_launch_update_*）、doca_dpa_completion メカニズム、機能クエリインターフェイス（doca_dpa_cap_*）、 クロスライブラリの DOCA_ERROR_* セットに対応付けられた DPA エラー分類、可観測性インターフェイス（ホスト側の完了通知に加え、 doca-public-knowledge-map 経由で利用できる公開 DPA 開発者ツールの インターフェイス）、および環境の前提条件を制御する安全性ポリシー （DPA 対応 BlueField、DOCA と DPACC のバージョンの一致、DPA 側の イメージとホスト側で想定するエントリーポイントの一致）です。
• tasks 補助ファイル — 対象範囲内の 6 つの DPA 動詞、configure、 build、modify、run、test、debug の手順を順番に説明する ワークフローです。さらに、対象範囲外の質問を適切な次のスキルに案内する Deferred task verbs ブロックも含まれます。

このスキルは、DOCA が標準の場所にすでにインストールされているホスト、 DPA プロセッサを搭載した BlueField が物理的に存在し、ホストから認識 できること、DOCA Compatibility Policy に従って DOCA のインストールと バージョンが一致する DPACC コンパイラーがインストールされていること、 そしてユーザーが dpacc でコンパイルする DPA 側カーネルの書き方を （少なくとも概要レベルで）すでに把握していることを前提とします。 DOCA や DPACC コンパイラーのインストールは対象外です。その手順については doca-setup/SKILL.md を参照してください。

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

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

• DOCA DPA アプリケーションのソースコードや DPA 側カーネルのソースコード （言語を問いません）。 検証済みの DPA ソースは、次の場所にある 提供済みの C + DPA 側サンプルです。 /opt/mellanox/doca/samples/doca_dpa/。エージェントの役割は、 ユーザーをこれらのファイルに案内し、 doca-programming-guide/SKILL.md の汎用的なサンプル変更ワークフローに DPA 固有の上書きを重ねた ## modify に従って、差分を最小限に抑えた 変更を指示することです。
• スキル内に置く単独のビルドマニフェスト （meson.build、CMakeLists.txt など）。エージェントは、 pkg-config --modversion doca-dpa とインストール済みの dpacc を 2 つの信頼できる情報源として、ユーザーのインストール済み DOCA と DPACC コンパイラーに合わせて、ユーザーのプロジェクトディレクトリ内に ビルドマニフェストを作成します。
• どのような種類であっても、samples/、bindings/、reference/ のサブツリー。このスキルのツリー内にあるモックや不完全な成果物は、 「reference」とラベル付けされていても誤解を招きます。ユーザーが ビルド可能なものとして読んでしまうためです。
• comm / verbs コンポーネント （libdoca_dpa_dev_comm.a / libdoca_dpa_dev_verbs.a）の DPA デバイス側の内容。 これらは doca-dpa の一部として提供される DPA 側のアーカイブであり、（別個の pkg-config モジュールでは ありません）。そのシンボルは DPA カーネル内部から呼び出され、 ホストからではなく、dpacc によって DPA イメージにリンクされます。 公開ガイドは doca-public-knowledge-map/SKILL.md 経由で参照できます。 このスキルはそれらの名前を挙げて案内しますが、内容を再定義するものでは ありません。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内（ホスト側のDPA作業であり、DPA側のカーネル作成ではない）であることを確認します。
2. DPAの機能マトリックス、インスタンスごとのdoca_dpaコンテキスト、ロード済みのdoca_dpa_appイメージ、doca_dpa_thread実行コンテキスト、カーネルの起動と完了のモデル、2種類の機能クエリ、環境の事前条件に関するポリシー、エラー分類、可観測性の範囲、安全性に関するポリシーについては、機能に関する補足資料を参照してください。
3. 構成、ビルド、変更、実行、テスト、デバッグの手順を順に説明するワークフローについては、タスクに関する補足資料を参照してください。

どちらの補足ファイルも相互にリンクしています。また、正規のDOCAバージョン処理ルール（DPA固有のオーバーレイとして、DOCAのバージョンはDPACCコンパイラーと一致する必要があります）を記載したdoca-version/SKILL.mdにもリンクしています。「DPAのホスト側に固有のガイダンス」ではなく、「公開されているDOCA DPA、DPACC、DPA-Comms、DPA-Verbsのガイド、またはディスク上のインストールレイアウトを調べる」ことが適切な回答となる場合は、doca-public-knowledge-map/SKILL.mdにもリンクしています。

関連スキル

• doca-public-knowledge-map/SKILL.md — 公開されているすべてのDOCAドキュメントソースと、インストール済みDOCAパッケージのディスク上のレイアウトを案内するルーティング表です。 DPAの公開ガイドは https://docs.nvidia.com/doca/sdk/DOCA-DPA/index.htmlにあります。 DPACCコンパイラーガイド、DPA-Commsガイド（DPA側の通信）、DPA-Verbsガイド（DPA側の動詞）、DPA Toolsの総合ガイド（DPA向け開発者用／管理者用CLI）も同じルーティング表に記載されています。これらはこのスキルで再定義されるものではなく、補完的な情報源です。
• doca-setup/SKILL.md — 環境の準備、インストールの検証、DPACCコンパイラーのインストール／検証、および公開NGC DOCAコンテナーを使う「まだインストールしていない」場合の手順を説明します。このスキルでは、前提条件が満たされており、DPACCがDOCAと一致するバージョンでインストールされていることを前提とします。
• doca-version/SKILL.md — 正規のDOCAバージョン処理ルールを説明します。このスキルの## Version compatibilityでは、4者のバージョン一致ルールへのリンクに加え、DOCA Compatibility Policyに基づくDPA固有のオーバーレイとして、DOCAとDPACCのバージョンは一致する必要があることを示します。
• doca-structured-tools-contract/SKILL.md — バンドルにおける構造化ツールの優先順位ルール（検出／優先／フォールバック／報告）を説明します。タスクに関する補足資料のCommand付録は、この契約に準拠しています。
• doca-programming-guide/SKILL.md — すべてのライブラリで共有される一般的なDOCAプログラミングパターンを説明します。正規のpkg-config＋mesonビルドパターン、配布サンプルを変更して最初のアプリを作成する共通ワークフロー、共通のCoreコンテキストのライフサイクル、ライブラリ間で共通のDOCA_ERROR_*分類、プログラム側のデバッグ順序が含まれます。このスキルでは、その上にDPA固有の説明を加えています。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／実行時／プログラム／ドライバーを順に確認する、横断的なデバッグ手順を説明します。DPACCとDOCAのバージョンの不一致、このBlueField世代にDPAが存在しないこと、ホスト側で完了が確認されないDPAカーネルのハング、ホスト側の起動呼び出しとDPA側の関数シグネチャの間での起動引数の形状不一致など、DPA固有のデバッグについては、この手順に重ねて説明しています。

DOCA DPAのデバイス側コンポーネントである通信アーカイブlibdoca_dpa_dev_comm.a（DPAカーネル自体が呼び出す通信プリミティブ。ヘッダーはdoca_dpa_dev_comch_msgq.h）と、動詞アーカイブlibdoca_dpa_dev_verbs.a（DPAカーネル自体が呼び出す、ibverbsに似たRDMA動詞。ヘッダーはdoca_dpa_dev_verbs.h）は、doca-dpa内に同梱されるDPA側のアーカイブであり、独立したpkg-configモジュールではありません。それぞれに独自の公開ガイドがあります。このバンドルには、これらを対象としたライブラリスキルはまだありません。DPA側に関する質問はすべて、doca-public-knowledge-map/SKILL.mdを通じて、公開されているDOCA DPA CommsおよびDOCA DPA Verbsガイドと、同梱の/opt/mellanox/doca/samples/doca_dpa/サンプル（ホスト側とDPA側の両方の翻訳単位を含みます）に案内してください。これらをdoca-dpaと混同することが、DPAで最初のアプリを設計する際に最もよくある誤りです。