doca-flow-dpa-provider

DOCA Flow DPA Provider

例

• 「DPA カーネルから、エクスポートされたパイプ内のエントリーが見えません。」 — これは対象範囲内です。エクスポートのハンドシェイク順序を守り、DPA カーネルから Flow パイプを再構築しないでください。
• 「_pipe_export で BAD_STATE が発生します。」 — _export_prepare を完了し、エントリーを追加してから _export を実行してください。デバイスアドレスに直接進まないでください。

手順

以下の読み込み順に従ってください。設定／エクスポート／デバッグについてはタスクの補足資料を開いてください。キューの種類とハンドシェイクについては機能の補足資料を開いてください。

最初に確認する内容： このスキルは、DOCA がすでにインストールされており、ユーザーが DOCA 経由でホストから認識できる DPA プロセッサを搭載した BlueField を所有し、ホストからすでに DOCA Flow（doca-flow）をプログラムし、ホストからすでに DPA カーネル（doca-dpa／DPACC コンパイラー）を実行しており、さらに DPA Flow Provider を実際に使って作業している ことを前提としています。つまり、doca-flow-dpa-provider を使って既存の DOCA Flow パイプまたは外部リソースを DPA アドレス空間にエクスポートし、DPA カーネルからインラインで操作します。ユーザーが何かを実行（設定／ビルド／変更／実行／テスト／デバッグ）したい場合はタスクの補足資料を開きます。このバージョンと BlueField の世代でプロバイダーが 何を表現できるか を尋ねている場合は、機能の補足資料を開きます。ユーザーがまだ DOCA をインストールしていない場合は、まず doca-setup/SKILL.md に案内してください。ホスト側の Flow パイプをまだ用意していない場合は、まず doca-flow/SKILL.md に案内してください。ホスト側の DPA 実行環境をまだ用意していない場合は、まず doca-dpa/SKILL.md に案内してください。

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

このスキルが回答できるよう設計されている、DPA Flow Providerに関する質問のクラスと、それぞれの具体例を示します。エージェントは、基盤となるのはクラスであり、具体例はその一例にすぎないと捉えてください。

• 「これは、やりたいことに本当に適したライブラリですか？」 — 具体例：「DPAカーネルからDOCA Flowパイプを読み取れるようにしたい、またはホスト側のdoca-flow APIでできることより高度な処理をしたい」。## Capabilities and modesの判断ルール（「3プログラムモデル：このライブラリが適切なインターフェースとなる場合と、純粋なホスト側Flow、純粋なDPAを使う場合」）で回答します。初めて質問するユーザーの多くは、このライブラリを必要としていません。このスキルの最初の役割は、必要性を確認することです。
• 「既存のDOCA FlowパイプをDPA側にエクスポートするにはどうすればよいですか？」 — 具体例：「各エントリにカウンターがあるFlowパイプを使っています。DPAカーネルからそのカウンターをインラインで読み取り、次の処理を判断したいです」。## Capabilities and modesのホスト側エクスポート手順と、## configureの初期化手順で回答します。
• 「DPAカーネル内からエクスポート済みパイプを操作するにはどうすればよいですか？」 — 具体例：「エクスポート済みのハッシュパイプのデバイスアドレスがあります。DPAからエントリを無効化するにはどうすればよいですか？また、処理が完了したことを確認するにはどうすればよいですか？」。## Capabilities and modesのデバイス側API（「DPA側での利用」）、ホスト側のキュー割り当て、## runのDPA側ポーリング手順で回答します。
• 「doca_flow_dpa_*の呼び出しで発生したこのDOCA_ERROR_*は何を意味しますか？また、問題はホスト側、DPA側、それとも両者間のエクスポートハンドシェイクにありますか？」 — 具体例：「doca_flow_dpa_pipe_exportでDOCA_ERROR_BAD_STATEが発生しました」。## Error taxonomyの、複数ライブラリにまたがるエラー分類へのプロバイダー固有の補足と、doca-debug/SKILL.mdへエスカレーションする## debugの段階的手順で回答します。
• 「パイプのエクスポートは成功したのに、DPAカーネルからエントリがまったく見えないのはなぜですか？」 — 具体例：「パイプにエントリを追加した後でdoca_flow_dpa_pipe_export_prepareを呼び出しました」。## Safety policyのライフサイクル順序のルールと、## testの段階的エクスポートワークフローで回答します。
• 「参照しているホスト側／DPA側のプロバイダーAPIは、インストール済みのDOCAで利用できますか？」 — 具体例：「このホストのDOCAとDPACCのバージョンで、3種類のキュータイプに対応するdoca_flow_dpa_queues_createを利用できますか？それとも、まだ旧式のdoca_flow_dpa_pipe_queuesベースのインターフェースですか？」。## Version compatibilityのバージョン互換性に関する補足で回答します。このセクションは、doca-version/SKILL.mdにある標準の検出手順への相互リンクと、doca-dpa/SKILL.mdから引き継いだプロバイダー固有の補足を加えています。

