doca-rdma

DOCA RDMA

例

• 「送信後に完了通知が届きません。」 — DOCA RDMA タスクとプログレスエンジンの経路を維持してください。raw verbs として書き直さないでください。
• 「片方向読み取りで権限が拒否されます。」 — タスクの種類を変更する前に、mmap と RDMA の権限、および doca_rdma_cap_* を確認してください。

手順

以下の読み込み順に従ってください。設定／ビルド／実行についてはタスクの補足ファイルを開いてください。タスク分類と安全ポリシーについては機能の補足ファイルを開いてください。すべての補足ファイルを開く必要はありません。

譲れない要件：成果物では raw verbs ではなく DOCA RDMA を使用する

このスキルが対象となる場合、ユーザーが求めているのは DOCA RDMA です。作成するプログラムは libdoca_rdma にリンクし、doca_rdma_* API を呼び出す必要があります（C/C++ から直接呼び出すか、別の言語から薄い FFI/cgo シムを介して呼び出します）。raw libibverbs / librdmacm / RDMA-CM でリクエストを実装して、それで完了としないでください。これらはデータを転送しますが、DOCA を完全に迂回します。これは、このライブラリを使用する目的そのものを損ない、DOCA のプログラミングモデル（プログレスエンジン、タスク／イベントのライフサイクル、機能の検出、BlueField／ConnectX 世代間の移植性）を失わせるものであり、最もよくある失敗の原因です。

「raw verbs のほうがコード行数が少ない」／「DOCA バインディング層のビルドを避けられる」は、DOCA を迂回する正当な理由にはなりません。C 以外の言語（Go、Rust、Python など）で手間を抑える正しい方法は、API 全体を再バインドすることではありません。対象で解決されたモジュールに置き換えて、$(pkg-config --variable=prefix doca)/samples/doca_rdma/ 配下にある 同梱の DOCA RDMA サンプルを出発点にし、そのエントリー関数を #cgo pkg-config: doca（Go）または同等の方法でビルドする 薄い cgo/FFI シムでラップしてください。このシムは小さな単一ファイルであり、「大規模なカスタムバインディング層」ではありません。## build Step 0 と

変更する場合

pkg-config doca または DOCA のビルドに失敗した場合は、ビルドを修正してください（モジュール名、PKG_CONFIG_PATH、サンプルのパス）。verbs に黙ってフォールバックしてはいけません。ldd の結果に libdoca_rdma が表示されないバイナリは、データが転送されたかどうかにかかわらず、DOCA-RDMA タスクの失敗です。

具体的な手順（DOCA 3.3、RoCE ポート 1 つ、プロセス 2 つで検証済み）：

0. まずインストール済みのバージョンを記録します：
   pkg-config --modversion doca-rdma を実行し、結果を表示します。
1. 同梱されているペアをその場でビルドし、出力先は別にします。 サンプルの meson.build は ../../../VERSION を読み取るため、コピーしたサンプルツリーでは 設定できません。インストール先のディレクトリから独自のビルドディレクトリに ビルドすれば、/opt 以下には何も書き込みません： cd /opt/mellanox/doca/samples/doca_rdma/rdma_receive && meson setup <work>/rr && ninja -C <work>/rr （rdma_send も同様に <work>/rs へビルドします）；バイナリは doca_rdma_receive、 doca_rdma_send です。--help でフラグを確認します。
2. 両方を 1 つのコマンドで実行します。 各側は接続記述子（-ld）を書き込み、 Enter キーを押すまで待ってから、相手側の記述子（-re）を読み取ります； 受信側で先に Enter キーを押す必要があります： ( sleep 6; echo ) | <work>/rr/doca_rdma_receive -d <dev> -g <gid> -ld <work>/recv.desc -re <work>/send.desc & 続けて sleep 2; ( sleep 6; echo ) | <work>/rs/doca_rdma_send -d <dev> -g <gid> -ld <work>/send.desc -re <work>/recv.desc; wait を実行します。 成功の目印：受信側に Got from sender: "..." が記録され、両方で Sample finished successfully が表示されます。Failed to open the file ... for reading は、相手側が書き込む前に一方が読み込んだことを意味します。コードではなく、 実行順序を修正してください。
3. 標準の実行が成功してからのみ拡張します。 追加出力（チェックサムや証明行など）が 必要な場合は、サンプルディレクトリから 3 階層上に /opt/mellanox/doca/VERSION を置いたまま、サンプルツリー全体をコピーし、ペイロードと 受信側の出力だけを変更します。実行順序は同じにし、ユーザーが指定したプログラム名や 出力形式も維持します。RDMA プログラムを一から新しく作成してはいけません。 インストール済みのサンプルを編集したり、raw verbs、 rdma_cm コード、ib_write_bw、rping、ループバックにフォールバックしたりしてはいけません。

