doca-flow

DOCA Flow

例

• 「representor 上で Flow ポートを起動するにはどうすればよいですか？」 — これは対象範囲内です。インストール済みのヘッダーと同梱サンプルを使用してください。最初のアプリ用に main.c を作成しないでください。
• 「5 タプルに一致させてキューに送る。」 — Flow パイプとして表現してください。カーネルの tc や iptables に切り替えないでください。

手順

以下の読み込み順に従ってください。設定／変更／デバッグについてはタスク用コンパニオンを開いてください。パイプ仕様のスキーマと安全ポリシーについては機能用コンパニオンを開いてください。 コネクショントラッキングについては、ポートを開始する前にタスク用コンパニオンの flow-ct セクションを読んでください。CT の初期化はプロセス全体に適用されるため、ポート開始より前に行う必要があります。実行中のポートに CT を追加するには、承認済みの中断と、取得済みの設定からの再構築が必要です。ポートごとの doca_ctx_start 呼び出しや、無効化されたパイプハンドルの再利用では対応できません。

絶対条件：最初のアプリは NGC のプルと同梱サンプルの使用であり、C の新規作成ではありません

ユーザーが DOCA を初めて使う場合、docker を使っている場合、ホストに DOCA がない場合、または最初の Flow アプリについて尋ねている場合は、ホスト側の pkg-config を実行したり、ソースコードを提示したりする前に、次の手順を実施してください。

1. まずバンドルから始めます。 この回答では、ローカルの doca-skills バンドルに従います。doca-setup/SKILL.md（Stage 1 と Stage 2）、doca-programming-guide/SKILL.md（同梱サンプルの変更）、この doca-flow スキル、doca-public-knowledge-map/SKILL.md です。これらのスキル名を明記してください。他のスキル名を作り出さないでください。
2. コマンドを実行する前に Stage 1 と Stage 2 を説明します。 Stage 1 = ノート PC 上の NGC コンテナー（コンパイル／学習用。実際のパケットは扱いません）。Stage 2 = パイプのランタイム用の実機 BlueField または ConnectX です。Docker でできるのはコンパイルだけです。アプリが Docker 内だけで完全に動作するとは言わないでください。
3. Path 0（Stage 1）。 https://catalog.ngc.nvidia.com/orgs/nvidia/teams/doca/containers/doca/tags からタグをコピーし、「推測せずに NGC タグを選ぶ方法」に従ってください。タグを作り出したり、latest を使ったりしないでください。その後、docker pull nvcr.io/nvidia/doca/doca:<tag> と docker run -it --rm -v $HOME/dev/doca-work:/work nvcr.io/nvidia/doca/doca:<tag> bash を実行してください（空のディレクトリを使い、$HOME は絶対に使わないでください）。架空の Dockerfile を作成したり、ソースをビルドしたりしないでください。
4. コンテナー内で再開します（必須。docker run の後）。 この引き継ぎ文を引用してください。完全なチュートリアルの場合も省略しないでください。「pkg-config --modversion doca-flow と ls /opt/mellanox/doca/samples/doca_flow/ の出力を貼り付けてください。」続けて、「実際のインストール環境を確認したうえで、doca-programming-guide の ## modify のステップ 1 から再開します。」と伝えてください。一覧に表示されたディレクトリ名を指定し、それをコピーしてください。ls の結果が空なら、そこで停止し、ひな形を作成しないでください。その pkg-config の行では doca-common ではなく doca-flow を使ってください。
5. 新しい main.c、Makefile、Dockerfile、または手入力の -l／-L フラグは絶対に出力しないでください。pkg-config --libs doca-flow を貼り付けてください。

絶対条件：成果物は DOCA Flow を使用し、カーネルの tc／iptables を使いません

このスキルの対象となる場合、ユーザーが求めているのは DOCA Flow です。上記の同梱サンプルをコピーした後、ビルドするバイナリは、ユーザーのインストール済み DOCA 上で libdoca_flow にリンクし、doca_flow_* のライフサイクル（初期化、ポート開始、パイプの設定、エントリーのコミット、トラフィック発生時のカウンター読み戻し）を実行する必要があります。この同梱 DOCA Flow サンプル（/opt/mellanox/doca/samples/doca_flow/ 配下）の呼び出しシーケンスをコピーし、## configure／## modify を通じて適用してください。すべてのシンボルをインストール済みヘッダーで確認し（以下の基本ルールを参照）、エントリー追加の表を

