launch_emulator Utility

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. launch_emulator.py Utility Options
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.
-aie-sim-options N/A 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.

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.
-config-file Configuration file (ini format) Configuration file that specifies options to use for the command.
-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.
-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.

-emu-data N/A <Additional emulation Data files>: AI Engine Kernel to run QEMU requires shim solution file.

Required for 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.
-forward-port <target> <host> Forwards TCP port from target to host.
-g | -graphic-xsim | -sim_gui N/A Start the Programmable Logic Simulator GUI.
-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.
-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-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 tool 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 (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.
-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 following sections for Zynq 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-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.
-ps-only N/A PS only emulation. No PL emulation
-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 devices.

-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.
-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".
-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.
-run-sim-in-gdb N/A Run Simulator in GDB.
-runtime c++/ocl Specify the runtime flow for C++ or OCL.
-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.
-timeout <n> Terminates emulation after <n> seconds.
-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).
-vivado $XILINX_VIVADO Sets the VIVADO_LOC and is used by simulate.sh to load simulation/c-model libraries
-wcfg-file-path N/A Specify the wcfg file created by the XSIM to open during GUI simulation
-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

Versal PS and PMC Arguments for QEMU

In the Versal™ device, the PS(a72) is emulated by qemu-system-aarch64 and PMC is emulated by qemu-system-microblazeel. Most common command line switches of PS are captured in qemu_args.txt and PMC command line switches are captured in pmc_args.txt.

Table 2. Versal Options for qemu_args.txt
Arg Name Value Description Source How to Extract the Info
-boot

mode=<boot-number>

Ex. for sd1 -boot mode=5

Specify boot mode on your platform:

  • qspi24 = 1
  • qspi32 = 2
  • sd0 = 3
  • sd1 = 5
  • emmc0 = 6
  • ospi = 8
 v++ -p DRC needed between CIPS enabled boot modes and v++ -p selection
-display none By default QEMU creates display for user I/O. This option disables the display Static Specify none to disable the display
-hw-dtb <ps-dtb-file> Device tree file which describes the PS (a72). The Vitis compiler --package command generates the dtb file and appends it to qemu-args.txt. v++ -p
-M arm-generic-fdt

This specifies the QEMU machine to create. arm-generic-fdt machine option tells QEMU to parse dtb for machine generation, passes by -hw-dtb user.dtb.

 Device specific Hard coded for Versal
-serial -serial null -serial null -serial mon:stdio

By default, QEMU connects invoking terminal to UART0 for user I/O operations. You can override this behavior by specifying this option. Versal platforms have four UARTs specified using positional arguments: the first two are for debug and the last two are UART0 and UART1.

To connect UART0 to the terminal, specify -serial null -serial null -serial mon:stdio which ignores debug related UARTS and connects to UART0 to terminal.

Similarly to connect only UART1 to terminal specify -serial null -serial null -serial null -serial mon:stdio

 Based on UARTs enabled on CIPS configuration.

The Versal device has four UARTs. The first two are debug related UARTs.

When enabling UART0: 
CONFIG.PS_UART0_PERIPHERAL_ENABLE = 1
CONFIG.PS_UART1_PERIPHERAL_ENABLE =0 or 1

Then specify -serial null -serial null -serial mon:stdio

When enabling only UART1: 
CONFIG.PS_UART0_PERIPHERAL_ENABLE = 0 
CONFIG.PS_UART1_PERIPHERAL_ENABLE = 1

Then specify: -serial null -serial null -serial null -serial mon:stdio
-sync-quantum Time in milliseconds Specifies how frequently QEMU will sync with the RTL simulator. Modifying this can have an impact on the speed of simulation. Static Hard coded for Versal devices (user need to change)

Versal CIPS has two Ethernet interfaces. Most of Xilinx Versal CIPS board has eth0 enabled. If no -net or -netdev is specified then QEMU by default enables eth0 and maps to user mode backend.