デバイスと GID。 アクティブなポートのデバイスと、値が設定された RoCE v2 GID（/sys/class/infiniband/<dev>/ports/<port>/gids/<i> と gid_attrs/types/<i>）を使用します。正しい順序で実行しても標準のペアが失敗した場合は、 そこで中止し、デバイス、GID テーブル、エラーを報告してください。

まず確認する場所： このスキルは、DOCA がすでにインストールされており、ユーザーが BlueField／ConnectX／DOCA 搭載ホストで実際に RDMA を操作していることを前提としています。 ユーザーが何か（設定／ビルド／変更／実行／テスト／デバッグ）を行いたい場合はタスク用の コンパニオンを開き、このバージョンで RDMA を使って何を表現できるかが質問の場合は 機能用のコンパニオンを開きます。ユーザーがまだ DOCA をインストールしていない場合は、 まず doca-setup/SKILL.md に案内してください。

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

このスキルが回答するために作られたRDMAの質問の種類と、それぞれの具体例を示します。エージェントは、個別の具体例ではなく、根幹となる「種類」に着目してください。具体例は、その種類に当てはまる1つのケースです。

• 「RDMAコンテキストを起動して、両側を接続するにはどうすればよいですか？」 — 具体例：「初回テスト用に、単一ホストでRDMA CMを使って送信側と受信側をセットアップする」。回答は、## configure のライフサイクルと接続ワークフロー

  • Capabilities and modes の接続方式の選択によって得られます。

• 「このデータ移動パターンに適したRDMAタスクの種類はどれですか？」 — 具体例：「小さな制御メッセージにSend-with-Immediateを使って、一方向のWriteを行い、完了を通知する」。回答は、## Capabilities and modes のタスク分類

  • modify のタスク設定ワークフローによって得られます。

• 「このタスクに必要なmmapの権限は何ですか？ mmapをエクスポートする必要がありますか？」 — 具体例：「Readタスクが権限不足で失敗する」。回答は、## Safety policy の権限マトリックス

  • test のmmapエクスポートのチェックリストによって得られます。

• 「このRDMA機能は、自分のデバイスとトランスポートでサポートされていますか？」 — 具体例：「このデバイスはRoCE経由のAtomic Compare-and-Swapをサポートしていますか？」。回答は、## Capabilities and modes の機能クエリ規則（doca_rdma_cap_task_*_is_supported を doca_devinfo に対して実行する）

  • configure の検出手順によって得られます。

• 「このRDMA APIは、インストール済みのDOCAのバージョンで利用できますか？」 — 具体例：「DOCA 2.6.0にRDMA CMは含まれていますか？」。回答は、## Version compatibility のバージョン互換性のセクション

  • configure に記載されたバージョン検出規則（pkg-config --modversion doca）によって得られます。

• 「RDMA呼び出しで発生したこのDOCA_ERROR_*は何を意味し、どのレイヤーが原因ですか？」 — 具体例：「doca_rdma_connection_disconnect が返す DOCA_ERROR_BAD_STATE」。回答は、## Error taxonomy のライブラリ横断の分類に対するRDMA向けの補足
  • doca-debug/SKILL.md へと段階的に切り分けを進める## debug のレイヤー別手順によって得られます。

対象読者

