doca-devemu

DOCA Device Emulation

例

• 「BlueField からホストにカスタム PCIe デバイスを公開したい。」 — これは対象範囲内です。PCI Generic／virtio-net／ virtio-fs を選択してください。ここでは SNAP や Virtio-net Service を起動しないでください。
• 「エミュレートしたデバイスが lspci に表示されません。」 — 変更を加える前に、 ファームウェアのエミュレーションタイプとホストドライバーを確認してください。 DPU 側のコードは変更しないでください。

手順

以下の「読み込み順」に従ってください。設定／エミュレート／ デバッグにはタスクの補足資料を開いてください。 サブライブラリと cap の照会には機能の補足資料を開いてください。 補足資料のファイルをすべて開かないでください。

最初に確認すること： このスキルでは、DOCA がホストと BlueField の両方にすでにインストールされており、 ユーザーが DPU 側からエミュレートした PCIe デバイスを実際に扱っている（エミュレートされた PCIe の接続面を介してホストのカーネルドライバーと通信するバックエンドを作成している）こと、 および作成したいエミュレートデバイスのクラスを把握していることを前提としています。 ユーザーが何かを実行（設定／ビルド／変更／実行／テスト／デバッグ）したい場合はタスクの補足資料を開いてください。 この DOCA バージョン＋BlueField の世代＋ファームウェアで Device Emulation が何を表現できるかという質問の場合は、機能の補足資料を開いてください。 ユーザーがまだ DOCA をインストールしていない場合は、まず doca-setup/SKILL.md に案内してください。何よりも先に、エージェントはユーザーを適切なサブライブラリに案内する必要があります。 DOCA Device Emulation は、PCI Generic（PCIe デバイスの生のエミュレーション）、virtio-net（エミュレートされた virtio ネットワークデバイス）、virtio-fs（エミュレートされた virtio ファイルシステムデバイス）を対象とする包括的なライブラリです。それぞれのサブライブラリには独自のコンテキスト、pkg-config モジュール、機能範囲があります。サブライブラリの選択ルールは、機能の補足資料に記載されています。 ライブラリではなくパッケージ化されたソリューションをユーザーが求めている場合（例：「自分でバックエンドを書かずに、ホストで NVMe SNAP を使いたい」、または*「管理された virtio-net デーモンを使いたい」*）は、 doca-public-knowledge-map/SKILL.md を介して DOCA SNAP Service／DOCA Virtio-net Service のガイドに案内してください。これらのサービスはこのライブラリを基盤として構築されており、このスキルの対象とは異なる成果物です。

対象ユーザー

このスキルの対象は、DOCA Device Emulation ライブラリを利用するアプリケーションを開発する外部開発者です。つまり、DPU 側のコードから doca_devemu_pci_*、 doca_devemu_virtio_*、または doca_devemu_vfs_* を直接 C／C++ で呼び出すか、別の言語から FFI／バインディングを介して呼び出して、ホストの既存のカーネルドライバーが実際の PCIe 周辺機器と同じように制御できるエミュレートされた PCIe デバイスをホストに公開するユーザーを指します。このスキルは、DOCA Device Emulation 自体に貢献する NVIDIA の開発者向けではありません。また、バックエンドを書く必要のない、パッケージ化されたエミュレートデバイスのデーモンを求めるユーザーにも適していません（DOCA SNAP Service と DOCA Virtio-net Service が、このライブラリを基盤とするパッケージ化された選択肢です）。

言語の範囲。 DOCA Device Emulation は C ライブラリとして提供されます。このスキルでは、3 つのサブライブラリをエンドツーエンドで扱います。ユーザーのエミュレーションクラスに応じて、インストール済みの適切な pkg-config モジュールを選択してください（機能の補足資料にあるサブライブラリ選択表を参照）。 /opt/mellanox/doca/samples/doca_devemu/ にある提供サンプルは C で記述されています。C および C++ の利用者が標準的なケースであり、タスクの補足資料にある実例もこの方法を前提としています。 その他の言語を使う利用者（Rust、Go、Python など）は、同じ *.so ファイルを FFI または言語固有のバインディングを介して使用します。その場合、このスキルでは、サブライブラリの選択、包括的なライフサイクル、機能の検出、権限、エラー分類に関するガイダンスを言語に依存しない形で提供し、ラッパーが最終的に呼び出す権威あるインターフェースとして公開 C ABI にエージェントを案内します。

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

ユーザーがDPU側で実践的なDOCA Device Emulation作業を行っている場合は、使用言語を問わずこのスキルを読み込みます。具体的には、次のような場合です。

