doca-eth

DOCA Ethernet

例

• 「RX キューは起動していますが、パケットが届きません。」 — RX と TX はそれぞれ別の Core コンテキストです。doca_ctx_start() を 1 回呼び出しても、両方は起動しません。
• 「送信タスクがラインレートで AGAIN を返します。」 — キューの種類を変更する前に、_cap_* クエリに基づいてバーストサイズを決めてください。

手順

以下の読み込み順に従ってください。設定／ビルド／実行についてはタスク用の補足ファイルを開いてください。RX タイプの分類と送信機能については、機能用の補足ファイルを開いてください。補足ファイルをすべて開く必要はありません。

最初に確認すること： このスキルは、DOCA がすでにインストールされており、ユーザーがホストまたは DOCA を搭載した BlueField でパケットキューを実際に扱う作業を行うことを前提としています。ユーザーが何か（設定／ビルド／変更／実行／テスト／デバッグ）を行いたい場合は、タスク用の補足ファイルを開いてください。このバージョンで DOCA Ethernet キューが何を表現できるかという質問には、機能用の補足ファイルを開いてください。ユーザーがまだ DOCA をインストールしていない場合は、まず doca-setup/SKILL.md を案内してください。RX と TX は独立した Core コンテキストです。 doca_eth_rxq と doca_eth_txq は、それぞれ独自の doca_ctx_create／_start／_stop／_destroy を使用します。doca_ctx_start() を 1 回呼び出しても、両方は起動しません。「キューペア」に対して単一のライフサイクルを案内しないでください。ユーザーが「パケットを RX キューに届かせるにはどうすればよいですか」と尋ねている場合、答えは doca-flow/SKILL.md にあります。DOCA Ethernet はキューの機能を提供し、DOCA Flow はステアリングの機能を提供します。この 2 つは独立したライブラリです。

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

このスキルが回答するために設計された、DOCA Ethernet に関する質問のクラスと、それぞれの具体例です。エージェントは、具体例はそのクラスの一例にすぎないため、回答の要となるのはクラスであることを理解する必要があります。

• 「リプレゼンターまたは物理ポートで RX キューと TX キューを起動するにはどうすればよいですか？」 — 具体例：「初回テストのため、単一の BlueField リプレゼンターに doca_eth_rxq と doca_eth_txq をそれぞれセットアップする」。## configure の独立した Core コンテキスト（それぞれ個別に開始）と、## Capabilities and modes の RX / TX オブジェクト表で回答します。
• 「データ形状に合う RX タイプはどれですか？通常、循環、managed-recv のどれでしょうか？」 — 具体例：「事前割り当て済みのバッファリングに固定サイズのフレームを受信するラインレートのイングレス」。## Capabilities and modes の RX タイプの分類と、## configure の doca_devinfo に対する機能クエリのルール（doca_eth_rxq_cap_is_type_supported）で回答します。
• 「ユーザーコードから doca_eth_txq を通じてパケットを送信するにはどうすればよいですか？」 — 具体例：「パケット用の doca_buf を割り当ててペイロードを設定し、送信タスクを 1 つ送信して、完了イベントを待つ」。## Capabilities and modes の TX 送信パターンと、## modify のプロパティ設定ワークフローで回答します。
• 「キューは起動していますが、パケットが届きません。なぜでしょうか？」 — 具体例：「doca_eth_rxq は正常に起動したが、recv コールバックが一度も呼び出されない」。## Safety policy のステアリング依存ルールと、## configure のステップ 1 にある環境準備チェックリストで回答します。ステアリング側は doca-flow/SKILL.md に、プロミスキャスモード側は doca-setup/SKILL.md に案内します。
• 「この Ethernet 機能は、自分のデバイスとインストール済みの DOCA で利用できますか？」 — 具体例：「このデバイスは L3 チェックサムオフロードをサポートしているか」。## Capabilities and modes の doca_devinfo に対する機能クエリのルール（doca_eth_txq_cap_is_l3_chksum_offload_supported）と、## Version compatibility のバージョンおよびデバイスに応じた補足情報で回答します。
• 「Ethernet の呼び出しで発生したこの DOCA_ERROR_* は何を意味し、どのレイヤーが原因ですか？」 — 具体例：「高レートで eth_txq の送信タスクを実行中に doca_task_submit が返す DOCA_ERROR_AGAIN」。## Error taxonomy のライブラリ横断的な分類に対する Ethernet 固有の補足と、## debug のレイヤー別の手順で回答し、必要に応じて doca-debug/SKILL.md に案内します。

