launch_emulator Utility - 2022.2 English

Vitis Unified Software Platform Documentation: Application Acceleration Development (UG1393)

Document ID

UG1393

Release Date

2022-12-07

Version

2022.2 English

For embedded platforms that have an Arm subsystem, the Vitis tool uses QEMU to emulate the PS subsystem. The QEMU processes must be run along with the RTL simulator process to emulate the entire system in hardware emulation. The launch_emulator.py is a utility which launches QEMU and manages the synchronization of the PL simulator processes. It launches QEMU and the simulation process with provided arguments. The Vitis IDE also calls this command when starting and stopping the emulator.

Tip: For help inside QEMU, press Ctrl + a h while in the emulator shell. To terminate the QEMU command, press Ctrl + a x while in the emulator shell.

For embedded platforms, the --package Options command generates scripts, launch_hw_emu.sh, or launch_sw_emu.sh to call the launch_emulator.py command with the required arguments based on the platform and the target application.

You can pass additional arguments to the launch_emulator utility from the command line when using the launch_hw_emu.sh or launch_sw_emu.sh wrapper scripts. Simply append the option to the command line when running the script. This allows you to customize the launch_emulator utility as needed to support your specific platform or application.

The following table shows the list of available options.

Table 1. Common Options for launch_emulator
Option	Accepted Value	Description
`-add-env ADD_ENV_CMD`	N/A	Specify additional Environment Variables for the emulation shell.
`-aie-sim-options`	AIE_SIM_OPTIONS file	Points to an AI Engine sim options file that has various AI Engine debug flags that are required for debugging the AI Engine SystemC module. Refer to Reusing AI Engine Simulator Options for more information. The options file should be specified with a relative path with respect to package.hw_emu/sim/behav_waveform/xsim/. Tip: This is optional and only applies to AI Engine designs.
`-enable-debug`	N/A	Debug mode opening two different XTERMs for QEMU and PL. Important: This is very useful for the batch mode users to understand the flow and handshake between the QEMU and PL process.
`-graphic-qemu`	N/A	Start the Quick Emulator(QEMU) in GUI mode
`-help`	N/A	Prints help message.
`-kernel-dbg`	`true`, `false`	Enable debug in SW_EMU. This is used only for software emulation.
`-pl-kernel-debug`	`true`, `false`	Enable debug for the PL kernel.
`-run-app`	<application_script_name>	Ensure that the application script is packaged using `--package.sd_file` option during package step. Only when it is packaged in `sd_card`, the application script is available to run after QEMU is up running and mounted. Tip: When using the `-run-app` option, all QEMU messages are initially written to a file called qemu_output.log inside the `package.hw_emu` or `package.sw_emu` folder, based on your emulation target, and then re-written to the console after some delay. This delay can cause you to think there is a problem with QEMU, but you can examine the contents of the qemu_output.log if needed.
`-timeout`	<n>	Terminates emulation after <n> seconds. The default value when -run-app is used is 4000 seconds. This means the application terminates after running for 4000 seconds without user intervention.
`-user-post-sim-script`	Path to Tcl script required to be done post simulation before quit	Creates Tcl for any post operations into a Tcl file and pass the Tcl script to this switch.
`-user-pre-sim-script`	Path to Tcl script	For first run, `launch_emulator.py` in GUI mode and add the signals that you want to observe. Copies the commands from the Tcl console and save into a Tcl script. From the next run, pass the Tcl script in batch mode, `launch_emulator.py -user-pre-sim-script <path_to_saved_tcl_script>`. Only supports the Vivado simulator (xsim).
`-verbose`	N/A	Enable additional debug messages
`-wcfg-file-path`	N/A	Specify the wcfg file created by the XSIM to open during GUI simulation
`-wdb-File`	Path to WDB file	Specify the wdb file to load. Please provide complete absolute path
`-x86-sim-options`	N/A	Points to the x86 simulation options file which has various AI Engine debug flags that are required for debugging the AI Engine Model. Used only for software emulation.
`-xtlm-aximm-log`	N/A	This switch generates xTLM AXI4 transaction logs for interface connection between two SystemC models (with information like address/data/size, etc.). While running the emulation log is available at (directory structure can vary based on `v++` options and simulator used): package.hw_emu/sim/behav_waveform/xsim/xsc_report.log
`-xtlm-axis-log`	N/A	This switch generates xTLM AXI4-Stream transaction logs for interface connection between two SystemC models. While running emulation log is available at (directory structure can vary based on `v++` options and simulator used): package.hw_emu/sim/behav_waveform/xsim/xsc_report.log