• ユーザーに必要なDevice Emulationサブライブラリ（PCI Generic、 virtio-net、virtio-fs）を判断する場合 — どれを選ぶかという包括的な 問いが、このスキルの最初の重要なステップです。
• DPU上でサブライブラリごとのDOCA Coreコンテキストを初期化し （エミュレートするデバイスごとに、サブライブラリごとに1つ）、 ホストのPCIe ドライバーがやり取りするドアベル／DMAプリミティブを設定する場合。
• 特定の機能ビットやデバイス特性が利用可能だと決めつける 前に、アクティブなdoca_devinfoに対して doca_devemu_pci_cap_*、doca_devemu_virtio_cap_*、または doca_devemu_vfs_cap_*クエリファミリーを使用して、 サブライブラリごとの機能を確認する場合。
• doca-devemuを使って独自にバックエンドを作成するか、 このライブラリをすでにラップしているパッケージ済みサービス （DOCA SNAP Service／DOCA Virtio-net Service）を採用するかを選ぶ場合。
• doca_devemu_*の呼び出しから返されたDOCA_ERROR_*をデバッグする場合。 特に、ファームウェアレベルでエミュレーションタイプが有効になっていない、 BlueFieldの世代がそのサブライブラリ自体をサポートしていない、 DPU側のプロセスに権限がない、ホスト側のカーネルドライバーがバインドされていない というケースを切り分ける場合。
• デバイスエミュレーションサブライブラリのいずれかをラップする C以外のバインディング（Rust、Go、Pythonなど）を設計または拡張する場合 — ラッパーが守るべきサブライブラリの選択、包括的なライフサイクル、 機能検出、権限、およびエラー分類のルールを確認する場合。

一般的なDOCAの概要説明、DOCA自体のインストール、エミュレートするデバイスクラスの ホスト側カーネルドライバー（virtio-net／virtio-blk／virtio-fsの カーネルドライバーはホストカーネルに付属しており、DOCAの一部ではありません）、 パッケージ済みのSNAP／Virtio-netサービス（これらは個別のアーティファクトであり、 それぞれに独自のサービスガイドがあります）、または BlueFieldのデータパスにおける標準NICの動作については、このスキルを読み込まないでください （代わりにdoca-flow/SKILL.md + doca-eth/SKILL.mdを使用してください — Device Emulationは カスタムエミュレートデバイス向けであり、BlueField内蔵NICの 動作特性を調整するものではありません）。

このスキルでできること

これは薄いローダーです。本体には、次に読むべきファイルを選ぶために必要な概要だけを残しています。Device Emulation固有の実質的な内容は、2つの関連ファイルに記載されています。

• capabilities関連ファイル — このバージョン、このBlueField世代、このファームウェアでDevice Emulationが実現できること： 全体的なアーキテクチャ（ホストにはエミュレートされたPCIeデバイスが見え、DPUがバックエンドを実行します）、サブライブラリの選択ルール（PCI Generic、virtio-net、virtio-fs）、サブライブラリごとのCoreコンテキストの構造、ホストとDPUを橋渡しするドアベル／DMAプリミティブ、サブライブラリごとの機能クエリファミリー（doca_devemu_*_cap_*）、サブライブラリごとのpkg-configモジュール名、Device Emulationのエラー分類とライブラリ共通のDOCA_ERROR_*セットとの対応、可観測性の範囲、ライブラリとパッケージ済みサービスのどちらを選択するかのルール、環境の前提条件を適用する安全ポリシー（DPU側の権限、BlueFieldファームウェアレベルでのエミュレーションタイプの有効化、対象のエミュレーションクラスを実際にサポートするBlueField世代）。
• tasks関連ファイル — 対象範囲内の6つのDevice Emulation動詞（configure、build、modify、run、test、debug）について、手順を追ったワークフローを示します。さらに、対象範囲外の質問を適切な次のスキルへ案内するDeferred task verbsブロックもあります。

このスキルでは、ホストとBlueFieldの両方にDOCAが標準の場所へインストール済みであり、BlueFieldファームウェアでユーザーがビルドしたいエミュレーションタイプが有効になっており、ユーザーが公開インストールプロファイルで想定される権限（特に、PCIeレベルのエミュレーションを実行するためのDPU側のsudo権限）を持ち、ホストカーネルにビルド対象のエミュレートされたデバイスクラス用の標準ドライバーが含まれているホストとBlueFieldのペアを想定しています。DOCAのインストール、ファームウェアレベルの設定変更、ホスト側カーネルドライバーのインストールは対象外です。これらについてはdoca-setup/SKILL.mdを参照してください。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内（doca-devemuライブラリでビルドするカスタムのエミュレートされたPCIeデバイス）であることを確認してください（パッケージ済みのSNAP／Virtio-netサービス、ホスト側カーネルドライバー、標準的なNICの動作は対象外です）。
2. 全体的なアーキテクチャ、サブライブラリの選択ルール（PCI Generic、virtio-net、virtio-fs）、サブライブラリごとのCoreコンテキストの構造、ドアベル／DMAプリミティブ、サブライブラリごとの機能クエリルール、サブライブラリごとのpkg-configモジュール、ライブラリとパッケージ済みサービスの選択ルール、エラー分類、可観測性の範囲、安全ポリシーについては、capabilities関連ファイルを参照してください。
3. 手順を追ったワークフロー（configure、build、modify、run、test、debug）については、tasks関連ファイルを参照してください。

