QEMU Documentation

https://www.qemu.org/docs/master/
Admin
QEMU is a generic and open source machine emulator and virtualizer. It can emulate a large number of...
Tokens:1,549,463
Snippets:10,152
Trust Score:9.7
Update:1 day ago
Show doc for...
Tokens:
Raw
### Quickstart: run docker-test-build@debian

Source: https://www.qemu.org/docs/master/devel/testing/main.html

Starts a container test build using the 'debian' image. The image is downloaded and initialized automatically, and the 'test-build' job is executed.

```make
make docker-test-build@debian
```

--------------------------------

### Build and run system example

Source: https://www.qemu.org/docs/master/about/emulation.html

Commands to install dependencies, clone the qemu-linux-stack repository, build the system image, run it with QEMU, and generate a uftrace trace. The trace.sh script collects symbols automatically.

```bash
# Install dependencies
$ sudo apt install -y podman qemu-user-static

$ git clone https://github.com/p-b-o/qemu-linux-stack
$ cd qemu-linux-stack
$ ./build.sh

# system can be started using:
$ ./run.sh /path/to/qemu-system-aarch64

# generate a uftrace for execution (collect symbols automatically)
$ ./trace.sh /path/to/qemu-system-aarch64
# show output log to read timestamps
$ cat uftrace.data/exec.log
# generate final trace (compressed) for perfetto
$ ./perfetto.sh <start_timestamp> <end_timestamp> ~/trace.gz
```

--------------------------------

### Docker installation and verification

Source: https://www.qemu.org/docs/master/devel/testing/main.html

Commands to install Docker, start the service, and verify it is ready by running 'docker ps' which should print an empty table.

```bash
$ sudo yum install docker
$ # or `apt-get install docker` for Ubuntu, etc.
$ sudo systemctl start docker
$ sudo docker ps
```

--------------------------------

### migrate-incoming command examples with uri and channels

Source: https://www.qemu.org/docs/master/interop/qemu-qmp-ref.html

Examples of the QMP migrate-incoming command. QEMU must be started with -incoming defer. The uri and channels arguments are mutually exclusive; exactly one must be present. The channels list is restricted to one item. The uri example uses tcp:0:4446. The channels examples use socket (inet), exec, and rdma transports.

```json
-> { "execute": "migrate-incoming",
     "arguments": { "uri": "tcp:0:4446" } }
<- { "return": {} }

-> { "execute": "migrate-incoming",
     "arguments": {
         "channels": [ { "channel-type": "main",
                         "addr": { "transport": "socket",
                                   "type": "inet",
                                   "host": "10.12.34.9",
                                   "port": "1050" } } ] } }
<- { "return": {} }

-> { "execute": "migrate-incoming",
     "arguments": {
         "channels": [ { "channel-type": "main",
                         "addr": { "transport": "exec",
                                   "args": [ "/bin/nc", "-p", "6000",
                                             "/some/sock" ] } } ] } }
<- { "return": {} }

-> { "execute": "migrate-incoming",
     "arguments": {
         "channels": [ { "channel-type": "main",
                         "addr": { "transport": "rdma",
                                   "host": "10.12.34.9",
                                   "port": "1050" } } ] } }
<- { "return": {} }
```

--------------------------------

### Run a microvm-based VM with default options

Source: https://www.qemu.org/docs/master/system/i386/microvm.html

Example command to start a microvm VM with default machine-specific options, using the legacy ISA serial device as console. It boots a host-side kernel with an initrd, uses virtio-blk and virtio-net devices.

```bash
$ qemu-system-x86_64 -M microvm \
   -enable-kvm -cpu host -m 512m -smp 2 \
   -kernel vmlinux -append "earlyprintk=ttyS0 console=ttyS0 root=/dev/vda" \
   -nodefaults -no-user-config -nographic \
   -serial stdio \
   -drive id=test,file=test.img,format=raw,if=none \
   -device virtio-blk-device,drive=test \
   -netdev tap,id=tap0,script=,downscript= \
   -device virtio-net-device,netdev=tap0
```

--------------------------------

### blockdev-backup QMP example

Source: https://www.qemu.org/docs/master/interop/qemu-storage-daemon-qmp-ref.html

Example of the blockdev-backup command. It starts a point-in-time copy of a block device. The example shows a full sync backup from 'src-id' to 'tgt-id'.

```json
-> { "execute": "blockdev-backup",
     "arguments": { "device": "src-id",
                    "sync": "full",
                    "target": "tgt-id" } }
<- { "return": {} }
```

