This section contains commonly used options and commands when using QEMU with virtual AMD hardware.

A larger list of options can be found here.

Options

These options are passed by the command line when starting QEMU.

If using PetaLinux tools, these options can be passed in by using the --qemu-args "<options>" argument when booting your machine.
If using a multi-architecture system, such as Zynq UltraScale+ MPSoC or Versal Adaptive SoC, arguments can be passed into the MicroBlaze QEMU machine by using the --pmu-qemu-args "<options>" argument.

Option	Description	Example

Option

Description

Example

-accel tcg,thread=<multi|single>

Forces multi-threaded tiny code generator (MTTCG) to run or not run on QEMU. This means each VCPU runs on an individual host CPU thread.

This is enabled by default on systems where it is stable and does not need to be explicitly passed in.

Forcing MTTCG may cause incorrect emulation.

MTTCG can not be enabled with icount, since icount forces QEMU to run in a single thread

-accel tcg,thread=multi

Enables MTTCG

-accel tcg,thread=single

Disables MTTCG

-boot [order=<drives>][,once=<drives>][mode=<n>]

Specifies boot parameters when using U-Boot.

Boot pins	ZynqMP Boot Mode	Versal Boot Mode
1	QSPI24	QSPI24
2	QSPI32	QSPI32
3	SD0	SD0
4	NAND (unsupported in QEMU)	N/A
5	SD1	SD1
6	eMMC	eMMC
7	USB (unsupported in QEMU)	USB (unsupported in QEMU)
8	N/A	OSPI

-boot mode=5

Sets the value of boot mode pins to 5 (boot from SD1).

-chardev <backend>,id=<id>[,mux=on|off][,options]
-chardev help

Creates a character devices that allows communication between a QEMU front-end and back-end.

This can be thought of as a file descriptor that routes text from inside QEMU to outside QEMU.

-chardev socket,host=127.0.0.1,port=8887,id=pmu-console,server,nowait,mux=on

Creates a multiplexed chardev server socket on localhost, with port 8887 that has the name pmu-console.

-d <log item 1, ...> | help

Enables logging to stderr for all log items specified.

If help is specified, a list of available log items is printed.

See QEMU Module Debug Printing for more information on how to use -d.

-d guest_errors

Prints any guest errors that occur during emulation to stderr.

-d guest_errors,trace:m25p80_command_decoded

Prints any guest errors, and trace output for m25p80 decoded commands to stderr.

-D <log file>

Redirects stderr to log file.

-D out.log

Redirects stderr to out.log.

-device <driver>[,prop[=<value>][,...]]
-device help

Adds the device driver.
Properties and values depend on the driver being added.

Typically, when emulating AMD hardware with QEMU, this option is used to load software and bring CPUs out of reset by using the loader driver. See: QEMU Loader Options for more information.

-device loader,file=/path/to/software/bl31.elf,cpu-num=0

Loads bl31.elf and runs it on CPU 0

-device loader,addr=0xFD1A0104,data=0x0000000E,data-len=4

Writes 0x0000000E to the register 0xFD1A0104, which brings A53 CPU 0 out of reset on ZymqMP.

When writing data to an address, the order must be addr=<addr>,data=<data>,data-len=<len>

-display <type>

The type of display to be used

-display none

Specifies there's no display.

-drive [file=<path>][,if=<interface>]\
[,format=<format>][index=<index>]

Defines a new drive.
See: Storage Media for more information.

-drive file=/path/to/img/qemu_boot.img,if=sd,format=raw,index=1

Creates an SD drive at index 1 with the image qemu_boot.img.

-dtb <dtb path>

The hardware description for the QEMU machine. Anything that QEMU cannot emulate is discarded.

If a Linux kernel is present, the dtb is passed to it through a memory buffer. See: -dtb vs -hw-dtb for more detail.

-dtb /path/to/dtb/system.dtb

Speficies the QEMU hardware description to be system.dtb and passes it to the Linux Kernel (if present).

-gdb <host>:<port>

Opens a GDB server on host:port.

-gdb tcp:127.0.0.1:9001

Creates a GDB server on 127.0.0.1:9001

-global <property>=<val>

Sets driver properties for devices created by the machine model.

-global xlnx,zynqmp-boot.cpu-num=0

Releases A53 CPU 0 from reset.

-hw-dtb <dtb path>

The hardware description for the QEMU machine.
See: -dtb vs -hw-dtb for how this differs from the -dtb parameter.

-hw-dtb /path/to/dtb/zynqmp-qemu-multiarch-arm.dtb

Specifies the QEMU hardware description to be zynqmp-qemu-multiarch-arm.dtb.

