doca-programming-guide

DOCA プログラミングガイド

例

• 「初めての DOCA プログラムはどう書けばよいですか？」 — 提供されているサンプルをコピーし、 変更ワークフローに従ってから、標準の pkg-config + meson ビルドを実行します。Docker / NGC でコンパイルとリンクはできますが、実行時には実機の BlueField または ConnectX が必要です。
• 「すべての DOCA オブジェクトがたどるライフサイクルは何ですか？」 — 作成 → 設定 → 開始 → 接続 → 使用 → 停止 → 破棄です。設定は開始前に 完了させます。

手順

以下の読み込み順に従ってください。手順についてはタスク用コンパニオンを、網羅範囲については機能用コンパニオンを開いてください。コンパニオンファイルをすべて開く必要はありません。

最初に読む場所： ## Audience を読んで、ユーザーが DOCA に 貢献する のではなく、DOCA を 利用する ことを確認してください。次に、動詞に合った H2 に進んでください（初めてのアプリを基にした開発なら ## modify、標準ビルドパターンなら ## build、テストの反復なら ## test、プログラムの種類に応じたデバッグ手順なら ## debug）。Docker / NGC はビルド側であり、実行側ではありません。 NGC コンテナではコンパイルとリンクができます。フローパイプの作成、RDMA QP 操作、およびポート上の doca_dev を必要とする呼び出しには、実機の BlueField または ConnectX が必要です。アプリ全体が docker 内で動作すると約束しないでください。

このスキルが得意とする質問の例

このスキルは、プログラムクラスに関する質問のうち、以下のクラスに対応するよう設計されています。それぞれに実例を示しています。ライブラリ固有のオーバーレイ（Flow／DMS／Caps／…）は対応するライブラリスキルにあり、このスキルではライブラリに依存しない部分に対応します。

• 「<任意のライブラリ>向けの最初の DOCA プログラムはどう書けばよいですか？」 — 実例：「docker はあります。最初の DOCA Flow アプリの作成を手伝ってください。」 ## modify の 提供済みサンプルを変更するワークフローと、## build の標準的なビルド パターンで回答します。docker ／ NGC でビルドとリンクはできますが、実行時には実機の NIC または DPU が必要であることも説明します。
• 「どの DOCA ライブラリでも適切なビルドコマンドは何ですか？」 — 実例：「doca_rdma_* を呼び出すプログラムをコンパイルするにはどうすればよいですか？」

  build の pkg-config doca-<library> パターン

  （C/C++ Track 1）と、Track 2 の FFI／バインディングパターンで回答します。
• 「すべての DOCA オブジェクトがたどるライフサイクルは何ですか？」 — 実例：「プログラム内で doca_flow_pipe_* を呼び出す適切な順序は何ですか？」 Core の create → configure → start → connect → use → stop → destroy の順序で回答します。## Capabilities and modes の （cfg-create ／ init は configure を実行し、start より前に完了します）。
• 「DOCA_ERROR_* が返されました。これは何を意味し、どうすればよいですか？」 — 実例：「コードで DOCA_ERROR_BAD_STATE が発生しました。」 ## Error taxonomy の、ライブラリ間で共通する doca_error_get_descr() のルールと、

  debug のプログラムクラス別デバッグ手順で回答します。

• 「プログラムはビルドされて起動しましたが、ワイヤ上で何も起きません。」 — 実例：「Flow プログラムは問題なく実行されますが、トラフィックが マッチしません。」 ## Safety policy の検証してからコミットするルールと、

  debug の多層的なプログラムクラス別デバッグ手順で回答します。

• 「DOCA を利用する<言語>のコード（FFI ／ バインディング）はどのようなものですか？」 — 実例：「C を 書かずに Rust から DOCA Comch を呼び出すにはどうすればよいですか？」 ## build の Track 2（公開 C ABI を介した FFI）と、## Capabilities and modes の言語に依存しないライフサイクルで回答します。
• 「提供されている DOCA サンプルとアプリケーションをすべて分類してビルドするにはどうすればよいですか？サンプルと アプリケーションの違いは何ですか？」 — 実例：「すべての DOCA アプリを ビルドしようとしたところ、20/159 が失敗しました。実際の リグレッションと、オプションのスタックがないことによる失敗を見分けるにはどうすればよいですか？」 ## sample-and-app-categorization のサンプルとアプリケーションのモデル、およびカテゴリ／依存関係／スキップと失敗の分類で回答します。これにより、*「SDK が壊れている」場合と、「この BlueField にオプションの GPU ／ RMAX ／ MPI スタックがない」*場合を区別できます。

質問が環境クラス（インストール／ビルド環境／hugepages ／ デバイス）に関する場合は、doca-setup/SKILL.md に案内してください。ライブラリ固有の質問（Flow のパイプトポロジー、RDMA QP のセットアップ、DMS サービスのデプロイ）であれば、対応するライブラリスキルを重ねて使用してください。

対象読者

