doca-verbs

DOCA Verbs

例

• 「doca-verbs と doca-rdma のどちらを使うべきですか？」 — raw QP／CQ／WR／SRQ／Address-Handle 属性が指定されていない通常の RDMA データ転送は対象外です。doca-rdma/SKILL.md に案内してください。
• 「タスク API では公開されない raw QP 属性が必要です。」 — ここで対応します。公開されている doca_verbs.h のインターフェースのみを使用し、制限付きヘッダーを引用しないでください。

手順

## Loading order に従ってください。質問に合うコンパニオンのみを開いてください。

停止 — RDMA タスクのほとんどはここに該当しません

タスクが一般的な RDMA データ転送（エンドポイント間の send／receive／read／write／atomic）であり、ユーザーが上位レベルの API では表現できない raw QP／CQ／work-request／SRQ／Address-Handle 属性を指定していない場合、このスキルの対象外です。doca-rdma/SKILL.md に案内し、その境界を説明したら終了してください。doca-rdma のガイダンスを読み込んでいない限り、その実装 API を推測しないでください。概念用語（QP、CQ、接続、send、receive）は実装 API 名ではありません。

このスキルを読み込んでも、libibverbs／librdmacm を独自に実装してよいことには決してなりません。ldd に libdoca_rdma が表示されない一般的な RDMA 成果物は、タスク失敗です。これは doca-rdma/SKILL.md が定めるのと同じルールです。raw doca_verbs_* が対象となるのは、以下に示す限定的な属性レベルのニーズのみです。それ以外はすべて上位のレイヤーに戻してください。

開始地点： このスキルは、上位レベルの DOCA ライブラリの下にある raw-verbs の回避策です（doca-rdma/SKILL.md、doca-eth/SKILL.md、doca-rmax/SKILL.md）。 最初に、ユーザーが本当に低いレイヤーに移る必要があるか確認してください。ほとんどのユーザーにその必要はありません。ほぼ常に、**「上位レベルのライブラリを使い続けてください」**が正解です。verbs インターフェースが公開するものと libibverbs との境界については CAPABILITIES.md を開き、raw verbs が必要と確認できたら TASKS.md を開いてください。DOCA がインストールされていない場合は、まず doca-setup/SKILL.md に案内してください。

必ず確認する回答項目

対象範囲内の移植、ライフサイクル、デバッグに関する回答では、該当する以下の項目をすべて明示するまで、回答を完了としないでください。

1. doca_verbs_context は verbs インターフェースを所有する DOCA Core コンテキストです。doca_dev をラップし、進行エンジンと統合され、CAPABILITIES.md ## Capabilities and modes に記載されている per-object PD／MR／CQ／QP のライフサイクルを管理します。
2. 送信時には成功したものの、その後 DOCA_ERROR_IO_FAILED が発生した場合は、再試行やコード変更を勧める前に、送信の戻り値ではなく、完了キューエントリーのエラーフィールドに基づいて原因を診断します。
3. 完了処理の経路は、進行エンジン、手動 CQ ポーリング、完了チャネルによる通知のいずれか1つだけを選びます。
4. シンボルを提示する前に、両方のバージョン軸を明示します。pkg-config --modversion doca-verbs は doca_caps --version および pkg-config --modversion doca-common と整合している必要があります。また、doca_verbs_* ABI は EXPERIMENTAL ティアで提供されるため、シンボル名はリリース間で変更されたり、安定版に移行したりする可能性があります。インストール済みヘッダーはドキュメントより優先されます（doca-version/SKILL.md）。動詞に対するデバイスのサポートは、どちらのバージョンでもなく、doca_devinfo の機能クエリで確認します。
5. 既存の ibv_* ハンドルは置き換えてください。同一のハードウェアオブジェクト上で doca_verbs_* ハンドルと混在させてはいけません。

このスキルで判断すること

このスキルを読み込むすべての会話では、コードレベルの議論に入る前に、まず次の判断を行う必要があります。