対象読者

このスキルの対象は、DOCA Flow DPA Provider ライブラリを利用するアプリケーションを開発する外部開発者です。つまり、ホスト側の doca-flow パイプとホスト側の doca-dpa 実行コンテキストをすでに用意しており、DPA カーネルがホスト CPU を介さずに、Flow パイプに関連付けられたカウンターを読み取ったり、エントリーを変更したり、外部リソースを読み書きしたりできるよう、両者を接続したいユーザーを指します。このスキルは、プロバイダーライブラリ自体に貢献する NVIDIA の開発者や、ホスト側の Flow プログラミング（doca-flow）のみを必要とするユーザー、Flow に関係のない汎用的な DPA コンピューティング（doca-dpa）のみを必要とするユーザーを対象としていません。

言語の範囲。 DOCA Flow DPA Provider は、ホスト側の C ライブラリ（pkg-config モジュール doca-flow-dpa-provider、ヘッダー doca_flow_dpa_provider.h）と、カーネルが doca_flow_dpa_provider_dev.h をインクルードしたときに DPACC コンパイラーが DPA 側の翻訳単位にリンクする、DPA 側のデバイスライブラリを組み合わせたライブラリとして提供されます。どちらの部分も C です。提供されるサンプル（インストール済みの DOCA サンプルツリー内）には、両方の翻訳単位が含まれています。ほかの言語を使うホスト側の利用者は、FFI を介してホスト側の C ライブラリを利用できますが、DPACC コンパイラーはカーネルイメージごとに単一の翻訳単位しか受け付けないため、DPA 側のカーネルには FFI による回避手段がありません。このスキルでは、ライフサイクル、機能の検出、環境の前提条件、エラー分類に関するガイダンスをホスト側では言語に依存しない形で提供し、DPA 側のカーネル作成に関する質問はすべて、公開されている DOCA DPA および DOCA Flow のプログラミングガイドを参照するよう、 doca-public-knowledge-map/SKILL.md を案内します。

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

ユーザーが、任意のホスト言語と dpacc でビルドする DPA 側の翻訳単位を使って、DOCA Flow DPA Provider の実作業を行う場合は、このスキルを読み込んでください。具体的には、次のような作業が該当します。

• ホストから DPA プロセッサーが認識できる BlueField に対応する flexio_process と、同じデバイスに対してすでに起動済みのホスト側 doca-flow ポートを使って、doca_flow_dpa_ctx を初期化する。
• doca_flow_dpa_queues_create を使って、ポート向けに 3 種類の DPA 側キュー（general / entries、resources-write、resources-read）を割り当てる。
• パイプにエントリーを追加する前に、doca_flow_dpa_pipe_export_prepare → _pipe_export → _pipe_get_device_addr の順序で、ホスト側の doca_flow_pipe を DPA のアドレス空間にエクスポートする。
• 対応する doca_flow_dpa_external_resource_* ファミリーを使って、外部 Flow リソース（インデックスセレクターリソース、メモリーリソース）を DPA にエクスポートする。
• 取得した doca_flow_dpa_addr デバイスポインターを DPA 側のカーネルに渡し、カーネルからそのポインターを使って doca_flow_pipe_hash_* / doca_flow_external_resource_* / doca_flow_queue_poll_completion を呼び出せるようにする。
• doca_flow_dpa_* 呼び出しから返された DOCA_ERROR_* をデバッグする。特に、パイプのライフサイクルでエクスポートを呼び出すタイミングが遅すぎた場合と、キューがまだ作成されていない場合と、DPA 側のキューが満杯で、排出されていない場合を区別する。
• プロバイダーのホスト側セットアップを実行し、デバイスアドレスを dpacc で別途ビルドした DPA アプリケーションイメージに渡す、C 以外の言語でホスト側バインディングを設計する。

一般的な DOCA Flow プログラミングにはこのスキルを読み込まないでください（doca-flow/SKILL.md を使用してください）。汎用的なホスト側 DPA 作業には（doca-dpa/SKILL.md を使用してください）、DPA 側のカーネル作成自体には使用しないでください（公開されている DOCA DPA / DPACC / Flow のプログラミングガイドについて、 doca-public-knowledge-map/SKILL.md を参照してください）。

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