-kernel <kernel img>

Specifies an image, such as a kernel or bare-metal image.

-kernel /path/to/kernel/pmu_rom_qemu_sha3.elf

Specifies the image pmu_rom_qemu_sha3.elf.

-m <memory size>

Allocates memory size bytes of RAM for the virtual machine.

By default, QEMU allocates 128MB of RAM.

-m 4G

This machine will have 4GB of RAM allocated

-m 512M

This machine will have 512MB of RAM allocated

-M <machine>

Specifies the machine architecture.

-M arm-generic-fdt

Specifies that this is an ARM-generic-fdt machine.

-M microblaze-fdt

Specifies that this is a microblaze-fdt machine.

-machine-path <dir>

Specifies a directory where QEMU creates shared memory files and named UNIX sockets.

When emulating AMD hardware with QEMU, this is used to share data between architectures in multiarch environments, or for co-simulation.

It is recommended you clear the -machine-path directory between boots. PetaLinux and Yocto tools do this for you.
See this section for more information.

-machine-path /tmp/qemu-shm

Specifies that /tmp/qemu-shm is where QEMU shared memory and UNIX sockets will be created.

When nic is specified, this option configures or creates an on-board network interface card and connects it either to the emulated hub, or to the netdev nd.

When user is specified, this option configures a host network back-end and connects it to the emulated default hub.

-net nic

Creates an on-board NIC.

-net user,id=eth0,tftp=/host/path/for/tftp

Creates a network back-end with the ID eth0 that has TFTP access to the host path
/host/path/for/tftp.

-nographic

This machine will have no graphic output.

Also passes in the -serial stdio option.

-nographic

Specifies there's no graphics and passes in -serial stdio as well.

-S

Pauses the machine on the first instruction.

Typically this is used with the gdb option to debug the boot sequence of your machine.

-S

Pauses the machine on the first instruction.

-s

Shorthand for -gdb tcp::1234

-s

Creates a GDB server on 127.0.0.1:1234

-serial <dev>

Connects the serial device to dev.

-serial mon:stdio

Connect this serial device to the QEMU monitor and STDIO.

-serial null

Don't connect this serial device

-serial chardev:pmu-console

Connect this serial device to the chardev pmu-console.

-dtb vs -hw-dtb

AMD QEMU supports two device tree options:

-hw-dtb is used for the hardware device tree binary that QEMU uses to generate the model. Hardware device tree binaries will have the name of the device it represents. For example, board-versal-ps-vc-p-a2197-00.dtb is for Versal and zcu102-arm.dtb for the ZCU102 board.
-dtb is generally a Linux device tree binary used for Linux kernel boots. With the DTB passed in with -dtb option, QEMU removes the nodes that it cannot emulate and later copies them to RAM for the kernel. AMD Linux kernel device tree binaries are typically named system.dtb.

For booting Linux on multi-arch platforms, such as Zynq Ultrascale+ MPSoC and Versal Adaptive SoC, we use the -hw-dtb option, since guest device tree loading is skipped by QEMU.
If both -hw-dtb and -dtb are used in multi-arch environments, the DTB passed in with -dtb is ignored.

For standalone (single-arch) flows, these two arguments are fully interchangeable; specify only one or the other.

This procedure is applicable only when -kernel is passed on QEMU command line.

For Zynq Ultrascale+ MPSoC and Versal Adaptive SoC in a multi-architecture environment, the QEMU DTB is different from the kernel system.dtb.

QEMU DTS are different for Zynq UltraScale+ MPSoC and Versal Adaptive SoC single and multi-architecture models. The following DTBs are available in PetaLinux project:

Zynq UltraScale+ MPSoC

Single-arch: zynqmp-qemu-arm.dtb
Multi-arch: zynqmp-qemu-multiarch-arm.dtb, zynqmp-qemu-multiarch-pmu.dtb

Versal Adaptive SoC

Single-arch: versal-qemu-ps.dtb
Multi-arch: versal-qemu-multiarch-ps.dtb, versal-qemu-multiarch-pmc.dtb

If building DTBs from source, the single-arch and multi-arch device trees will appear under path/to/dts-repo/LATEST/SINGLE_ARCH and path/to/dts-repo/LATEST/MULTI_ARCH respectively.

QEMU Loader Options

[-device loader,(file=<file_name>|data=<value>,data-len=4),[addr=<value>],[cpu-num=<value>],[force-raw=true]] ...

This (repeatable) argument configures the QEMU machine for boot.

The loader driver can perform the following tasks:

Load software or data into RAM sections
Set the CPU entry points
Release CPUs from reset
Write to registers

