doca-dma

DOCA DMA

例

• 「CPU を使わずに、ホストバッファーを BlueField に memcpy する。」 — これは対象範囲内です。同梱の DMA サンプルと doca_dma_task_memcpy を使用してください。
• 「最初の送信時にコピーが NOT_PERMITTED を返す。」 — タスクの種類を変更する前に、mmap の権限と doca_dma_cap_* を確認してください。

手順

以下の読み込み順に従ってください。設定／ビルド／実行についてはタスクのコンパニオンを開いてください。memcpy タスクと、パス選択と RDMA の比較については、機能のコンパニオンを開いてください。すべてのコンパニオンファイルを開く必要はありません。

最初に確認すること： このスキルは、DOCA がすでにインストールされており、ユーザーが BlueField／ConnectX／ホスト上で実際に DMA を扱っていることを前提としています。ユーザーが何かを実行（設定／ビルド／変更／実行／テスト／デバッグ）したい場合は、タスクのコンパニオンを開いてください。このバージョンで DMA が何を表現できるかが質問の場合は、機能のコンパニオンを開いてください。ユーザーがまだ DOCA をインストールしていない場合は、まず doca-setup/SKILL.md に案内してください。DMA が適切なライブラリかどうかも不明な場合 — データがネットワークを通過する必要がある、または 2 つのプロセス間でやり取りするのが小さなメッセージである場合 — 何かを設定する前に

機能とモード

のパス選択ルールを読んでください。

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

このスキルが回答するために作られた DMA に関する質問のクラスと、それぞれの実例です。エージェントは、実例は 1 つのケースにすぎず、重要なのはそのクラスであると捉えてください。

• 「DOCA DMA コンテキストを立ち上げて、ホストと DPU の間でバッファーをコピーするにはどうすればよいですか？」 — 実例：「同梱の DMA Copy リファレンスアプリケーションを出発点として、1 つのタスクでホストメモリーから DPU メモリーに 64 KiB のバッファーをコピーする」。ライフサイクルと memcpy タスクのワークフロー（

  設定 +

  機能とモード

  のタスクタイプ表）が回答します。
• 「このデバイスで、1 つのタスクで memcpy できるバッファーの最大サイズはどのくらいですか？」 — 実例：「1 回の doca_dma_task_memcpy で 16 MiB をコピーできますか」。機能クエリのルール（doca_dma_cap_task_memcpy_get_max_buf_size と、scatter-gather の場合は _get_max_buf_list_len）が、

  機能とモード

  と

  設定

  の検出手順で回答します。
• 「ソースと宛先の mmap には、どの権限が必要ですか？」 — 実例：「memcpy タスクが最初の送信時に DOCA_ERROR_NOT_PERMITTED を返します」。

  安全ポリシー

  のソース／宛先の権限マトリックスと、

  テスト

  の権限チェックリストで回答します。
• 「このコピーには DOCA DMA、DOCA RDMA／Comch、それとも単純な CPU memcpy のどれを使うべきですか？」 — 実例：「ホストプロセスから DPU プロセスへ 1 MiB をコピーする必要があります。DMA と Comch のファストパスのどちらがよいですか」。

  機能とモード

  の「DMA を使う場合」と「使わない場合」のパス選択項目、および ## 関連スキル の案内先で回答します。
• 「インストール済みのバージョンで DOCA DMA を使えますか。また、このデバイスは memcpy タスクをサポートしていますか？」 — 実例：「この ConnectX-6 で DOCA 2.6 の doca_dma_task_memcpy を利用できますか」。

  バージョン互換性

  のバージョン互換性オーバーレイで回答します。ここから、doca-version/SKILL.md の正式な検出手順と、

  機能とモード

  の機能クエリのルールを相互参照します。
• 「DMA 呼び出しのこの DOCA_ERROR_* は何を意味し、どのレイヤーで発生したのですか？」 — 実例：「doca_dma_task_memcpy に対する doca_task_submit が返す DOCA_ERROR_AGAIN」。このライブラリ横断の分類に対する DMA オーバーレイ（

  エラー分類

  ）と、

  デバッグ

  の段階的な手順で回答し、doca-debug/SKILL.md へのエスカレーションにつなげます。

対象読者

