launch_emulator ユーティリティ - 2022.1 日本語

Vitis 統合ソフトウェア プラットフォームの資料: アプリケーション アクセラレーション開発 (UG1393)

Document ID
UG1393
Release Date
2022-05-25
Version
2022.1 日本語

Arm サブシステム含むエンベデッド プラットフォームでは、Vitis ツールで QEMU を使用して PS サブシステムがエミュレートされます。QEMU プロセスは RTL シミュレータ プロセスと共に実行し、ハードウェア エミュレーションでシステム全体をエミュレートする必要があります。launch_emulator.py は、QEMU を起動し、PL シミュレータ プロセスの同期を管理するユーティリティです。QEMU とシミュレーション プロセスを指定した引数を使用して実行します。Vitis IDE は、エミュレーターを開始および停止するのにこのコマンドを呼び出します。

ヒント: QEMU 内部のヘルプを参照するには、エミュレーター シェルで Ctrl + a h を押します。QEMU コマンドを終了するには、エミュレーター シェルで Ctrl + a x を押します。

エンベデッド プラットフォームでは、プラットフォームおよびターゲット アプリケーションに必要な引数を使用して launch_emulator.py コマンドを呼び出すため、--package オプション コマンドで launch_hw_emu.sh または launch_sw_emu.sh スクリプトが生成されます。

launch_hw_emu.sh または launch_sw_emu.sh ラッパー スクリプトを使用する際、コマンド ラインで launch_emulator に追加の引数を指定できます。スクリプトを実行するときに、コマンド ラインにオプションを追加します。これにより、使用するプラットフォームまたはアプリケーションをサポートするために必要に応じて launch_emulator ユーティリティをカスタマイズできます。

次の表に、使用可能なオプションを示します。

表 1. launch_emulator の共通オプション
オプション 有効な値 説明
-add-env ADD_ENV_CMD なし エミュレーション シェルの追加の環境変数を指定します。
-aie-sim-options AIE_SIM_OPTIONS ファイル AI エンジン SystemC モジュールのデバッグに必要なさまざまな AI エンジン デバッグ フラグを持つ AI エンジン シミュレーション オプション ファイルを指定します。

オプション ファイルは、package.hw_emu/sim/behav_waveform/xsim/ を基準とした相対パスで指定する必要があります。

ヒント: このオプションは必須ではなく、AI エンジン にのみ適用されます。
-enable-debug 該当なし QEMU と PL に 2 つの異なる XTERM を開くデバッグ モード。
重要: これは、バッチ モードを使用する場合に、フローおよび QEMU と PL プロセス間のハンドシェイクを理解するのに便利です。
-graphic-qemu なし クイック エミュレーター (QEMU) を GUI モードで起動します。
-help 該当なし ヘルプ メッセージを表示します。
-kernel-dbg true, false SW_EMU でデバッグをイネーブルにします。これはソフトウェア エミュレーションにのみ使用されます。
-pl-kernel-debug true, false PL カーネルのデバッグをイネーブルにします。
-run-app <application_script_name> アプリケーション スクリプトがパッケージ ステップ中に --package.sd_file オプションを使用してパッケージされるようにします。アプリケーション スクリプトは、sd_card にパッケージされる場合にのみ、QEMU が実行されマウントされた後に実行できます。
ヒント: -run-app オプションを使用すると、すべての QEMU メッセージは、エミュレーション ターゲットに基づいて、package.hw_emu または package.sw_emu フォルダー内にある qemu_output.log というファイルに最初に書き込まれ、その後少し遅れてコンソールに書き出し直されます。この遅延が原因で、QEMU に問題があると考えられる場合があります。この場合、必要であれば、qemu_output.log の内容を確認できます。
-timeout <n> <n> 秒後にエミュレーションを終了します。-run-app が使用される場合のデフォルト値は 4000 秒です。つまり、ユーザーが介入することなく、アプリケーションが 4000 秒間実行された後に終了します。
-user-post-sim-script シミュレーション後に終了前に実行する必要のある Tcl スクリプトへのパス シミュレーション後に実行する操作を含む Tcl ファイルを作成し、そのファイルをこのオプションで指定します。
-user-pre-sim-script Tcl スクリプトへのパス 初回は GUI モードで launch_emulator.py を実行し、確認する信号を追加します。