複数のレイヤーが症状の原因として考えられる場合に、根本原因のレイヤーを特定する方法。 下位から上位へ（インストール → バージョン → ビルド → リンク → ランタイム → プログラム → ドライバー）の順にたどり、TASKS.md の ## debug で各レイヤーに指定されている読み取り専用の確認を行います。確認に失敗した最も下位のレイヤーが根本原因です。そこを修正し、一度に 1 つだけ変数を変更してから、上位へ進む前に同じ確認を再実行します。RX キューが無反応の場合は、プログラムやドライバーが原因だと考える前に、ランタイムの前提条件 3 つ（デバイスへのアクセス、ポートの起動、キューへのトラフィックのステアリング）を確認します。

対象読者

このスキルは、DOCA Ethernet ライブラリを利用するアプリケーションを開発する外部開発者、つまり、BlueField または ConnectX デバイスの物理ポート、リプレゼンター、SF でラインレートのパケット I/O を行うために、doca_eth_rxq_* / doca_eth_txq_* を呼び出すコードを記述するユーザーを対象としています（C/C++ から直接呼び出す場合、または別の言語から FFI／バインディング経由で呼び出す場合を含みます）。DOCA Ethernet 自体に貢献する NVIDIA の開発者向けではありません。

対象言語。 DOCA Ethernet は、pkg-config のモジュール名が doca-eth の C ライブラリとして提供されています。付属のサンプルは C で記述されています。C および C++ の利用者が標準的なケースであり、タスクの補足資料にある具体例もこのケースを前提としています。その他の言語（Rust、Go、Python、…）の利用者も、FFI または言語固有のバインディングを通じて同じ *.so を利用します。その場合、このスキルはキューオブジェクトの分割、ライフサイクル、機能の検出、権限、RX タイプの分類、エラーの分類に関するガイダンスを言語に依存しない形で提供し、すべてのラッパーが最終的に呼び出す基準となるインターフェースとして、公開 C ABI をエージェントに案内します。

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

ユーザーが言語を問わず、DOCA Ethernet を実際に扱っているときに読み込みます。具体的には、次のような場合です。

• 物理ポート、レプリゼンタ、または SF に対して開いた doca_dev 上で doca_eth_rxq を初期化し、データの形状に基づいて doca_ctx_start() の前に通常型／サイクリック型／マネージド受信型の RX タイプを選ぶ場合。
• 同じ、または別の doca_dev 上で doca_eth_txq を初期化し、パケット doca_bufs のペイロードバッファーに対して送信タスクをポストする場合。
• doca_eth_rxq_set_*／doca_eth_txq_set_* で Ethernet キューのプロパティを読み取る、または設定し、doca_eth_rxq_cap_*／doca_eth_txq_cap_* でデバイスの機能（最大バーストサイズ、RX タイプのサポート、最大散布／収集長、チェックサムオフロードの有無）を照会する場合。
• ポートがアップしており、トラフィックが実際に選択した RX キューへステアリングされていることを確認する場合（DOCA Flow ルールを使う標準的な方法、またはカーネル側のプロミスキャスモードを使う手早い初回実行方法）。
• Ethernet キューを、より上位のデータプレーン（DOCA GPUNetIO による GPU パケット処理、カスタムのユーザー空間転送エージェント、またはすべてのパケットのコピーを取得するテレメトリーミラー）に接続する場合。
• Ethernet 呼び出しから返された DOCA_ERROR_*（ライフサイクル、権限、機能、送信キュー満杯、ドライバーより下位のエラー）や、キューごとのプログレスエンジンイベントをデバッグする場合。
• DOCA Ethernet の C ABI をラップする、C 以外のバインディング（Rust、Go、Python など）を設計または拡張する場合（ライフサイクル、キュー分割、RX タイプ、機能、権限に関するラッパーが遵守すべきルール）。

一般的な DOCA の概要、DOCA 自体のインストール、フロールールのプログラミング（doca-flow/SKILL.md を使用）、ホストと DPU 間の制御メッセージング（doca-comch/SKILL.md を使用）、または RDMA によるデータ転送（doca-rdma/SKILL.md を使用）には、このスキルを読み込まないでください。 DOCA のドキュメントの概要については、doca-public-knowledge-map/SKILL.md を使用してください。

このスキルの内容

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

• 機能に関する関連ファイル — このバージョンで DOCA Ethernet キューが実現できることを説明します。RX／TX オブジェクトの分割、RX タイプの分類（通常型／サイクリック型／マネージド受信型）、送信タスク／フレームの送信インターフェイス、機能照会インターフェイス（doca_eth_rxq_cap_*／doca_eth_txq_cap_*）、Ethernet エラーの分類（ライブラリ横断の DOCA_ERROR_* セットへの対応付け）、可観測性のインターフェイス（キューごとのプログレスエンジンイベント、機能スナップショット）、およびステアリング／権限／ポート状態の前提条件を制御する安全ポリシーを扱います。
• タスクに関する関連ファイル — 対象範囲内の 6 つの Ethernet 動詞（configure、build、modify、run、test、debug）について、手順を追ったワークフローを説明します。また、対象範囲外の質問を適切な次のスキルに案内する Deferred task verbs ブロックと、エージェントが繰り返し使用するコマンドをまとめた Command appendix も含まれています。

