launch_emulator Utility

For embedded platforms that have an Arm sub-system, the Vitis tool uses QEMU to emulate the PS sub-system. The QEMU processes must be run along with the RTL simulator process to emulate the entire system in hardware emulation. The launch_emulator 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.

For embedded platforms, the --package Options command generates scripts, launch_hw_emu.sh, or launch_sw_emu.sh to call the launch_emulator 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. launch_emulator Utility Options
Option Accepted Value Description
-add-env "name=value" Specifies environment variables before launching qemu/pmc/simulator
-cardano $XILINX_VITIS/cardano Sets the value of XILINX_CARDANO
-config-file Configuration file (ini format) Configuration file that specifies the environment setup for the command
-device-family 7Series | UltraScale | UltraScale+ Required to specify the device family for the platform.

This is auto passed by the v++ package generates scripts launch_hw_emu.sh or launch_sw_emu.sh based on the target chosen.

Need to be passed explicitly for direct usage of launch_emulator tool.
-enable-debug N/A Debug mode opening two different XTERMs for QEMU and PL. This is very useful for the batch mode users to understand the flow and handshake between the QEMU and PL process.
-forward-port <target> <host> Forwards TCP port from target to host
-gdb-port Port number QEMU waits for GDB connection on <port>
-help N/A Prints help message
-kill <pid> Kills a specified emulator process
-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.
-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-args Arguments to simulator These arguments gets appended to simulator command line. Alternative to pm-sim-args-file.
-pl-sim-args-file Simulation arguments file name Any options to simulator toll can be given in this file
-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 (eg. 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.
-pmc-args Arguments to PMC The MicroBlaze QEMU is run to emulate the PMC. 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-args-file PMC QEMU arguments file name Any options to be passed to PMU/PMC 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-args Arguments to QEMU Instead of writing into a file called qemu_args.txt, you can directly provide all the arguments that needs to be appended to the QEMU command line. This is an alternative to qemu-args-file.
-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.
-qspi-high-image Specify QSPI high image file

The image file which will be 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.
-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.
-sim-gui N/A Starts the Programmable Logic Simulator in GUI to debug the design
-t / -target sw_emu -or- hw_emu Specifies 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.
-timeout <n> Terminates emulation after <n> seconds
-user-post-sim-script Path to Tcl script required to be done post simulation before quit Create 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 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, for example:

launch_emulator -user-pre-sim-script <path_to_saved_tcl_script>

Only supports the Vivado simulator (xsim).

-vivado $XILINX_VIVADO Sets the VIVADO_LOC and is used by simulate.sh to load simulation/c-model libraries
-xtlm-aximm-log N/A Even though you run the v++ with -g, you can view only the waveform. However, logs are disabled by default. At runtime, enable the log for AXI4 Memory Map transactions using this switch.
-xtlm-axis-log N/A Even though you run the v++ with -g, you can view only the waveform. However, logs are disabled by default. At runtime, enable the log for AXI4-Stream transactions using this switch.
TIP: For QEMU help, press Ctrl + A H while in the emulator.