doca-urom

DOCA UROM

例

• 「BlueField に UCX トラフィックを送る。」 — これは対象範囲内です。ホスト側の doca-urom を使用してください。ここでは DPU 側の UROM Service をデプロイしないでください。
• 「最初の doca_urom 呼び出しが NOT_PERMITTED を返す。」 — まず、ホストとサービスのバージョンが一致しているか、RDMA 基盤に問題がないかを確認してください。

手順

以下の読み込み順に従ってください。設定／オフロード／デバッグを行う場合はタスク用の補足ファイルを開いてください。サービスとワーカーのコンテキストについては、機能用の補足ファイルを開いてください。補足ファイルをすべて開く必要はありません。

最初に確認すること： このスキルは、ホストと BlueField の両方に DOCA がインストールされ、DOCA UROM Service が BlueField にデプロイされて実行中であり、ユーザーがホスト側で UROM を実際に操作していることを前提としています。つまり、HPC／UCX／MPI スタックから doca-urom を使用して、ホストに代わって DPU が実行するリモートメモリー操作（put、get、atomic、アクティブメッセージ、collective）をキューに追加している状況です。何かを実行する（設定／ビルド／変更／実行／テスト／デバッグする）場合はタスク用の補足ファイルを開いてください。このバージョンと BlueField、および UROM Service のバージョンで、ホスト側の UROM API が何を表現できるかを確認する場合は、機能用の補足ファイルを開いてください。DOCA がインストールされていない場合は、まず doca-setup/SKILL.md に案内してください。DPU 側の UROM Service 自体（デプロイ、コンテナー、ライフサイクル）については、これは別の成果物です。doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）を経由して、公開されている DOCA UROM Service ガイドに案内してください。このスキルが扱うのはホスト側ライブラリーで、UROM Service はDPU 側の実行エンジンです。両者は対になった契約です。

このスキルの使い方： このファイルを読み、質問に必要な ## <name> 見出しを補足ファイルから検索して、そのセクション全体を読んでください。回答は、その内容だけに基づいて完全に行い、記載されているシンボルとコマンドのみを引用してください。ドキュメントを閲覧せず、doca-public-knowledge-map に記載されたエントリーポイントを使用してください。対象範囲外の依頼については、担当するスキルを示して、そこで終了してください。

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

このスキルが回答するUROMの質問のクラスと、それぞれの具体例を1つ示します。重要なのは クラス であり、具体例はその一例です。

• 「MPI／UCXのリモートメモリー操作をホストCPUからBlueFieldにオフロードするにはどうすればよいですか？」 — 具体例：「MPIの全リデュースにホストCPUサイクルを消費していて、その分を計算に使いたいのですが、UROM経由でBlueFieldに処理を移すにはどうすればよいですか？」 回答は、capabilities companionのペア契約モデルと、tasks companionのホスト側の起動ワークフローで確認できます。
• 「DOCA UROM ServiceはBlueField上で実行されていますか。また、doca_urom_*のコードを書く前にそれを確認する必要があるのはなぜですか？」 — 具体例：「それ以外は正常なホストで、最初のdoca_urom_*呼び出しがDOCA_ERROR_NOT_PERMITTEDを返します」。回答は、capabilities companionの環境前提条件マトリックスと、tasks companionのステップ1にあるServiceのデプロイ確認で確認できます。Service側の環境に関する質問は、doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）に案内されます。
• 「このUROMの操作タイプ／アトミック操作／コレクティブ操作は、自分のデバイス＋DOCAのインストール環境＋UROM Serviceのバージョンでサポートされていますか？」 — 具体例：「自分のBlueFieldはMPIウィンドウに対するリモートのFetch-and-Addアトミック操作をサポートしていますか？」 回答は、capabilities companionのプラグイン検出ルール（起動済みService上でのdoca_urom_service_get_plugins_list — UROM操作はプラグインで定義されるCommandタスクなので、プラグインリストが機能の一覧となります）と、tasks companionの検出ステップで確認できます。
• 「doca-uromはdoca-rdmaとどう関係していますか。置き換えるのか、上に重ねて使うのか、それとも別の方法ですか？」 — 具体例：「すでに生のdoca-rdmaは動作しています。UROMを使うように書き換えるべきですか？」 回答は、capabilities companionの方式選択ルールで確認できます（UROMはRDMA基盤を利用しつつ、DPUオフロードの契約を追加します。ホストCPUがボトルネックの場合にのみ適したツールであり、単純なポイントツーポイントのケースでは引き続きdoca-rdmaを使います）。
• 「このUROM APIは、インストール済みのDOCAバージョンで使えますか？」 — 具体例：「DOCA 3.xで、コレクティブ操作プラグインはdoca_urom_service_get_plugins_listから検出できますか？」 回答は、capabilities companionのバージョン互換性オーバーレイで確認できます。これはdoca-version/SKILL.mdにある正規の検出手順への相互リンクに加え、ホストライブラリとDPU Serviceのバージョンを一致させる必要があるというオーバーレイを追加しています。
• 「doca_urom_*の呼び出しで返されたこのDOCA_ERROR_*は何を意味し、どのレイヤーが原因ですか？」 — 具体例：「doca_ctx_start()が成功した後、最初のenqueueでDOCA_ERROR_NOT_PERMITTEDが返されます」。回答は、capabilities companionのライブラリ横断的なエラー分類に対するUROMオーバーレイと、doca-debug/SKILL.mdへエスカレーションするtasks companionのレイヤー別手順で確認できます。

