Running the System on Embedded Processor Platform - 2025.2 English - UG1701

Use the xrt.ini file to configure various options applicable to emulation. There is an [Emulation] specific section in xrt.ini, as described in xrt.ini File .

Emulation for a system with the AI Engine can be useful in:

• Checking initial system behavior with a limited known data set
• Functional integration and debugging of PS, PL, and ADF graph using GDB
• Testing the system with external traffic generator using Python, or C++
• Running system with C-based models for RTL kernels
• Applying AI Engine simulation options through the aiesim_options.txt found in the aiesimulator_output directory

When launching hardware emulation, specify options for the AI Engine component according to the simulator being used. These options can be specified from the launch_hw_emu.sh script using the -aie-sim-options.

Reusing AI Engine Simulator Options

The AI Engine simulator generates an options file that lists the options used for simulating the AI Engine graph application. The options file is automatically generated when the AI Engine simulator is run. This helps reuse the AI Engine simulator options from the initial graph-level simulation later in the system-level hardware emulation. You can also manually edit the options file to specify other options as required. The following table lists the options that can be specified in the aiesim_options.txt file. This file is located in the aiesimulator_output directory and is created if the --dump-vcd option is used with the aiesimulator command. An example command line is as follows.

./launch_hw_emu.sh \
-aie-sim-options ${FULL_PATH}/aiesimulator_output/aiesim_options.txt

where ${FULL_PATH} must be the full path to the file or directory.

When creating a simulation option file manually it needs to follow the format of COMMAND=ARGUMENT, with each command being on a separate line. The following example shows best practice.

AIE_DUMP_VCD=foo

To view the AMD Vivado™ simulator waveform GUI, use the launch_hw_emu script with -g option, and also use the -g option during the v++ --link stage as well.

./launch_hw_emu.sh -g

When the emulation environment is fully booted and the Linux prompt is up, make sure to set the following environment variables in the QEMU environment to ensure that the host application works. These must also be set when running on hardware.

export XILINX_XRT=/usr
export LD_LIBRARY_PATH=/mnt/sd*1:
export XCL_EMULATION_MODE=hw_emu

Below are end-to-end steps to launch HW Emulation:

1. Set the desired runtime settings in the xrt.ini file.

   As described in xrt.ini File , the file specifies various parameters to control debugging, profiling, and message logging in XRT when running the host application and kernel execution. As described in Enabling Profiling in Your Application this enables the runtime to capture debugging and profile data as your application is running.

   The xrt.ini file, as well as any additional files required for running the application, must be included in the output files as explained in Packaging for Vitis Flow

   Tip: Be sure to use the v++ -g option when compiling your kernel code for emulation mode.
2. Launch the QEMU emulation environment by running the launch_hw_emu.sh script.

   The script is created in the emulation directory during the packaging process, and uses the launch_emulator.py command to setup and launch QEMU. When launching the emulation script you can also specify options for the launch_emulator.py command. Such as the -forward-port option to forward the QEMU port to an open port on the local system. This is needed when trying to copy files from QEMU as discussed in Step 5 below. Refer to launch_emulator Utility in the Vitis Reference Guide (UG1702) for details of the command.

   For AI Engine, specify the AI Engine Options for HW Emulation as described in above paragraph.

   Another example would be to specify launch_hw_emu.sh -enable-debug to configure additional XTERMs to be opened for QEMU and PL processes to observe live transcripts of command execution to aid in debugging the application. This is not enabled by default, but can be useful when needed for debug.

   Additionally, you can add more advanced options to log waveform data without having to launch emulation with the Vivado logic simulator GUI. An example command line is as follows.

   ./launch_hw_emu.sh \
   -user-pre-sim-script pre-sim.tcl

   The pre-sim.tcl contains Tcl commands to add waveforms or log design waveforms. For an example, for Tcl commands see Vivado Design Suite User Guide: Logic Simulation (UG900).

   Tip: Details on debugging techniques in Hardware Emulation can be found in Profile and Debug in Hardware Emulation.