このスキルの対象は、DOCA ライブラリを利用するアプリケーションを構築する外部開発者です。つまり、doca_<library>_* シンボルを1つ以上（C/C++で直接、または別の言語からFFI／バインディングを介して）呼び出すコードを開発するユーザーです。これはDOCAを利用してプログラミングすることであり、DOCAそのものをプログラミングすることではありません。DOCA自体に貢献するNVIDIAの開発者向けではなく、DOCAのソースツリーやNVIDIA内部のツール、非公開情報へのアクセスも前提としません。このスキルがエージェントに案内するのは、すべての外部ユーザーが利用できる情報源のみです。すなわち、公開ドキュメントのdocs.nvidia.com/doca/sdk/、公開カタログのcatalog.ngc.nvidia.com、github.com/NVIDIA／github.com/NVIDIA-DOCA配下の公開GitHubリポジトリ、公開開発者フォーラム、そして公開DOCAインストール（または公開NGC DOCAコンテナnvcr.io/nvidia/doca/doca）によってユーザーのホストに配置されるオンディスクの/opt/mellanox/docaツリーです。入手先やインストール方法に関する質問は別の場所に案内します。以下の関連スキル*を参照してください。

言語の対象範囲。 DOCA自体はCライブラリ群です。/opt/mellanox/doca/samples/に含まれるすべてのサンプルと、/opt/mellanox/doca/applications/に含まれるすべてのリファレンスアプリケーションはCで書かれています。このスキルで規範的なワークフローを示す際の標準的な対象は、CおよびC++の利用者です。それ以外の言語の利用者（Rust、Go、Pythonなど）は、FFIまたは言語固有のバインディングを介して、公開C ABIに基づき同じ*.soライブラリを利用します。このスキルでは、ライフサイクル、機能、エラー、オブザーバビリティ、安全性に関するガイダンスは言語に依存しない形で示し、言語固有のビルド／FFI作業についてはラッパーを作成せず、利用者自身のツールチェーンに委ねます。

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

ユーザーが DOCA をインストール済みで、環境クラスの前提条件もすでに満たしている場合（つまり、doca-setup/SKILL.md によって、pkg-config doca-<library> で解決でき、hugepages がマウントされ、デバイスが認識される正常なインストール環境が構築されている場合）に、このスキルを読み込みます。そのうえで、ユーザーがライブラリに依存しない方法で DOCA を使った実際のプログラミング方法について質問している場合に適用します。

• DOCA の構成要素（ライブラリ、アプリ、サービス、ツール）と、それらが通信経路のどちら側で動作するかを理解する。
• 使用するライブラリを問わず、すべての DOCA アプリケーションが従う標準的な pkg-config ＋ meson のビルドパターン。
• 同梱サンプルからカスタムの初めてのアプリケーションを派生させる、すべてのライブラリスキルがライブラリ固有のオーバーライドで拡張する共通のワークフロー。これは環境に関する動詞ではなく、プログラミングに関する動詞であるため、doca-setup からここに移されました。
• 共通の DOCA Core のライフサイクル（create → configure (including permissions and task set_conf) → start → connect → use → stop → destroy）と、それがライブラリごとにどのように現れるか。doca_ctx_start() を呼び出す前に、設定を必ず完了させてください。接続は開始後の独立した手順です。connect/use をひとまとまりのトークンとして記述しないでください。
• 一般的な DOCA_ERROR_* パターン、doca_error_t、doca_error_get_descr()。これはライブラリ間で共通する形式であり、Flow 固有または RDMA 固有の追加情報は含みません。
• 検証してから確定するルールと、すべてのライブラリスキルが継承するプログラム側の安全ポリシー。
• あらゆる言語の利用者に適用されるプログラミングパターン（C/C++ での直接利用、Rust / Go / Python / …向けの FFI / バインディング）。このスキルでは言語に依存しないパターンを維持し、エージェントには正式な API として公開 C ABI を参照するよう案内します。

次の場合には、このスキルを読み込まないでください。

• 「インストールは正常ですか？なぜ pkg-config で doca-flow が見つからないのですか？hugepages をマウントするにはどうすればよいですか？まだ DOCA をインストールしていませんが、コンテナーを使えますか？」 — 環境クラスの質問は doca-setup/SKILL.md の担当です。このスキルではインストールの検証、環境の準備、環境クラスのデバッグ、および DOCA がない macOS、Windows、Linux のユーザー向けの 未インストール時の NGC コンテナーへのフォールバックを扱います。
• 「DOCA とは何ですか？Flow プログラミングガイドはどこにありますか？どのパッケージをインストールすればよいですか？」 — 案内や概要に関する質問は doca-public-knowledge-map/SKILL.md の担当です。
• 「Flow パイプを構築するにはどうすればよいですか？RDMA キューを設定するには？Comch を使ってメッセージを送信するには？」 — ライブラリ内部 API に関する質問は、該当するライブラリスキル（例：doca-flow/SKILL.md）の担当です。

このスキルの内容

これは薄いローダーです。本体には、次に参照するファイルを選ぶために必要な概要のみを残しています。実質的な内容は、次の 2 つの関連ファイルに記載されています。

