doca-dpdk-bridge

DOCA DPDK ブリッジ

例

• 「DPDK アプリに DOCA Flow を追加するにはどうすればよいですか？」 — これは対象範囲内です。doca_dpdk_port_probe で DPDK ポートをバインドしてください。データプレーンをネイティブな doca-eth に書き換えないでください。
• 「ポート登録で DOCA_ERROR_NOT_FOUND が発生します。」 — probe の呼び出しを変更する前に、DPDK と DOCA の対応バージョンの組み合わせを確認してください。

手順

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

最初に確認する内容： このスキルは、DOCA と DPDK がすでにインストールされていて、ユーザーが既存の DPDK アプリケーションを持ち、データプレーンを DOCA ネイティブ API に移行せず、その場で DOCA の機能を追加したい（最も一般的なのはハードウェアステアリング用の DOCA Flow）ことを前提としています。ユーザーが何かを実行したい（設定／ビルド／変更／実行／テスト／デバッグ）場合はタスク用のコンパニオンを開いてください。このバージョンでブリッジが何を表現できるかについて質問している場合は、機能用のコンパニオンを開いてください。ユーザーがまだ DOCA をインストールしていない場合は、まず doca-setup/SKILL.md に案内してください。ユーザーが新規に開始する（DPDK コードはまだない）ので、DOCA を使用したラインレートのパケット I/O だけを実現したい場合は、代わりに doca-eth/SKILL.md に案内してください。ブリッジは相互運用のためのものであり、新規に開始するケース向けではありません。

このスキルの使い方： このファイルを読んだ後、質問に必要な ## <name> 見出しをコンパニオンファイル内で検索し、そのセクション全体を読んでください。回答はその内容だけに基づいて完全に作成し、記載されているシンボルとコマンドのみを引用してください。ドキュメントを閲覧せず、doca-public-knowledge-map にあるエントリーポイントを使用してください。環境の確認には、ユーザーの DOCA ホスト上で実行するコマンドを提示してください。対象範囲外の依頼については、その依頼を扱うスキルを示して、そこで終了してください。

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

このスキルが回答するために作られている、DOCA DPDK Bridge に関する質問のカテゴリと、それぞれの具体例です。エージェントは、回答を支える要素はカテゴリであり、具体例はその一例にすぎないことを念頭に置いてください。

• 「DPDK アプリを使っています。データプレーンを書き直さずに、DOCA Flow ルールを追加するにはどうすればよいですか？」 — 具体例：「パケット処理アプリですでに rte_eth_* ポート経由で mbuf を処理しています。HW オフロード用に、これらのポートに DOCA Flow ステアリングルールをインストールしたいです」。回答の根拠は、## Capabilities and modes のブリッジとネイティブ実装の選択ルール、および ## configure step 3 のポート引き継ぎワークフローです。
• 「DPDK ポートを DOCA から見えるようにするにはどうすればよいですか？」 — 具体例：「rte_eth_dev_* から DPDK ポート ID を取得しました。DOCA からはどのように見えますか」。回答の根拠は、## Capabilities and modes のブリッジオブジェクトの表にある DPDK ポート ID ↔ doca_dev の対応付け（doca_dpdk_port_probe / doca_dpdk_port_as_dev）と、## configure step 4 のバインドワークフローです。
• 「DPDK mbuf と DOCA buf の間でパケットを移動するにはどうすればよいですか？」 — 具体例：「DPDK が高速パスに rte_mbuf を渡します。ペイロードを DOCA ライブラリで処理したいです」。回答の根拠は、## Capabilities and modes の mbuf ↔ DOCA-buf 変換の形式と、## modify の変換ステップワークフローです。
• 「ブリッジはインストールされていますか。また、その DPDK は私の DOCA と互換性がありますか？」 — 具体例：「DPDK が別途インストールされているホストで pkg-config --exists doca-dpdk-bridge が失敗します」。回答の根拠は、## Version compatibility のバージョン連動ルールと、## configure step 1 の機能チェックワークフローです。
• 「doca-dpd k-bridge と doca-eth のどちらを使うべきですか？」 — 具体例：「新規プロジェクトで、まだ DPDK を使うと決めていません」。回答の根拠は、## Capabilities and modes のパス選択表にあるブリッジとネイティブ実装の行、および ## Deferred task verbs の遅延 verbs に関する注記です。
• 「ブリッジ呼び出しで発生したこの DOCA_ERROR_* は何を意味し、どのレイヤーが原因ですか？」 — 具体例：「DPDK ポートが正常に起動した後、ポート登録呼び出しで DOCA_ERROR_NOT_FOUND が発生しました」。回答の根拠は、## Error taxonomy のクロスライブラリ分類に対するブリッジの補足と、doca-debug/SKILL.md へのエスカレーションにつながる ## debug の段階的な手順です。