このスキルの対象は、DOCA DMA ライブラリを利用するアプリケーションを構築する外部開発者です。つまり、ホスト CPU ではなく BlueField DMA エンジンを使って、2 つの doca_mmap 領域間でバイト列をコピーするために、doca_dma_* を直接（C/C++ で）呼び出すか、他の言語から FFI／バインディング経由で呼び出すコードを書くユーザーです。DOCA DMA 自体にコントリビュートする NVIDIA の開発者向けではありません。

対象言語。 DOCA DMA は、pkg-config のモジュール名が doca-dma の C ライブラリとして提供されます。付属のサンプルは C で記述されています。C および C++ の利用が標準的なケースであり、タスク用の補助ドキュメントにある具体例はこの利用方法を前提としています。他の言語（Rust、Go、Python など）の利用者も、FFI または言語固有のバインディングを通じて同じ *.so を利用します。その場合、このスキルでは、ライフサイクル、機能の検出、権限、エラー分類、経路選択に関するガイダンスを言語に依存しない形で示し、ラッパーが最終的に呼び出す権威あるインターフェイスとして公開 C ABI をエージェントに案内します。

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

ユーザーが言語を問わず、実際に DOCA DMA を扱うときにこのスキルを読み込みます。具体的には、次のような場合です。

• doca_dev 上の doca_dma コンテキストを初期化し、doca_ctx_start() の前に doca_dma_task_memcpy_set_conf を使って memcpy タスクタイプを設定するとき。
• memcpy 用のソースおよび宛先 doca_mmap 領域を設定するとき。これには、各側の権限フラグ（ソースでは DOCA_ACCESS_FLAG_LOCAL_READ_ONLY、宛先では DOCA_ACCESS_FLAG_LOCAL_READ_WRITE）や、ピア間コピーの場合の doca_mmap_export_* 手順が含まれます。
• バッファーサイズを決めたり、scatter-gather が利用可能だと想定したりする前に、doca_dma_cap_task_memcpy_* クエリファミリー（_is_supported、_get_max_buf_size、_get_max_buf_list_len）を使って DMA のデバイス機能を確認するとき。
• DOCA プログレスエンジンに対して doca_dma_task_memcpy タスクを投入し、タスクごとの完了イベントに対応するとき。
• DOCA DMA と隣接する選択肢を比較するとき（データをネットワーク越しに送る必要がある場合は DOCA RDMA、メッセージ指向のプロデューサー／コンシューマーフローには DOCA Comch の高速パス、サイズが小さく一度きりのコピーには通常の CPU memcpy）。
• DMA 呼び出しから返された DOCA_ERROR_*（ライフサイクル、権限、機能、またはブロック中を示すエラー）や、プログレスエンジンから報告されるタスクごとの完了ステータスをデバッグするとき。
• DMA C ABI をラップする非 C バインディング（Rust、Go、Python など）を設計または拡張するとき。ライフサイクル、権限、機能に関するルールをラッパーが守る必要があります。

一般的な DOCA の概要、DOCA 自体のインストール、または DMA 以外のライブラリに関する質問では、このスキルを読み込まないでください。その場合は doca-public-knowledge-map/SKILL.md を使用してください。

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

これは薄いローダーです。本体には、次に読むべきファイルを選ぶために必要な概要のみを残しています。DMA 固有の詳細は、2 つの補助ファイルに記載されています。

• 機能に関する補助ファイル — このバージョンで DMA が実行できる内容。単一の doca_dma_task_memcpy タスクタイプとその scatter-gather バッファーリストの形式、機能クエリ用インターフェイス（doca_dma_cap_task_memcpy_*）、DMA エラーの分類（ライブラリ共通の DOCA_ERROR_* セットへのマッピング）、可観測性用インターフェイス（プログレスエンジン上のタスクごとの完了イベント）、ソース／宛先 mmap の権限ポリシー、隣接ライブラリ（RDMA／Comch／CPU memcpy）との経路選択ルールが説明されています。
• タスク用の補助ファイル — 対象範囲内の 6 つの DMA 動詞、configure、build、modify、run、test、debug の手順を順を追って説明しています。さらに、対象範囲外の質問を適切な次のスキルに案内する Deferred task verbs ブロックもあります。

このスキルでは、DOCA がすでに標準の場所にインストールされ、ユーザーが公開インストールプロファイルで想定されている権限を持つホストまたは BlueField を前提としています。DOCA のインストール方法は扱いません。この手順については doca-setup/SKILL.md を参照してください。

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

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