In Zynq Ultrascale+ MPSoC, by default, the six ARM CPUs (four ARM-A53 and two ARM-R5) are in reset by their respective reset controllers when no software is loaded.
You can use a combination of -device loader arguments to load software and setup the CPUs.

There are two basic modes for the loader argument: file mode and single transaction mode. Specify only one mode for each -device argument.
The following subsections describe these modes.

File Mode

In file mode, the loader accepts a file as data to load. The file can be in any format and is passed using the file=<file_name> sub-option.

If the file is an ELF or a U-Boot image, the file is parsed and the sections loaded into memory as specified by the image; otherwise, the file is assumed as a raw image and loaded accordingly as an image into memory.

When loading raw images, the address is specified with the addr=<value> argument. The default address is 0. The address is ignored if the file is an ELF or U-Boot image.

Optionally, you can specify a CPU using the cpu-num=<value> sub-option. Specifying cpu-num also sets the Program Counter (PC).

The CPU has a set entry point in the following situations:

For ELFs and U-Boot images, the entry point is set as specified by the image.
For raw images, the entry point is set to the start address.
If you do not specify a CPU, the bus for CPU0 loads images, but no program entry point is set.

There are cases where you might want to treat an ELF or a U-Boot image as a raw data image (particularly useful for testing bootloaders with ELF or U-Boot capability).
In this case, you can pass the force-raw=true sub-option to instruct the loader to treat the image as raw.
You must specify the addr, since the section information in the ELF and U-Boot images are ignored.

Single Transaction Mode

In single transaction mode, a single bus transaction occurs.

addr and data-len must be specified.
data-len must equal 4 (corresponding to a single 4-byte transaction).
addr must be 32-bit aligned.

Before the initial system reset for Zynq Ultrascale+ MPSoC or Versal Adaptive SoC, QEMU performs the specified bus transaction.

Optionally, you can specify a CPU using the cpu-num=<value> sub-option.
The list of CPU enumeration values for Zynq Ultrascale+ MPSoC and Versal Adaptive SoC are given below:

Value	Zynq Ultrascale+ MPSoC CPU

Value	Zynq Ultrascale+ MPSoC CPU
0	A53-0
1	A53-1
2	A53-2
3	A53-3
4	R5-0
5	R5-1

Value	Versal Adaptive SoC CPU

Value	Versal Adaptive SoC CPU
0	A72-0
1	A72-1
2	R5-0
3	R5-1

If you edit the /cpus node in the DTB, these enumerations change.

The single transaction occurs from the perspective of the specified CPU. If you do not specify a CPU, then the system assumes CPU0.

Storage Media

Several disk and storage media interfaces are modeled. You can pass each to a regular file(s) to use for stored data.
QEMU updates the files so the data can persist across multiple sessions.

Argument Format

-drive file=<image-path>, if=(mtd|sd|pflash),format=<fmt>,index=<value>[,readonly]

The argument allows specification of extra options such as marking the file as read-only.
The argument can also be used to specify the index of the device, allowing specifying files for devices in an order-independent way.

QSPI

QSPI is modeled with the Flash specified in DTS. The SPI flashes can connect in a single or dual-parallel arrangement.
The file size for each should match Flash model size.

If you are using only a single mode QSPI, then only one QSPI argument is needed.

For each drive, if an image is not provided, QEMU still models the flash, but initializes with NULL data and discards the data after QEMU exists.
Data can be written and read back within a single session in this case.

Creating a QSPI image and booting with QSPI is outlined here.

Flash Striper Utility

In parallel mode, the data that QSPI passes in for each flash is unique to that flash chip.
The QSPI controller also performs bit or byte striping in dual parallel mode, and because of this a special utility is needed to take a single QSPI data image and format it into two images.
The syntax is as follows:

flash_strip <input> <out1> <out0>
flash_strip_be <input> <out1> <out0>
flash_strip_bw <input> <out1> <out0>

Where:

flash_strip and flash_strip_be formats with bit striping.
flash_strip_be expects the flash data bits in big endian.
flash_strip_bw formats the output with byte wise striping.
<input> is a 128MB image for Zynq UltraScale+ or a 256MB image on Versal Adaptive SoC.
<out0> and <out1> are the two images with half the size of the input image (64MB or 128MB) passable to the -mtdblock arguments for QSPI.

The reverse is also possible, taking the two striped images and converting them back to a single 128MB or 256MB image as shown in the following command:

flash_unstrip <output> <in1> <in0>
flash_unstrip_be <output> <in1> <in0>
flash_unstrip_bw <output> <in1> <in0>

Building the Flash Striper utilities

The complete flash striper utility source code is available here.

QEMU Options and Commands