doca-rmax

DOCA Rivermax

例

• 「ST 2110 の受信でフレームを受信できません。」 — Rivermax SDK とライセンスがすでに用意されている場合は、このスキルの対象です。
• 「doca_rmax_init から NOT_SUPPORTED が返されます。」 — ストリームの設定を変更する前に、doca_rmax_get_*_supported クエリを実行してください。

手順

以下の読み込み順に従ってください。設定／ストリーム／デバッグについてはタスク用コンパニオンを開いてください。Rivermax の前提条件については機能用コンパニオンを開いてください。すべてのコンパニオンファイルを開かないでください。

最初に確認すること： このスキルは、対象の BlueField DPU に DOCA がすでにインストールされていること（DOCA Rivermax アプリは対象の DPU 上でのみ動作します）、かつ Rivermax ライブラリ（DOCA リポジトリの doca-sdk-rmax／libdoca-sdk-rmax-dev）がインストールされ、DPU 上に有効な Rivermax ライセンスがあることを前提とします。Rivermax に関する質問を受けたとき、エージェントが最初に行うべきことは、その両方を確認することです。Rivermax ライブラリとライセンスがなければ、DOCA 側のコードがどれほど適切でも doca-rmax は動作しません。これは初めてアプリを作成する際に最もよくある混乱の原因です（Rivermax ライセンスとドライバーは、Rivermax SDK のページに記載されているとおり、DOCA とは別に入手します）。ユーザーが何かを実行したい（設定／ビルド／変更／実行／テスト／デバッグ）場合はタスク用コンパニオンを開いてください。質問が「このバージョンと Rivermax のインストール環境で DOCA Rivermax に何ができるか」であれば、機能用コンパニオンを開いてください。ユーザーがまだ DOCA をインストールしていない場合は、まず doca-setup/SKILL.md に案内してください。Rivermax SDK とライセンス自体のインストールについては、doca-public-knowledge-map/SKILL.md を通じて、公開 DOCA Rivermax ガイド（スラッグ DOCA-Rivermax）に案内してください。 ユーザーが「Rivermax の入力ストリームにパケットを届けるにはどうすればよいか」と尋ねている場合、答えは複数の層に分かれます。doca-rmax は Rivermax 統合 のインターフェース、doca-eth/SKILL.md はパケットを運ぶ キュー のインターフェース、doca-flow/SKILL.md はパケットを振り分ける ステアリング のインターフェースです。

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

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

• 「このホストで doca-rmax を使うことはできますか？」 — 具体例：「公開ドキュメントに doca-rmax とありますが、ほかに何もせずに使えますか？」。## Safety policy の Rivermax-SDK とライセンスの前提条件ルール、および ## configure step 1 の環境準備チェックリストで回答します。インストールに関する質問は doca-public-knowledge-map/SKILL.md を通じて公開されている Rivermax ガイドに誘導し、タイミング特性がひそかに失われる doca-eth だけへのフォールバックは推奨しません。
• 「SMPTE ST 2110 の動画受信ストリームを設定するにはどうすればよいですか？」 — 具体例：「初回テスト用に、BlueField ポートの representor で Rivermax の受信ストリームを準備する」。## configure のストリームごとのオブジェクトライフサイクルと、## Capabilities and modes の入力ストリーム機能テーブルで回答します。
• 「PTP クロックまたはハードウェアのパケット配置順序を選ぶ前に、どの doca_rmax_get_*_supported クエリを呼び出す必要がありますか？」 — 具体例：「このデバイスとこの Rivermax インストールで、ST 2110-20 のシーケンス番号配置を使えますか？」。## Capabilities and modes の機能クエリルールと、## configure のステップ 3 で回答します。
• 「ストリームを設定したのにパケットが届きません。なぜですか？」 — 具体例：「Rivermax ストリームオブジェクトは正常に起動しましたが、recv イベントが発生しません」。## Safety policy の前提条件マトリクスと、## configure step 1 の環境準備チェックリストで回答します。ステアリング関連は doca-flow/SKILL.md に、キュー関連は doca-eth/SKILL.md に誘導し、ライセンス関連は Rivermax 側の前提条件に誘導します。
• 「この Rivermax 統合機能は、私のデバイス、インストール済みの DOCA、Rivermax SDK で利用できますか？」 — 具体例：「このデバイスとこの Rivermax バージョンで、必要な PTP クロックまたは配置モードがサポートされていると示されていますか？」。## Capabilities and modes の機能クエリルールと、## Version compatibility のバージョンおよびデバイスの補足情報で回答します。これにより、doca-version/SKILL.md の標準的な DOCA バージョン処理の流れに、Rivermax 側のバージョンももう一つの軸となるというルールが加わります。
• 「Rivermax の呼び出しで発生したこの DOCA_ERROR_* は何を意味し、どのレイヤーが原因ですか？」 — 具体例：「doca_rmax_init() で DOCA_ERROR_NOT_SUPPORTED が発生しました」。## Error taxonomy のライブラリ横断的な分類に対する Rivermax 側の補足と、## debug の段階的な調査手順で回答し、doca-debug/SKILL.md にエスカレーションします。また、インストール済みヘッダーに記載された呼び出し固有の対応関係を維持します。初期化時の _NOT_SUPPORTED はまず Rivermax SDK とライセンスの確認に誘導し、それ以降のエラーはライセンスの問題と決めつけず、実際に失敗した呼び出しに基づいて解釈します。

