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