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 147gic-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 164its 165 Set ``on``/``off`` to enable/disable ITS instantiation. The default is ``on`` 166 for machine types later than ``virt-2.7``. 167 168iommu 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 176default-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 181ras 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 185acpi 186 Set ``on``/``off``/``auto`` to enable/disable ACPI. 187 188dtb-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 198dtb-kaslr-seed 199 A deprecated synonym for dtb-randomness. 200 201x-oem-id 202 Set string (up to 6 bytes) to override the default value of field OEMID in ACPI 203 table header. 204 205x-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 209Linux guest kernel configuration 210"""""""""""""""""""""""""""""""" 211 212The 'defconfig' for Linux arm and arm64 kernels should include the 213right device drivers for virtio and the PCI controller; however some older 214kernel versions, especially for 32-bit Arm, did not have everything 215enabled by default. If you're not seeing PCI devices that you expect, 216then check that your guest config has:: 217 218 CONFIG_PCI=y 219 CONFIG_VIRTIO_PCI=y 220 CONFIG_PCI_HOST_GENERIC=y 221 222If you want to use the ``virtio-gpu-pci`` graphics device you will also 223need:: 224 225 CONFIG_DRM=y 226 CONFIG_DRM_VIRTIO_GPU=y 227 228Hardware configuration information for bare-metal programming 229""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 230 231The ``virt`` board automatically generates a device tree blob ("dtb") 232which it passes to the guest. This provides information about the 233addresses, interrupt lines and other configuration of the various devices 234in the system. Guest code can rely on and hard-code the following 235addresses: 236 237- Flash memory starts at address 0x0000_0000 238 239- RAM starts at 0x4000_0000 240 241All other information about device locations may change between 242QEMU versions, so guest code must look in the DTB. 243 244QEMU supports two types of guest image boot for ``virt``, and 245the 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