doca-rdmi

DOCA RDMA Initiator

例

• 「DPA カーネルからリモートのレスポンダーに RDMA 書き込みを発行する必要があります。」 — これは対象範囲内です。doca_rdmi_* を使い、ホスト CPU 用の doca-rdma に書き換えないでください。
• 「リンク時に doca_rdmi_ の関数が見つかりません。」* — 代替 API を考案する前に、そのシンボルがこの DOCA バージョンで EXPERIMENTAL かどうかを確認してください。

手順

以下の読み込み順に従ってください。設定／ビルド／デバッグについてはタスク用の関連ファイルを開いてください。RDMI と RDMA の違いおよび EXPERIMENTAL シンボルのルールについては、機能用の関連ファイルを開いてください。関連ファイルをすべて開く必要はありません。

最初に確認すること： このスキルは、doca-rdmi ライブラリを含む DOCA パッケージセットがすでにインストールされており、ホストまたは BlueField で実際に RDMI を扱っていることを前提としています。ユーザーが何かを実行する（インストール／設定／ビルド／変更／実行／テスト／デバッグ／使用する）場合はタスク用の関連ファイルを開いてください。質問が「このバージョンで RDMI に何を表現できるか」、つまりオブジェクトモデル、DPA 側のハンドル型、doca-rdma との関係、EXPERIMENTAL タグのポリシー、安全性に関する補足についての場合は、機能用の関連ファイルを開いてください。

「doca-rdmi について順を追って説明して」というエンドツーエンドの質問には、このスキルだけで回答できます。 そのまま

エンドツーエンド（クイックリファレンス）

に進んでください。インストール確認 → デバイス／機能の検出 → サンプル → pkg-config によるビルド → 実行 → デバッグまで、正確なコマンドを使った自己完結型の手順が記載されています。RDMI のビルド／実行／デバッグに関する質問に答えるために、doca-setup や doca-programming-guide を開く必要はありません。必要な DOCA の前提条件が不足している、一部しか満たされていない、またはバージョンが一致しない場合は、doca-setup/SKILL.md を参照してください。

このスキルで回答しやすい質問の例

このスキルが回答できる RDMI 質問の種類と、それぞれの具体例です。エージェントは、実例そのものではなく、土台となる「質問の種類」を重視してください。実例はその一例にすぎません。

• 「このケースでは doca-rdmi と doca-rdma のどちらを使うべきですか？」 — 実例：「DPA カーネルからリモートのレスポンダーに 1 MB の RDMA 書き込みを発行したいのですが、どちらのライブラリを使えばよいですか？」。回答は、

  機能とモード

  のインターフェース選択表にあるイニシエーター側と汎用の選択ルールに加え、ユースケースが両側での通信、またはホスト CPU からの開始である場合に doca-rdma/SKILL.md を参照する案内に記載されています。
• 「DPA データパス上で RDMI 接続を確立するにはどうすればよいですか？」 — 実例：「doca_rdmi_connection を作成し、DPA コンプレーションコンテキストを関連付け、DPA 側ハンドルをカーネルに渡したいです」。 回答は、

  機能とモード

  の接続オブジェクトのライフサイクルと、

  設定

  の設定手順に記載されています。
• 「接続とポスターはどのような関係にありますか？ どちらも必要になるのはどのような場合ですか？」 — 実例：「アプリケーションでワークリクエストを受け取り、さらに RDMA 書き込みも発行します。doca_rdmi_connection と doca_rdmi_poster の両方が必要ですか？ それともどちらか一方だけですか？」。 回答は、

  機能とモード

  の 2 オブジェクトモデルと、

  変更

  のサンプルからの変更箇所をまとめた表に記載されています。
• 「DPA 側でコンプレーションを処理するにはどうすればよいですか？」 — 実例： 「接続を doca_dpa_completion に接続し、カーネルからコンプレーションを直接ポーリングしたいです」。回答は、

  機能とモード

  の DPA 側コンプレーション接続パターンと、

  実行

  の実行時の配線方法に記載されています。DPA プログラミングのインターフェースそのものについては、doca-dpa/SKILL.md も参照してください。
• 「必要なシンボルは利用可能ですか？ また、リリースに使えるほど安定していますか？」 — 実例： 「インストール済みの DOCA で doca_rdmi_poster_post は GA ですか？ それともまだ EXPERIMENTAL ですか？」。回答は、

  バージョン互換性

  の EXPERIMENTAL タグのポリシーと、

  設定

  に記載されたバージョン確認ルール（pkg-config --modversion doca-rdmi）にあります。
