For embedded platforms that have an Arm sub-system, 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 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.
| Option | Accepted Value | Description |
|---|---|---|
-aie-device-file-path
|
N/A | Pointer to the AI Engine array size information. |
-aie-shim-sol-path
|
N/A | Points to the AI Engine shim solution file that provides the AI Engine constraints required for the Kernel. |
-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 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 This needs to be passed manually for direct usage of the |
-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_memeory_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 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. The specific format is determined by the base file on your chosen platform. This is auto passed in the |
-ps-only
|
N/A | PS only emulation. No PL emulation |
-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 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. |
-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 For |
-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 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, 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 will generate 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
package.hw_emu/sim/behav_waveform/xsim/xsc_report.log |
-xtlm-axis-log
|
N/A | This switch will generate 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 package.hw_emu/sim/behav_waveform/xsim/xsc_report.log |