1. ユーザーは、対応する上位レベルの DOCA ライブラリでは必要なセマンティクスを提供していないことを確認していますか？ いいえの場合は、該当するライブラリに戻します。一般的な RDMA については doca-rdma/SKILL.md、Ethernet TX / RX については doca-eth/SKILL.md、タイミング精度が求められるメディアについては doca-rmax/SKILL.md を参照してください。最もよくある失敗は、ユーザーが「verbs」や「QP」と言っただけで、上位レベルのインターフェースで対応できるかどうかを確認せずに、不要な raw verbs の使用を勧めてしまうことです。
2. 必要なセマンティクスは、上位レベルのライブラリでは提供されない特定の verb／opcode／WR フラグ／QP 属性／SRQ オプションですか？ 例：doca_rdma_task_* では表面化しない raw WR フラグ、進捗エンジンを超えるカスタム CQ 処理、特殊な QP 属性（path MTU、PSN、ECE）、明示的な SRQ 制御、輻輳制御グループ（doca_verbs_cc_group_*）のアタッチ、Address-Handle のチューニング（DGID／DLID／SL／SGID index／hop limit／traffic class／UDP source port）。該当する場合は対象範囲内です。
3. ユーザーは既存の libibverbs コードを DOCA Core モデルに移植していますか？ 対象範囲内です。その場合、エージェントは移植手順（ibv_* ハンドルを doca_verbs_* ハンドルに置き換える、doca_verbs_context_create 経由で統合する、CQ をポーリングする代わりに DOCA 進捗エンジンで完了処理を行う）を説明する必要があります。機械的な 1 対 1 の置き換えではありません。

（1）〜（3）のいずれにも当てはまらない場合、「doca-verbs を使うべきですか？」への答えはいいえです。対応する上位レベルのライブラリに戻してください。ユーザーに raw verbs を使わないよう勧める raw-verbs スキルは、適切に役割を果たしています。

対象読者

このスキルは、DOCA Verbs ライブラリを利用するアプリケーションを構築する外部開発者向けです。DOCA Core コンテキスト内で、raw QP／CQ／PD／MR／SRQ／Address-Handle／Ethernet-SQ／Ethernet-RQ を制御するために、doca_verbs_* を直接 C/C++ から、または FFI／バインディング経由で呼び出すコードが対象です。DOCA Verbs に貢献する NVIDIA の開発者向けではなく、一般的な DOCA RDMA／Eth／RMAX 作業の入り口でもありません。それらについては、対応する上位レベルのライブラリスキルを参照してください。

言語の対象範囲

DOCA Verbs は C ライブラリ（pkg-config モジュール doca-verbs）として提供されます。公開ヘッダーはインストールされた DOCA ツリー内にあります（$(pkg-config --variable=includedir doca-common)/doca_verbs.h と doca_verbs_*.h ファミリー）。doca-version/SKILL.md のヘッダー優先ルールに従い、これらがシンボルの正式な定義元です。TASKS.md が想定する標準的なケースは C／C++ です。他の言語では FFI を介して同じ *.so にアクセスします。このスキルでは言語に依存しないルールを維持しつつ、正式なインターフェースとして公開 C ABI を参照します。

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

対応する高レベルの DOCA ライブラリでは必要なセマンティクスが公開されていないことを、ユーザーが確認した後に限りこのスキルを読み込んでください。 具体的には、次のような場合です。

• ユーザーが 「この場合、doca-verbs に切り替える必要がありますか？」 と尋ねた場合です。 回答のために読み込みますが、ユーザーが高レベルライブラリで公開されていない動詞／オペコード／オプションを具体的に挙げられない限り、「いいえ、高レベルライブラリを使い続けてください」 と答えることを想定してください。
• ユーザーが、高レベルライブラリでは公開されていない特定の生の WR フラグ、QP オプション、SRQ 機能、カスタム CQ 処理パターン、または輻輳制御グループのアタッチメントを必要としている場合です。
• ユーザーが libibverbs のコードを DOCA Core モデルに移植しており、統合方法（ライフサイクル、進行エンジン、混在禁止）を必要としている場合です。
• doca_verbs_* 呼び出しから DOCA_ERROR_* が返され、診断が必要な場合です。これには IO_FAILED も含まれます。この場合、答えは送信時の戻り値ではなく、完了キューエントリーにあります。
• 境界、ライフサイクル、機能照会の規則を守る必要がある、Verbs C ABI をラップする非 C バインディングを設計する場合です。