このスキルは、DOCA RDMAライブラリを利用するアプリケーションを開発する外部開発者を対象としています。つまり、RDMAデータを両側間（ホスト↔ホスト、ホスト↔BlueField、DPU↔DPU、またはBlueField上のSF↔SF）で移動させるために、doca_rdma_* を呼び出すコードを記述するユーザーです（C/C++で直接呼び出す場合、または別の言語からFFI／バインディング経由で呼び出す場合）。DOCA RDMA自体に貢献するNVIDIAの開発者向けではありません。

対象言語。 DOCA RDMAは通常、Cライブラリとして、包括モジュールdocaのpkg-configモジュール内で提供されます（公開ヘッダーdoca_rdma.h、共有オブジェクトlibdoca_rdma.so）。分割インストールでは、ライブラリごとのモジュールが公開されることがあります。どちらの構成かを決めつけず、対象システムで常にモジュールを検出してください（pkg-config --list-all | grep -i doca）。付属のサンプルはCで記述されています（NVIDIAによる選択です）。CおよびC++の利用が標準的なケースであり、タスクの補足資料にある具体例もこの経路を前提としています。その他の言語（Rust、Go、Pythonなど）の利用者は、FFIまたは言語固有のバインディングを通じて同じ*.soを利用します。その場合、このスキルでは、ライフサイクル、機能検出、権限マトリックス、エラー分類、接続方式に関するガイダンスを言語に依存しない形で提供し、最終的にあらゆるラッパーが呼び出す権威あるインターフェースとして公開C ABIへエージェントを案内します。C以外の言語での成果物も、依然としてDOCAプログラムです。付属のdoca_rdmaサンプルを基にした薄いcgo／FFIシムで、libdoca_rdma（#cgo pkg-config: doca）にリンクするものとします。DOCAのラッパーを避けるために、生のlibibverbsを使って再実装してはいけません（このファイルの冒頭にある必須要件を参照してください）。

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

ユーザーが、どの言語であっても、DOCA RDMA の実作業を行っているときに読み込みます。具体的には、次のような場合です。

• doca_dev 上で RDMA コンテキストを初期化する場合です。Core の順序は、作成 → 設定（タスクの set_conf ＋ mmap/RDMA 権限 ＋ オプションの set_*）→ 開始 → 接続 → 使用 → 停止 → 破棄です。 設定は doca_ctx_start() より前に必ず完了させてください。
• 接続を確立する場合です。RDMA CM（doca_rdma_connect_to_addr() / doca_rdma_start_listen_to_port() / doca_rdma_connection_accept()）、ブリッジ / OOB （doca_rdma_bridge_*）、または gRPC（doca_rdma_export() の出力を帯域外で交換）のいずれを選ぶかを判断します。
• 選択したタスク種別に応じて、doca_mmap に正しい権限を設定する場合です（Read には RDMA 読み取り ＋ ローカルの読み書き、Write には RDMA 書き込み、Atomic には RDMA アトミック、Send にはローカルの読み書きのみが必要です）。
• doca_rdma_set_* と doca_rdma_cap_get_* を使ってライブラリのプロパティを読み取ったり設定したりし、キュー、リストの長さ、トランスポート種別の選択を決める場合です。
• アクティブな doca_devinfo で、どの RDMA タスク種別とトランスポート種別がサポートされているかを確認する場合です。
• RDMA 呼び出しから返された DOCA_ERROR_*（ライフサイクル、権限、機能、または下位ドライバーに関するもの）や、接続状態の状態遷移（doca_rdma_set_connection_state_callbacks）をデバッグする場合です。
• RDMA C ABI をラップする非 C バインディング（Rust、Go、Python など）を設計または拡張する場合です。ラッパーが守るべきライフサイクル、権限、機能に関するルールが対象です。

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

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

これは薄いローダーです。本体には、次に参照すべきファイルを選ぶための概要だけが含まれます。RDMA 固有の実質的な情報は、次の 2 つの関連ファイルにあります。