対象読者

このスキルは、DPDK ベースのパケット処理アプリケーションをすでに保守している外部開発者、つまり、データプレーンですでに rte_eth_* ポートと rte_mbuf バッファを処理しており、同じプロセスにブリッジをリンクして DOCA の機能（主に DOCA Flow によるハードウェアステアリング）を追加したいユーザーを対象としています。新しい DOCA ネイティブプロジェクトを始めるユーザー（doca-eth/SKILL.md を案内してください）や、DOCA に関心のない純粋な DPDK ユーザー（このバンドルには該当するスキルはありません）は対象外です。また、DOCA DPDK Bridge 自体に貢献する NVIDIA の開発者も対象外です。

言語の対象範囲。 DOCA DPDK Bridge は、pkg-config モジュール名 doca-dpdk-bridge の C ライブラリとして提供されています（エージェントは pkg-config --exists doca-dpdk-bridge を使って、ユーザーのインストール環境での表記を確認する必要があります。DOCA のリリースによってはモジュール名が少し異なるため、エージェントは推測してはいけません）。同梱のサンプルは C で記述されています。C および C++ の利用者が標準的な対象であり、タスク用の補足資料にある具体例はこの方法を前提としています。その他の言語（Rust、Go、Python など）の利用者は、通常このブリッジを使用しません。DPDK 自体が C を前提とした設計であり、C 以外の DPDK アプリはまれです。この少数派に該当するユーザーに対しては、言語に依存しないポート引き継ぎ、機能、権限、エラー分類に関するガイダンスを維持し、信頼できる公開インターフェースとして C ABI を案内することが、このスキルの役割です。

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

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

• ユーザーが既存の DPDK アプリケーション（データプレーンで既に rte_eth_dev_* ポートと rte_mbuf バッファーを使用している）を持っており、その上に DOCA を追加しようとしている場合 — DOCA Flow ルールの追加、パケットの DOCA アクセラレーター（Compress、AES-GCM、…）への受け渡し、または同じプロセスへの DOCA サービスの組み込みなど。
• ユーザーが DPDK ポート ID を doca_dev にバインドして（doca_dpdk_port_probe / doca_dpdk_port_as_dev を使用）、DOCA Core / DOCA Flow が同じ物理ポートを操作できるようにする必要がある場合。
• ユーザーがデータプレーンの境界で DPDK mbuf と DOCA-buf を変換する必要があり、変換ヘルパーとそのコストについて尋ねている場合。
• ユーザーがブリッジ呼び出しから返される DOCA_ERROR_*（ライフサイクル、権限、機能、DPDK ポート未登録、mbuf 変換失敗）と、その下層にある DPDK ↔ DOCA スタックをデバッグしている場合。
• ユーザーがバージョン間の問題に直面している場合 — インストール済みの DPDK と DOCA が、ブリッジの想定する対応バージョンの組み合わせではない場合。
• ユーザーが 「ネイティブの doca-eth と doca-dpdk-bridge のどちらを使うべきか？」 と尋ねており、エージェントが選択基準を示す必要がある場合。