• 機能に関する関連ファイル — 抽象的な観点で、すべての DOCA プログラムに共通する内容を説明します。DOCA の構成（ホスト / DPU / スイッチ、ライブラリ / アプリ / サービス / ツール、ビルド形式を選択する理由）、共通のプログラムライフサイクル、DOCA をリンクするあらゆるプログラムに適用される統一バージョン互換性ルール、ライブラリ間で共通する DOCA_ERROR_* の分類、プログラム側の可観測性機能（DOCA ロギング、機能スナップショット）、およびすべてのライブラリスキルが継承するプログラム側の安全ポリシーを扱います。
• タスクに関する関連ファイル — 対象となる 6 つのプログラミング動詞（configure、build、modify、run、test、debug）について、段階的なワークフローを説明します。## modify の動詞では、同梱サンプルからカスタムアプリを作成する共通パターンを扱います。このパターンは、すべての DOCA ライブラリスキルがライブラリ固有のオーバーライドで拡張します。## build の動詞では、2 つの言語トラック（C/C++ による直接利用、FFI を使う非 C 言語）で、標準的な pkg-config doca-<library> ビルドパターンを扱います。

このスキルでは、doca-setup/SKILL.md によって正常なインストール環境がすでに構築されていることを前提とします。環境の準備は扱いません。それは doca-setup の担当であり、DOCA がない macOS、Windows、Linux のユーザー向けの 未インストール時に NGC コンテナー（nvcr.io/nvidia/doca/doca）へフォールバックする方法も含まれます。

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

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

• **言語を問わず、あらかじめ作成された DOCA アプリケーションのソースコード。**これには、C / C++ ファイル、Rust クレート、Go パッケージ、Python モジュール、およびその他の言語用のラッパーコードが含まれます。DOCA API の仕様はリリースごとに変化します。また、ドキュメントの説明文をもとに書かれたコードは、実際のインストール環境で稼働中のライブラリに対してコンパイル／リンク／FFI 読み込みを行わない限り、検証できません。検証済みの DOCA アプリケーションのソースコードは、ユーザーがインストールしたシステムに含まれる C サンプルです。エージェントの役割は、ユーザーをそのファイルに案内し、最小限の差分で変更する方法（## modify）を指示すること（C/C++ ユーザーの場合）、または非 C ユーザーを、バインディングが呼び出す公開 C ABI の仕様（## build Track 2）に案内することであり、ラッパーを作成することではありません。
• 独立したビルドマニフェスト（meson.build、CMakeLists.txt、Cargo.toml、setup.py、go.mod、…）をスキル内に置くこと。エージェントは、ユーザーがインストールした DOCA を対象として、ユーザーのプロジェクトディレクトリ内にビルドマニフェストを作成します。その際、pkg-config --modversion doca-<library> を信頼できる情報源とします。
• **種類を問わず、samples/、bindings/、reference/ のサブツリー。**このスキルのツリー内にあるモックや不完全な成果物は、たとえ「reference」と表示されていても、ユーザーにビルド可能だと誤解させます。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問がプログラミングに関する質問であること（環境、ルーティング、ライブラリ API に関する質問ではないこと）を確認します。
2. DOCA の構造、共通のライフサイクル、ライブラリ横断のエラー分類、プログラム側の可観測性の仕様、およびすべてのライブラリスキルが継承する安全性ポリシーについては、capabilities コンパニオンを参照してください。
3. プログラミングの手順（configure、build、modify、run、test、debug）については、tasks コンパニオンを参照してください。

特定のライブラリで最初のアプリを作りたいという質問の場合は、まず共通のコピーして編集するパターンについて ## modify を説明し、その後、ライブラリ固有の置き換え値を確認するために、該当するライブラリスキル（例：doca-flow/SKILL.md）を案内してください。

関連スキル

• doca-public-knowledge-map/SKILL.md — 公開 DOCA ドキュメントへの案内と、インストール済み DOCA パッケージのディスク上のレイアウトについて説明します。このスキルは、「X はどこに記載されていますか」、「Y はディスク上のどこにありますか」、*「インストール済みのバージョンを確認するにはどうすればよいですか」*という質問をすべて knowledge-map に委ねます。
• doca-setup/SKILL.md — 環境の準備、インストールの検証、環境クラスに関するデバッグ、および macOS、Windows、Linux のいずれを使用していても、まだ DOCA をインストールしていないユーザー向けの、NGC コンテナ（nvcr.io/nvidia/doca/doca）を汎用の Stage-1 フォールバックとする手順。このスキルでは、doca-setup の前提条件がすでに満たされているものとします。
• doca-flow/SKILL.md — BlueField 上の DOCA Flow。このスキルの ## modify（最初のアプリを作成する共通の手順）を拡張し、Flow 固有の置き換え対象フィールドを示します。
• doca-container-deployment/SKILL.md — すでにビルドできるアプリケーションの出荷について説明します。コンテナマニフェスト、ロールアウト、サービス準備状態の検証が含まれます。このスキルの対象は、プログラムがローカルでコンパイルされ、実行できるようになるまでです。デプロイについては扱いません。