• 「doca_rdmi_* 呼び出しで返されたこの DOCA_ERROR_* は何を意味しますか？」 — 実例： 「doca_rdmi_connection_dpa_completion_attach で DOCA_ERROR_BAD_STATE が返されました」。回答は、

  エラー分類

  のライブラリ横断の分類に対する RDMI 固有の補足と、 doca-debug/SKILL.md まで掘り下げる

  デバッグ

  の段階的な手順に記載されています。

対象読者

このスキルは、リモートのレスポンダーに対して一方的な RDMA 操作を開始する必要がある、DPA 上に配置された DOCA アプリケーションを開発する外部開発者を対象としています。つまり、アクセラレーター側のコードから、ホスト CPU を経由せずにアクセラレーターから直接送信、書き込み、読み取りをポストしたいユーザー向けです。代表的な呼び出し元は、doca-dpacc-compiler でコンパイルされ、BlueField DPA データパス上で実行される DPA カーネルです。DPU の RDMA キューを操作する GPU 側の呼び出し元は、関連するケースですが、doca-gpi/SKILL.md の対象です。このスキルは、DOCA RDMI 自体に貢献する NVIDIA 開発者向けではなく、一般的なホスト CPU の双方向 RDMA に適した窓口でもありません。そちらは doca-rdma/SKILL.md の対象です。

言語の対象範囲

DOCA RDMI は、pkg-config モジュール名が doca-rdmi の C ライブラリとして提供されています。ライブラリのホスト側の API（doca_rdmi_connection_*、doca_rdmi_poster_*）は C です。アクセラレーターカーネルが使用するDPA 側の API も C で、doca-dpa/SKILL.md に記載されている DOCA DPA ツールチェーンでコンパイルします。他の言語を使用する利用者（Rust、Go、Python など）は、FFI 経由でホスト側の *.so を利用します。その場合、このスキルでは、接続／ポスターのライフサイクル、EXPERIMENTAL タグのポリシー、DPA 側への受け渡し規則、安全性に関する補足を言語に依存しない形で示し、最終的にラッパーが呼び出す正式な API として、エージェントを公開 C ABI に案内します。DPA 側の API は別の言語でラップできません。DPA バイナリ自体にコンパイルされ、リンクされるためです。

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

ユーザーが DOCA をインストールしたホストまたは BlueField で、DOCA RDMI を実際に使用している場合に、このスキルを読み込んでください。具体的には、次のような場合です。

• DPA データパスから実行される新しい一方的 RDMA ワークロードで、doca-rdmi と doca-rdma のどちらを使うか判断するとき。
• doca_rdmi_connection または doca_rdmi_poster を作成し、doca_dpa_completion または doca_verbs_cq を接続して、DPA データパス上でコンテキストを開始するとき。
• doca_rdmi_connection_get_dpa_handle／doca_rdmi_poster_get_dpa_handle が返す DPA 側のハンドルを、対応するデバイス側ヘッダー（doca_rdmi_dev_connection.h、doca_rdmi_dev_poster.h、doca_rdmi_dev_cqe.h）を呼び出す DPA カーネルに渡すとき。
• DPA カーネルが受信完了を処理した後、ホスト側で doca_rdmi_connection_recv_ack を使って受信完了を確認するとき。
• RDMI を使用するコンポーネントを本番環境で安定して使用できると宣言する前に、インストールされている DOCA バージョンでどの RDMI シンボルが EXPERIMENTAL かを監査するとき。
• doca_rdmi_* 呼び出しが返す DOCA_ERROR_* をデバッグし、原因が設定ミス、ライフサイクルの順序に関するバグ、このデバイスでサポートされていない機能、または DOCA より下位のレイヤーにあるかを判断するとき。

一般的な DOCA の概要、DOCA 自体のインストール、またはホスト CPU の双方向 RDMA に関する質問では、このスキルを読み込まないでください。それぞれ doca-public-knowledge-map/SKILL.md、doca-setup/SKILL.md、doca-rdma/SKILL.md を使用してください。

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

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

• capabilities 関連ファイル — このバージョンで RDMI が表現できるもの：doca_rdmi_connection オブジェクトモデルと doca_rdmi_poster オブジェクトモデル、DPA 側の完了処理をアタッチするパターン、doca-verbs（RDMI は doca_verbs_context を基盤とします）および doca-dpa（アクセラレーター側のデータパス）との関係、バージョンの扱いに関する EXPERIMENTAL タグのルール、ライブラリ横断の DOCA_ERROR_* 分類における RDMI の位置づけ、可観測性の範囲（PE 上の完了イベント／DPA 側の完了処理）、およびアクセラレーターカーネルからリモートレスポンダーのメモリへのポスト処理を制御する安全ポリシー。
• tasks 関連ファイル — 対象となる8つの動詞（install、configure、build、modify、run、test、debug、use）の手順を示すワークフロー。さらに、動詞／接続／DPA アタッチ／MR スタックを対象とした RDMI 固有の5段階のティアダウンを含む ## rollback オーバーレイと、5フェーズの汎用デバッグループを ## debug に追加したものも含まれます。また、対象範囲外の質問を適切な次のスキルに案内する Deferred task verbs ブロックもあります。

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

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

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