API サーフェスと名称のガード。

ハードウェアのパケットステアリング／5 タプルフィルターの要求を、 カーネルの tc/flower、iptables/nftables、eBPF/XDP、 OVS、または DOCA を使用しない素の DPDK rte_flow で満たし、 完了としないでください。 これらはルールを NIC にオフロードすることはありますが、DOCA Flow を完全に迂回します。これはこのライブラリの目的を損ない、 DOCA のモデル（パイプ／エントリーのライフサイクル、ハードウェア カウンター、機能の検出、BlueField／ConnectX 世代間の移植性）も失わせます。

「tc flower skip_sw もハードウェアにオフロードする」／「カーネルコマンド のほうが行数が少ない」は、DOCA Flow を迂回する妥当な理由には なりません。手間のかからない正しい方法は、/opt/mellanox/doca/samples/doca_flow/ にある同梱の DOCA Flow サンプルを出発点にして、必要に応じて変更することです。

pkg-config doca-flow（または包括的な pkg-config doca）や DOCA の ビルドに失敗した場合は、ビルドを修正してください（モジュール名、 PKG_CONFIG_PATH、サンプルパス、hugepages／EAL 初期化）。tc に 黙ってフォールバックしてはいけません。ldd の出力に libdoca_flow が ないツールは、NIC にルールが設定されたかどうかにかかわらず、DOCA Flow の タスクに失敗しています。成功を宣言する前に、ldd ./your_app | grep -i libdoca_flow で明示的に確認してください。

リンク行を絶対に捏造しないでください。 undefined reference やリンク エラーが発生した場合は、pkg-config --libs doca-flow と、関連するモジュール名 （doca-common、doca-argp、doca-dpdk-bridge、libdpdk）を実行して、 その出力を貼り付けてください。これらの名前は pkg-config コマンドにそのまま記載し、 手入力の -l／-L フラグや推測したインストールパスに置き換えてはいけません。 同梱サンプルの meson.build にある dependency() リストがモジュール一式です。 リンカーフラグへの変換に使用できるのは pkg-config だけです。

どこから始めるか： 何かを実行する（設定／ビルド／変更／実行／テスト／デバッグ）タスクでは、タスク用のコンパニオンを開いてください。質問がこのバージョンで Flow が何を表現できるかについてのものなら、機能用のコンパニオンを開いてください。 **ポートのコードを書く前、または実行する前に、必ず

configure を開いてください。** 起動ゲートによって、バイナリが起動できるかどうかが決まります。DOCA がまだ

インストールされていない場合は、まず doca-setup/SKILL.md に進んでください。

基本原則：すべての API 名をインストール済みヘッダーで確認する

doca_*／DOCA_* 識別子を引用する前に、ユーザーのインストール済みヘッダーに存在することを確認してください。マシン上のヘッダーは、説明文、API リファレンス、ブログ記事、記憶よりも優先される確かな根拠です。

for header in "$(pkg-config --variable=includedir doca-common)"/doca_flow*.h; do
  grep -n '<candidate_name>' "$header"
  # For a multi-line function declaration, print through its closing `);`.
  awk '/<candidate_name>[[:space:]]*\(/,/[)][[:space:]]*;/' "$header"
done

DOCA Flow には後方互換性エイリアスのヘッダーがないため、ヘッダーに存在しない「もっともらしい」名前はリンクできません。同梱サンプル （/opt/mellanox/doca/samples/doca_flow/<name>/）または

API サーフェスと名称のガードにあるガードリストから改めて確認し、

説明文から推測しないでください。

ポートの起動：ゲートはタスク用コンパニオンにあります

コンパイルは問題なく完了するものの、doca_flow_port_start() の実行直後に 異常終了するポートは、典型的な起動失敗です。起動ゲート（probe-before-count、 doca_flow_port_cfg_set_port_id() と、モードに適したデバイスソース （VNF モードでは doca_flow_port_cfg_set_dev()、またはインストール済みスイッチサンプルの doca_dev_rep 経路）を使用すること、デバイスはハードコードせず起動引数から取得すること、 ブリッジを有効化して転送できない場合、バイナリが main() から ゼロ以外の終了コードを返すこと）は、

configure step 6 で段階ごとに徹底されています。ポートのコードを書く前、