このスキルは、DOCA が標準の場所にすでにインストールされており、ユーザーが公開インストールプロファイルで想定される権限（通常は、ポートに対して doca_dev を開くための sudo、または mlnx グループへの所属）を持つホストまたは BlueField を前提としています。DOCA のインストールについては扱いません。その手順については doca-setup/SKILL.md を参照してください。

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

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

• あらゆる言語で書かれた、事前作成済みの DOCA Ethernet アプリケーションのソースコード。 検証済みの Ethernet ソースコードは、同梱されている /opt/mellanox/doca/samples/doca_eth/<name>/ の C サンプルです。エージェントの役割は、ユーザーをこれらのファイルに案内し、doca-programming-guide/SKILL.md にある共通のサンプル変更ワークフローに、## modify の Ethernet 固有の上書き設定を組み合わせて、最小限の差分で変更する方法を指示することです。
• スキル内に置かれたスタンドアロンのビルドマニフェスト（meson.build、CMakeLists.txt、Cargo.toml など）。エージェントは、pkg-config --modversion doca-eth を信頼できる情報源として、ユーザーのインストール済み DOCA を使い、ユーザーのプロジェクトディレクトリ内でビルドマニフェストを作成します。
• あらゆる種類の samples/、bindings/、または reference/ サブツリー。たとえ「reference」とラベル付けされていても、このスキルのツリー内にあるモックや不完全な成果物は誤解を招きます。ユーザーはそれをビルド可能なものとして受け取るでしょう。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内であることを確認します。
2. Ethernet の機能マトリックス、RX タイプの分類、送信 API、機能照会のルール、エラー分類、可観測性、安全ポリシーについては、機能のコンパニオンを参照してください。
3. 設定、ビルド、変更、実行、テスト、デバッグの段階的なワークフローについては、タスクのコンパニオンを参照してください。

どちらのコンパニオンファイルからも、相互にリンクしているほか、正規のバージョン処理ルールを記載した doca-version/SKILL.md、RX キューが依存するステアリング側の doca-flow/SKILL.md、さらに、適切な回答が「Ethernet 固有のガイダンス」ではなく「公開ドキュメントまたはインストール済みパッケージのレイアウトを調べる」である場合に参照する doca-public-knowledge-map/SKILL.md にリンクしています。

関連スキル

• doca-public-knowledge-map/SKILL.md — 公開されている DOCA ドキュメントソースすべてへのルーティング表と、インストール済み DOCA パッケージのディスク上のレイアウトを記載しています。Ethernet の URL スラッグは DOCA-Ethernet です。
• doca-setup/SKILL.md — 環境の準備、インストールの確認、ポート状態のチェック（devlink dev show、ip link）、doca_dev を開くために必要な権限とグループ所属について説明しています。このスキルは、これらの前提条件が満たされていることを想定しています。
• doca-version/SKILL.md — 正規の DOCA バージョン処理ルールを記載しています。このスキルの ## Version compatibility では、4 要素の一致ルールへのリンクに加え、Ethernet 固有のオーバーレイ（RX タイプの利用可能期間、デバイスに依存するチェックサムオフロード対応）のみを追加しています。
• doca-structured-tools-contract/SKILL.md — バンドルの構造化ツールの優先順位ルール（検出／優先／フォールバック／報告）を記載しています。タスクのコンパニオンにある「コマンド」付録は、この契約に準拠しています。
• doca-programming-guide/SKILL.md — すべてのライブラリに共通する DOCA の一般的なプログラミングパターンを記載しています。正規の pkg-config + meson ビルドパターン、同梱サンプルを変更して最初のアプリケーションを作る共通ワークフロー、共通のライフサイクル、ライブラリ間で共通する DOCA_ERROR_* の分類、プログラム側のデバッグ順序が含まれます。このスキルでは、その上に Ethernet 固有の内容を追加しています。
• doca-flow/SKILL.md — どのパケットをどの doca_eth_rxq に送るかを決定するステアリング API について説明しています。DOCA Ethernet 自体はステアリングを設定しません。空の RX キューは、ほぼ常に Flow ルールの欠落または誤りが原因であり、Ethernet の不具合ではありません。
• doca-debug/SKILL.md — 複数の領域にまたがるデバッグ手順（インストール／バージョン／ビルド／リンク／実行時／プログラム／ドライバー）を記載しています。RX タイプの不一致、送信キュー満杯時の再試行、ステアリングされずキューが空になる症状など、Ethernet 固有のデバッグ内容はこの手順に重ねて適用します。