対象読者

このスキルは、ホスト側で DOCA UROM ライブラリを利用する HPC／UCX／MPI アプリケーションを開発する外部開発者を対象としています。つまり、doca_urom_* を直接 C／C++ で呼び出す場合や、FFI／バインディングを介して呼び出す場合、または UROM をトランスポートとして使用するよう設定された OpenMPI／MPICH などの UCX ベースのスタックを通じて、ホスト CPU ではなく BlueField 上でリモートメモリ操作を実行するコードが対象です。NVIDIA の DOCA UROM 開発に貢献する開発者向けではありません。また、DPU 側の UROM Service のデプロイ／運用を学ぶためのものでもありません。その場合は、doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）から公開されている DOCA UROM Service ガイドを参照してください。

対象言語。 DOCA UROM はホスト側の C ライブラリ（pkg-config モジュール doca-urom）として提供されています。/opt/mellanox/doca/samples/doca_urom/ に含まれるサンプルは C です。このスキルと連携するタスクで想定している標準的なケースは、ライブラリをラップする UCX ベースのスタックを含む、C／C++ の利用者です。その他の言語（Rust、Go、Python など）の利用者も、FFI を介して同じ *.so にアクセスします。このスキルでは、ライフサイクル、機能の検出、エラー分類、RDMA 基盤に関するガイダンスを言語に依存しない形で示し、正式なインターフェースとして公開 C ABI を案内します。

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

ユーザーが言語を問わず、ホスト側から DOCA UROM を実際に使用する場合に、このスキルを読み込みます。具体的には、次のような場合です。

• 対象の BlueField に対応付けられた doca_dev 上で UROM Service コンテキスト（doca_urom_service_*）を初期化し、それに接続する Worker コンテキスト（doca_urom_worker_*）を作成して、最初のエンキュー前に対応する DPU 側の UROM Service に到達できることを確認する。
• doca_urom_* を通じてリモートメモリ操作（put、get、アトミック操作、アクティブメッセージ、集合通信）をエンキューし、完了のために DOCA プログレスエンジンを進行させる。
• 起動済みの Service で doca_urom_service_get_plugins_list を呼び出し、このデバイス、DOCA のインストール環境、UROM Service のバージョンがサポートするプラグインを検出する。操作の種類、アトミック操作、集合通信はプラグインによって定義されます。
• UROM を使用するようすでに設定されている UCX ベースの HPC スタック（OpenMPI、MPICH、カスタム UCX 利用者）に、UROM のライフサイクル、機能検出、エラーに関するルールを適用する。UCX トランスポートとの統合自体の設計は、上流スタックの作業です。
• doca_urom_* が返す DOCA_ERROR_* をデバッグし、DPU 側の UROM Service に到達できない場合、このデバイスで操作の種類がサポートされていない場合、通常の doca_dev アクセス拒否、基盤となる RDMA トランスポートの障害を区別する。
• UROM C ABI をラップする非 C バインディング（Rust、Go、Python など）を設計し、同じライフサイクルとエラーに関するルールに従う必要がある。