Tcl コンソールからコマンドをコピーして Tcl スクリプトに保存します。

次の実行では、バッチ モードで Tcl スクリプトを渡します (launch_emulator.py -user-pre-sim-script <path_to_saved_tcl_script>)。

Vivado シミュレータのみサポートされます。

-verbose なし その他のデバッグ メッセージをイネーブルにします。
-wcfg-file-path 該当なし GUI シミュレーション中に開く XSIM で作成された wcfg ファイルを指定します。
-wdb-File WDB ファイルへのパス

読み込む wdb ファイルを指定します。完全な絶対パスを指定してください。

-x86-sim-options なし AI エンジン モデルのデバッグに必要なさまざまな AI エンジン デバッグ フラグを含む x86 シミュレーション オプション ファイルを指定します。ソフトウェア エミュレーションにのみ使用されます。
-xtlm-aximm-log なし このオプションは、2 つの SystemC モデル間のインターフェイス接続用の xTLM AXI4 トランザクション ログを生成します (アドレス/データ/サイズなどの情報を含む)。

実行中、エミュレーション ログは、次から入手できます (ディレクトリ構造は、使用する v++ オプションとシミュレータによって異なる場合があります)。

package.hw_emu/sim/behav_waveform/xsim/xsc_report.log

-xtlm-axis-log なし このオプションは、2 つの SystemC モデル間のインターフェイス接続用に xTLM AXI4-Stream トランザクション ログ生成します。

実行中、エミュレーション ログは、次から入手できます (ディレクトリ構造は、使用する v++ オプションとシミュレータによって異なる場合があります)。

package.hw_emu/sim/behav_waveform/xsim/xsc_report.log

表 2. launch_emulator のアドバンス オプション
オプション 有効な値 説明
-disable-host-completion-check 該当なし ホスト/テストが完了したかどうかのチェックをスキップします。通常は Python スクリプトがテスト完了ステータスの PASS/FAIL をチェックするアプリケーションで使用されます。

デフォルトでは、-run-app オプションを使用するときに「TEST PASSED」という文字列を検索します。

-enable-tcp-sockets なし TCP ソケットをイネーブルにします。
-kill <pid> 指定したエミュレーター プロセスを停止します。
-kill-pid-file なし プロセスの強制終了に使用するファイルを指定します。このファイルには、プロセスのグループ PID が保存されます。これは -pid-file を使用して作成された可能性があります。
-no-reboot 該当なし QEMU をリブートせずに終了します。組み込み Linux プロンプトで reboot -f コマンドを実行して QEMU を終了するために使用します。
-no_build なし ビルド プロセスを実行せずに、ビルド コマンドのチェックをイネーブルにします。
-no_run なし ビルドしますが、エミュレーションは実行しません。
-ospi-image OSPI イメージ ファイル 起動する OSPI イメージ ファイルを指定します。
-pl-sim-args シミュレータに渡す引数 シミュレータのコマンド ラインに追加する引数。pm-sim-args-file の代わりに使用します。
-pmc-args PMC に渡す引数

PMC/PMU は、qemu-system-microblazeel でエミュレートされます。PMC の一般的なコマンド ライン オプションのほとんどは、pmc_args.txt に記述されています。

pmc_args.txt というファイルに記述する代わりに、PMC コマンド ラインに追加する必要のあるすべての引数を直接指定できます。-pmc-args-file の代わりに使用します。

特定のデバイスの PMC/PMU 引数については、QEMU の Versal PS 引数と PMC 引数 および QEMU の Zynq UltraScale+ MPSoC PS および PMU 引数 を参照してください。