次の場合は読み込まないでください。一般的な RDMA（doca-rdma/SKILL.md）、イーサネットのキューイング（doca-eth/SKILL.md）、タイミング精度が重要なメディア（doca-rmax/SKILL.md）、別の高レベルライブラリで対応できるケース（ステアリングには doca-flow/SKILL.md、NVMe-oF には storage-transport）、DOCA のインストール（doca-setup/SKILL.md）、または一般的な概要です。これらはすべて doca-public-knowledge-map/SKILL.md 経由で案内します。

このスキルで得られるもの

これは薄いローダーです。実質的な生の Verbs に関する資料は、次の 2 つの関連ファイルにあります。

• CAPABILITIES.md — このバージョンで doca-verbs が表現できる内容です。高レベルライブラリと Verbs の選択表、libibverbs との境界、Verbs のオブジェクトモデル（doca_verbs_context ＋ QP／CQ／PD／MR／SRQ／Address-Handle／Completion-Channel／Ethernet-SQ／Ethernet-RQ／CC-group）、機能照会のインターフェース（doca_verbs_query_device ＋ doca_verbs_device_attr_get_*）、エラーの分類（DOCA_ERROR_* へのマッピングと IO_FAILED → 完了エントリーのオーバーレイを含む）、可観測性のインターフェース（進行エンジンと手動 CQ ポーリング、コンパネルによる配信）、および libibverbs との混在禁止ルールを適用する安全ポリシーについて説明します。
• TASKS.md — 対象となる 6 つの Verbs ワークフローです。configure、build、modify、run、test、debug に加えて、Deferred task verbs ブロックがあります。すべてのワークフローで上記の切り替え判断が済んでいることを前提とし、## configure でその判断を再確認します。

このスキルは、DOCA がインストール済みであり、ユーザーがインストールプロファイルで想定されている権限を持っていることを前提とします（ホスト上の RDMA スタック。doca-rdma/SKILL.md と同様です）。DOCA のインストールは扱いません。doca-setup/SKILL.md に案内してください。

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

このスキルはエージェント向けガイダンスであり、サンプルやテンプレートのバンドルではありません。次のものは意図的に含めておらず、プルリクエストで追加すべきではありません。

• 言語を問わず、あらかじめ作成された DOCA Verbs アプリケーションのソースコード。 検証済みの Verbs ソースは、インストール環境に同梱されている C サンプルです（ls /opt/mellanox/doca/samples/ で確認できます）。エージェントはそこへ案内し、doca-programming-guide/SKILL.md のサンプルを変更するワークフローに従って、変更を最小限に抑える方法を指示します。これに、TASKS.md ## modify の Verbs 固有のオーバーライドを適用します。
• スキル内に置かれた、単独で使えるビルドマニフェスト（meson.build、CMakeLists.txt、Cargo.toml など）。エージェントは、インストール済みの DOCA を使用するユーザーのプロジェクト内でマニフェストを作成します。その際、pkg-config --modversion doca-verbs を信頼できる情報源とします。
• いかなる種類の samples/、bindings/、reference/ サブツリーも含みません。 「reference」と表示されたモック成果物は、ビルド可能なものと受け取られ、誤解を招きます。
• libibverbs から doca-verbs への移行スクリプト。 移植には判断が必要であり、機械的な置換ではありません。詳しくは TASKS.md ## modify を参照してください。

読み込み順序

1. 上記のドロップダウン式の判断フローをたどり、質問が対象範囲内であることを確認します。
2. 高レベルと動詞の切り分け、libibverbs の境界、オブジェクトモデル、機能の検出、エラー分類、可観測性、安全ポリシーについては、CAPABILITIES.md を参照してください。
3. 設定、ビルド、変更、実行、テスト、デバッグの手順を追ったワークフローについては、TASKS.md を参照してください。