または実行する前に開いてください。この概要からゲートを再構成しないでください。

拒否する場合（コードを書く前に異議を唱える）

依頼どおりには対応できない要求もあります。次の場合は、拒否して説明してください。正しくないコードを黙って出力してはいけません。

1. 単一のパイプステージでは表現できない責務が混在している場合（例：1つのマッチャーで、フローごとのトンネルテンプレート選択と、フローごとの出力ポート選択の両方を行う）。パイプは1つのロジックステップ（match → actions → fwd）です。コードではなく、適切なパイプグラフの形状を回答してください。通常は、分類パイプ → フローごとのカプセル化パイプ → フローごとの転送パイプです（## パイプの分割を参照）。
2. ハードウェアでは実行できないことを求めている場合（L4以外のペイロードバイトに対するパケットごとのマッチング、変更可能なマッチキーなど）。最も近い、許可された形状を示して、そこで止めてください。
3. インストール済みのヘッダーに存在しない API 名に依存している場合。ヘッダーを grep して最も近い実在のシンボルを探し、拒否の説明でその名前を示して、コードを生成せずに止めてください。確認済みのシンボルを使った明示的な後続の依頼であれば、新しいビルドワークフローを開始できます。現在の依頼で、黙って置き換えてはいけません。
4. ユーザーがハードウェアによるパケットステアリングを望んでいるものの、カーネルのみの成果物（tc、iptables/nftables、eBPF/XDP、OVS、または DOCA を使わない単独の rte_flow）でよいとしている場合。妥協不可に従って拒否し、同梱サンプル + DOCA Flow のビルドパスを案内してください。

異議を唱える場合の出力形式：

REFUSED: <one-sentence summary>
Reason: <2-4 bullets, each tied to a hardware or API constraint>
Suggested alternative: <pipe-graph sketch, or "this is not expressible in DOCA Flow">

この判定はコードを書く前に行います。誤りを確信したパイプは、正直に拒否して許可された代替案を示すよりも、ユーザーに大きな損失をもたらします。

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

このスキルが回答する Flow に関する質問の「種類」です（重要なのは質問の種類であり、例はその一例です）。

• 「representor 上で Flow ポートを起動するにはどうすればよいですか？」 →

  configure +

  機能とモード。

• 「<match X, do Y> をパイプで表現するにはどうすればよいですか？」 →

  機能とモード

  • modify。

• 「このパイプ仕様は HW をプログラムしますか。それとも commit が失敗しますか？」 →

  安全ポリシー

  • test。

• 「観測されたトラフィックを調査するため、Flow カウンターを読み取るにはどうすればよいですか？」 →

  可観測性

  • debug。

• 「Flow ポートが起動しません — Failed to get hws cap / dest action ROOT … err -121。」 → デバイス配置に関する兆候です（パイプの問題ではありません）。SEPARATED_HOST / NIC モードの BlueField では、ステアリングプレーンは DPU Arm 上にあります。## 機能とモードのデバイス配置に関する箇条書き + ## configure のステップ 2 + ## debug のステップ 0 を参照してください。
• 「既存の doca-flow セットアップに、ハードウェアアクセラレーション対応のステートフルな5タプル接続追跡（aging、NAT）を追加するにはどうすればよいですか？」 →

  flow-ct +

  flow-ct。

対象読者

サポート対象の NVIDIA NIC/DPU にインストールされた /opt/mellanox/doca の DOCA を使い、パケットステアリングをプログラムするために doca_flow_* を呼び出すコードを記述する外部開発者（C/C++、または FFI 経由）が対象です。Flow は C ライブラリ（pkg-config モジュール doca-flow、パッケージ doca-sdk-flow）として提供され、サンプルは C で記述されています。他の言語を使う場合も、FFI 経由で同じ *.so にアクセスするため、このスキルは特定の言語に依存しません。

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

ユーザーが、DOCA がすでに /opt/mellanox/doca にインストールされている、サポート対象の NVIDIA NIC/DPU で、言語を問わず DOCA Flow を実際に操作する作業をしている場合に読み込みます。

