| Message ID | 20200309215818.2021-4-peter.maydell@linaro.org |
|---|---|
| State | Superseded |
| Headers | show |
| Series | docs/system: Split target-arm.rst | expand |
Peter Maydell <peter.maydell@linaro.org> writes: > Now we've moved the various bits of per-board documentation into > their own files, the top level document is a little bare. Add > some introductory information, including a note that many > of the board models we support are currently undocumented. > > (Most sections of this new text were originally written by me > for the wiki page https://wiki.qemu.org/Documentation/Platforms/ARM) > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> > --- > --- > docs/system/target-arm.rst | 66 ++++++++++++++++++++++++++++++++++++-- > 1 file changed, 64 insertions(+), 2 deletions(-) > > diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst > index c7df6fc1f97..86ea6f2f568 100644 > --- a/docs/system/target-arm.rst > +++ b/docs/system/target-arm.rst > @@ -1,9 +1,71 @@ > .. _ARM-System-emulator: > > -ARM System emulator > +Arm System emulator > ------------------- > > -Use the executable ``qemu-system-arm`` to simulate a ARM machine. > +QEMU can emulate both 32-bit and 64-bit Arm CPUs. Use the > +``qemu-system-aarch64`` executable to simulate a 64-bit Arm machine. > +You can use either ``qemu-system-arm`` or ``qemu-system-aarch64`` > +to simulate a 32-bit Arm machine: in general, command lines that > +work for ``qemu-system-arm`` will behave the same when used with > +``qemu-system-aarch64``. > + > +QEMU has generally good support for Arm guests. It has support for > +nearly fifty different machines. The reason we support so many is that > +Arm hardware is much more widely varying than x86 hardware. Arm CPUs > +are generally built into "system-on-chip" (SoC) designs created by > +many different companies with different devices, and these SoCs are > +then built into machines which can vary still further even if they use > +the same SoC. Even with fifty boards QEMU does not cover more than a > +small fraction of the Arm hardware ecosystem. > + > +The situation for 64-bit Arm is fairly similar, except that we don't > +implement so many different machines. > + > +As well as the more common "A-profile" CPUs (which have MMUs and will > +run Linux) QEMU also supports "M-profile" CPUs such as the Cortex-M0, > +Cortex-M4 and Cortex-M33 (which are microcontrollers used in very > +embedded boards). For most boards the CPU type is fixed (matching what > +the hardware has), so typically you don't need to specify the CPU type > +by hand, except for special cases like the ``virt`` board. > + > +Choosing a board model > +====================== > + > +For QEMU's Arm system emulation, you must specify which board > +model you want to use with the ``-M`` or ``--machine`` option; > +there is no default. > + > +Because Arm systems differ so much and in fundamental ways, typically > +operating system or firmware images intended to run on one machine > +will not run at all on any other. This is often surprising for new > +users who are used to the x86 world where every system looks like a > +standard PC. (Once the kernel has booted, most userspace software > +cares much less about the detail of the hardware.) > + > +If you already have a system image or a kernel that works on hardware > +and you want to boot with QEMU, check whether QEMU lists that machine > +in its ``-machine help`` output. If it is listed, then you can probably > +use that board model. If it is not listed, then unfortunately your image > +will almost certainly not boot on QEMU. (You might be able to > +extract the filesystem and use that with a different kernel which > +boots on a system that QEMU does emulate.) > + > +If you don't care about reproducing the idiosyncrasies of a particular > +bit of hardware, such as small amount of RAM, no PCI or other hard > +disk, etc., and just want to run Linux, the best option is to use the > +``virt`` board. This is a platform which doesn't correspond to any > +real hardware and is designed for use in virtual machines. You'll > +need to compile Linux with a suitable configuration for running on > +the ``virt`` board. ``virt`` supports PCI, virtio, recent CPUs and > +large amounts of RAM. It also supports 64-bit CPUs. > + > +Board-specific documentation > +============================ > + > +Unfortunately many of the Arm boards QEMU supports are currently > +undocumented; you can get a complete list by running > +``qemu-system-aarch64 --machine help``. > > .. toctree:: -- Alex Bennée
Reviewed-by: Niek Linnenbank <nieklinnenbank@gmail.com> On Mon, Mar 9, 2020 at 10:58 PM Peter Maydell <peter.maydell@linaro.org> wrote: > Now we've moved the various bits of per-board documentation into > their own files, the top level document is a little bare. Add > some introductory information, including a note that many > of the board models we support are currently undocumented. > > (Most sections of this new text were originally written by me > for the wiki page https://wiki.qemu.org/Documentation/Platforms/ARM) > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > --- > --- > docs/system/target-arm.rst | 66 ++++++++++++++++++++++++++++++++++++-- > 1 file changed, 64 insertions(+), 2 deletions(-) > > diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst > index c7df6fc1f97..86ea6f2f568 100644 > --- a/docs/system/target-arm.rst > +++ b/docs/system/target-arm.rst > @@ -1,9 +1,71 @@ > .. _ARM-System-emulator: > > -ARM System emulator > +Arm System emulator > ------------------- > > -Use the executable ``qemu-system-arm`` to simulate a ARM machine. > +QEMU can emulate both 32-bit and 64-bit Arm CPUs. Use the > +``qemu-system-aarch64`` executable to simulate a 64-bit Arm machine. > +You can use either ``qemu-system-arm`` or ``qemu-system-aarch64`` > +to simulate a 32-bit Arm machine: in general, command lines that > +work for ``qemu-system-arm`` will behave the same when used with > +``qemu-system-aarch64``. > + > +QEMU has generally good support for Arm guests. It has support for > +nearly fifty different machines. The reason we support so many is that > +Arm hardware is much more widely varying than x86 hardware. Arm CPUs > +are generally built into "system-on-chip" (SoC) designs created by > +many different companies with different devices, and these SoCs are > +then built into machines which can vary still further even if they use > +the same SoC. Even with fifty boards QEMU does not cover more than a > +small fraction of the Arm hardware ecosystem. > + > +The situation for 64-bit Arm is fairly similar, except that we don't > +implement so many different machines. > + > +As well as the more common "A-profile" CPUs (which have MMUs and will > +run Linux) QEMU also supports "M-profile" CPUs such as the Cortex-M0, > +Cortex-M4 and Cortex-M33 (which are microcontrollers used in very > +embedded boards). For most boards the CPU type is fixed (matching what > +the hardware has), so typically you don't need to specify the CPU type > +by hand, except for special cases like the ``virt`` board. > + > +Choosing a board model > +====================== > + > +For QEMU's Arm system emulation, you must specify which board > +model you want to use with the ``-M`` or ``--machine`` option; > +there is no default. > + > +Because Arm systems differ so much and in fundamental ways, typically > +operating system or firmware images intended to run on one machine > +will not run at all on any other. This is often surprising for new > +users who are used to the x86 world where every system looks like a > +standard PC. (Once the kernel has booted, most userspace software > +cares much less about the detail of the hardware.) > + > +If you already have a system image or a kernel that works on hardware > +and you want to boot with QEMU, check whether QEMU lists that machine > +in its ``-machine help`` output. If it is listed, then you can probably > +use that board model. If it is not listed, then unfortunately your image > +will almost certainly not boot on QEMU. (You might be able to > +extract the filesystem and use that with a different kernel which > +boots on a system that QEMU does emulate.) > + > +If you don't care about reproducing the idiosyncrasies of a particular > +bit of hardware, such as small amount of RAM, no PCI or other hard > +disk, etc., and just want to run Linux, the best option is to use the > +``virt`` board. This is a platform which doesn't correspond to any > +real hardware and is designed for use in virtual machines. You'll > +need to compile Linux with a suitable configuration for running on > +the ``virt`` board. ``virt`` supports PCI, virtio, recent CPUs and > +large amounts of RAM. It also supports 64-bit CPUs. > + > +Board-specific documentation > +============================ > + > +Unfortunately many of the Arm boards QEMU supports are currently > +undocumented; you can get a complete list by running > +``qemu-system-aarch64 --machine help``. > > .. toctree:: > > -- > 2.20.1 > > -- Niek Linnenbank <div dir="ltr">Reviewed-by: Niek Linnenbank <<a href="mailto:nieklinnenbank@gmail.com">nieklinnenbank@gmail.com</a>><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, Mar 9, 2020 at 10:58 PM Peter Maydell <<a href="mailto:peter.maydell@linaro.org">peter.maydell@linaro.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">Now we've moved the various bits of per-board documentation into<br> their own files, the top level document is a little bare. Add<br> some introductory information, including a note that many<br> of the board models we support are currently undocumented.<br> <br> (Most sections of this new text were originally written by me<br> for the wiki page <a href="https://wiki.qemu.org/Documentation/Platforms/ARM" rel="noreferrer" target="_blank">https://wiki.qemu.org/Documentation/Platforms/ARM</a>)<br> <br> Signed-off-by: Peter Maydell <<a href="mailto:peter.maydell@linaro.org" target="_blank">peter.maydell@linaro.org</a>><br> ---<br> ---<br> docs/system/target-arm.rst | 66 ++++++++++++++++++++++++++++++++++++--<br> 1 file changed, 64 insertions(+), 2 deletions(-)<br> <br> diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst<br> index c7df6fc1f97..86ea6f2f568 100644<br> --- a/docs/system/target-arm.rst<br> +++ b/docs/system/target-arm.rst<br> @@ -1,9 +1,71 @@<br> .. _ARM-System-emulator:<br> <br> -ARM System emulator<br> +Arm System emulator<br> -------------------<br> <br> -Use the executable ``qemu-system-arm`` to simulate a ARM machine.<br> +QEMU can emulate both 32-bit and 64-bit Arm CPUs. Use the<br> +``qemu-system-aarch64`` executable to simulate a 64-bit Arm machine.<br> +You can use either ``qemu-system-arm`` or ``qemu-system-aarch64``<br> +to simulate a 32-bit Arm machine: in general, command lines that<br> +work for ``qemu-system-arm`` will behave the same when used with<br> +``qemu-system-aarch64``.<br> +<br> +QEMU has generally good support for Arm guests. It has support for<br> +nearly fifty different machines. The reason we support so many is that<br> +Arm hardware is much more widely varying than x86 hardware. Arm CPUs<br> +are generally built into "system-on-chip" (SoC) designs created by<br> +many different companies with different devices, and these SoCs are<br> +then built into machines which can vary still further even if they use<br> +the same SoC. Even with fifty boards QEMU does not cover more than a<br> +small fraction of the Arm hardware ecosystem.<br> +<br> +The situation for 64-bit Arm is fairly similar, except that we don't<br> +implement so many different machines.<br> +<br> +As well as the more common "A-profile" CPUs (which have MMUs and will<br> +run Linux) QEMU also supports "M-profile" CPUs such as the Cortex-M0,<br> +Cortex-M4 and Cortex-M33 (which are microcontrollers used in very<br> +embedded boards). For most boards the CPU type is fixed (matching what<br> +the hardware has), so typically you don't need to specify the CPU type<br> +by hand, except for special cases like the ``virt`` board.<br> +<br> +Choosing a board model<br> +======================<br> +<br> +For QEMU's Arm system emulation, you must specify which board<br> +model you want to use with the ``-M`` or ``--machine`` option;<br> +there is no default.<br> +<br> +Because Arm systems differ so much and in fundamental ways, typically<br> +operating system or firmware images intended to run on one machine<br> +will not run at all on any other. This is often surprising for new<br> +users who are used to the x86 world where every system looks like a<br> +standard PC. (Once the kernel has booted, most userspace software<br> +cares much less about the detail of the hardware.)<br> +<br> +If you already have a system image or a kernel that works on hardware<br> +and you want to boot with QEMU, check whether QEMU lists that machine<br> +in its ``-machine help`` output. If it is listed, then you can probably<br> +use that board model. If it is not listed, then unfortunately your image<br> +will almost certainly not boot on QEMU. (You might be able to<br> +extract the filesystem and use that with a different kernel which<br> +boots on a system that QEMU does emulate.)<br> +<br> +If you don't care about reproducing the idiosyncrasies of a particular<br> +bit of hardware, such as small amount of RAM, no PCI or other hard<br> +disk, etc., and just want to run Linux, the best option is to use the<br> +``virt`` board. This is a platform which doesn't correspond to any<br> +real hardware and is designed for use in virtual machines. You'll<br> +need to compile Linux with a suitable configuration for running on<br> +the ``virt`` board. ``virt`` supports PCI, virtio, recent CPUs and<br> +large amounts of RAM. It also supports 64-bit CPUs.<br> +<br> +Board-specific documentation<br> +============================<br> +<br> +Unfortunately many of the Arm boards QEMU supports are currently<br> +undocumented; you can get a complete list by running<br> +``qemu-system-aarch64 --machine help``.<br> <br> .. toctree::<br> <br> -- <br> 2.20.1<br> <br> </blockquote></div><br clear="all"><br>-- <br><div dir="ltr" class="gmail_signature"><div dir="ltr"><div>Niek Linnenbank<br><br></div></div></div>
diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst index c7df6fc1f97..86ea6f2f568 100644 --- a/docs/system/target-arm.rst +++ b/docs/system/target-arm.rst @@ -1,9 +1,71 @@ .. _ARM-System-emulator: -ARM System emulator +Arm System emulator ------------------- -Use the executable ``qemu-system-arm`` to simulate a ARM machine. +QEMU can emulate both 32-bit and 64-bit Arm CPUs. Use the +``qemu-system-aarch64`` executable to simulate a 64-bit Arm machine. +You can use either ``qemu-system-arm`` or ``qemu-system-aarch64`` +to simulate a 32-bit Arm machine: in general, command lines that +work for ``qemu-system-arm`` will behave the same when used with +``qemu-system-aarch64``. + +QEMU has generally good support for Arm guests. It has support for +nearly fifty different machines. The reason we support so many is that +Arm hardware is much more widely varying than x86 hardware. Arm CPUs +are generally built into "system-on-chip" (SoC) designs created by +many different companies with different devices, and these SoCs are +then built into machines which can vary still further even if they use +the same SoC. Even with fifty boards QEMU does not cover more than a +small fraction of the Arm hardware ecosystem. + +The situation for 64-bit Arm is fairly similar, except that we don't +implement so many different machines. + +As well as the more common "A-profile" CPUs (which have MMUs and will +run Linux) QEMU also supports "M-profile" CPUs such as the Cortex-M0, +Cortex-M4 and Cortex-M33 (which are microcontrollers used in very +embedded boards). For most boards the CPU type is fixed (matching what +the hardware has), so typically you don't need to specify the CPU type +by hand, except for special cases like the ``virt`` board. + +Choosing a board model +====================== + +For QEMU's Arm system emulation, you must specify which board +model you want to use with the ``-M`` or ``--machine`` option; +there is no default. + +Because Arm systems differ so much and in fundamental ways, typically +operating system or firmware images intended to run on one machine +will not run at all on any other. This is often surprising for new +users who are used to the x86 world where every system looks like a +standard PC. (Once the kernel has booted, most userspace software +cares much less about the detail of the hardware.) + +If you already have a system image or a kernel that works on hardware +and you want to boot with QEMU, check whether QEMU lists that machine +in its ``-machine help`` output. If it is listed, then you can probably +use that board model. If it is not listed, then unfortunately your image +will almost certainly not boot on QEMU. (You might be able to +extract the filesystem and use that with a different kernel which +boots on a system that QEMU does emulate.) + +If you don't care about reproducing the idiosyncrasies of a particular +bit of hardware, such as small amount of RAM, no PCI or other hard +disk, etc., and just want to run Linux, the best option is to use the +``virt`` board. This is a platform which doesn't correspond to any +real hardware and is designed for use in virtual machines. You'll +need to compile Linux with a suitable configuration for running on +the ``virt`` board. ``virt`` supports PCI, virtio, recent CPUs and +large amounts of RAM. It also supports 64-bit CPUs. + +Board-specific documentation +============================ + +Unfortunately many of the Arm boards QEMU supports are currently +undocumented; you can get a complete list by running +``qemu-system-aarch64 --machine help``. .. toctree::
Now we've moved the various bits of per-board documentation into their own files, the top level document is a little bare. Add some introductory information, including a note that many of the board models we support are currently undocumented. (Most sections of this new text were originally written by me for the wiki page https://wiki.qemu.org/Documentation/Platforms/ARM) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> --- --- docs/system/target-arm.rst | 66 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 64 insertions(+), 2 deletions(-) -- 2.20.1