どちらの関連ファイルからも、相互にリンクされています。また、正規のDOCAバージョン処理ルール（選択したサブライブラリのpkg-configモジュール、ファームウェアレベルのエミュレーションスロット、doca_devemu_*_cap_*クエリのすべてが、「この環境でこのエミュレーションがサポートされているか」の判断に含まれるというDevice Emulation固有の補足付き）についてはdoca-version/SKILL.md、正しい回答が「Device Emulation固有のガイダンス」ではなく、「公開されているDOCA Device Emulationの概要ガイド、そこからリンクされているサブライブラリのガイド、DOCA SNAP／Virtio-net Serviceガイド、またはオンディスクのインストールレイアウトで確認する」である場合はdoca-public-knowledge-map/SKILL.mdを参照してください。

関連スキル

• doca-public-knowledge-map/SKILL.md — すべての公開 DOCA ドキュメントソースと、インストール済み DOCA パッケージのディスク上のレイアウトを網羅するルーティングテーブルです。Device Emulation の包括 URL は https://docs.nvidia.com/doca/sdk/DOCA-Device-Emulation/index.html です。 サブライブラリごとのガイドは包括ページからリンクされており、 パッケージに含まれる DOCA SNAP / Virtio-net サービスは DOCA Services の包括ページに別個のアーティファクトとして掲載されています。
• doca-setup/SKILL.md — 環境の準備、 インストールの検証、DPU 側の権限チェック、BlueField ファームウェアの設定（サブライブラリごとのエミュレーションタイプの有効化を含む）、および公開 NGC DOCA コンテナを使用する まだインストールしていない場合 の手順です。このスキルでは、前提条件が満たされていることに加え、ユーザーが選択したサブライブラリのファームウェアレベルのエミュレーションタイプが有効になっていることを前提とします。
• doca-version/SKILL.md — DOCA のバージョン処理に関する正式な ルールです。このスキルのバージョン互換性の補足では、 4 要素一致ルールへの相互リンクに加え、Device Emulation 固有のサブライブラリごとの pkg-config + doca_devemu_*_cap_* の補足を追加しています。
• doca-structured-tools-contract/SKILL.md — バンドルの構造化ツールに関する優先順位ルール（検出 / 優先 / フォールバック / 報告）です。タスクの補足資料にあるコマンドの付録は この契約に従います。
• doca-programming-guide/SKILL.md — すべてのライブラリで共通する DOCA の一般的なプログラミングパターンです。 正式な pkg-config + meson のビルドパターン、同梱サンプルを変更することから始める共通の最初のアプリケーション開発ワークフロー、共通の Core コンテキストのライフサイクル、ライブラリ間で共通する DOCA_ERROR_* の分類、およびプログラム側のデバッグ順序を扱います。 このスキルは、その上に Device Emulation 固有の内容を追加します。
• doca-comch/SKILL.md — PCIe 経由でホストプロセスと DPU プロセス間の コントロールプレーンチャネル が必要だが、ホストに DPU を標準のホストカーネルドライバーを備えたエミュレート済み PCIe デバイスとして認識させたくない場合に適したライブラリです。Device Emulation は、実在するように見える PCIe デバイスクラスの背後に DPU を隠します。Comch は明示的なホスト ↔ DPU 間の IPC です。
• doca-flow/SKILL.md および doca-eth/SKILL.md — カスタム エミュレート済み PCIe デバイスを公開するのではなく、BlueField に組み込まれた NIC の機能でトラフィックを制御したい場合に適したライブラリです。Device Emulation は、ホストが以前は認識していなかった 新しい エミュレート済み PCIe デバイス向けです。Flow / Eth は、BlueField が既に備える NIC の機能向けです。
• doca-debug/SKILL.md — インストール / バージョン / ビルド / リンク / ランタイム / プログラム / ドライバーを網羅する、分野横断的な デバッグ手順です。Device Emulation 固有のデバッグ （ファームウェアレベルのエミュレーションタイプが有効になっていない、サブライブラリの選択ミス、ホストカーネルドライバーがエミュレート済みデバイスにバインドしない、virtio 機能のネゴシエーション失敗） は、この手順に重ねて適用します。