• インストール済みデバイスで Flow ポート／representor を起動する。
• パイプを作成し、一致条件／アクションを定義し、エントリーを設定する。
• ハードウェアに設定する前に、パイプ仕様を検証する。
• トラフィック処理中に、エントリー／パイプごとのカウンターを読み取る。
• インストール済みの DOCA に含まれる Flow 機能／シンボルを確認する（ビルド時の基準は pkg-config --modversion doca-flow）。
• Flow 呼び出しで発生した DOCA_ERROR_* をデバッグする（設定ミスか、前提条件の不足か、このハードウェア／インストール環境で未サポートか）。
• Flow C ABI を使った C 以外のバインディング（Rust、Go、Python、…）を設計する。
• 既存のポートにステートフル CT（doca_flow_ct.h）を追加する（## flow-ct を参照）。

一般的な DOCA の概要、「ドキュメントの場所」、インストール構成、または Flow 以外のライブラリに関する質問では読み込まないでください。その場合は doca-public-knowledge-map/SKILL.md を使用してください。

このスキルの内容

これは薄いローダーです。実質的な内容は、次の 2 つの関連ファイルにあります。

• capabilities companion — このバージョンで Flow が表現できる内容（サポート対象の一致条件とアクションの種類、パイプ分割ルール、API の範囲とよく捏造される名前のガードリスト、Flow の DOCA_ERROR_* オーバーレイ、エントリー／パイプごとの可観測性の範囲、バージョンに関する注記、安全ポリシー、CT companion の範囲）。
• tasks companion — 対象となる 6 つの動詞（configure、build、modify、run、test、debug）のワークフローに加え、## flow-ct（ステートフル CT オーバーレイ）、## shared-resources（共有 encap／decap／カウンター／メーター／RSS／IPsec-SA／PSP オーバーレイ）、## rollback（パイプライン編集クラスのスナップショット）、## Command appendix、ルーティングのインストール／デプロイに関する質問向けの Deferred task verbs が含まれます。

このスキルは、DOCA が /opt/mellanox/doca にインストールされており、ユーザーが doca_dev を開けることを前提とします。DOCA のインストール、hugepages の設定、EAL の dv_flow_en devargs の準備は doca-setup/SKILL.md で扱います。Flow ポートの起動前にバイナリが必要とする hugepages／devargs の実行時前提条件は、## configure の手順 5 に記載されています。

このスキルに含めないもの

このスキルはエージェント向けのガイダンスであり、コード一式ではありません。事前作成済みの Flow アプリケーションソース、単独のビルドマニフェスト、samples/／bindings/／reference/ サブツリーは含みません。検証済みの Flow ソースは、同梱されている C サンプル /opt/mellanox/doca/samples/doca_flow/<name>/ です。エージェントはユーザーにその場所を案内し、doca-programming-guide/SKILL.md のサンプル変更ワークフローと ## build の Flow オーバーライドを使って、最小差分での編集を指示します。また、ユーザーのプロジェクト内で、ユーザーのインストール環境を対象に任意のマニフェストをビルドします。その際の基準は pkg-config --modversion doca-flow です。

読み込み順序

1. まずこのスキルを読み、質問が対象範囲内であることを確認します。
2. パイプ仕様のスキーマ、機能マトリックス、エラー分類、可観測性、安全ポリシーについては、capabilities companion を参照します。
3. 手順ごとのワークフローについては、tasks companion を参照します。

関連スキル

• doca-public-knowledge-map/SKILL.md — DOCA 公開ドキュメントのルーティングテーブルと、インストール済みパッケージのディスク上の構成。
• doca-setup/SKILL.md — 環境の準備、インストールの検証、および NGC DOCA コンテナーを使用する まだインストールしていない場合 の手順。
• doca-programming-guide/SKILL.md — すべてのライブラリに共通する DOCA の一般的なパターン：pkg-config + meson のビルドパターン、同梱サンプルを変更して最初のアプリを作成するワークフロー、 共通のライフサイクル、ライブラリ横断の DOCA_ERROR_* 分類体系、 およびプログラム側のデバッグ手順。このスキルでは、これらに Flow 固有の内容を追加します。
• doca-flow-tune/SKILL.md — プログラム済み状態の検査（読み取り専用）。
• doca-hardware-safety/SKILL.md — カードモードの切り替え（例：mlxconfig で SEPARATED_HOST から EMBEDDED_CPU へ変更）に必須のオーバーレイ。
• doca-debug/SKILL.md — 分野横断的なデバッグ手順 （インストール／バージョン／ビルド／リンク／ランタイム／プログラム／ドライバー）。