• **言語を問わず、あらかじめ作成された DOCA RDMI アプリケーションのソースコード。**エージェントの役割は、ユーザーがインストールした DOCA に含まれる検証済みのリファレンスコードへユーザーを案内し、doca-programming-guide/SKILL.md の汎用サンプル変更ワークフローに ## modify の RDMI 固有の上書きを適用して、最小限の差分で変更するよう指示することです。執筆時点ではすべての RDMI シンボルに EXPERIMENTAL のタグが付いているため、このスキルはドキュメントの説明文から RDMI のソースコードを作成しません。API はリリース間で変更される可能性があり、その結果、コードがコンパイルすらできない場合があります。
• スキル内に置かれた、単独で使えるビルドマニフェスト（meson.build、CMakeLists.txt、Cargo.toml など）。エージェントはユーザーのプロジェクトディレクトリ内で、ユーザーがインストールした DOCA を対象にビルドマニフェストを作成します。その際、信頼できる情報源となるのは pkg-config --modversion doca-rdmi です。
• **DPA 側カーネルのテンプレート。**DPA 側の範囲は doca-dpa/SKILL.md が扱います。RDMI の DPA 側ヘッダーは、同ファイルで説明されている DPA プログラミングモデルで使用されるものです。このスキルでは、DPA 固有の引き継ぎ（DPA ハンドル型、完了処理をアタッチする呼び出し）を示しますが、DPA カーネルは作成しません。
• samples/、bindings/、reference/ のいずれかのサブツリー。「リファレンス」とラベル付けされていても、このスキルのツリー内にモックや不完全な成果物があると、ユーザーはビルド可能なものだと誤解するため、誤解を招きます。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内か確認します。
2. RDMI オブジェクトモデル、DPA 側の引き継ぎパターン、EXPERIMENTAL タグのポリシー、エラー分類、可観測性、安全ポリシーについては、capabilities 関連ファイルを参照してください。
3. 手順を含むワークフロー（install、configure、build、modify、run、test、debug、use）については、tasks 関連ファイルを参照してください。

どちらの関連ファイルも、適切な回答が「RDMI 固有のガイダンス」ではなく「公開ドキュメントまたはインストール済みパッケージの構成を調べる」である場合は、互いに、また doca-public-knowledge-map/SKILL.md へのリンクを記載しています。

関連スキル

• doca-rdma/SKILL.md — 双方向 RDMA とホスト CPU 起点の RDMA を扱う、より上位の RDMA ライブラリです。RDMI はイニシエーター側に特化したインターフェースです。大半の RDMA ユースケースには doca-rdma が適しています。## Capabilities and modes の選択表が、判断の要となります。
• doca-dpa/SKILL.md — DOCA DPA のプログラミングインターフェースです。RDMI は、DPA カーネルがデバイス側ヘッダー（doca_rdmi_dev_connection.h、doca_rdmi_dev_poster.h、doca_rdmi_dev_cqe.h）を通じて使用する DPA 側ハンドル（doca_dpa_dev_rdmi_connection_t、doca_rdmi_dev_poster_t）を返します。DPA ツールチェーン、カーネルのビルド、実行モデルについては、このスキルが扱います。
• doca-gpi/SKILL.md — このスキルの GPU 側の姉妹スキルです。GPI は、CUDA カーネルが RDMA を開始するために使用するチャネル／キューのインターフェースで、RDMI は DPA 側のインターフェースです。どちらも同じ DOCA RDMA／verbs 基盤上に構築されています。イニシエーターが DPA と GPU のどちらにあるかによって、適用するスキルが異なります。
• 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_* の分類が含まれます。このスキルでは、これらに RDMI 固有の内容を重ねて説明します。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／ランタイム／プログラム／ドライバーを横断するデバッグ手順です。RDMI 固有のデバッグ内容は、その上に重ねて説明します。
• doca-hardware-safety/SKILL.md — バンドル全体に適用されるハードウェア安全性のメタポリシーです。capabilities companion の ## Safety policy オーバーレイから相互参照されています。
• doca-version/SKILL.md — バージョン検出と、各アーティファクトの ## Version compatibility アンカーが基礎とする 4 方向の照合ルールを説明します。このスキルでは、RDMI 固有のオーバーレイのみを引用します。
• doca-structured-tools-contract/SKILL.md — エージェントが優先的に使用する構造化ヘルパー（環境プローブ、機能スナップショット、バージョンマトリックス検索）の JSON スキーマコントラクトです。tasks companion の ## Command appendix では、手動の手順にフォールバックする前に、これらを利用します。