3. Once the emulation environment is fully booted and the Linux prompt is up, mount and configure the QEMU shell with the required settings.

   The AMD embedded base platforms have rootfs on a separate EXT4 partition on the SD card. After booting Linux, this partition needs to be mounted. If you are running emulation manually, you need to run the following commands from the QEMU shell:

   mount /dev/mmcblk0p1 /mnt
   cd /mnt
   export LD_LIBRARY_PATH=/mnt:/tmp:$LD_LIBRARY_PATH
   export XCL_EMULATION_MODE=hw_emu
   export XILINX_XRT=/usr
   export XILINX_VITIS=/mnt

   Tip: You can set the XCL_EMULATION_MODE environment variable to hw_emu for hardware emulation. This configures the host application to run in emulation mode.
4. Run the application from within the QEMU shell.

   With the runtime initialization (xrt.ini), the XCL_EMULATION_MODE environment set, run the host executable with the command line as required by the host application. For example:

   ./host.elf kernel.xclbin

   Tip: This command line assumes that the host program is written to take the name of the xclbin file as an argument, as most AMD Vitis™ examples and tutorials do. However, your application can have the name of the xclbin file hard-coded into the host program, or can require a different approach to running the application.
5. After the application run has completed is generated, the xrt.run_summary can be found in the /mnt folder inside the QEMU environment. However, to view the file you must copy them from the QEMU Linux system back to your local system.
   Note: The files can be copied either from the Guest or Host machine using the scp command. Key terminology to notice here are Host and Guest. The Host machine is the machine hosting QEMU, and the Guest machine is the one with PetaLinux running on QEMU. Host-ip-address is the IP address of the machine from which QEMU is launched.
   1. Copying files from the Host machine:
      1. First, copy the required files from the root area to the petalinux (default) user home area using the following command from the Guest machine: cp -rf /mnt/<files> /home/petalinux/
      2. Switch from the default login user petalinux using the exit command
      3. Change the permission of the copied files using sudo chmod 755 <files>

      The files can be copied using the scp command from the Host machine as follows: scp -P <port-num> <guest-machine-user-name>@<host-ip-address>:<source-file> <dest-path>. For example: scp -P 1440 root@192.168.1.xxx:/mnt/xrt.run_summary.

      <port-num>: To copy Guest machine files to the Host, the Port number through which Host and Guest are connected is required. 1440 is the QEMU port to connect to the Guest port. The -forward-port 1440 22 is passed to the launch_emulator to map the Guest port to the Host port. Here, 22 is the Guest TCP port and 1440 is the Host port. Both ports are mapped. To access the Guest TCP services (on port 22), use the Host machine's mapped port (for example 1440). Accessing the Host's port 1440 means accessing Guest port 22.

      <guest-machine-user-name>The guest machine user name can be found by using the whoami command from the PetaLinux terminal.

      <host-ip-address>: The host IP address can be found with a Linux command such as nslookup <machine name> or hostname-i

      <source-file>: The path and name of the file you want to copy from the QEMU environment.

      <dest-path>: The destination path to copy the file to on the local system.

   2. Copying files from the Guest machine:

      You can copy from the guest machine using the scp command: scp <guest-file> <userid-of-hostmachine>@<host-ip-address>:<host's-dir-path> For example: scp /mnt/xrt.run_summary userabcd@192.168.1.xxx:~

6. When your application has completed emulation and you have copied the required files, press the Ctrl + a + x keys to terminate the QEMU shell and return to the Linux shell.
   Note: If you have trouble terminating the QEMU environment, you can kill the processes it launches to run the environment. The tool reports the process IDs (pids) at the start of the transcript, or you can specify the -pid-file option to capture the pids when launching emulation.

Viewing the Run Summary

After hardware emulation is launched and run with the above simulation options, the run summary is available as follows:

For AI Engine run summary generated inside <package_dir>/sim/behav_waveform/<simulator>/default.aierun_summary, the VCD file is generated at the same location, for example: <package_dir>/sim/behav_waveform/<simulator>/<vcd filename>.