Table 3. Versal Options for pmc_args.txt
Switch Name Value Description Source of the Config How to Extract the Info
-M microblaze-fdt Specifies the QEMU machine to create. QEMU creates MicroBlaze with nodes from dtb. Static Hard coded for Versal Devices
-display none By default, QEMU creates display for user I/O. This option instructs QEMU that there is no need for display. Static Hard coded for Versal Devices
-device loader,file=<BOOT_bh.bin>,addr=0xf201e000,force-raw Specifies Boot header file with load address as 0xF201E000 (BOOT_bh.bin is loaded at address 0xF201E000). This is fixed argument in pmc_args.txt which is processed by v++ -p for final argument which has absolute path of BOOT_bh.bin file. BOOT_bh.bin is generated by v++ -p from final PDI. BOOT_bh.bin is directly loaded onto QEMU because there is no BOOT ROM access for QEMU to load boot header from PDI. v++ -pack v++ pack extracts BOOT_bh.bin and generates this switch
-device loader,file=<pmc_cdo.bin>,addr=0xF2000000,force-raw Specifies pmc_cdo.bin with load address as 0xF2000000. This is fixed argument in pmc_args.txt. This is processed by v++ -p for final argument which has absolute path of pmc_cdo.bin file. v++ -pack v++ pack extracts pmc_cdo.bin and generates this switch
-device loader,file=<plm.bin>,addr=0xF0200000,force-raw Specifies plm binary firmware with load address as 0xF0200000. This is a fixed argument in pmc_args.txt which is processed by v++ -p for final argument. This has an absolute path of plm.bin file. This plm is executed by PPU1 when it is out of reset. v++ -pack v++ pack extracts plm.bin and generates this switch
-device loader,addr=0xf0000000,data=0xba020004,data-len=4 -device loader,addr=0xf0000004,data=0xb800fffc,data-len=4 Specifies PPU0 process to be in boot loop. As there is no BOOTROM access for QEMU, PPU0 is put in bootloop which generally loads BOOT header from PDI to memory. Static Hard coded for Versal Devices
-device loader,addr=0xF1110624,data=0x0,data-len=4 -device loader,addr=0xF1110620,data=0x1,data-len=4 Makes PPU1 out of reset and puts in executing mode. Static Hard coded for Versal Devices
-hw-dtb <ps-dtb-file> dtb file which describes aout PS(a72). v++ pack generates this dtb file and appends to qemu-args.txt. v++ pack v++ pack generates dtb files based on DDR config on device

Zynq UltraScale+ MPSoC PS and PMU Arguments for QEMU

The Zynq UltraScale+ MPSoC PS(a53) is emulated by qemu-system-aarch64 and PMU is emulated by qemu-system-microblazeel. Most common command line switches of PS are captured in qemu_args.txt and PMC command line switches are captured in pmu_args.txt.

Table 4. Zynq UltraScale+ MPSoC Options for qemu_args.txt
Switch Name Value Description Source of the Config How to Extract the Info
-M arm-generic-fdt This specifies the QEMU machine to create. arm-generic-fdt machine option tells QEMU to parse dtb for machine generation, passes by -hw-dtb user.dtb. Static Hard-coded for Zynq devices
-serial mon:stdio -serial is a positional argument. Redirect the serial port to specified char dev (i.e., stdio, tcp port, file, etc.). Based on UART configuration on Zynq UltraScale+ MPSoC

Zynq has two UARTs.

When enabling UART0: 
CONFIG.PSU__UART0__PERIPHERAL__ENABLE = 1
CONFIG.PSU__UART1__PERIPHERAL__ENABLE = 0 or 1

Then specify: -serial mon:stdio

When enabling only UART1: 
CONFIG.PSU__UART0__PERIPHERAL__ENABLE = 0 
CONFIG.PSU__UART1__PERIPHERAL__ENABLE = 1

Then specify: -serial null -serial mon:stdio
-global xlnx,zynqmp-boot.cpu-num=0 Make the specified CPU come out of reset. Static Hard coded for Zynq devices
-net -net nic -net nic -net nic -net nic -net user

-net is positional argument. Initialize network interfaces gem3. Connect the specified network adapter to user mode network.

TIP: -net none will disable all Ethernet interfaces.
Static

Based on Ethernet configurations:

If gem0(eth0) is enabled: 
CONFIG.PSU__ENET0__PERIPHERAL__ENABLE =1

Then specify -net nic -net user

If gem1 is enabled: 
CONFIG.PSU__ENET1__PERIPHERAL__ENABLE = 1

Then specify -net nic -net nic -net user

If gem2 is enabled: 
CONFIG.PSU__ENET2__PERIPHERAL__ENABLE = 1

Then specify -net nic -net nic -net nic -net user

