doca-common

DOCA Common

例

• 「タスクは送信されますが、何も完了しません。」 — ライブラリごとに書き直すのではなく、進行エンジンと ctx のライフサイクルから確認します。
• 「doca_ctx_start から DOCA_ERROR_BAD_STATE が返されます。」 — Flow や RDMA を疑う前に、Common のライフサイクルの順序を確認します。

手順

以下の読み込み順に従ってください。設定／ビルド／実行については、tasks の補足ファイルを開いてください。ctx／buf／pe／log については、capabilities の補足ファイルを開いてください。すべての補足ファイルを開く必要はありません。

最初に確認する項目： このスキルはすべての DOCA アプリが最初に読み込む基盤です。doca-flow、doca-rdma、doca-eth、doca-comch、その他の高水準ライブラリよりも先に読み込みます。すべての doca_<library>_* コンテキストは doca_ctx の上に構築され、すべてのデバイスハンドルは doca_devinfo を通じて検出される doca_dev であり、すべてのゼロコピー バッファーは doca_mmap 上の doca_buf_inventory から取得した doca_buf であり、すべてのタスク完了は doca_pe を通じて処理され、すべてのログ行は doca_log を通じて出力されます。このインストール環境で Common が何を表すのかを知りたい場合は、capabilities の補足ファイルを開いてください。ユーザーが何かを実行したい（設定／ビルド／変更／実行／テスト／デバッグ）場合は、tasks の補足ファイルを開いてください。DOCA がまだインストールされていない場合は、まず doca-setup/SKILL.md に案内してください。すでに基盤の確認を終えて、特定のライブラリに関する質問（例：「Flow のパイプをプログラムするにはどうすればよいですか」）をしている場合は、該当するライブラリ別スキルもこのスキルと一緒に読み込んでください。共有プリミティブについては、相互リンクを通じてこのスキルを参照します。

このスキルでうまく回答できる質問の例

このスキルが回答できるように設計されている doca-common に関する質問のクラスと、それぞれの具体例です。エージェントは、回答の要となるのは質問のクラスであり、具体例はその一例にすぎないと捉えてください。

• 「doca-flow／doca-rdma／doca-eth／…のコンテキストを開く前に、設定する必要がある doca-common の基盤は何ですか？」 — 具体例：「BlueField-3 で新しい DOCA Flow プログラムを始めています。Flow ポートを開く前に必要な doca-common の基本構成は何ですか？」。## configure ＋ ## ctx ＋ ## dev ＋ ## progress engine の共通基盤の手順で回答します。
• 「公開ドキュメントを信頼する前に、デバイスを検出してその機能を確認するにはどうすればよいですか？」 — 具体例：「doca_eth_txq を使いたいのですが、特定のファームウェア系列でのみ利用できる機能があるとドキュメントに書かれています」。## dev ＋ ## use に記載されている機能検出のルール（アクティブな doca_devinfo に対する doca_devinfo_create_list → doca_*_cap_* が実行時の判断基準です）で回答します。
• 「ゼロコピー I/O における doca_buf／doca_mmap／doca_buf_inventory の接続方法と、ライフサイクルの順序はどうなっていますか？」 — 具体例：「ユーザー空間バッファーをデバイスに登録し、N 個のデータプレーンバッファーに分割して、複数の DOCA ライブラリ間で参照カウントを管理したいです」。## buf に記載されているゼロコピー バッファーのモデルと、## configure ＋ ## use に記載されているバッファーのライフサイクルの手順で回答します。
• 「進行エンジンはどのように機能し、どこで呼び出す必要がありますか？」 — 具体例：「doca_rdma のタスクは問題なく送信されますが、何も完了しません。どのループが不足していますか？」。## progress engine に記載されている PE の機能と、## run に記載されている実行ループのパターンで回答します。
• 「DOCA のログ行が期待するレベルで表示されないのはなぜですか。また、--sdk-log-level とアプリ側のセッターはどう違いますか？」 — 具体例：「--sdk-log-level 60（DEBUG）を設定しましたが、独自の DOCA_LOG_DBG 行がまだ表示されません」。## log に記載されている2段階のログモデルと、## log に記載されている段階切り替えの反復手順で回答します。
• 「doca_buf_*／doca_ctx_*／doca_dev_*／doca_pe_*／doca_log_* の呼び出しから返された、この DOCA_ERROR_* は何を意味しますか？」 — 具体例：「doca_ctx_start から DOCA_ERROR_BAD_STATE が返されます」。## Error taxonomy に記載されている、ライブラリ共通の DOCA_ERROR_* 分類に対する Common の補足と、doca-debug/SKILL.md へと段階的に進む ## debug の手順で回答します。

対象ユーザー