対象読者

このスキルは、DOCA Rivermax 統合を利用するアプリケーションを構築する外部開発者を対象としています。つまり、別途インストールされた NVIDIA Rivermax SDK を使用し、BlueField または ConnectX ホスト上で、タイミング精度が求められる IP メディアストリーム（SMPTE ST 2110、リアルタイム市場データ、高スループットの科学計測機器ストリーム）を制御するために、doca_rmax_* を直接（C/C++ から）または他の言語から FFI／バインディング経由で呼び出すコードを使用するユーザーです。DOCA Rivermax 自体に貢献する NVIDIA の開発者を対象とするものではなく、ベストエフォートのパケット I/O を求めるユーザー向けでもありません。その場合は、doca-eth/SKILL.md に直接誘導してください。

言語の範囲。 DOCA Rivermax は、pkg-config モジュール名が doca-rmax の C ライブラリとして提供されています。付属のサンプルは /opt/mellanox/doca/samples/doca_rmax/ にあり、C で記述されています。C および C++ の利用が標準的なケースであり、タスク用の付属資料にある実例もこの方法を前提としています。その他の言語（Rust、Go、Python など）の利用者は、FFI または言語固有のバインディングを通じて同じ *.so を利用します。その場合、このスキルでは、前提条件（Rivermax SDK とライセンス）、ストリームごとのライフサイクル、機能検出、権限、スケジューリング規律、エラー分類に関するガイダンスを言語に依存しない形で維持し、最終的にあらゆるラッパーが呼び出すことになる正式なインターフェイスとして、公開 C ABI をエージェントに案内します。

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

ユーザーが言語を問わず、DOCA Rivermax を実際に使用しているときに、このスキルを読み込みます。具体的には、次のような場合です。

• DOCA 側のコードを書く前に、NVIDIA Rivermax SDK と有効な Rivermax ライセンスがホストに存在することを確認する場合 — これは必須の前提条件であり、エラー時の対応ではありません。これらがない場合の回答は「doca-rmax は使用できません。別のライブラリを選んでください」であり、「試して何が失敗するか見てみましょう」ではありません。
• doca_rmax_init()／doca_rmax_release() でグローバルな DOCA Rivermax エンジンを初期化し、物理ポート、representor、または SF に接続して開いた doca_dev 上で、doca_rmax_in_stream_create() を使って doca_rmax_in_stream（受信）コンテキストを作成し、doca_ctx_start() の前に doca_rmax_in_stream_as_ctx() で変換する場合。公開されている DOCA Rivermax API は受信専用であり、送信／出力ストリームオブジェクトはありません。
• SMPTE ST 2110 の IP 経由の音声＋映像、リアルタイムの市場データフィード、または科学機器のストリーム向けに Rivermax 入力ストリームを設定する場合 — PTP クロックとハードウェアパケット配置順序のサポートはデバイスおよび Rivermax の条件によって異なり、対応する doca_rmax_get_*_supported クエリによって利用可否が決まることを把握しておきます。
• doca_rmax_in_stream_set_* を使用して Rivermax ストリームのプロパティを読み取る、または設定する場合や、PTP クロックまたはハードウェアパケット配置順序がサポートされていると想定する前に、doca_rmax_get_*_supported ファミリーを使用してデバイスと Rivermax の機能を確認する場合。
• パケットを運ぶ doca-eth のキューインターフェースと、パケットを誘導する doca-flow のルールを Rivermax ストリームと組み合わせる場合 — Rivermax 自体はパケットの誘導を設定しません。
• ストリーミングスレッドのリアルタイムスケジューリング方式を設計する場合（基盤となる Rivermax スタックは、サブマイクロ秒のジッターを実現するためにリアルタイム優先度を想定しています。標準的なスケジューリングの指針は、doca-public-knowledge-map/SKILL.md から参照できる Rivermax SDK ドキュメントに記載されています）。
• Rivermax 呼び出しから返された DOCA_ERROR_* をデバッグする場合（ライフサイクル、ライセンス／権限、機能、またはドライバーより下位の問題）。原因は DOCA 側のラッパー、基盤となる Rivermax スタック、またはライセンス層にある可能性があります。
• DOCA Rivermax C ABI をラップする非 C バインディング（Rust、Go、Python など）を設計または拡張する場合 — ラッパーは前提条件、ライフサイクル、機能、権限、スケジューリングに関する規則を順守する必要があります。