どちらの関連ファイルからも、もう一方のファイルと、より高レベルのライブラリ（上位に戻るための参照先としての doca-rdma/SKILL.md、doca-eth/SKILL.md、doca-rmax/SKILL.md）、基盤となるプリミティブ doca_dev／doca_pe／doca_ctx を説明する doca-common/SKILL.md、標準的なバージョン規則を説明する doca-version/SKILL.md、そして「公開ドキュメントまたはインストール構成を調べる」が適切な答えとなる場合の doca-public-knowledge-map/SKILL.md へ相互リンクしています。

関連スキル

以下の手順で、まだ読み込まれていない別のスキルに案内された場合は、まずそのスキルを読んでください。利用できない場合は、そこで作業を中断し、そのスキル名と対象レイヤーを示してください。そのレイヤーについて、記憶に頼って作業を続けてはいけません。

• doca-rdma/SKILL.md — 標準的な高レベル RDMA ライブラリであり、このスキルがほとんどの RDMA ユーザーに戻る先です。RDMA に関する質問で doca-verbs を読み込む場合は、上位に戻るための回答をすぐに提示できるよう、doca-rdma も読み込んでください。
• doca-eth/SKILL.md — 高レベルの Ethernet キューライブラリです。doca-verbs は Ethernet SQ／RQ 動詞（doca_verbs_eth_sq_*、doca_verbs_eth_rq_*）も公開しています。必要なオプション（TS ソースタイプの調整、プレーンインデックスの固定、multi-pkt-send-WQE）が doca-eth にないことをユーザーが確認した後は、このスキルが引き継ぎます。
• doca-rmax/SKILL.md — タイミング精度が重要なメディア向けの高レベル Rivermax ライブラリです。ほとんどの Rivermax のケースはここで扱います。公開されていない Rivermax 動詞が必要となるまれなケースでは、raw verbs が代替手段になります。
• doca-common/SKILL.md — doca_verbs_context を含む、すべての DOCA コンテキストの基盤です。doca_dev／doca_pe／doca_ctx、doca_devinfo の機能照会ルール、ライフサイクルについて説明します。このスキルは、その上に verbs 固有の詳細を重ねます。
• doca-public-knowledge-map/SKILL.md — 公開 DOCA ドキュメントとインストール構成へのルーティング表です。DOCA Verbs の公開ガイドもここに記載されています。
• doca-setup/SKILL.md — 環境の準備、インストールの検証、および NGC DOCA コンテナーを使った「まだインストールされていない」場合の手順を扱います。このスキルは、前提条件が満たされていることを想定しています。
• doca-version/SKILL.md — DOCA の標準的なバージョン管理規則です。## Version compatibility では、4 つの要素の一致ルール（doca-verbs.pc を一致対象に追加）と、機能照会が実行時の基準となるルールへの相互リンクを提供します。
• doca-structured-tools-contract/SKILL.md — バンドル内での構造化ツールの優先順位ルール（検出／優先／フォールバック／報告）を扱います。TASKS.md のコマンド付録は、このルールに従います。
• doca-programming-guide/SKILL.md — すべてのライブラリで共通する、一般的な DOCA プログラミングパターンを扱います。pkg-config と meson によるビルド、出荷済みサンプルを変更して最初のアプリケーションを作る手順、共通のライフサイクル、DOCA_ERROR_* の分類、デバッグの順序について説明します。このスキルは、その上に raw verbs 固有の詳細を重ねます。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／実行時／プログラム／ドライバーをまたぐデバッグ手順を扱います。raw verbs のデバッグ（完了エントリーの検査、libibverbs との併用禁止、verbs 用語でのライフサイクル）は、その上に重ねて適用します。
• doca-hardware-safety/SKILL.md — このスキルの ## Safety policy が重ねて適用する、ハードウェア安全性に関する共通のメタポリシーです。