Table 2. Advanced Options for launch_emulator
Option	Accepted Value	Description
`-disable-host-completion-check`	N/A	Skip the check for host/test completion. Generally used in applications where python scripts check for the test completion status PASS/FAIL. By default, you search for "TEST PASSED" string when `-run-app` switch is used.
`-enable-tcp-sockets`	N/A	Enables TCP Sockets
`-kill`	<pid>	Kills a specified emulator process.
`-kill-pid-file`	N/A	Specifies the file to be used to kill the process. This file stores the group PID of the process. This might have been created using -pid-file.
`-no-reboot`	N/A	Exit QEMU instead of rebooting. Used to exit gracefully from QEMU by executing command `reboot -f` at the embedded Linux prompt.
`-no_build`	N/A	Enables a check of the build command without running the build process.
`-no_run`	N/A	Build but don't run the emulation.
`-ospi-image`	OSPI Image file	Specify an OSPI image file for booting.
`-pl-sim-args`	Arguments to simulator	These arguments gets appended to simulator command line. Alternative to `pm-sim-args-file`.
`-pmc-args`	Arguments to PMC	The PMC/PMU is emulated by `qemu-system-microblazeel`. Most common command line switches of the PMC are captured in pmc_args.txt. Instead of writing into a file called pmc_args.txt, you can directly provide all the arguments that need to be appended to the PMC command line. This is an alternative to `-pmc-args-file`. PMC/PMU arguments for specific devices can be found in Versal PS and PMC Arguments for QEMU and Zynq UltraScale+ MPSoC PS and PMU Arguments for QEMU. Tip: This option is not supported for Zynq-7000 devices.
`-pmc-args-file`	PMC QEMU arguments file name	Any options to be passed to PMU/PMC can be given in this file. The specific format is determined by the base file on your chosen platform. This is auto passed in the `v++` package generated script. PMC/PMU arguments for specific devices can be found in Versal PS and PMC Arguments for QEMU and Zynq UltraScale+ MPSoC PS and PMU Arguments for QEMU. Tip: This option is not supported for Zynq-7000 devices.
`-print-qemu-version`	N/A	Prints the version of QEMU being used.
`-qemu-args`	Arguments to QEMU	The PS is emulated by `qemu-system-aarch64`. Most common command line switches of the PS are captured in qemu_args.txt. Instead of writing into a file called qemu_args.txt, you can directly provide all the arguments that need to be appended to the QEMU command line. This is an alternative to `qemu-args-file`. PS arguments for specific devices can be found in Versal PS and PMC Arguments for QEMU and following sections for Zynq UltraScale+ MPSoC devices.
`-qemu-dtb`	<path_to_DTB_file>	`v++ --package` automatically creates a DTB file based on the addressing in the design and passes it to the `launch_emulator` command. This option lets you specify the DTB file to override the defaults. Note: Ensure the DTB is compatible with the noc_memory_config.txt file used.
`-qspi-high-image`	Specify QSPI high image file	The image file which is passed as a QEMU argument in the form of boot mode. This is auto passed in the `V++` package generated script. Required only when DUAL QSPI mode is used.
`-qspi-image`	Specify `qspi.bin`	The image file is passed as a QEMU argument in the form of boot mode. This is auto passed in the `V++` package generated script. Required only when you opt for QSPI mode.
`-qspi-low-image`	Specify QSPI low image file	The image file is passed as a QEMU argument in the form of boot mode. This is auto passed in the `V++` package generated script. Required only when DUAL QSPI mode is used.
`-result-string`	N/A	Result string searches for the status of test completion. Default = "TEST PASSED."
`-use-qemu-version-v4`	N/A	Use QEMU version 4.2