一般的な DOCA の概要、DOCA のインストール、DPU 側の UROM Service のデプロイ／運用（独立した成果物であり、doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）から専用の公開ガイドを参照できます）、または UROM 以外のライブラリに関する質問には、このスキルを読み込まないでください。その場合は doca-public-knowledge-map/SKILL.md を使用してください。

このスキルでできること

これは薄いローダーです。本体には、適切な次のファイルを選ぶために必要な概要だけを記載しています。UROM 固有の実質的な内容は、次の2つの関連ファイルにあります。

• 機能に関する関連ファイル — このバージョンと BlueField、および UROM Service のバージョンで、ホスト側の UROM API が表現する内容です。ホストがエンキューし、DPU サービスが実行するというペア契約モデル、2種類のコンテキスト（BlueField ごとに1つ作成し、その doca_dev にバインドされる doca_urom_service と、アタッチされる doca_urom_worker コンテキスト）、プラグイン定義の Worker Command タスクとして配信されるエンキュー側の操作サーフェス（put、get、アトミック操作、アクティブメッセージ、コレクティブ。シンボルの正確な形式はプラグインとインストール環境に依存するため、一般的な名前で記載）、プラグイン検出サーフェス（doca_urom_service_get_plugins_list）、DOCA_ERROR_* に対応付けられた UROM エラー分類、可観測性サーフェス（完了イベント、機能スナップショット、RDMA カウンター）、および環境の前提条件を満たす安全ポリシー（DPU に UROM Service がデプロイされていること、ホストライブラリと DPU サービスのバージョンが一致していること、RDMA 対応の BlueField と DOCA がインストールされていること）。
• タスクに関する関連ファイル — 対象範囲内の6つの UROM 動詞（configure、build、modify、run、test、debug）の手順を説明するワークフローです。さらに、対象範囲外の質問を適切な次のスキルへ案内する Deferred task verbs ブロックもあります。

このスキルは、DOCA がインストールされ、UROM Service が BlueField にデプロイされて稼働中で、両者間の RDMA トランスポートが正常であり、オフロードする HPC／UCX／MPI スタックの概要をユーザーが把握しているホストと BlueField のペアを前提とします。DOCA のインストール、UROM Service コンテナーのデプロイ、RDMA／RoCE／IB トランスポートの起動については扱いません。これらは doca-setup/SKILL.md、公開されているDOCA UROM Service ガイド、および doca-rdma/SKILL.md を参照してください。

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

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

• どの言語であっても、事前に作成された DOCA UROM アプリケーションのソースコード。 検証済みの UROM ソースは、同梱されている C サンプル /opt/mellanox/doca/samples/doca_urom/ です。エージェントはユーザーをそこへ案内し、doca-programming-guide/SKILL.md のサンプル変更ワークフローに、タスクに関する関連ファイルの UROM 固有の上書きを適用して、最小限の差分で変更するよう指示します。
• MPI／UCX のアルゴリズムやコレクティブの実装。 このライブラリはリモートメモリ操作をオフロードします。特定の MPI プリミティブでどの put／get／アトミック操作／コレクティブを発行するかの選択は、ユーザーの HPC スタックまたは専門分野の知識に委ねられます。コレクティブのアルゴリズムを考案することは避けてください。「自分の all-reduce にはどのアルゴリズムを使うべきか」という質問は、上流の MPI／UCX ドキュメントへ案内してください。これはスタック設計の質問であり、UROM API の質問ではありません。
• スキル内に置く独立したビルドマニフェスト（meson.build、CMakeLists.txt、Cargo.toml など）。エージェントは、インストール済みの DOCA を使ってユーザーのプロジェクト内でマニフェストを作成します。その際、pkg-config --modversion doca-urom を信頼できる情報源とします。
• いかなる種類の samples/、bindings/、reference/ サブツリー。 「reference」と表示されたモック成果物はビルド可能に見え、誤解を招きます。
• DOCA UROM Service のサーフェス。 このサービスは独自の公開ガイドを持つ別の成果物です。案内先は doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）にあります。ライブラリ（ホスト側のエンキュー）とサービス（DPU 側の実行主体）を混同することが、UROM を使った最初のアプリケーション設計で最もよくある誤りです。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内（ホスト側ライブラリの作業であり、DPU 側のサービスデプロイでも MPI ／ UCX のアルゴリズム設計でもないこと）を確認してください。
2. UROM の機能マトリックス、ペア契約モデル（ホストライブラリ ＋ DPU サービス）、Service ＋ Worker のコンテキストモデル、エンキュー側の操作サーフェス、プラグイン検出ルール、環境変数の事前条件ポリシー、エラー分類、可観測性サーフェス、安全性ポリシーについては、機能のコンパニオン資料を参照してください。
3. 設定、ビルド、変更、実行、テスト、デバッグの手順については、タスクのコンパニオン資料を参照してください。