--------------------------------

### Start vhost-user-bridge daemon

Source: https://www.qemu.org/docs/master/system/devices/virtio/vhost-user-contrib.html

Command to start the vhost-user-bridge daemon with a Unix socket and local/remote addresses. Used as the first step in the example.

```bash
$ vhost-user-bridge -u /tmp/vubr.sock \
                    -l 127.0.0.1:4444 \
                    -r 127.0.0.1:5555
```

--------------------------------

### bootfile option example with tftp

Source: https://www.qemu.org/docs/master/system/invocation.html

Example using pxelinux to network boot a guest from a local directory via TFTP.

```bash
qemu-system-x86_64 -hda linux.img -boot n -device e1000,netdev=n1 \
    -netdev user,id=n1,tftp=/path/to/tftp/files,bootfile=/pxelinux.0
```

--------------------------------

### QEMU startup command for S390 CPU topology

Source: https://www.qemu.org/docs/master/devel/s390-cpu-topology.html

Example command to start QEMU with 4 CPUs, where CPU[0] is defined by -smp and has default values. It enables KVM, sets the CPU model to z14 with ctop=on, and defines a topology with 3 drawers, 3 books, 2 sockets, 2 cores, and maxcpus=36. Additional CPUs are added via -device options with specific core-ids and entitlements.

```bash
qemu-system-s390x \
   -enable-kvm \
   -cpu z14,ctop=on \
   -smp 1,drawers=3,books=3,sockets=2,cores=2,maxcpus=36 \
   -device z14-s390x-cpu,core-id=19,entitlement=high \
   -device z14-s390x-cpu,core-id=11,entitlement=low \
   -device z14-s390x-cpu,core-id=12,entitlement=high \
  ...
```

--------------------------------

### blockdev-snapshot QMP example

Source: https://www.qemu.org/docs/master/interop/qemu-storage-daemon-qmp-ref.html

Example of the blockdev-snapshot command, which takes a snapshot of a block device by installing 'node' as the backing image of 'overlay'. The example shows the required blockdev-add command followed by the blockdev-snapshot command and their returns.

```json
-> { "execute": "blockdev-add",
     "arguments": { "driver": "qcow2",
                    "node-name": "node1534",
                    "file": { "driver": "file",
                              "filename": "hd1.qcow2" },
                    "backing": null } }

<- { "return": {} }

-> { "execute": "blockdev-snapshot",
     "arguments": { "node": "ide-hd0",
                    "overlay": "node1534" } }
<- { "return": {} }
```

--------------------------------

### Example: loading an ELF file for CPU0 to boot

Source: https://www.qemu.org/docs/master/system/generic-loader.html

Example command that loads an ELF file and sets CPU0's PC to the entry point, making it the boot image.

```shell
-device loader,file=./images/boot.elf,cpu-num=0
```

--------------------------------

### Start vhost-user daemon with virtio-foo

Source: https://www.qemu.org/docs/master/system/devices/virtio/vhost-user.html

Command to start a vhost-user daemon, using virtio-foo as an example. The daemon connects to QEMU via a socket at the specified path.

```bash
$ virtio-foo --socket-path=/var/run/foo.sock $OTHER_ARGS
```

--------------------------------

### qtest_qemu_args

Source: https://www.qemu.org/docs/master/devel/testing/qtest.html

Return the command line used to start QEMU, sans binary.

```APIDOC
## qtest_qemu_args

### Description
Return the command line used to start QEMU, sans binary.

### Signature
gchar *qtest_qemu_args(const char *extra_args)

### Parameters
- **extra_args** (const char *) - Required - Other arguments to pass to QEMU.

### Return
gchar* - The command line used to start QEMU, sans binary.
```

--------------------------------

### query-hotpluggable-cpus example for s390x machine

Source: https://www.qemu.org/docs/master/interop/qemu-qmp-ref.html

Example QMP command and response for query-hotpluggable-cpus on an s390x machine started with -smp 1,maxcpus=2. Shows the request and the returned list of HotpluggableCPU objects.

```qmp
-> { "execute": "query-hotpluggable-cpus" }
<- {"return": [
     { "props": { "core-id": 0 }, "type": "s390x-cpu",
       "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
   ]}
```

--------------------------------

### Configure QEMU with --enable-qatzip

Source: https://www.qemu.org/docs/master/devel/migration/qatzip-compression.html

Example configure command to build QEMU with QATzip support. Use this when building QEMU to enable the QATzip compression method for migration.

