stubs: Move qemu_timer_notify_cb() and remove qemu_notify_event() stub
[qemu.git] / docs / system / target-arm.rst
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 Unfortunately many of the Arm boards QEMU supports are currently
67 undocumented; you can get a complete list by running
68 ``qemu-system-aarch64 --machine help``.
69
70 ..
71    This table of contents should be kept sorted alphabetically
72    by the title text of each file, which isn't the same ordering
73    as an alphabetical sort by filename.
74
75 .. toctree::
76    :maxdepth: 1
77
78    arm/integratorcp
79    arm/mps2
80    arm/musca
81    arm/realview
82    arm/versatile
83    arm/vexpress
84    arm/aspeed
85    arm/digic
86    arm/musicpal
87    arm/gumstix
88    arm/nseries
89    arm/orangepi
90    arm/palm
91    arm/xscale
92    arm/collie
93    arm/sx1
94    arm/stellaris
95    arm/virt
96    arm/xlnx-versal-virt
97
98 Arm CPU features
99 ================
100
101 .. toctree::
102    arm/cpu-features