Table 3. Auto-Populated by V++ in Emulation Script
Option	Accepted Value	Description
`-aie-sim-config`	N/A	Points to the AI Engine sim config file that provides various AI Engine files that are required for the SystemC Model of AI Engine. This is auto passed by the `v++` package. Required for AI Engine designs.
`-boot-bh`	Path to BH file	Specify the boot BH file path
`-device-family`	7Series \| UltraScale \| Versal	Required to specify the device family for the platform. This is auto passed by the `v++` package generated scripts launch_hw_emu.sh or launch_sw_emu.sh based on the target chosen. This needs to be passed manually for direct usage of the `launch_emulator` command.
`-enable-prep-target`	N/A	Enable pre-process target.
`-forward-port`	<target> <host>	Forwards TCP port from target to host.
`-gdb-port`	Port number	QEMU waits for GDB connection on <port>.
`-noc-memory-config <path/to/noc_memory_config.txt>`	N/A	By default, `v++ --package` creates the NoC memory configuration based on the design configuration, and you can see this file parallel to simulation binaries. You can override this file by replacing the file specified in the simulation binary folder. Use the `-user-pre-sim-script` option to copy your noc_memory_config.txt file to the simulation binary area and to get the configuration applied.
`-pid-file`	File name	Write process ID to <file> for later use with `-kill`. Used by the Vitis software platform to kill once emulation is successful.
`-pl-sim-dir`	Simulation directory	Start the Programmable Logic Simulator by launching the scripts from this directory. This is auto passed in the `v++` package generated script. The tool expects a file called simulate.sh in the specified directory and will execute it to launch the PL simulator (for example, XSIM).
`-pl-sim-script`	Simulation script location	Advanced users can have one direct script to launch simulation (for example, Vivado users). When this option is given, run the script, other options are of no value.
`-platform-name`	NAME	The platform name
`-pmc-args-file`	PMC QEMU arguments file name	Any options to be passed to PMU/PMC can be given in this file. The specific format is determined by the base file on your chosen platform. This is auto passed in the `v++` package generated script. PMC/PMU arguments for specific devices can be found in Versal PS and PMC Arguments for QEMU and Zynq UltraScale+ MPSoC PS and PMU Arguments for QEMU. Tip: This option is not supported for Zynq-7000 devices.
`-pmc-dtb`	<path_to_DTB_file>	`v++ --package` automatically creates a device-tree binary (DTB) file based on the addressing in the design and passes it to the `launch_emulator` command. This option lets you specify the DTB file to override the defaults. Note: Ensure the DTB is compatible with the noc_memory_config.txt file used. PMC/PMU arguments for specific devices can be found in Versal PS and PMC Arguments for QEMU and Zynq UltraScale+ MPSoC PS and PMU Arguments for QEMU. Tip: This option is not supported for Zynq-7000 devices.
`-protoinst-File`	Path to ProtoInst file	Specify the protoinst file to load. Please provide complete absolute path
`-qemu-args-file`	PS QEMU Arguments file name	Any options to be passed to QEMU can be given in this file. This is specific format where you fetch the base file from the platform chosen. This is auto passed in the `v++` package generated script.
`-qemu-dtb`	<path_to_DTB_file>	`v++ --package` automatically creates a DTB file based on the addressing in the design and passes it to the `launch_emulator` command. This option lets you specify the DTB file to override the defaults. Note: Ensure the DTB is compatible with the noc_memory_config.txt file used.
`-sd-card-image`	Specify sd_card.img	The image file is passed as a QEMU argument in the form of boot mode. This is auto passed in the `V++` package generated script. Required only when SD mode is used.
`-t` \| `-target`	`sw_emu` or `hw_emu`	Specify to run `sw_emu` or `hw_emu`. Based on the target chosen in the `v++`, respective script is generated by the `v++` package. For `sw_emu` target, launch_sw_emu.sh is generated and for `hw_emu` target, launch_hw_emu.sh is generated.
`-xtlm-log-state`	WAVEFORM \| LOG \| BOTH	Option to specify what the XTLM Log should contain. It can contain the waveform, the text log, or both. This option is used only for hardware emulation.