これは薄いローダーです。本文には、次に参照すべきファイルを選ぶために必要な案内だけを残しています。プロバイダー固有の詳細は、次の2つの関連ファイルに記載されています。

• capabilities 関連ファイル — このバージョンおよび BlueField の世代で、ホスト側と DPA 側のプロバイダー API が表現できる機能を説明します。ポートごとの doca_flow_dpa_ctx コンテキスト、3種類のキュー（DOCA_FLOW_DPA_QUEUE_TYPE_GENERAL / _RESOURCES_WRITE / _RESOURCES_READ）、パイプのエクスポートハンドシェイク（prepare → export → get-device-addr）、外部リソースの並列エクスポートハンドシェイク、ハッシュパイプのエントリーを操作する DPA 側デバイス API（doca_flow_pipe_hash_enable_index / _hash_disable_index / _hash_replace_index）、外部リソース用の DPA 側デバイス API（doca_flow_external_resource_index_selector_modify*、 doca_flow_external_resource_memory_update、 doca_flow_external_resource_memory_read*）、完了キューのポーリング（doca_flow_queue_poll_completion）、3つのプログラミングモデルのルール（ホスト側の doca-flow + ホスト側の doca-dpa + DPA 側カーネル）、ライブラリ間で共通の DOCA_ERROR_* セットに対応付けられたエラー分類、可観測性の範囲、およびエクスポートのライフサイクルを制御する安全ポリシーです。
• tasks 関連ファイル — 対象範囲内のプロバイダー操作（install、configure、build、modify、run、test、debug、use）について、手順ごとのワークフローを説明します。また、対象範囲外の質問を適切な次のスキルへ案内する Deferred task verbs ブロックも含まれています。

このスキルは、DOCA が標準の場所にすでにインストールされており、DPA プロセッサーを搭載した BlueField が物理的に存在してホストから認識され、DOCA Compatibility Policy に従って DOCA のインストールに適合するバージョンの DPACC コンパイラーがインストールされていて、ユーザーが doca-flow ポートを起動し、カーネル実行用のホスト側 doca_dpa（またはその FlexIO 相当）を作成する方法をすでに把握しており、エクスポートされたパイプのデバイスアドレスを使用する DPA 側カーネルの概略を少なくとも把握しているホストを前提としています。

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

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

• DOCA Flow DPA Provider アプリケーションのソースコード、または DPA 側カーネルのソースコード（言語を問いません）。 検証済みのプロバイダーソースは、インストール済み DOCA サンプルツリーに含まれる C および DPA 側のサンプルです（インストールごとのサンプルツリーのパスについては doca-public-knowledge-map/SKILL.md を参照してください）。エージェントの役割は、ユーザーを該当ファイルへ案内し、doca-programming-guide/SKILL.md の共通のサンプル変更ワークフローに、## modify のプロバイダー固有の上書きを重ねて、最小限の差分で変更する方法を指示することです。
• スキル内に置かれた単独のビルドマニフェスト（meson.build、 CMakeLists.txt、…）。エージェントは、ユーザーのプロジェクトディレクトリで、ユーザーがインストールした DOCA と DPACC コンパイラーを対象にビルドマニフェストを作成します。その際、pkg-config --modversion doca-flow-dpa-provider（doca-flow および doca-dpa と併せて）と、インストール済みの dpacc が、相互に整合する信頼できる情報源となります。
• いかなる種類の samples/、bindings/、reference/ サブツリー。 このスキルのツリーにあるモックや不完全な成果物は、「reference」と表示されていても誤解を招きます。ユーザーは、それをビルド可能なものとして受け取るでしょう。
• ホスト側 doca-flow のパイプ仕様の内容。 これは doca-flow/SKILL.md の対象範囲です。このスキルは、すでに構築されたパイプをエクスポートするものであり、その構築方法を再定義するものではありません。
• DPA 側カーネルプログラミング全般。 DPA 側関数本体の作成、カーネル内での DPA メモリの割り当て、組み込み関数、doca-dpa-comms や doca-dpa-verbs などの DPA 側ライブラリは対象範囲外です。doca-public-knowledge-map/SKILL.md を通じて、公開されている DOCA DPA / DPACC ガイドへ案内してください。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内であることを確認してください（Flow-pipe-exported-to-DPA の作業であり、純粋な doca-flow の作業でも、一般的な doca-dpa の作業でもありません）。
2. プロバイダー機能マトリックス、3 プログラムモデル、ポートごとの doca_flow_dpa_ctx、3 種類のキュー、 パイプのエクスポートと外部リソースのエクスポートのハンドシェイク、DPA 側のデバイス API サーフェス、 完了モデル、エラー分類、可観測性サーフェス、安全性ポリシーについては、 機能に関するコンパニオンファイルを参照してください。
3. インストール、設定、ビルド、変更、実行、テスト、デバッグ、使用といった手順を追ったワークフローについては、タスクに関するコンパニオンファイルを参照してください。

