doca-comch

DOCA Comch

例

• 「PCIe 経由でホストから BlueField に制御メッセージを送信する。」 — これは対象範囲内です。サーバー（DPU）とクライアント（ホスト）の役割を選び、 Comch の送受信経路を使い続けてください。TCP にフォールバックしないでください。
• 「接続コールバックが一度も呼び出されません。」 — アプリを生の verbs に 書き換える前に、役割、representor の可視性、2.5 のリネームオーバーレイを 確認してください。

手順

以下の読み込み順に従ってください。設定／変更／デバッグについてはタスク用 コンパニオンファイルを開いてください。スローパスとファストパス、および 2.5 の リネームについては機能用コンパニオンファイルを開いてください。すべての コンパニオンファイルを開く必要はありません。

最初に確認すること： このスキルは、DOCA がすでにインストールされており、 ユーザーが DOCA を使って BlueField とホストのペアでComch を実際に操作している ことを前提としています。ユーザーが何かを実行（設定／ビルド／変更／実行／テスト／デバッグ） したい場合はタスク用コンパニオンファイルを開いてください。このバージョンで Comch が何を表現できるかについて質問している場合は、機能用コンパニオンファイルを 開いてください。まだ DOCA をインストールしていない場合は、まず doca-setup/SKILL.md に誘導してください。読んだドキュメントに doca-comm-channel と記載されているため、ユーザーが「この DOCA に Comch は あるのか」と尋ねている場合は、2.5 のリネームについて

バージョン互換性

に誘導してください。

このスキルが的確に回答できる質問の例

このスキルが回答するように設計されている Comch の質問のクラスと、それぞれの 具体例を示します。エージェントは、具体例は一例に過ぎず、重要なのはクラスで あると捉えてください。

• 「ホストと DPU の間で Comch チャネルを立ち上げるにはどうすればよいですか？」 — 具体例：「DPU 側をサーバー、ホスト側をクライアントにして、最初の制御メッセージを 交換する」。回答は、## 設定 +

  機能とモード

  にあるサーバーとクライアントの比較表に記載された、役割選択とライフサイクルの ワークフローで説明されています。
• 「CPU 負荷を抑えて Comch 経由で大量のデータを転送するにはどうすればよいですか？」 — 具体例：「ホストドライバーから DPU エージェントへ、100 µs ごとに 64 KiB の チャンクをストリーミングする」。回答は、

  機能とモード

  に記載されたプロデューサー／コンシューマーのファストパスと、

  設定

  のステップ 4 にあるチャネル設定ワークフローで説明されています。選択ルールは *「スローパスとファストパス」*です。
• 「送信できるメッセージの最大サイズはいくつですか？」 — 具体例： 「4 MiB の制御メッセージを一度に送信できますか？」。 回答は、

  機能とモード

  にある機能クエリのルール（doca_comch_cap_get_max_msg_size）と、

  変更

  にあるプロパティ設定ワークフローで説明されています。
• 「DPU 側で representor が見えないのはなぜですか？」 — 具体例： 「イメージを適用したばかりの BlueField で、doca_comch_server_create が DOCA_ERROR_NOT_PERMITTED を返す」。 回答は、

  安全ポリシー

  にある representor と権限のオーバーレイ、および

  設定 のステップ 1 にある環境準備チェックリストで説明されています。

  representor 側の環境に関する質問は doca-setup/SKILL.md に誘導されます。
• 「この Comch 機能は、インストール済みの DOCA バージョンで使えますか？」 — 具体例：「doca_comch_producer は DOCA 2.6.0 にありますか。それとも、まだ 古いスローパス API が必要ですか？」。回答は、

  バージョン互換性

  にあるバージョン互換性のオーバーレイで説明されています。ここでは、 doca-version/SKILL.md にある正規の検出手順への相互リンクに加えて、Comch 固有の 2.5 リネームルールを示しています。
• 「Comch の呼び出しで発生したこの DOCA_ERROR_* は何を意味し、どのレイヤーが 原因ですか？」 — 具体例：「doca_task_submit 経由で doca_comch_task_send を送信した際の DOCA_ERROR_AGAIN」。回答は、

  エラー分類

  にあるライブラリー横断のエラー分類に対する Comch オーバーレイと、 doca-debug/SKILL.md へのエスカレーションを示す

  デバッグ

  の段階的な手順で説明されています。

対象読者

このスキルは、DOCA Comch ライブラリを利用するアプリケーションを開発する外部の開発者を対象とします。つまり、PCIe 経由でホストプロセスと BlueField エージェント間の制御メッセージまたはデータメッセージをやり取りするために、doca_comch_* を呼び出すコードを記述するユーザーです（C/C++ から直接呼び出す場合や、別の言語から FFI／バインディング経由で呼び出す場合を含みます）。DOCA Comch 自体に貢献する NVIDIA の開発者向けではありません。

言語の範囲。 DOCA Comch は、pkg-config のモジュール名が doca-comch の C ライブラリとして提供されています。付属のサンプルは C で記述されています。C と C++ の利用者が標準的なケースであり、タスク用コンパニオンの実例もこの経路を前提としています。他の言語の利用者（Rust、Go、Python など）は、FFI または言語固有のバインディングを介して同じ *.so を利用します。その場合、このスキルでは、役割分担、ライフサイクル、機能の検出、権限、エラー分類に関するガイダンスを言語に依存しない形で維持し、最終的にあらゆるラッパーが呼び出す権威あるインターフェースとして、エージェントを公開 C ABI へ案内します。

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