ヒント: このオプションは、Zynq-7000 デバイスではサポートされません。
-pmc-args-file PMC QEMU の引数を含むファイルの名前 PMU/PMC に渡す引数を含むファイル。特定の形式は、選択したプラットフォームのベース ファイルによって決まります。

これは、v++ パッケージで生成されるスクリプトで自動的に渡されます。

特定のデバイスの PMC/PMU 引数については、QEMU の Versal PS 引数と PMC 引数 およびQEMU の Zynq UltraScale+ MPSoC PS および PMU 引数 を参照してください。

ヒント: このオプションは、Zynq-7000 デバイスではサポートされません。
-print-qemu-version なし 使用される QEMU のバージョンを表示します。
-qemu-args QEMU に渡す引数

PS は、qemu-system-aarch64 でエミュレートされます。PS の一般的なコマンド ライン オプションのほとんどは、qemu_args.txt に記述されています。

qemu_args.txt というファイルに記述する代わりに、QEMU コマンド ラインに追加する必要のあるすべての引数を直接指定できます。qemu-args-file の代わりに使用します。

特定のデバイスの PS 引数については、QEMU の Versal PS 引数と PMC 引数 およびその後の Zynq デバイスのセクションを参照してください。

-qemu-dtb <path_to_DTB_file>

v++ --package は、デザイン内のアドレス指定に基づいて DTB ファイルを自動的に作成し、launch_emulator コマンドに渡します。このオプションを使用すると、デフォルトより優先される DTB ファイルを指定できます。

注記: DTB が使用されている noc_memory_config.txt ファイルと互換性があるようにします。
-qspi-high-image QSPI ハイ イメージ ファイル

イメージ ファイルは、ブート モードで QEMU 引数として渡されます。これは、V++ パッケージで生成されるスクリプトで自動的に渡されます。

DUAL、QSPI モードを使用している場合にのみ必要です。

-qspi-image SD カード イメージ ファイル (qspi.bin) イメージ ファイルは、ブート モードで QEMU 引数として渡されます。これは、V++ パッケージで生成されるスクリプトで自動的に渡されます。

QSPI モードを使用する場合にのみ必要です。

-qspi-low-image QSPI ロー イメージ ファイル イメージ ファイルは、ブート モードで QEMU 引数として渡されます。これは、V++ パッケージで生成されるスクリプトで自動的に渡されます。

DUAL、QSPI モードを使用している場合にのみ必要です。

-result-string 該当なし 結果の文字列は、テスト完了のステータスを検索します。デフォルト = "TEST PASSED".
-use-qemu-version-v4 なし QEMU バージョン 4.2 を使用します。
表 3. エミュレーション スクリプトで v++ によって自動入力
オプション 有効な値 説明
-aie-sim-config 該当なし AI エンジン の SystemC モデルに必要なさまざまな AI エンジン ファイルを提供する AI エンジン sim config ファイルを指定します。

これは、v++ パッケージにより自動的に渡されます。

AI エンジン デザインでは必須です。

-boot-bh BH ファイルへのパス ブート BH ファイル パスを指定します。
-device-family 7Series | UltraScale | Versal プラットフォームのデバイス ファミリを指定します。

これは、v++ パッケージで生成される launch_hw_emu.sh または launch_sw_emu.sh スクリプト (ターゲットによって異なる) で自動的に渡されます。

これは、launch_emulator コマンドを直接使用する場合は、手動で渡す必要があります。