両方のコンパニオンファイルは相互にリンクしており、 このライブラリが橋渡しするホスト側のサーフェスについては doca-flow/SKILL.md と doca-dpa/SKILL.md に、正規の DOCA バージョン処理ルールについては doca-version/SKILL.md にリンクしています（DOCA と DPACC のオーバーレイは doca-dpa/SKILL.md から継承されます）。また、適切な回答が「プロバイダー固有のガイダンス」ではなく、「公開されている DOCA Flow／DOCA DPA／DPACC プログラミングガイド、またはディスク上のインストールレイアウトで確認する」である場合は、 doca-public-knowledge-map/SKILL.md を参照してください。

関連スキル

• doca-flow/SKILL.md — ホスト側の Flow プログラミングに関する標準スキルです。このライブラリがエクスポートする Flow パイプは、まず doca-flow ## Capabilities and modes に照らして起動する必要があります。このスキルは、その上に DPA エクスポート層を追加するものです。
• doca-dpa/SKILL.md — ホスト側の DPA 制御ライブラリです。エクスポートされたデバイスアドレスを使用する DPA カーネルは、doca-dpa（またはその FlexIO プロセス相当機能）を通じて読み込まれ、起動されます。このスキルは、2 サイドプログラムモデル、DPACC と DOCA のバージョン一致ルール、および環境の前提条件マトリックスを引き継ぎます。
• doca-public-knowledge-map/SKILL.md — 公開されている DOCA ドキュメントソース（ https://docs.nvidia.com/doca/sdk/doca-flow/index.html の DOCA Flow ガイド、 https://docs.nvidia.com/doca/sdk/doca-dpa/index.html の DOCA DPA ガイド、 同じルーティングテーブルからアクセスできる DPACC コンパイラーガイドと DPA Tools の総合情報）へのルーティングテーブルと、インストール済み DOCA パッケージのディスク上のレイアウトを示します。
• doca-setup/SKILL.md — 環境の準備、インストールの検証、DPACC コンパイラーのインストール／検証、および公開 NGC DOCA コンテナーを使用する インストールがまだない 場合の手順を説明します。このスキルの前提条件が満たされており、DPACC が DOCA と一致するバージョンでインストールされていることを前提とします。
• doca-version/SKILL.md — DOCA のバージョン処理に関する標準ルールです。このスキルの ## Version compatibility では、4 項目の一致ルールへの相互リンクを示し、DOCA Compatibility Policy に基づくプロバイダー固有の DOCA と DPACC のバージョンは一致させる必要がある という補足を追加します（doca-dpa/SKILL.md から継承）。
• doca-structured-tools-contract/SKILL.md — バンドルの構造化ツールの優先順位ルール（検出／優先／フォールバック／報告）です。タスクのコンパニオンにあるコマンドの付録は、この契約に従います。
• doca-programming-guide/SKILL.md — DOCA プログラミングの一般的なパターンを説明します。標準の pkg-config + meson ビルドパターン、配布サンプルを変更して最初のアプリを作成する汎用ワークフロー、汎用 Core コンテキストのライフサイクル、ライブラリ横断の DOCA_ERROR_* 分類、プログラム側のデバッグ手順を含みます。このスキルは、その上にプロバイダー固有の情報を重ねます。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／ランタイム／プログラム／ドライバーにまたがるデバッグ手順です。プロバイダー固有のデバッグ（Flow パイプ作成、キュー作成、エクスポートの準備、エントリー追加、エクスポート間のライフサイクル順序、DPA 側のポーリングでのキュー満杯、異なる doca_flow_dpa_ctx を対象とするカーネルへのパイプデバイスアドレスの受け渡し）は、その上に適用されます。
• doca-hardware-safety/SKILL.md — このスキルの ## Safety policy が補足する、ハードウェア安全性に関する横断的な基本方針です。エクスポートされたパイプは DPA 側のカーネルコードによってインラインで変更されるため、doca-flow のコミット前検証の原則と doca-dpa の 2 サイドプログラム再ビルドの原則の両方が適用されます。この基本方針は、横断的な枠組みを提供します。