1'virt' generic virtual platform (``virt``) 2========================================== 3 4The ``virt`` board is a platform which does not correspond to any 5real hardware; it is designed for use in virtual machines. 6It is the recommended board type if you simply want to run 7a guest such as Linux and do not care about reproducing the 8idiosyncrasies and limitations of a particular bit of real-world 9hardware. 10 11This is a "versioned" board model, so as well as the ``virt`` machine 12type itself (which may have improvements, bugfixes and other minor 13changes between QEMU versions) a version is provided that guarantees 14to have the same behaviour as that of previous QEMU releases, so 15that VM migration will work between QEMU versions. For instance the 16``virt-5.0`` machine type will behave like the ``virt`` machine from 17the QEMU 5.0 release, and migration should work between ``virt-5.0`` 18of the 5.0 release and ``virt-5.0`` of the 5.1 release. Migration 19is not guaranteed to work between different QEMU releases for 20the non-versioned ``virt`` machine type. 21 22VM migration is not guaranteed when using ``-cpu max``, as features 23supported may change between QEMU versions. To ensure your VM can be 24migrated, it is recommended to use another cpu model instead. 25 26Supported devices 27""""""""""""""""" 28 29The virt board supports: 30 31- PCI/PCIe devices 32- Flash memory 33- Either one or two PL011 UARTs for the NonSecure World 34- An RTC 35- The fw_cfg device that allows a guest to obtain data from QEMU 36- A PL061 GPIO controller 37- An optional SMMUv3 IOMMU 38- hotpluggable DIMMs 39- hotpluggable NVDIMMs 40- An MSI controller (GICv2M or ITS). GICv2M is selected by default along 41 with GICv2. ITS is selected by default with GICv3 (>= virt-2.7). Note 42 that ITS is not modeled in TCG mode. 43- 32 virtio-mmio transport devices 44- running guests using the KVM accelerator on aarch64 hardware 45- large amounts of RAM (at least 255GB, and more if using highmem) 46- many CPUs (up to 512 if using a GICv3 and highmem) 47- Secure-World-only devices if the CPU has TrustZone: 48 49 - A second PL011 UART 50 - A second PL061 GPIO controller, with GPIO lines for triggering 51 a system reset or system poweroff 52 - A secure flash memory 53 - 16MB of secure RAM 54 55The second NonSecure UART only exists if a backend is configured 56explicitly (e.g. with a second -serial command line option) and 57TrustZone emulation is not enabled. 58 59Supported guest CPU types: 60 61- ``cortex-a7`` (32-bit) 62- ``cortex-a15`` (32-bit; the default) 63- ``cortex-a35`` (64-bit) 64- ``cortex-a53`` (64-bit) 65- ``cortex-a55`` (64-bit) 66- ``cortex-a57`` (64-bit) 67- ``cortex-a72`` (64-bit) 68- ``cortex-a76`` (64-bit) 69- ``cortex-a710`` (64-bit) 70- ``a64fx`` (64-bit) 71- ``host`` (with KVM only) 72- ``neoverse-n1`` (64-bit) 73- ``neoverse-v1`` (64-bit) 74- ``neoverse-n2`` (64-bit) 75- ``max`` (same as ``host`` for KVM; best possible emulation with TCG) 76 77Note that the default is ``cortex-a15``, so for an AArch64 guest you must 78specify a CPU type. 79 80Also, please note that passing ``max`` CPU (i.e. ``-cpu max``) won't 81enable all the CPU features for a given ``virt`` machine. Where a CPU 82architectural feature requires support in both the CPU itself and in the 83wider system (e.g. the MTE feature), it may not be enabled by default, 84but instead requires a machine option to enable it. 85 86For example, MTE support must be enabled with ``-machine virt,mte=on``, 87as well as by selecting an MTE-capable CPU (e.g., ``max``) with the 88``-cpu`` option. 89 90See the machine-specific options below, or check them for a given machine 91by passing the ``help`` suboption, like: ``-machine virt-9.0,help``. 92 93Graphics output is available, but unlike the x86 PC machine types 94there is no default display device enabled: you should select one from 95the Display devices section of "-device help". The recommended option 96is ``virtio-gpu-pci``; this is the only one which will work correctly 97with KVM. You may also need to ensure your guest kernel is configured 98with support for this; see below. 99 100Machine-specific options 101"""""""""""""""""""""""" 102 103The following machine-specific options are supported: 104 105secure 106 Set ``on``/``off`` to enable/disable emulating a guest CPU which implements the 107 Arm Security Extensions (TrustZone). The default is ``off``. 108 109virtualization 110 Set ``on``/``off`` to enable/disable emulating a guest CPU which implements the 111 Arm Virtualization Extensions. The default is ``off``. 112 113mte 114 Set ``on``/``off`` to enable/disable emulating a guest CPU which implements the 115 Arm Memory Tagging Extensions. The default is ``off``. 116 117highmem 118 Set ``on``/``off`` to enable/disable placing devices and RAM in physical 119 address space above 32 bits. The default is ``on`` for machine types 120 later than ``virt-2.12`` when the CPU supports an address space 121 bigger than 32 bits (i.e. 64-bit CPUs, and 32-bit CPUs with the 122 Large Physical Address Extension (LPAE) feature). If you want to 123 boot a 32-bit kernel which does not have ``CONFIG_LPAE`` enabled on 124 a CPU type which implements LPAE, you will need to manually set 125 this to ``off``; otherwise some devices, such as the PCI controller, 126 will not be accessible. 127 128compact-highmem 129 Set ``on``/``off`` to enable/disable the compact layout for high memory regions. 130 The default is ``on`` for machine types later than ``virt-7.2``. 131 132highmem-redists 133 Set ``on``/``off`` to enable/disable the high memory region for GICv3 or 134 GICv4 redistributor. The default is ``on``. Setting this to ``off`` will 135 limit the maximum number of CPUs when GICv3 or GICv4 is used. 136 137highmem-ecam 138 Set ``on``/``off`` to enable/disable the high memory region for PCI ECAM. 139 The default is ``on`` for machine types later than ``virt-3.0``. 140 141highmem-mmio 142 Set ``on``/``off`` to enable/disable the high memory region for PCI MMIO. 143 The default is ``on``. 144 145gic-version 146 Specify the version of the Generic Interrupt Controller (GIC) to provide. 147 Valid values are: 148 149 ``2`` 150 GICv2. Note that this limits the number of CPUs to 8. 151 ``3`` 152 GICv3. This allows up to 512 CPUs. 153 ``4`` 154 GICv4. Requires ``virtualization`` to be ``on``; allows up to 317 CPUs. 155 ``host`` 156 Use the same GIC version the host provides, when using KVM 157 ``max`` 158 Use the best GIC version possible (same as host when using KVM; 159 with TCG this is currently ``3`` if ``virtualization`` is ``off`` and 160 ``4`` if ``virtualization`` is ``on``, but this may change in future) 161 162its 163 Set ``on``/``off`` to enable/disable ITS instantiation. The default is ``on`` 164 for machine types later than ``virt-2.7``. 165 166iommu 167 Set the IOMMU type to create for the guest. Valid values are: 168 169 ``none`` 170 Don't create an IOMMU (the default) 171 ``smmuv3`` 172 Create an SMMUv3 173 174default-bus-bypass-iommu 175 Set ``on``/``off`` to enable/disable `bypass_iommu 176 <https://gitlab.com/qemu-project/qemu/-/blob/master/docs/bypass-iommu.txt>`_ 177 for default root bus. 178 179ras 180 Set ``on``/``off`` to enable/disable reporting host memory errors to a guest 181 using ACPI and guest external abort exceptions. The default is off. 182 183acpi 184 Set ``on``/``off``/``auto`` to enable/disable ACPI. 185 186dtb-randomness 187 Set ``on``/``off`` to pass random seeds via the guest DTB 188 rng-seed and kaslr-seed nodes (in both "/chosen" and 189 "/secure-chosen") to use for features like the random number 190 generator and address space randomisation. The default is 191 ``on``. You will want to disable it if your trusted boot chain 192 will verify the DTB it is passed, since this option causes the 193 DTB to be non-deterministic. It would be the responsibility of 194 the firmware to come up with a seed and pass it on if it wants to. 195 196dtb-kaslr-seed 197 A deprecated synonym for dtb-randomness. 198 199x-oem-id 200 Set string (up to 6 bytes) to override the default value of field OEMID in ACPI 201 table header. 202 203x-oem-table-id 204 Set string (up to 8 bytes) to override the default value of field OEM Table ID 205 in ACPI table header. 206 207Linux guest kernel configuration 208"""""""""""""""""""""""""""""""" 209 210The 'defconfig' for Linux arm and arm64 kernels should include the 211right device drivers for virtio and the PCI controller; however some older 212kernel versions, especially for 32-bit Arm, did not have everything 213enabled by default. If you're not seeing PCI devices that you expect, 214then check that your guest config has:: 215 216 CONFIG_PCI=y 217 CONFIG_VIRTIO_PCI=y 218 CONFIG_PCI_HOST_GENERIC=y 219 220If you want to use the ``virtio-gpu-pci`` graphics device you will also 221need:: 222 223 CONFIG_DRM=y 224 CONFIG_DRM_VIRTIO_GPU=y 225 226Hardware configuration information for bare-metal programming 227""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 228 229The ``virt`` board automatically generates a device tree blob ("dtb") 230which it passes to the guest. This provides information about the 231addresses, interrupt lines and other configuration of the various devices 232in the system. Guest code can rely on and hard-code the following 233addresses: 234 235- Flash memory starts at address 0x0000_0000 236 237- RAM starts at 0x4000_0000 238 239All other information about device locations may change between 240QEMU versions, so guest code must look in the DTB. 241 242QEMU supports two types of guest image boot for ``virt``, and 243the way for the guest code to locate the dtb binary differs: 244 245- For guests using the Linux kernel boot protocol (this means any 246 non-ELF file passed to the QEMU ``-kernel`` option) the address 247 of the DTB is passed in a register (``r2`` for 32-bit guests, 248 or ``x0`` for 64-bit guests) 249 250- For guests booting as "bare-metal" (any other kind of boot), 251 the DTB is at the start of RAM (0x4000_0000) 252