```bash
configure –target-list=x86_64-softmmu –enable-kvm --enable-qatzip
```

--------------------------------

### drive-mirror QMP command example

Source: https://www.qemu.org/docs/master/interop/qemu-storage-daemon-qmp-ref.html

Example of the drive-mirror QMP command, showing how to start mirroring a block device's writes to a new destination. The example uses device 'ide-hd0', target '/some/place/my-image', sync 'full', and format 'qcow2'. The expected response is an empty return object.

```json
-> { "execute": "drive-mirror",
     "arguments": { "device": "ide-hd0",
                    "target": "/some/place/my-image",
                    "sync": "full",
                    "format": "qcow2" } }
<- { "return": {} }
```

--------------------------------

### migrate-start-postcopy example

Source: https://www.qemu.org/docs/master/interop/qemu-qmp-ref.html

Example QMP exchange for the migrate-start-postcopy command, showing the request and an empty return.

```qmp
-> { "execute": "migrate-start-postcopy" }
<- { "return": {} }
```

--------------------------------

### query-hotpluggable-cpus example for pseries machine

Source: https://www.qemu.org/docs/master/interop/qemu-qmp-ref.html

Example QMP command and response for query-hotpluggable-cpus on a pseries machine started with -smp 2,cores=2,maxcpus=4 -cpu POWER8. Shows the request and the returned list of HotpluggableCPU objects.

```qmp
-> { "execute": "query-hotpluggable-cpus" }
<- {"return": [
     { "props": { "core-id": 8 }, "type": "POWER8-spapr-cpu-core",
       "vcpus-count": 1 },
     { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
       "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
   ]}
```

--------------------------------

### Start new VM based on template with memory-backend-file (readonly=on, rom=off)

Source: https://www.qemu.org/docs/master/system/vm-templating.html

Command-line example to create a 2GB VM based on the existing 2GB file 'template'. Requires memory-backend-file with share=off (implicit), readonly=on, and rom=off. Other VM state must be restored separately.

```shell
qemu-system-x86_64 [...] -m 2g \
    -object memory-backend-file,id=pc.ram,mem-path=template,size=2g,readonly=on,rom=off,... \
    -machine q35,memory-backend=pc.ram
```

--------------------------------

### Start guest with secure boot options

Source: https://www.qemu.org/docs/master/system/s390x/secure-ipl.html

QEMU command line to start an s390x guest with secure boot enabled and specify the certificate path.

```bash
qemu-system-s390x -machine s390-ccw-virtio,secure-boot=on,boot-certs.0.path=cert.pem ...
```

--------------------------------

### Debug migration stream with analyze-migration.py

Source: https://www.qemu.org/docs/master/devel/migration/best-practices.html

Example usage of the analyze-migration.py script to analyze a migration stream. The example shows starting QEMU, migrating to a file, quitting, and then running the script to output a JSON representation of the migration data.

```shell
$ qemu-system-x86_64 -display none -monitor stdio
(qemu) migrate "exec:cat > mig"
(qemu) q
$ ./scripts/analyze-migration.py -f mig
{
  "ram (3)": {
      "section sizes": {
          "pc.ram": "0x0000000008000000",
...
```

--------------------------------

### Configure QEMU with --enable-qpl

Source: https://www.qemu.org/docs/master/devel/migration/qpl-compression.html

Build QEMU with QPL compression support by passing --enable-qpl to the configure script. The example also includes --target-list=x86_64-softmmu and --enable-kvm.

```bash
configure –target-list=x86_64-softmmu –enable-kvm --enable-qpl
```

--------------------------------

### ivshmem server and doorbell device setup

Source: https://www.qemu.org/docs/master/system/devices/ivshmem.html

Commands to start the ivshmem-server and then launch QEMU instances with ivshmem-doorbell for interrupt support. The server must be started first, and the QEMU arguments must match the server's path and vectors.

```bash
# First start the ivshmem server once and for all
ivshmem-server -p pidfile -S path -m shm-name -l shm-size -n vectors
```

```bash
# Then start your qemu instances with matching arguments
qemu-system-x86_64 -device ivshmem-doorbell,vectors=vectors,chardev=id
                 -chardev socket,path=path,id=id
```

--------------------------------

### Start source QEMU with monitor

Source: https://www.qemu.org/docs/master/system/devices/net.html

Starts QEMU with a monitor to send the migrate command. Replace placeholders with actual options.

```bash
qemu-system-x86_64 [...OPTIONS...] [...VHOST USER OPTIONS...] -monitor stdio
```