• あらゆる言語で書かれた、事前作成済みの DOCA DMA アプリケーションのソースコード。 検証済みの DMA ソースコードは、同梱されている C サンプル /opt/mellanox/doca/samples/doca_dma/<name>/ と、 doca-public-knowledge-map/SKILL.md から参照できる DMA Copy リファレンスアプリケーションです。 エージェントの役割は、ユーザーをこれらのファイルに案内し、 doca-programming-guide/SKILL.md の汎用的な サンプル変更ワークフローに沿って、最小限の差分で変更するよう指示することです。 これに、## modify にある DMA 固有の上書きルールを適用します。
• スキル内に置かれた、単独で使うビルドマニフェスト （meson.build、CMakeLists.txt、 Cargo.toml、…）。エージェントは、pkg-config --modversion doca-dma を信頼できる情報源として、ユーザーがインストールした DOCA に対する ビルドマニフェストをユーザーのプロジェクトディレクトリ内で作成します。
• いかなる種類の samples/、bindings/、または reference/ サブツリー。 このスキルのツリー内にあるモックや不完全な成果物は、「リファレンス」と ラベル付けされていても誤解を招きます。ユーザーがビルド可能なものとして 読み取ってしまうためです。

読み込み順

1. まずこのスキルを読み、ユーザーの質問が対象範囲内であることを確認します。
2. DMA の機能範囲、memcpy タスクタイプ、機能照会のルール、 ソース／宛先の権限マトリックス、エラー分類、可観測性、 および RDMA／Comch／CPU memcpy と比較したパス選択ルールについては、 capabilities companion を参照してください。
3. 設定、ビルド、変更、実行、テスト、デバッグの手順については、 tasks companion を参照してください。

どちらの companion ファイルも、相互にリンクしているほか、 標準的なバージョン処理ルールについては doca-version/SKILL.md に、正しい回答が「DMA 固有の ガイダンス」ではなく「公開ドキュメントまたはインストール済みパッケージの レイアウトを調べる」である場合は doca-public-knowledge-map/SKILL.md にリンクしています。

関連スキル

• doca-public-knowledge-map/SKILL.md — 公開されているすべての DOCA ドキュメントソースと、インストール済み DOCA パッケージのディスク上のレイアウトを案内するルーティングテーブルです。DMA の URL は https://docs.nvidia.com/doca/sdk/DOCA-DMA/index.html です。 標準リファレンスアプリケーションは DMA Copy です。
• doca-setup/SKILL.md — 環境の準備、 インストールの検証、そして公開 NGC DOCA コンテナーを使う まだインストールしていない場合 の手順です。このスキルでは、 これらの前提条件が満たされているものとします。
• doca-version/SKILL.md — 標準的な DOCA バージョン処理ルールです。このスキルの ## Version compatibility では、4 者間の一致ルールと検出チェーンにリンクし、 DMA 固有のオーバーレイルールを最大 1 つ追加します。
• doca-structured-tools-contract/SKILL.md — バンドルにおける構造化ツールの優先順位ルール（検出／優先／フォールバック／報告）です。 tasks companion の Command 付録は、この契約に従います。
• doca-programming-guide/SKILL.md — すべてのライブラリに共通する DOCA の一般的なプログラミングパターンです。 標準的な pkg-config + meson ビルドパターン、同梱サンプルの変更を 最初に行う汎用アプリケーション作成ワークフロー、汎用ライフサイクル、 ライブラリ間で共通する DOCA_ERROR_* エラー分類、 プログラム側のデバッグ順序を扱います。このスキルはその上に DMA 固有の情報を 重ねます。
• doca-rdma/SKILL.md — コピーをネットワーク経由で行う 必要がある場合に適したライブラリです。このスキルの パス選択ルールでは、DMA が適切な答えではない場合に RDMA を案内します。
• doca-comch/SKILL.md — フローが、未加工の mmap 間コピーではなく、 ホストと DPU のプロセスペア間のプロデューサー／コンシューマー型メッセージングである 場合に適したライブラリです。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／実行時／ プログラム／ドライバーにわたる、横断的なデバッグ手順です。DMA 固有のデバッグ （ライフサイクル違反、権限の不一致、バッファーサイズ超過による拒否）は、 この手順に重ねて適用します。