QEMU Documentation Release 4.2.50 The QEMU Project Developers Mar 02, 2020 Contents: 1 QEMU System Emulation Management and Interoperability Guide1 1.1 Dirty Bitmaps and Incremental Backup.................................1 1.2 D-Bus................................................... 25 1.3 D-Bus VMState............................................. 26 1.4 Live Block Device Operations...................................... 27 1.5 Persistent reservation helper protocol.................................. 44 1.6 QEMU Guest Agent........................................... 45 1.7 Vhost-user Protocol........................................... 47 1.8 Vhost-user-gpu Protocol......................................... 70 2 QEMU Developer’s Guide 75 2.1 QEMU and Kconfig........................................... 75 2.2 Load and Store APIs........................................... 79 2.3 The memory API............................................. 88 2.4 Migration................................................. 117 2.5 QEMU and the stable process...................................... 129 2.6 Testing in QEMU............................................ 130 2.7 Decodetree Specification......................................... 142 2.8 Secure Coding Practices......................................... 146 2.9 Translator Internals............................................ 147 2.10 QEMU TCG Plugins........................................... 149 2.11 Bitwise operations............................................ 151 2.12 Reset in QEMU: the Resettable interface................................ 158 2.13 Booting from real channel-attached devices on s390x.......................... 162 3 QEMU System Emulation Guest Hardware Specifications 165 3.1 POWER9 XIVE interrupt controller................................... 165 3.2 XIVE for sPAPR (pseries machines)................................... 168 3.3 QEMU and ACPI BIOS Generic Event Device interface........................ 172 3.4 QEMU TPM Device........................................... 173 4 QEMU System Emulation User’s Guide 181 4.1 Quick Start................................................ 181 4.2 Invocation................................................ 181 4.3 Keys in the graphical frontends..................................... 229 4.4 Keys in the character backend multiplexer................................ 229 4.5 QEMU Monitor............................................. 230 i 4.6 Disk Images............................................... 238 4.7 Network emulation............................................ 251 4.8 USB emulation.............................................. 252 4.9 Inter-VM Shared Memory device.................................... 254 4.10 Direct Linux Boot............................................ 255 4.11 VNC security............................................... 255 4.12 TLS setup for network services..................................... 257 4.13 GDB usage................................................ 262 4.14 Managed start up options......................................... 263 4.15 QEMU System Emulator Targets.................................... 263 4.16 Security.................................................. 278 4.17 Adjunct Processor (AP) Device..................................... 280 4.18 Deprecated features........................................... 294 4.19 Recently removed features........................................ 300 4.20 Supported build platforms........................................ 301 4.21 License.................................................. 302 5 QEMU Tools Guide 303 5.1 QEMU disk image utility........................................ 303 5.2 QEMU Disk Network Block Device Server............................... 313 5.3 QEMU SystemTap trace tool....................................... 317 5.4 QEMU 9p virtfs proxy filesystem helper................................ 318 5.5 QEMU virtio-fs shared file system daemon............................... 319 6 QEMU User Mode Emulation User’s Guide 321 6.1 QEMU User space emulator....................................... 321 Index 325 ii CHAPTER 1 QEMU System Emulation Management and Interoperability Guide This manual contains documents and specifications that are useful for making QEMU interoperate with other software. Contents: 1.1 Dirty Bitmaps and Incremental Backup Dirty Bitmaps are in-memory objects that track writes to block devices. They can be used in conjunction with various block job operations to perform incremental or differential backup regimens. This document explains the conceptual mechanisms, as well as up-to-date, complete and comprehensive documenta- tion on the API to manipulate them. (Hopefully, the “why”, “what”, and “how”.) The intended audience for this document is developers who are adding QEMU backup features to management appli- cations, or power users who run and administer QEMU directly via QMP. Contents • Dirty Bitmaps and Incremental Backup – Overview – Supported Image Formats – Dirty Bitmap Names – Bitmap Status – Basic QMP Usage * Supported Commands * Creation: block-dirty-bitmap-add * Deletion: block-dirty-bitmap-remove 1 QEMU Documentation, Release 4.2.50 * Resetting: block-dirty-bitmap-clear * Enabling: block-dirty-bitmap-enable * Enabling: block-dirty-bitmap-disable * Merging, Copying: block-dirty-bitmap-merge * Querying: query-block – Bitmap Persistence – Transactions * Justification * Supported Bitmap Transactions – Incremental Backups - Push Model * Example: New Incremental Backup Anchor Point * Example: Resetting an Incremental Backup Anchor Point * Example: First Incremental Backup * Example: Second Incremental Backup * Example: Incremental Push Backups without Backing Files * Example: Multi-drive Incremental Backup – Push Backup Errors & Recovery * Example: Individual Failures * Example: Partial Transactional Failures * Example: Grouped Completion Mode 1.1.1 Overview Bitmaps are bit vectors where each ‘1’ bit in the vector indicates a modified (“dirty”) segment of the corresponding block device. The size of the segment that is tracked is the granularity of the bitmap. If the granularity of a bitmap is 64K, each ‘1’ bit means that a 64K region as a whole may have changed in some way, possibly by as little as one byte. Smaller granularities mean more accurate tracking of modified disk data, but requires more computational overhead and larger bitmap sizes. Larger granularities mean smaller bitmap sizes, but less targeted backups. The size of a bitmap (in bytes) can be computed as such: size = ceil(ceil(image_size / granularity) / 8) e.g. the size of a 64KiB granularity bitmap on a 2TiB image is: size = ((2147483648K / 64K) / 8) = 4194304B = 4MiB. QEMU uses these bitmaps when making incremental backups to know which sections of the file to copy out. They are not enabled by default and must be explicitly added in order to begin tracking writes. Bitmaps can be created at any time and can be attached to any arbitrary block node in the storage graph, but are most useful conceptually when attached to the root node attached to the guest’s storage device model. That is to say: It’s likely most useful to track the guest’s writes to disk, but you could theoretically track things like qcow2 metadata changes by attaching the bitmap elsewhere in the storage graph. This is beyond the scope of this document. 2 Chapter 1. QEMU System Emulation Management and Interoperability Guide QEMU Documentation, Release 4.2.50 QEMU supports persisting these bitmaps to disk via the qcow2 image format. Bitmaps which are stored or loaded in this way are called “persistent”, whereas bitmaps that are not are called “transient”. QEMU also supports the migration of both transient bitmaps (tracking any arbitrary image format) or persistent bitmaps (qcow2) via live migration. 1.1.2 Supported Image Formats QEMU supports all documented features below on the qcow2 image format. However, qcow2 is only strictly necessary for the persistence feature, which writes bitmap data to disk upon close. If persistence is not required for a specific use case, all bitmap features excepting persistence are available for any arbitrary image format. For example, Dirty Bitmaps can be combined with the ‘raw’ image format, but any changes to the bitmap will be discarded upon exit. Warning: Transient bitmaps will not be saved on QEMU exit! Persistent bitmaps are available only on qcow2 images. 1.1.3 Dirty Bitmap Names Bitmap objects need a method to reference them in the API. All API-created and managed bitmaps have a human- readable name chosen by the user at creation time. • A bitmap’s name is unique to the node, but bitmaps attached to different nodes can share the same name. Therefore, all bitmaps are addressed via their (node, name) pair. • The name of a user-created bitmap cannot be empty (“”). • Transient bitmaps can have JSON unicode names that are effectively not length limited. (QMP protocol may restrict messages to less than 64MiB.) • Persistent storage formats may impose their own requirements on bitmap names and namespaces. Presently, only qcow2 supports persistent bitmaps. See docs/interop/qcow2.txt for more details on restrictions. Notably: – qcow2 bitmap names are limited to between 1 and 1023 bytes long. – No two bitmaps saved to the same qcow2 file may share the same name. • QEMU occasionally uses bitmaps for internal use which have no name. They are hidden from API query calls, cannot be manipulated by the external API, are never persistent, nor ever migrated. 1.1.4 Bitmap Status Dirty Bitmap objects can be queried with