If gem 3 is enabled:
CONFIG.PSU__ENET3__PERIPHERAL__ENABLE = 1

Then specify -net nic -net nic -net nic -net nic -net user

TIP: If no -net (and/or -netdev) is mentioned then by default QEMU will enable the first Ethernet (gem0) and map it to user mode backend.
-m 4G Enabling 4 GB DDR on Zynq UltraScale+ MPSoC. Static Emulating full DDR on Zynq UltraScale+ MPSoC
-device loader,file=<bl31.elf>,cpu-num=0 Load bl31.elf file on A53 core 0. Static v++ --package should replace bl31.elf with absolute path of bl31.elf
-device loader,file=<u-boot.elf> Loading u-boot.elf. Static v++ --package should replace bl31.elf with absolute path of u-boot.elf
-hw-dtb <ps-dtb-file> dtb file which describes PS which is emulated by QEMU can be specified using -hw-dtb. Static

Hard coded for Zynq devices:

<ps-dtb-file>=/proj/xbuilds/HEAD_daily_latest/installs/lin64/Vitis/HEAD//data/emulation/dtbs/zynqmp/zynqmp-arm-cosim.dtb
Table 5. Zynq UltraScale+ MPSoC Options for pmu_args.txt
Switch Name Value Description Source of the Config How to Extract the Info
-M microblaze-fdt This specifies the QEMU machine to create. microblaze-fdt tells QEMU to parse dtb for machine generation, passes by -hw-dtb user.dtb. Static Hard coded for Zynq devices
-device loader,file=<pmufw.elf> Load pmufw.elf file on PMU RAM. Static Hard coded for Zynq devices
-machine-path <path-to-xsim-dir> Point -machine-path to folder to create shared RAM and remote-port sockets. Static launch_emulator command will set this machine path
-display none By default, QEMU creates display for user I/O. This option disables the display. Static Hard coded for Zynq devices
-hw-dtb <pmu-dtb-file> dtb file which describes PMU which is emulated by QEMU can be specified using -hw-dtb. Static <pmu-dtb-file>=/proj/xbuilds/HEAD_daily_latest/installs/lin64/Vitis/HEAD//data/emulation/dtbs/zynqmp/zynqmp-pmu.dtb
TIP: Although the file is called pmu_args.txt here, the file is specified for launch_emulator using the -pmc-args-file command.

Zynq-7000 PS Arguments for QEMU

Zynq-7000 PS(a9) is emulated by qemu-system-aarch64 QEMU binary. Most common command line switches of PS are captured in qemu_args.txt.

Table 6. Zynq-7000 Options for qemu_args.txt
Switch Name Value Description Source of the Config How to Extract the Info
-M arm-generic-fdt-7series Indicates the QEMU machine to create. arm-generic-fdt-7series tells QEMU to parse dtb for machine generation, passes by -hw-dtb user.dtb. Static Hard coded for Zynq devices
-serial -serial /dev/null -serial mon:stdio Redirect the serial port to specified char dev (i.e., stdio, tcp port, file, etc.) Based on the UART configuration of the Zynq IP.

Zynq has two UARTs.

When enabling UART0:
CONFIG.PCW_UART0_PERIPHERAL_ENABLE = 1 
CONFIG.PCW_UART1_PERIPHERAL_ENABLE = 0 or 1

Then specify: -serial mon:stdio

When enabling only UART1: 
CONFIG.PCW_UART1_PERIPHERAL_ENABLE = 1

Then specify: -serial null -serial mon:stdio
-device loader,addr=0xf8000008,data=0xDF0D,data-len=4 -device loader,addr=0xf8000140,data=0x00500801,data-len=4 -device loader,addr=0xf800012c,data=0x1ed044d,data-len=4 -device loader,addr=0xf8000108,data=0x0001e008,data-len=4 -device loader,addr=0xF800025C,data=0x00000005,data-len=4 -device loader,addr=0xF8000240,data=0x00000000,data-len=4 Register writes to SLCR block, to set PLL and CLK_CTRL regs (required for Linux). Static Hard coded for Zynq devices
-boot mode=5 Boot mode 5 is for SD boot. v++ -p
-kernel <u-boot.elf> Guest software to load during boot up. Static <u-boot.elf> is replaced with the absolute path of u-boot.elf from the target platform
-machine linux=on Make QEMU itself a loader of the Linux image. Static Hard coded for Zynq devices