| 1 | .. _ARM-System-emulator: |
| 2 | |
| 3 | Arm System emulator |
| 4 | ------------------- |
| 5 | |
| 6 | QEMU can emulate both 32-bit and 64-bit Arm CPUs. Use the |
| 7 | ``qemu-system-aarch64`` executable to simulate a 64-bit Arm machine. |
| 8 | You can use either ``qemu-system-arm`` or ``qemu-system-aarch64`` |
| 9 | to simulate a 32-bit Arm machine: in general, command lines that |
| 10 | work for ``qemu-system-arm`` will behave the same when used with |
| 11 | ``qemu-system-aarch64``. |
| 12 | |
| 13 | QEMU has generally good support for Arm guests. It has support for |
| 14 | nearly fifty different machines. The reason we support so many is that |
| 15 | Arm hardware is much more widely varying than x86 hardware. Arm CPUs |
| 16 | are generally built into "system-on-chip" (SoC) designs created by |
| 17 | many different companies with different devices, and these SoCs are |
| 18 | then built into machines which can vary still further even if they use |
| 19 | the same SoC. Even with fifty boards QEMU does not cover more than a |
| 20 | small fraction of the Arm hardware ecosystem. |
| 21 | |
| 22 | The situation for 64-bit Arm is fairly similar, except that we don't |
| 23 | implement so many different machines. |
| 24 | |
| 25 | As well as the more common "A-profile" CPUs (which have MMUs and will |
| 26 | run Linux) QEMU also supports "M-profile" CPUs such as the Cortex-M0, |
| 27 | Cortex-M4 and Cortex-M33 (which are microcontrollers used in very |
| 28 | embedded boards). For most boards the CPU type is fixed (matching what |
| 29 | the hardware has), so typically you don't need to specify the CPU type |
| 30 | by hand, except for special cases like the ``virt`` board. |
| 31 | |
| 32 | Choosing a board model |
| 33 | ====================== |
| 34 | |
| 35 | For QEMU's Arm system emulation, you must specify which board |
| 36 | model you want to use with the ``-M`` or ``--machine`` option; |
| 37 | there is no default. |
| 38 | |
| 39 | Because Arm systems differ so much and in fundamental ways, typically |
| 40 | operating system or firmware images intended to run on one machine |
| 41 | will not run at all on any other. This is often surprising for new |
| 42 | users who are used to the x86 world where every system looks like a |
| 43 | standard PC. (Once the kernel has booted, most userspace software |
| 44 | cares much less about the detail of the hardware.) |
| 45 | |
| 46 | If you already have a system image or a kernel that works on hardware |
| 47 | and you want to boot with QEMU, check whether QEMU lists that machine |
| 48 | in its ``-machine help`` output. If it is listed, then you can probably |
| 49 | use that board model. If it is not listed, then unfortunately your image |
| 50 | will almost certainly not boot on QEMU. (You might be able to |
| 51 | extract the filesystem and use that with a different kernel which |
| 52 | boots on a system that QEMU does emulate.) |
| 53 | |
| 54 | If you don't care about reproducing the idiosyncrasies of a particular |
| 55 | bit of hardware, such as small amount of RAM, no PCI or other hard |
| 56 | disk, etc., and just want to run Linux, the best option is to use the |
| 57 | ``virt`` board. This is a platform which doesn't correspond to any |
| 58 | real hardware and is designed for use in virtual machines. You'll |
| 59 | need to compile Linux with a suitable configuration for running on |
| 60 | the ``virt`` board. ``virt`` supports PCI, virtio, recent CPUs and |
| 61 | large amounts of RAM. It also supports 64-bit CPUs. |
| 62 | |
| 63 | Board-specific documentation |
| 64 | ============================ |
| 65 | |
| 66 | .. |
| 67 | This table of contents should be kept sorted alphabetically |
| 68 | by the title text of each file, which isn't the same ordering |
| 69 | as an alphabetical sort by filename. |
| 70 | |
| 71 | .. toctree:: |
| 72 | :maxdepth: 1 |
| 73 | |
| 74 | arm/max78000 |
| 75 | arm/integratorcp |
| 76 | arm/mps2 |
| 77 | arm/musca |
| 78 | arm/realview |
| 79 | arm/sbsa |
| 80 | arm/versatile |
| 81 | arm/vexpress |
| 82 | arm/aspeed |
| 83 | arm/bananapi_m2u.rst |
| 84 | arm/b-l475e-iot01a.rst |
| 85 | arm/sabrelite |
| 86 | arm/digic |
| 87 | arm/cubieboard |
| 88 | arm/emcraft-sf2 |
| 89 | arm/exynos |
| 90 | arm/kzm |
| 91 | arm/nrf |
| 92 | arm/nuvoton |
| 93 | arm/imx25-pdk |
| 94 | arm/mcimx6ul-evk |
| 95 | arm/mcimx7d-sabre |
| 96 | arm/imx8m |
| 97 | arm/orangepi |
| 98 | arm/raspi |
| 99 | arm/collie |
| 100 | arm/sx1 |
| 101 | arm/stellaris |
| 102 | arm/stm32 |
| 103 | arm/virt |
| 104 | arm/vmapple |
| 105 | arm/xenpvh |
| 106 | arm/xlnx-versal-virt |
| 107 | arm/xlnx-zynq |
| 108 | arm/xlnx-zcu102 |
| 109 | |
| 110 | Emulated CPU architecture support |
| 111 | ================================= |
| 112 | |
| 113 | .. toctree:: |
| 114 | arm/emulation |
| 115 | |
| 116 | Arm CPU features |
| 117 | ================ |
| 118 | |
| 119 | .. toctree:: |
| 120 | arm/cpu-features |