一般的な DOCA の概要、DOCA 自体のインストール、新規の DOCA ネイティブなパケット I/O（doca-eth/SKILL.md を使用）、単独でのフロールールのプログラミング（doca-flow/SKILL.md を使用）、ホスト ↔ DPU の制御メッセージング（doca-comch/SKILL.md を使用）、または RDMA データ転送には、このスキルを読み込まないでください。DOCA ドキュメントの概要については、doca-public-knowledge-map/SKILL.md を使用してください。

このスキルでできること

これは簡易ローダーです。本体には、次に読むべきファイルを選ぶために必要な概要だけを残しています。ブリッジ固有の詳細は、次の 2 つの関連ファイルにあります。

• 機能に関する関連ファイル — このバージョンの DOCA DPDK Bridge で表現できることを説明します。ブリッジとネイティブの選択基準（doca-dpdk-bridge とネイティブの doca-eth の使い分け）、ブリッジオブジェクトのインターフェイス（DPDK ポート ID ↔ doca_dev のマッピング、doca_dpdk_mempool による mbuf ↔ DOCA-buf の変換）、機能照会インターフェイス（単一の doca_dpdk_cap_is_rep_port_supported）、ブリッジエラーの分類（複数ライブラリにまたがる DOCA_ERROR_* セットへの対応付け）、可観測性のインターフェイス（DPDK 側のカウンター + DOCA 側の PE イベント）、および DPDK ↔ DOCA の対応バージョン連携、EAL が起動済みであることの前提条件、DPDK 側の権限を条件とする安全ポリシーを扱います。
• タスクに関する関連ファイル — 対象となる 6 つのブリッジ操作 configure、build、modify、run、test、debug の手順を説明します。また、対象外の質問に適切な次のスキルを案内する Deferred task verbs セクションと、エージェントが繰り返し使用するコマンドをまとめた Command appendix もあります。

このスキルは、DOCA と DPDK が標準の場所にすでにインストールされており、ユーザーが公開インストールプロファイルで想定される権限（通常、DOCA には sudo または mlnx グループへの所属、さらに hugepages のマウント、PCIe ポートのバインド、対象の rte_eth デバイスを開くための DPDK 側の権限）を持つホストまたは BlueField を前提としています。DOCA のインストールは対象外です。この作業には doca-setup/SKILL.md を使用してください。DPDK 自体のインストールや学習も対象外で、doca-public-knowledge-map/SKILL.md から参照できる DPDK 上流ドキュメントの範囲です。

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

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

• あらかじめ作成された DOCA DPDK Bridge アプリケーションのソースコード（言語を問いません）。 検証済みのブリッジのソースコードは、提供されている C 言語の DOCA Flow サンプル内にあるブリッジの使用例です。場所は /opt/mellanox/doca/samples/doca_flow/ です（例：doca_dpdk_port_probe() / doca_dpdk_port_as_dev() を呼び出す flow_common.c）。 これに加えて、DPDK + DOCA Flow を組み合わせた正規のリファレンスアプリケーションがあります（リファレンスアプリケーションの索引については doca-public-knowledge-map/SKILL.md を参照してください）。エージェントの役割は、ユーザーをこれらのファイルに案内し、共通のサンプル変更ワークフロー doca-programming-guide/SKILL.md に従って、最小限の差分で変更する方法を提示することです。そこに、このブリッジ固有の上書きルールを

  modify

  に重ねて適用します。
• スキル内に置く単独のビルドマニフェスト（meson.build、 CMakeLists.txt、Cargo.toml など）。 エージェントは、ユーザーがインストールした DOCA + DPDK を対象に、ユーザーのプロジェクトディレクトリ内でビルドマニフェストを作成します。その際は、 pkg-config --modversion doca-dpdk-bridge と pkg-config --modversion libdpdk を信頼できる情報源とします。
• 種類を問わず、samples/、bindings/、または reference/ のサブツリー。 このスキルのツリー内にあるモックや不完全な成果物は、「リファレンス」とラベル付けされていても誤解を招きます。ユーザーはそれをビルド可能なものとして受け取るでしょう。

読み込み順