• 機能に関する関連ファイル — このバージョンで RDMA がサポートする内容です。11 種類のタスクとその権限マトリックス、3 種類の接続方法、トランスポート種別（ベースラインの RC と、エクスポート / 接続の CPU データパスフローで使用するアルファレベルの DC。UD はありません）を扱います。これらは doca_rdma_set_transport_type() で制御される QP ごとのサービスタイプであり、デバイスポートの構成から継承されるリンクレイヤー（IB と RoCE の違い）ではないことに注意してください。また、機能クエリーの API（doca_rdma_cap_*）、RDMA エラーの分類（ライブラリ横断の DOCA_ERROR_* セットへのマッピング）、可観測性の API（タスクごとのイベント、接続状態コールバック）、権限とエクスポートの判断を制御する安全ポリシーも扱います。
• タスクに関する関連ファイル — 対象範囲に含まれる 6 つの RDMA 動詞、configure、build、modify、run、test、debug の手順を説明します。さらに、対象範囲外の質問を適切な次のスキルに案内する Deferred task verbs ブロックもあります。

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

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

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

• いずれの言語でも、DOCA RDMA アプリケーションの事前作成済みソースコード。 検証済みの RDMA ソースコードは、以下のインストール先プレフィックス配下にある、同梱済みの C サンプルです。 $(pkg-config --variable=prefix doca)/samples/doca_rdma/<name>/ （ターゲット上で解決されたモジュールを使用します）。エージェントの役割は、ユーザーをこれらのファイルに案内し、 doca-programming-guide/SKILL.md の汎用的なサンプル変更ワークフローを使って、最小限の差分で変更する方法を指示することです。これに RDMA 固有のオーバーライドを

  modify

  で重ねます。
• 単独のビルドマニフェスト（meson.build、CMakeLists.txt、Cargo.toml、…）をスキル内に置くこと。エージェントは、ユーザーのインストール済み DOCA を参照して、ユーザーのプロジェクトディレクトリ内にビルドマニフェストを作成します。正確な情報源は pkg-config --modversion doca です（## build の Step 0 に従ってモジュールを解決します。解決できる場合は doca-rdma を優先します）。
• あらゆる種類の samples/、bindings/、または reference/ サブツリー。 「reference」と表示されていても、このスキルのツリー内にモックや不完全な成果物を置くと誤解を招きます。ユーザーはビルド可能なものとして受け取ってしまいます。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内であることを確認します。
2. 質問が RDMA で何を表現できるか（タスクの分類、リンク層とトランスポートタイプの選択、接続方法、権限、エラー、可観測性、安全性）に関する場合は、機能のコンパニオンを読みます。
3. 質問が 実行方法（設定、ビルド、変更、実行、テスト、デバッグ）に関する場合は、タスクのコンパニオンにある該当する H2 を読みます。ワークフローが機能や安全性に関する判断に依存する場合に限り、両方のコンパニオンを読みます。無条件に両方を読み込まないでください。

どちらのコンパニオンファイルも相互にリンクしており、適切な答えが「RDMA 固有のガイダンス」ではなく「公開ドキュメントまたはインストール済みパッケージのレイアウトを調べる」である場合は、doca-public-knowledge-map/SKILL.md にもリンクしています。

関連スキル

• doca-public-knowledge-map/SKILL.md — すべての公開 DOCA ドキュメントソースと、インストール済み DOCA パッケージのディスク上のレイアウトを示すルーティングテーブルです。このスキルと常に併用できます。
• doca-setup/SKILL.md — 環境の準備、インストールの確認、および公開 NGC DOCA コンテナを使う まだインストールしていない場合 の手順です。このスキルは、前提条件が満たされていることを想定しています。
• doca-programming-guide/SKILL.md — すべてのライブラリに共通する DOCA プログラミングパターンです。標準的な pkg-config + meson のビルドパターン、同梱サンプルを変更する汎用的な初回アプリケーションのワークフロー、汎用的なライフサイクル、ライブラリ横断の DOCA_ERROR_* 分類、プログラム側のデバッグ順序を扱います。このスキルでは、その上に RDMA 固有の内容を重ねます。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／ランタイム／プログラム／ドライバーを対象とする、横断的なデバッグ手順です。RDMA 固有のデバッグ（状態機械の遷移、権限エラー、接続コールバック）は、この手順に重ねて適用します。