- 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 Embedded Platforms.
Tip: Be sure to use thev++ -g
option when compiling your kernel code for emulation mode. - Launch the QEMU emulation environment by running the launch_sw_emu.sh script or launch_hw_emu.sh script.
launch_sw_emu.sh -forward-port 1440 22
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 thelaunch_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 for details of the command.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. - 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 theXCL_EMULATION_MODE
environment variable tosw_emu
for software emulation, orhw_emu
for hardware emulation. This configures the host application to run in emulation mode. - 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. - After the application run has completed, it is possible to have files that
were produced by the runtime, such as opencl_summary.csv, opencl_trace.csv, and xrt.run_summary. These files can be found in the /mnt folder inside the QEMU environment. However,
to view these files 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.- Copying files from the Host machine:
- 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/
- Switch from the default login user
petalinux
using theexit
command - 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@172.55.12.26:/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 thelaunch_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 (i.e. 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 thewhoami
command from the PetaLinux terminal.<host-ip-address>
: The host IP address can be found with a linux command such asnslookup <machine name>
orhostname-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.
- First, copy the required files from the root area
to the
- 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@172.55.12.26:~
- Copying files from the Host machine:
- 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.
Recommended: The file size limit on your machine should either be set to
unlimited or a higher value (over 16 GB) because embedded HW Emulation can create files
with larger file size for memory.
Tip: Set up the command shell or
window as described in Setting Up the Vitis Environment prior to
running the builds.