--------------------------------

### Get vhost_virtqueue status for vhost-vsock

Source: https://www.qemu.org/docs/master/interop/qemu-qmp-ref.html

Example QMP command to retrieve vhost_virtqueue status for a vhost-vsock device. The command is unstable/experimental and returns a VirtVhostQueueStatus object.

```json
 -> { "execute": "x-query-virtio-vhost-queue-status",
      "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
                     "queue": 0 }
    }
 <- { "return": {
          "avail-phys": 5182261248,
          "name": "vhost-vsock",
          "used-phys": 5182261568,
          "avail-size": 262,
          "desc-size": 2048,
          "used-size": 1030,
          "num": 128,
          "call": 0,
          "desc-phys": 5182259200,
          "kick": 0
      }
    }
```

--------------------------------

### Boot order examples with -boot

Source: https://www.qemu.org/docs/master/system/invocation.html

Three examples showing how to set boot order: network first then hard disk, boot from CD-ROM once, and boot with a splash picture for 5 seconds. The legacy format '-boot drives' is discouraged.

```shell
# try to boot from network first, then from hard disk
qemu-system-x86_64 -boot order=nc
```

```shell
# boot from CD-ROM first, switch back to default order after reboot
qemu-system-x86_64 -boot once=d
```

```shell
# boot with a splash picture for 5 seconds.
qemu-system-x86_64 -boot menu=on,splash=/root/boot.bmp,splash-time=5000
```

--------------------------------

### Get vhost_virtqueue status for vhost-crypto

Source: https://www.qemu.org/docs/master/interop/qemu-qmp-ref.html

Example QMP command to retrieve vhost_virtqueue status for a vhost-crypto device. The command is unstable/experimental and returns a VirtVhostQueueStatus object.

```json
 -> { "execute": "x-query-virtio-vhost-queue-status",
      "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
                     "queue": 0 }
    }
 <- { "return": {
          "avail-phys": 5216124928,
          "name": "virtio-crypto",
          "used-phys": 5216127040,
          "avail-size": 2054,
          "desc-size": 16384,
          "used-size": 8198,
          "num": 1024,
          "call": 0,
          "desc-phys": 5216108544,
          "kick": 0
      }
    }
```

--------------------------------

### Use passt as replacement for -netdev user

Source: https://www.qemu.org/docs/master/system/invocation.html

Example showing how to start passt as a non-privileged user and connect QEMU to it using a Unix domain socket stream.

```bash
# start passt server as a non privileged user
passt
UNIX domain socket bound at /tmp/passt_1.socket
# start QEMU to connect to passt
qemu-system-x86_64 linux.img \
              -device virtio-net,netdev=net0 \
              -netdev stream,id=net0,server=off,addr.type=unix,addr.path=/tmp/passt_1.socket
```

--------------------------------

### Full example with two storage controllers on different PHBs

Source: https://www.qemu.org/docs/master/system/ppc/powernv.html

Complete QEMU command line with megasas and ich9-ahci controllers on separate PHBs, a PCIe bridge, and an e1000e NIC.

```bash
$ qemu-system-ppc64 -m 2G -machine powernv9 -smp 2,cores=2,threads=1 -accel tcg,thread=single \
-kernel ./zImage.epapr -initrd ./rootfs.cpio.xz -bios ./skiboot.lid \
\
-device megasas,id=scsi0,bus=pcie.0,addr=0x0 \
-drive file=./rhel7-ppc64le.qcow2,if=none,id=drive-scsi0-0-0-0,format=qcow2,cache=none \
-device scsi-hd,bus=scsi0.0,channel=0,scsi-id=0,lun=0,drive=drive-scsi0-0-0-0,id=scsi0-0-0-0,bootindex=2 \
\
-device pcie-pci-bridge,id=bridge1,bus=pcie.1,addr=0x0 \
\
-device ich9-ahci,id=sata0,bus=bridge1,addr=0x1 \
-drive file=./ubuntu-ppc64le.qcow2,if=none,id=drive0,format=qcow2,cache=none \
-device ide-hd,bus=sata0.0,unit=0,drive=drive0,id=ide,bootindex=1 \
-device e1000e,netdev=net0,mac=C0:FF:EE:00:00:02,bus=bridge1,addr=0x2 \
-netdev bridge,helper=/usr/libexec/qemu-bridge-helper,br=virbr0,id=net0 \
-device nec-usb-xhci,bus=bridge1,addr=0x7 \
\
-serial mon:stdio -nographic
```

