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