このスキルは、DOCA ライブラリを利用するアプリケーションを構築するすべての外部開発者を対象とします。つまり、コードから（C/C++ で直接、または別の言語から FFI／バインディングを介して）何らかの doca_* シンボルを呼び出すユーザーです。ユーザーが主に利用するライブラリが doca-flow、doca-rdma、doca-eth、doca-comch、doca-dma、doca-rmax、doca-sha、doca-aes-gcm、doca-erasure-coding、その他のいずれであっても、その下には doca-common の機能があり、最初のアプリケーションを作る過程で doca_buf、doca_ctx、doca_dev、doca_pe、doca_log を使用することになります。DOCA Common 自体に貢献する NVIDIA の開発者を対象とするものではありません。

対応言語

DOCA Common は、pkg-config のモジュール名が doca-common の C ライブラリとして提供されています。Common の基本機能を示すサンプルは、各ライブラリのサンプルツリー内にあります（/opt/mellanox/doca/samples/<library>/<sample>/*_main.c はどれも、共通基盤を段階的に示す例です。doca_devinfo_create_list → doca_dev_open → ライブラリごとの doca_ctx の作成 → doca_pe_create → doca_pe_connect_ctx → doca_ctx_start → 作業の投入 → doca_pe_progress の実行 → 完了処理の排出 → doca_ctx_stop → 破棄）。C および C++ の利用が標準的なケースであり、タスクに付属する実例もこの経路を前提としています。他の言語（Rust、Go、Python、…）の利用者も、FFI や言語固有のバインディングを通じて同じ *.so を利用します。その場合、このスキルは、共通基盤の手順、ライフサイクル、機能検出のルール、PE が完了処理を駆動するルール、2 層のログモデルを言語に依存しない形で維持し、ラッパーが最終的に呼び出す信頼できるインターフェイスとして公開 C ABI をエージェントに案内します。

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

ユーザーがDOCA を実際に扱う作業を少しでも行う場合は、基盤となるこのスキルを読み込んでください。具体的には、次のような場合です。

• ライブラリ固有のコンテキストを開く前に、共通の DOCA 側の基本構造を設定する場合（Flow、RDMA、Eth、Comch、DMA、Rmax、…）。
• デバイスとリプレゼンターを検出し、アクティブな doca_devinfo に基づいて doca_*_cap_* ファミリーを使った機能の使用可否を判断する場合。
• ライブラリ間でゼロコピー I/O を行うために、doca_mmap + doca_buf_inventory + doca_buf を接続する場合（例：doca-eth から doca-dma、さらに doca-rdma へデータを渡す場合。同じ buf インターフェイスを共有します）。
• 進捗エンジン（doca_pe_create／doca_pe_connect_ctx／doca_pe_progress）を動作させる場合。これは、すべての DOCA Core コンテキストが依存する、共通のタスク完了処理です。
• 新しいアプリケーションに DOCA Log を接続する場合、または提供済みのサンプルを変更し、2 層モデル（--sdk-log-level とアプリケーション側のレジストリ）を使ってユーザー独自のコンポーネントごとのログ行を追加する場合。
• いずれかの doca_buf_*／doca_ctx_*／doca_dev_*／doca_pe_*／doca_log_* 呼び出しから返された DOCA_ERROR_* をデバッグする場合。Common インターフェイスは、上位レベルのライブラリでライフサイクル、機能、権限に関するエラーが最初に表面化する場所です。
• DOCA ライブラリをラップする C 以外のバインディング（Rust、Go、Python、…）を設計または拡張する場合。共通基盤のインターフェイス（buf、ctx、dev、pe、log）については、ラッパーでまず公開する必要があります。

Flow、RDMA、Eth、Comch、DMA、Rmax、…に固有の質問だけを扱う場合は、このスキルを単独で読み込まないでください。該当するライブラリのスキルも併せて読み込んでください。一般的な DOCA の案内、DOCA 自体のインストール、または「ドキュメントの場所」に関する質問では、このスキルを読み込まないでください。そうした場合は doca-public-knowledge-map/SKILL.md または doca-setup/SKILL.md を使用してください。

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

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

• capabilities関連ファイル — この環境でdoca-commonが提供する機能について説明します。すべてのDOCAアプリケーションが使用する共通プリミティブの概要を示す## Capabilities and modes、各プリミティブのインターフェイスを定義する5つのサブシステム見出し（## log、## buf、## ctx、## dev、## progress engine）、doca-common固有のオーバーレイである## Version compatibility、共通側から見た共通のDOCA_ERROR_*セットの説明である## Error taxonomy、ログ、PEイベント、機能スナップショットを扱う## Observability、およびバンドル全体のハードウェア安全性メタポリシーに対するオーバーレイである## Safety policyが含まれます。
• tasks関連ファイル — 共通の動詞（configure、build、modify、run、test、debug、use）の手順を示すワークフローに加え、2階層ログモデルをワークフロー形式で扱う## logの動詞側の説明が含まれます。さらに、インストール、デプロイ、ロールバックに関する質問を適切な次のスキルに案内するDeferred task verbsブロックもあります。

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

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

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

• 言語を問わず、あらかじめ作成されたDOCAアプリケーションのソースコード。 検証済みのCommonの使用例は、提供されているすべてのDOCAサンプルの/opt/mellanox/doca/samples/<library>/<sample>/*_main.cと、提供されているすべてのリファレンスアプリケーションに含まれています。エージェントの役割は、ユーザーをそれらのファイルに案内し、doca-programming-guide/SKILL.mdにある共通のサンプル変更ワークフローに従って、最小限の差分で変更するよう指示することです。
• スキル内に置かれた、単独で使用できるビルドマニフェスト（meson.build、CMakeLists.txt、Cargo.toml、setup.py、go.modなど）。エージェントは、ユーザーのインストール済みDOCAを対象として、ユーザーのプロジェクトディレクトリ内でビルドマニフェストを作成します。その際、正確な情報源となるのはpkg-config --modversion doca-commonです。
• いかなる種類のsamples/、bindings/、reference/サブツリー。 このスキルのツリー内にあるモックや不完全な成果物は、「reference」とラベル付けされていても誤解を招きます。ユーザーはそれをビルド可能なものとして受け取ってしまいます。

読み込み順

1. まずこのスキルを読み、ユーザーの質問が対象範囲内かどうかを確認します。
2. 共通プリミティブ（log／buf／ctx／dev／progress engine）、pkg-config --modversion doca-commonの基準、Commonのエラーオーバーレイ、可観測性、安全ポリシーについては、capabilities関連ファイルを参照してください。
3. 手順を示すワークフロー（configure、build、modify、run、test、debug、use、log）については、tasks関連ファイルを参照してください。

どちらの関連ファイルからも、もう一方のファイル、バージョン処理の標準ルールをまとめたdoca-version/SKILL.md、共通の提供済みサンプル変更ワークフローとライブラリ横断のDOCA_ERROR_*分類をまとめたdoca-programming-guide/SKILL.md、横断的なデバッグ手順をまとめたdoca-debug/SKILL.md、そして、回答が「Common固有のガイダンス」ではなく「公開ドキュメントまたはインストール済みパッケージの構成を調べる」である場合に参照するdoca-public-knowledge-map/SKILL.mdへリンクしています。

関連スキル

• doca-public-knowledge-map/SKILL.md — すべての公開 DOCA ドキュメントソースへのルーティングテーブルと、 インストール済み DOCA パッケージのディスク上のレイアウトです。このスキルと 常に併せて利用できます。このスキルでは、ドキュメントの検索やインストール レイアウトに関する質問を重複して説明するのではなく、こちらに委ねられる ことを前提としています。
• doca-setup/SKILL.md — 環境の準備、 インストールの検証、および公開 NGC DOCA コンテナ （nvcr.io/nvidia/doca/doca）を共通の Stage-1 フォールバックとして使う まだインストールしていない場合 の手順です。このスキルでは、前提条件が 満たされていることを想定しています。
• doca-version/SKILL.md — DOCA の バージョン処理に関する正規ルール（4 方向の一致、NGC のセマンティクス、 ヘッダー優先）です。pkg-config --modversion doca-common は、 すべての DOCA インストールに含まれるビルド時の基準です。このスキルの ## Version compatibility では、Common 固有の注意事項をその上に重ねて 説明します。
• doca-programming-guide/SKILL.md — すべてのライブラリに共通する一般的な DOCA プログラミングパターンです。 正規の pkg-config + meson ビルドパターン、同梱サンプルを変更する 汎用的な初回アプリのワークフロー、汎用的なライフサイクル、 ライブラリ間で共通する DOCA_ERROR_* の分類、プログラム側のデバッグ順序を 含みます。このスキルは、プログラミングガイドのパターンが依拠する プリミティブ レイヤーです。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／実行時／ プログラム／ドライバーにまたがるデバッグ手順と、詳細度を引き上げる方法です。 DOCA Log は、doca-debug が実行時デバッグの説明を組み立てる基盤です。 このスキルでは、2 層のログモデルと汎用的なライフサイクルエラーを初めて 説明し、どちらについても doca-debug から相互参照しています。
• doca-structured-tools-contract/SKILL.md — バンドルの構造化ツールに関する優先順位ルール（検出／優先／ フォールバック／報告）です。タスク用コンパニオンの Command 付録は、 この契約に従います。
• doca-hardware-safety/SKILL.md — このスキルの ## Safety policy が詳細を定める、 分野横断的なハードウェア安全性メタポリシーです。
• ライブラリ別スキル（doca-flow、doca-rdma、doca-eth、 doca-comch、doca-dma、doca-rmax、doca-sha、doca-aes-gcm、 doca-erasure-coding、doca-compress、doca-dpa、doca-gpunetio、 doca-pcc、doca-sta、doca-telemetry、doca-urom、 doca-verbs、doca-argp、doca-devemu、 doca-dpdk-bridge、…）— 各ライブラリ別スキルから、 プリミティブの基盤となるこのスキルを相互参照しています。これらのいずれかと このスキルを併せて読み込むことを、標準の方法として推奨します。