ユーザーが言語を問わず DOCA Comch の実作業を行っている場合に、このスキルを読み込みます。具体的には、次のような場合です。

• DPU 側で doca_comch_server を、またはホスト側で doca_comch_client を、ホストから到達可能な representor または PCIe アドレス上に初期化する場合。
• doca_ctx_start() の前に、少なくとも次のいずれかを設定する場合：低速パスのメッセージ用 recv コールバック、高速パスの送信用 producer、高速パスの受信用 consumer。
• doca_comch_set_* および doca_comch_cap_get_* を介して comch のプロパティを読み取る、または設定する場合（最大メッセージサイズ、最大クライアント数（サーバー側）、producer／consumer のキューサイズなど）。
• 2 つの側の間に接続を確立し、開始前に登録した接続コールバックを介して接続状態の遷移に対応する場合。
• 低速パス（send-task／recv-callback、メッセージ指向、スループットは低め、単一呼び出しで簡潔）と、高速パス（producer／consumer、非同期、はるかに高いスループット、2 コンテキストのセットアップ）のどちらを使うか選択する場合。
• Comch の呼び出しから返された DOCA_ERROR_* をデバッグする場合（ライフサイクル、権限、機能、would-block のいずれか）や、ホスト／DPU 間の接続ステートマシンをデバッグする場合。
• Comch C ABI をラップする、C 以外のバインディング（Rust、Go、Python など）を設計または拡張する場合。ライフサイクル、役割分担、権限、機能に関するルールをラッパーが守るための情報を提供します。

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

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

これは簡易ローダーです。本体には、次に読むファイルを選ぶために必要な概要だけを記載しています。Comch 固有の詳細は、次の 2 つのコンパニオンファイルに記載されています。

• 機能コンパニオン — このバージョンで Comch が提供できるもの：サーバーとクライアントの役割分担、低速パスの send-task／recv-callback インターフェース、高速パスの producer／consumer インターフェース、機能照会インターフェース（doca_comch_cap_get_*）、Comch のエラー分類（ライブラリ間で共通の DOCA_ERROR_* セットへのマッピング）、可観測性インターフェース（接続状態コールバック、タスク完了コールバック）、および representor と権限に関する判断を制御する安全ポリシー。
• タスクコンパニオン — 対象範囲内の Comch の 6 つの動詞（configure、build、modify、run、test、debug）に関する、手順ごとのワークフロー。さらに、対象範囲外の質問を適切な次のスキルへ案内する Deferred task verbs ブロックもあります。

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

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

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

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

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内であることを確認します。
2. Comch の機能マトリックス、役割分担、スローパス／ ファストパスのインターフェース、権限ポリシー、エラー分類、 オブザーバビリティ、安全性ポリシーについては、機能の補足ドキュメントを参照してください。
3. 設定、ビルド、変更、実行、 テスト、デバッグの手順については、タスクの補足ドキュメントを参照してください。

両方の補足ファイルは相互にリンクしているほか、 バージョン処理の正式なルールについては doca-version/SKILL.md に、 「Comch 固有のガイダンス」ではなく「公開ドキュメントまたは インストール済みパッケージのレイアウトを調べる」のが適切な場合については doca-public-knowledge-map/SKILL.md にリンクしています。

関連スキル

• doca-public-knowledge-map/SKILL.md — すべての公開 DOCA ドキュメントソースと、インストール済み DOCA パッケージの ディスク上のレイアウトを示すルーティングテーブルです。Comch の URL スラッグは doca-comm-channel ではなく DOCA-Comch（DOCA 2.5 以降）です。
• doca-setup/SKILL.md — 環境の準備、 インストールの検証、representor の可視性チェック、および公開 NGC DOCA コンテナーを使った まだ何もインストールしていない場合の手順です。 このスキルでは、前提条件が満たされているものとします。
• doca-version/SKILL.md — DOCA バージョン処理の正式な ルールです。このスキルの ## Version compatibility では、4 項目の一致ルールへの相互リンクに加えて、Comch 固有の 2.5 の名称変更に関する補足を追加しています。
• doca-structured-tools-contract/SKILL.md — バンドルの構造化ツールの優先順位ルール（検出／優先／ フォールバック／報告）です。タスクの補足ドキュメントのコマンド付録は、 この契約に従います。
• doca-programming-guide/SKILL.md — すべてのライブラリで共有する DOCA プログラミングの一般的なパターンです。正式な pkg-config と meson のビルドパターン、同梱サンプルを変更する共通の初回アプリケーションワークフロー、共通のライフサイクル、ライブラリ横断の DOCA_ERROR_* エラー分類、およびプログラム側のデバッグ順序が含まれます。このスキルでは、その上に Comch 固有の内容を重ねます。
• doca-debug/SKILL.md — ライブラリ横断の デバッグ手順（インストール／バージョン／ビルド／リンク／実行時／ プログラム／ドライバー）です。Comch 固有のデバッグ（ライフサイクル違反、representor の可視性、スローパスとファストパスそれぞれのキュー満杯時の症状）は、この手順に重ねて適用します。