--------------------------------

### Find PCR entries for TPM 2 in sysfs

Source: https://www.qemu.org/docs/master/specs/tpm.html

Starting with Linux 5.12 there are PCR entries for TPM 2 in sysfs. Example command and partial output.

```bash
# find /sys/devices/ -type f | grep pcr-sha
...
/sys/devices/LNXSYSTEM:00/LNXSYBUS:00/MSFT0101:00/tpm/tpm0/pcr-sha256/1
...
/sys/devices/LNXSYSTEM:00/LNXSYBUS:00/MSFT0101:00/tpm/tpm0/pcr-sha256/9
...
```

--------------------------------

### Launch a basic SGX guest with QEMU

Source: https://www.qemu.org/docs/master/system/i386/sgx.html

Use this command to start a QEMU guest with SGX support. It enables the sgx-provisionkey CPU feature, creates a 64M EPC memory backend, and attaches it to the machine's sgx-epc.0 device on NUMA node 0.

```bash
qemu-system-x86_64 \
 -cpu host,+sgx-provisionkey \
 -object memory-backend-epc,id=mem1,size=64M,prealloc=on \
 -M sgx-epc.0.memdev=mem1,sgx-epc.0.node=0
```

--------------------------------

### Start Guest3 with vfio-ap

Source: https://www.qemu.org/docs/master/system/s390x/vfio-ap.html

QEMU command to start Guest3 with the vfio-ap device and CPU features enabled.

```bash
/usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid3 ...
```

--------------------------------

### struct QOSGraphObject

Source: https://www.qemu.org/docs/master/devel/testing/qgraph.html

Each driver, test or machine of this framework will have a QOSGraphObject as first field. It provides function pointers for getting drivers/devices, starting hardware, destructing, and freeing.

```APIDOC
## struct QOSGraphObject

### Description
Each driver, test or machine of this framework will have a QOSGraphObject as first field.

### Definition
```c
struct QOSGraphObject {
    QOSGetDriver get_driver;
    QOSGetDevice get_device;
    QOSStartFunct start_hw;
    QOSDestructorFunc destructor;
    GDestroyNotify free;
};
```

### Members
- **get_driver** (QOSGetDriver) - See **get_device**.
- **get_device** (QOSGetDevice) - Once a machine-to-test path has been found, the framework traverses it again and allocates all the nodes, using the provided constructor. To satisfy their relations, i.e. for produces or contains, where a struct constructor needs an external parameter represented by the previous node, the framework will call **get_device** (for contains) or **get_driver** (for produces), depending on the edge type, passing them the name of the next node to be taken and getting from them the corresponding pointer to the actual structure of the next node to be used in the path.
- **start_hw** (QOSStartFunct) - This function is executed after all the path objects have been allocated, but before the test is run. It starts the hw, setting the initial configurations (*_device_enable) and making it ready for the test.
- **destructor** (QOSDestructorFunc) - Opposite to the node constructor, destroys the object. This function is called after the test has been executed, and performs a complete cleanup of each node allocated field. In case no constructor is provided, no destructor will be called.
- **free** (GDestroyNotify) - Free the memory associated to the QOSGraphObject and its contained children.
```

--------------------------------

### qtest_init_ext

Source: https://www.qemu.org/docs/master/devel/testing/qtest.html

Like qtest_init(), but use a different environment variable for the QEMU binary, allow specify capabilities and skip connecting to QEMU monitor.

```APIDOC
## qtest_init_ext

### Description
Like qtest_init(), but use a different environment variable for the QEMU binary, allow specify capabilities and skip connecting to QEMU monitor.

### Signature
QTestState *qtest_init_ext(const char *var, const char *extra_args, QList *capabilities, bool do_connect)

### Parameters
- **var** (const char *) - Required - Environment variable from where to take the QEMU binary.
- **extra_args** (const char *) - Required - Other arguments to pass to QEMU. CAUTION: these arguments are subject to word splitting and shell evaluation.
- **capabilities** (QList *) - Required - List of QMP capabilities (strings) to enable.
- **do_connect** (bool) - Required - Connect to qemu monitor and qtest socket.

### Return
QTestState instance.
```

--------------------------------

### QMP query-sev-launch-measure example

Source: https://www.qemu.org/docs/master/interop/qemu-qmp-ref.html

Example QMP command and response for query-sev-launch-measure, returning the SEV guest launch measurement.

```qmp
-> { "execute": "query-sev-launch-measure" }
<- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
```
Tokens:
Raw