-enable-prep-target なし prep target をイネーブルにします。
-forward-port <target> <host> TCP ポートをターゲットからホストに転送します。
-gdb-port ポート番号 QEMU が <port> ポートの GDB 接続を待ちます。
-noc-memory-config <path/to/noc_memory_config.txt> 該当なし デフォルトでは、v++ --package がデザイン コンフィギュレーションに基づいて NoC メモリ コンフィギュレーションを作成します。このファイルは、シミュレーション バイナリと並べて表示できます。このファイルは、シミュレーション バイナリ フォルダー内で指定したファイルを置き換えると上書きできます。-user-pre-sim-script オプションを使用して、noc_memory_config.txt ファイルをシミュレーションバイナリ ディレクトリにコピーし、適用されたコンフィギュレーションを取得します。
-pid-file ファイル名 後で -kill で使用するためプロセス ID をファイルに記述します。エミュレーションが問題なく実行された後、エミュレーションを停止するために Vitis ソフトウェア プラットフォームで使用されます。
-pl-sim-dir シミュレーション ディレクトリ スクリプトを実行してプログラマブル ロジック シミュレータを起動するディレクトリを指定します。これは、v++ パッケージで生成されるスクリプトで自動的に渡されます。指定したディレクトリに simulate.sh というファイルが含まれている必要があり、ツールはこれを実行して PL シミュレータ (XSIM など) を起動します。
-pl-sim-script シミュレーション スクリプトの場所 上級ユーザーは、シミュレーションを起動する直接スクリプトを 1 つ含むことができます (Vivado ユーザーなど)。

このオプションを指定してスクリプトを実行する場合、ほかのオプションは無視されます。

-platform-name NAME プラットフォーム名
-pmc-args-file PMC QEMU の引数を含むファイルの名前 PMU/PMC に渡す引数を含むファイル。特定の形式は、選択したプラットフォームのベース ファイルによって決まります。

これは、v++ パッケージで生成されるスクリプトで自動的に渡されます。

特定のデバイスの PMC/PMU 引数については、QEMU の Versal PS 引数と PMC 引数 およびQEMU の Zynq UltraScale+ MPSoC PS および PMU 引数 を参照してください。

ヒント: このオプションは、Zynq-7000 デバイスではサポートされません。
-pmc-dtb <path_to_DTB_file>

v++ --package は、デザイン内のアドレス指定に基づいてデバイス ツリー バイナリ (DTB) ファイルを自動的に作成し、launch_emulator コマンドに渡します。このオプションを使用すると、デフォルトより優先される DTB ファイルを指定できます。

注記: DTB が使用されている noc_memory_config.txt ファイルと互換性があるようにします。

特定のデバイスの PMC/PMU 引数については、QEMU の Versal PS 引数と PMC 引数 およびQEMU の Zynq UltraScale+ MPSoC PS および PMU 引数 を参照してください。

ヒント: このオプションは、Zynq-7000 デバイスではサポートされません。
-protoinst-File protoInst ファイルへのパス

読み込む protoinst ファイルを指定します。完全な絶対パスを指定してください。

-qemu-args-file PS QEMU の引数を含むファイルの名前 QEMU に渡す引数を含むファイル。これは特定のフォーマットで、選択したプラットフォームからベース ファイルをフェッチします。これは、v++ パッケージで生成されるスクリプトで自動的に渡されます。
-qemu-dtb <path_to_DTB_file>

v++ --package は、デザイン内のアドレス指定に基づいて DTB ファイルを自動的に作成し、launch_emulator コマンドに渡します。このオプションを使用すると、デフォルトより優先される DTB ファイルを指定できます。

注記: DTB が使用されている noc_memory_config.txt ファイルと互換性があるようにします。
-sd-card-image SD カード イメージ ファイル (sd_card.img) イメージ ファイルは、ブート モードで QEMU 引数として渡されます。これは、V++ パッケージで生成されるスクリプトで自動的に渡されます。

SD モードを使用している場合にのみ必要です。

-t | -target sw_emu または hw_emu sw_emu または hw_emu を実行するように指定します。

v++ で選択されたターゲットに基づいて、対応するスクリプトが v++ パッケージにより生成されます。

sw_emu ターゲットの場合は launch_sw_emu.sh が生成され、hw_emu ターゲットの場合は launch_hw_emu.sh が生成されます。

-xtlm-log-state WAVEFORM | LOG | BOTH

XTLM ログに含める内容を指定するオプションです。波形、テキスト ログ、またはその両方を含めることができます。このオプションはハードウェア エミュレーションにのみ使用されます。