どちらのコンパニオンファイルからも、相互にリンクしています。また、標準的なバージョンルールを記載した doca-version/SKILL.md（ホストライブラリと DPU サービスのバージョンを一致させる UROM 固有の補足あり）、基盤となる RDMA サブストレートを記載した doca-rdma/SKILL.md、および適切な回答が「公開 UROM ライブラリ／Service ガイドまたはディスク上のインストールレイアウトを調べる」である場合に参照する doca-public-knowledge-map/SKILL.md にもリンクしています。

関連スキル

• doca-public-knowledge-map/SKILL.md — 公開 DOCA ドキュメントのすべての情報源と、インストール済み DOCA パッケージのディスク上のレイアウトを示すルーティングテーブルです。DOCA UROM ライブラリの公開ガイドは https://docs.nvidia.com/doca/sdk/DOCA-UROM/index.html にあります。DOCA UROM Service は別のアーティファクトであり、このマップのDOCA servicesセクションで別途説明されています。
• doca-rdma/SKILL.md — UROM が操作をオフロードした後に BlueField がデータを転送するための基盤となる RDMA トランスポートサブストレートです。UROM は RDMA を置き換えるものではなく、その上に DPU オフロード契約を追加します。ホスト CPU がボトルネックではない単純なポイントツーポイント RDMA には、doca-rdma を直接使用してください。その場合、UROM のサービス側契約はオーバーヘッドに見合いません。
• doca-setup/SKILL.md — 環境の準備、インストールの検証、BlueField のセットアップ、および公開 NGC DOCA コンテナーを使ったまだインストールしていない場合の手順を説明します。このスキルでは、前提条件が満たされており、DPU 側の UROM Service がデプロイされ、実行中であることを前提とします。
• doca-version/SKILL.md — DOCA の標準的なバージョン管理ルールを説明します。このスキルの ## Version compatibility では、4 つの要素を一致させるルールへのリンクに加えて、ホストライブラリと DPU サービスのバージョンを一致させる補足を加えています。
• doca-structured-tools-contract/SKILL.md — このバンドルの構造化ツールに関する優先順位ルール（検出／優先／フォールバック／報告）を説明します。タスクのコンパニオン資料にある「コマンド」付録は、この契約に従います。
• doca-programming-guide/SKILL.md — すべてのライブラリに共通する一般的な DOCA プログラミングパターンを説明します。pkg-config ＋ meson ビルド、同梱サンプルを変更して最初のアプリを作成する方法、Core コンテキストのライフサイクル、ライブラリ間で共通の DOCA_ERROR_* 分類、デバッグの順序が含まれます。このスキルでは、その上に UROM 固有の情報を重ねています。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／ランタイム／プログラム／ドライバーに関する、横断的なデバッグ手順を説明します。UROM 固有のデバッグ（UROM Service に到達できない、ホストライブラリと DPU サービスのバージョン不一致、その下層での RDMA トランスポート障害、このデバイス ＋ ファームウェア ＋ サービスバージョンでサポートされていない操作タイプ）は、その上に重ねて適用します。

DPU 側で実行する DOCA UROM Service は、意図的に対象範囲外としています。これは別のアーティファクトであり、doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）から参照できる独自の公開ガイドがあります。ライブラリとサービスを混同することが、UROM の最初のアプリの設計で最もよくある誤りです。両方にまたがる質問では、必ずこの区別を明示してください。