1. まずこのスキルを読み、ユーザーの質問が対象範囲内であること（既存の DPDK アプリに DOCA を追加したいという内容で、新規作成ではないこと）を確認します。
2. ブリッジの機能マトリクス、ブリッジとネイティブの選択ルール、ポート引き渡しの対象範囲、機能クエリのルール、エラー分類、可観測性、安全ポリシーについては、機能のコンパニオンを参照してください。
3. 設定、ビルド、変更、実行、テスト、デバッグの手順については、タスクのコンパニオンを参照してください。

両方のコンパニオンファイルは、互いへのリンクに加えて、 正規の DOCA バージョン処理ルールを記載した doca-version/SKILL.md、 ブリッジが意図的に代替する、新規作成の手順を記載した doca-eth/SKILL.md、 そもそもこのブリッジを使う最も一般的な理由となるステアリングライブラリについて記載した doca-flow/SKILL.md、 そして、適切な回答が「ブリッジ固有のガイダンス」ではなく「公開ドキュメントまたはインストール済みパッケージの構成を確認する」である場合に参照する doca-public-knowledge-map/SKILL.md にも相互リンクしています。

関連スキル

• doca-public-knowledge-map/SKILL.md — すべての公開 DOCA ドキュメントソースと、インストール済み DOCA パッケージのディスク上のレイアウトを示すルーティングテーブルです。ブリッジの URL スラッグは DOCA-DPDK-Bridge です。DPDK + DOCA Flow を組み合わせるリファレンスアプリケーション（このブリッジを採用する代表例）は、同じマップのリファレンスアプリケーションインデックスから参照できます。
• doca-setup/SKILL.md — 環境の準備、インストールの検証、hugepage のマウント（DPDK の要件）、ポート状態の確認（devlink dev show、ip link）、doca_dev を開くための権限とグループ所属要件、および DPDK で PCIe ポートをバインドするための要件を扱います。このスキルでは、これらの前提条件が満たされているものとします。
• doca-version/SKILL.md — DOCA のバージョン管理に関する標準ルールです。このスキルの ## Version compatibility では、4 要素の一致ルールへの相互リンクを示し、ブリッジ固有の補足（DPDK ↔ DOCA の対応バージョン間の連携）のみを追加します。
• doca-structured-tools-contract/SKILL.md — バンドルにおける構造化ツールの優先順位ルール（検出／優先／フォールバック／報告）です。タスク用コンパニオンのコマンド付録は、この契約に従います。
• doca-programming-guide/SKILL.md — すべてのライブラリに共通する一般的な DOCA プログラミングパターンです。標準の pkg-config + meson ビルドパターン、出荷されたサンプルを変更する汎用的な最初のアプリのワークフロー、共通のライフサイクル、ライブラリ横断の DOCA_ERROR_* 分類、プログラム側のデバッグ順序を扱います。このスキルはその上にブリッジ固有の内容を重ねます。
• doca-eth/SKILL.md — 新規に始めるユーザー向けの代替パスです。DPDK を使わず、doca_eth_rxq / doca_eth_txq による DOCA ネイティブなキュー I/O を扱います。既存の DPDK アプリを doca-eth に移行することは、多くの場合、適切なトレードオフではありません。このブリッジはそのために存在します。DPDK への依存がない新規プロジェクトでは、doca-eth が適切な選択肢です。
• doca-flow/SKILL.md — DPDK アプリがこのブリッジを利用する最も一般的な理由となるステアリングライブラリです。このブリッジは DPDK ポート ID を doca_dev にバインドし、DOCA Flow はその doca_dev にステアリングルールを設定します。この 2 つのライブラリは、組み合わせて使えるよう設計されています。
• doca-debug/SKILL.md — 複数の領域にまたがるデバッグ手順（インストール／バージョン／ビルド／リンク／ランタイム／プログラム／ドライバー）です。ブリッジ固有のデバッグ（DPDK ↔ DOCA のバージョンの不一致、ポート未登録の症状、mbuf 変換の失敗）は、この手順に重ねて行います。