一般的な DOCA の概要を把握する場合、DOCA 自体をインストールする場合、Rivermax SDK をインストールする場合、Rivermax ライセンスファイルを管理する場合（これらは doca-public-knowledge-map/SKILL.md から参照できる公開 Rivermax SDK ガイドに記載されています）、タイミング要件のないベストエフォートのパケット I/O を行う場合（doca-eth/SKILL.md を直接使用してください）、またはネットワークを使用しないホスト側のデータ処理のみを行う場合は、このスキルを読み込まないでください。DOCA ドキュメントの概要を把握するには、doca-public-knowledge-map/SKILL.md を使用してください。

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

これは薄いローダーです。本文には、次に参照する適切なファイルを選ぶために必要な概要だけを残しています。Rivermax 固有の実質的な情報は、次の 2 つの補助ファイルに記載されています。

• 機能に関する補助ファイル — このバージョンおよびこの Rivermax SDK のインストール環境で DOCA Rivermax が表現できる内容。Rivermax をハード依存とするルール、受信専用の doca_rmax_in_stream オブジェクトモデル、機能クエリのインターフェイス（doca_rmax_get_*_supported）、Rivermax のエラー分類（ライブラリ間で共通の DOCA_ERROR_* セットに対応付け、各行で Rivermax 固有の原因を明記）、可観測性のインターフェイス（ストリームごとの進捗エンジンイベント、機能スナップショット、Rivermax 側のライセンスとドライバーの状態）、および Rivermax SDK の存在／ライセンスの存在／デバイスアクセス／スケジューリング規律という前提条件を確認する安全性ポリシー。
• タスクに関する補助ファイル — 対象となる 6 つの Rivermax 動詞、configure、build、modify、run、test、debug のステップごとのワークフロー。さらに、対象外の質問（Rivermax のインストール、ライセンスの管理、ステアリングのプログラミング、基盤となるキューのプログラミング）を適切な次のスキルへ案内する Deferred task verbs ブロックと、エージェントが繰り返し使うコマンドをまとめた Command appendix も含まれます。

このスキルは、DOCA が標準の場所にすでにインストールされており、NVIDIA Rivermax SDK が想定される場所に有効なライセンスとともにインストールされ、ユーザーが公開されているインストールプロファイルで想定される権限（通常は doca_dev をポートに対して開くための sudo 権限または mlnx グループへの所属）を持つホストまたは BlueField を前提としています。DOCA のインストールは対象外です。その手順については doca-setup/SKILL.md を参照してください。Rivermax またはそのライセンスのインストールも対象外です。その手順については、doca-public-knowledge-map/SKILL.md から参照できる一般公開の Rivermax SDK ガイドを参照してください。

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

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

• DOCA Rivermax アプリケーションの、言語を問わない事前作成済みソースコード。 検証済みの Rivermax ソースコードは、同梱されている C サンプル /opt/mellanox/doca/samples/doca_rmax/<name>/ です。エージェントの役割は、ユーザーにこれらのファイルを案内し、doca-programming-guide/SKILL.md にある汎用のサンプル変更ワークフローに Rivermax 固有の ## modify のオーバーライドを重ねて、最小限の差分で変更するよう指示することです。
• スキル内に置かれた単独のビルドマニフェスト（meson.build、CMakeLists.txt、Cargo.toml など）。エージェントは、pkg-config --modversion doca-rmax を信頼できる情報源として、ユーザーがインストールした DOCA を利用するビルドマニフェストをユーザーのプロジェクトディレクトリ内で作成します。
• 公開されているファミリーパターン以外の Rivermax シンボル名（機能の検出には doca_rmax_get_*_supported、標準的な DOCA Core コンテキストのライフサイクルで駆動される受信専用の doca_rmax_in_stream セッションオブジェクトを使用）。正確な Rivermax シンボル名はインストール環境および Rivermax SDK のバージョンに依存します。エージェントは記憶に頼らず、インストール済みヘッダー（$(pkg-config --variable=includedir doca-common)）と一般公開されている DOCA Rivermax ガイドを参照してください。
• いかなる種類の samples/、bindings/、reference/ サブツリーも含めません。このスキルのツリーにあるモックや不完全な成果物は、たとえ 「reference」 とラベル付けされていても誤解を招きます。ユーザーはそれをビルド可能なものとして受け取ってしまいます。

読み込み順序

1. まずこのスキルを読んで、ユーザーの質問が対象範囲内であることと、Rivermax-SDK とライセンスの前提条件が考慮されていることを確認してください。
2. Rivermax の機能マトリックス、受信専用の入力ストリームモデル、機能クエリのルール、エラー分類、可観測性、安全ポリシーについては、機能に関する関連ドキュメントを参照してください。
3. 設定、ビルド、変更、実行、テスト、デバッグといった手順ごとのワークフローについては、タスクに関する関連ドキュメントを参照してください。

どちらの関連ドキュメントからも、互いのドキュメント、DOCA の正規のバージョン処理ルールを記載した doca-version/SKILL.md（Rivermax ではさらに Rivermax-SDK のバージョン軸が加わります）、パケットを運ぶキューのインターフェイスを記載した doca-eth/SKILL.md、どのパケットをどのキューに送るかを決めるステアリング側を記載した doca-flow/SKILL.md、および「Rivermax 統合固有のガイダンス」ではなく「公開されている Rivermax SDK ガイドまたはインストール済みパッケージのレイアウトを調べる」ことが適切な回答となる場合の doca-public-knowledge-map/SKILL.md へリンクしています。

関連スキル

• doca-public-knowledge-map/SKILL.md — 公開されているすべての DOCA ドキュメントソースと、インストール済み DOCA パッケージのディスク上のレイアウトを案内するルーティングテーブルです。Rivermax の URL スラッグは DOCA-Rivermax です。ユーザーが Rivermax またはそのライセンスのインストール方法を尋ねた場合、別製品である公開 Rivermax SDK ガイドにも同じルーティングテーブルからアクセスできます。
• doca-setup/SKILL.md — 環境の準備、インストールの確認、ポート状態の確認（devlink dev show、ip link）、doca_dev を開くために必要な権限とグループメンバーシップを扱います。このスキルでは前提条件が満たされていることを想定しており、Rivermax-SDK とライセンスの前提条件はさらにその上に追加されます。
• doca-version/SKILL.md — DOCA の正規のバージョン処理ルールです。このスキルの ## Version compatibility では、4 つの要素の一致ルールへのリンクに加えて、Rivermax 固有のオーバーレイを記載しています（Rivermax SDK のバージョンが 2 つ目の軸となり、このホストで利用できる機能セットは、DOCA 側の機能クエリ結果と Rivermax 側の機能の積集合になります）。
• doca-structured-tools-contract/SKILL.md — バンドルにおける構造化ツールの優先順位ルール（検出／優先／フォールバック／報告）です。タスクに関する関連ドキュメントの Command 付録は、この契約に準拠しています。
• doca-programming-guide/SKILL.md — すべてのライブラリに共通する一般的な DOCA プログラミングパターンです。正規の pkg-config と meson によるビルドパターン、同梱サンプルを変更する普遍的な初回アプリのワークフロー、普遍的なライフサイクル、ライブラリ間で共通の DOCA_ERROR_* 分類、プログラム側のデバッグ順序を扱います。このスキルでは、これらに Rivermax 固有の内容を追加します。
• doca-eth/SKILL.md — Rivermax ストリームが生成または消費するパケットを運ぶキューのインターフェイスです。DOCA Rivermax 自体は基盤となるキューを設定しません。doca-eth を介して設定したキューと統合します。2 つのスキルのライフサイクルは独立しています。
• doca-flow/SKILL.md — どのパケットをどのキューに送るかを決めるステアリングのインターフェイスです。DOCA Rivermax 自体はステアリングを設定しません。Rivermax の入力ストリームにデータがまったくない場合、ほとんどの場合、Rivermax のバグではなく、Flow ルールがないか正しく設定されていないこと（または Rivermax ライセンスがないこと）が原因です。
• doca-debug/SKILL.md — 分野横断的なデバッグの手順（インストール／バージョン／ビルド／リンク／ランタイム／プログラム／ドライバー）です。ライセンス前提条件の不足、ストリーム種別とパケットレートの機能不一致、スケジューリング方式に起因するジッター症状といった Rivermax 固有のデバッグ項目は、この手順に重ねて扱います。