Merge remote-tracking branch 'remotes/pmaydell/tags/pull-docs-20200312' into staging

docs queue:
 * Remove some no longer needed texinfo infrastructure
 * Reorder the top level index docs to put most useful manuals first
 * Split the Arm target-specific info into sub-pages
 * Improve the Arm documentation a bit with info previously
   only on the wiki page

# gpg: Signature made Thu 12 Mar 2020 11:42:10 GMT
# gpg:                using RSA key E1A5C593CD419DE28E8315CF3C2525ED14360CDE
# gpg:                issuer "peter.maydell@linaro.org"
# gpg: Good signature from "Peter Maydell <peter.maydell@linaro.org>" [ultimate]
# gpg:                 aka "Peter Maydell <pmaydell@gmail.com>" [ultimate]
# gpg:                 aka "Peter Maydell <pmaydell@chiark.greenend.org.uk>" [ultimate]
# Primary key fingerprint: E1A5 C593 CD41 9DE2 8E83  15CF 3C25 25ED 1436 0CDE

* remotes/pmaydell/tags/pull-docs-20200312:
  docs: Be consistent about capitalization of 'Arm'
  docs: Move arm-cpu-features.rst into the system manual
  docs/system/target-arm.rst: Add some introductory text
  docs/system: Split target-arm.rst into sub-documents
  Makefile: Allow for subdirectories in Sphinx manual dependencies
  docs/qemu-option-trace.rst.inc: Remove redundant comment
  docs/index.rst, docs/index.html.in: Reorder manuals
  Makefile: Make all Sphinx documentation depend on the extensions
  docs/sphinx/hxtool.py: Remove STEXI/ETEXI support
  hxtool: Remove Texinfo generation support
  Update comments in .hx files that mention Texinfo
  Makefile: Remove redundant Texinfo related code

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

11 files changed, 655 insertions, 213 deletions

diff --git a/docs/system/arm/cpu-features.rst b/docs/system/arm/cpu-features.rst
new file mode 100644
index 0000000000..2d5c06cd01
--- /dev/null
+++ b/docs/system/arm/cpu-features.rst
@@ -0,0 +1,346 @@
+Arm CPU Features
+================
+
+CPU features are optional features that a CPU of supporting type may
+choose to implement or not.  In QEMU, optional CPU features have
+corresponding boolean CPU proprieties that, when enabled, indicate
+that the feature is implemented, and, conversely, when disabled,
+indicate that it is not implemented. An example of an Arm CPU feature
+is the Performance Monitoring Unit (PMU).  CPU types such as the
+Cortex-A15 and the Cortex-A57, which respectively implement Arm
+architecture reference manuals ARMv7-A and ARMv8-A, may both optionally
+implement PMUs.  For example, if a user wants to use a Cortex-A15 without
+a PMU, then the `-cpu` parameter should contain `pmu=off` on the QEMU
+command line, i.e. `-cpu cortex-a15,pmu=off`.
+
+As not all CPU types support all optional CPU features, then whether or
+not a CPU property exists depends on the CPU type.  For example, CPUs
+that implement the ARMv8-A architecture reference manual may optionally
+support the AArch32 CPU feature, which may be enabled by disabling the
+`aarch64` CPU property.  A CPU type such as the Cortex-A15, which does
+not implement ARMv8-A, will not have the `aarch64` CPU property.
+
+QEMU's support may be limited for some CPU features, only partially
+supporting the feature or only supporting the feature under certain
+configurations.  For example, the `aarch64` CPU feature, which, when
+disabled, enables the optional AArch32 CPU feature, is only supported
+when using the KVM accelerator and when running on a host CPU type that
+supports the feature.  While `aarch64` currently only works with KVM,
+it could work with TCG.  CPU features that are specific to KVM are
+prefixed with "kvm-" and are described in "KVM VCPU Features".
+
+CPU Feature Probing
+===================
+
+Determining which CPU features are available and functional for a given
+CPU type is possible with the `query-cpu-model-expansion` QMP command.
+Below are some examples where `scripts/qmp/qmp-shell` (see the top comment
+block in the script for usage) is used to issue the QMP commands.
+
+1. Determine which CPU features are available for the `max` CPU type
+   (Note, we started QEMU with qemu-system-aarch64, so `max` is
+   implementing the ARMv8-A reference manual in this case)::
+
+      (QEMU) query-cpu-model-expansion type=full model={"name":"max"}
+      { "return": {
+        "model": { "name": "max", "props": {
+        "sve1664": true, "pmu": true, "sve1792": true, "sve1920": true,
+        "sve128": true, "aarch64": true, "sve1024": true, "sve": true,
+        "sve640": true, "sve768": true, "sve1408": true, "sve256": true,
+        "sve1152": true, "sve512": true, "sve384": true, "sve1536": true,
+        "sve896": true, "sve1280": true, "sve2048": true
+      }}}}
+
+We see that the `max` CPU type has the `pmu`, `aarch64`, `sve`, and many
+`sve<N>` CPU features.  We also see that all the CPU features are
+enabled, as they are all `true`.  (The `sve<N>` CPU features are all
+optional SVE vector lengths (see "SVE CPU Properties").  While with TCG
+all SVE vector lengths can be supported, when KVM is in use it's more
+likely that only a few lengths will be supported, if SVE is supported at
+all.)
+
+(2) Let's try to disable the PMU::
+
+      (QEMU) query-cpu-model-expansion type=full model={"name":"max","props":{"pmu":false}}
+      { "return": {
+        "model": { "name": "max", "props": {
+        "sve1664": true, "pmu": false, "sve1792": true, "sve1920": true,
+        "sve128": true, "aarch64": true, "sve1024": true, "sve": true,
+        "sve640": true, "sve768": true, "sve1408": true, "sve256": true,
+        "sve1152": true, "sve512": true, "sve384": true, "sve1536": true,
+        "sve896": true, "sve1280": true, "sve2048": true
+      }}}}
+
+We see it worked, as `pmu` is now `false`.
+
+(3) Let's try to disable `aarch64`, which enables the AArch32 CPU feature::
+
+      (QEMU) query-cpu-model-expansion type=full model={"name":"max","props":{"aarch64":false}}
+      {"error": {
+       "class": "GenericError", "desc":
+       "'aarch64' feature cannot be disabled unless KVM is enabled and 32-bit EL1 is supported"
+      }}
+
+It looks like this feature is limited to a configuration we do not
+currently have.
+
+(4) Let's disable `sve` and see what happens to all the optional SVE
+    vector lengths::
+
+      (QEMU) query-cpu-model-expansion type=full model={"name":"max","props":{"sve":false}}
+      { "return": {
+        "model": { "name": "max", "props": {
+        "sve1664": false, "pmu": true, "sve1792": false, "sve1920": false,
+        "sve128": false, "aarch64": true, "sve1024": false, "sve": false,
+        "sve640": false, "sve768": false, "sve1408": false, "sve256": false,
+        "sve1152": false, "sve512": false, "sve384": false, "sve1536": false,
+        "sve896": false, "sve1280": false, "sve2048": false
+      }}}}
+
+As expected they are now all `false`.
+
+(5) Let's try probing CPU features for the Cortex-A15 CPU type::
+
+      (QEMU) query-cpu-model-expansion type=full model={"name":"cortex-a15"}
+      {"return": {"model": {"name": "cortex-a15", "props": {"pmu": true}}}}
+
+Only the `pmu` CPU feature is available.
+
+A note about CPU feature dependencies
+-------------------------------------
+
+It's possible for features to have dependencies on other features. I.e.
+it may be possible to change one feature at a time without error, but
+when attempting to change all features at once an error could occur
+depending on the order they are processed.  It's also possible changing
+all at once doesn't generate an error, because a feature's dependencies
+are satisfied with other features, but the same feature cannot be changed
+independently without error.  For these reasons callers should always
+attempt to make their desired changes all at once in order to ensure the
+collection is valid.
+
+A note about CPU models and KVM
+-------------------------------
+
+Named CPU models generally do not work with KVM.  There are a few cases
+that do work, e.g. using the named CPU model `cortex-a57` with KVM on a
+seattle host, but mostly if KVM is enabled the `host` CPU type must be
+used.  This means the guest is provided all the same CPU features as the
+host CPU type has.  And, for this reason, the `host` CPU type should
+enable all CPU features that the host has by default.  Indeed it's even
+a bit strange to allow disabling CPU features that the host has when using
+the `host` CPU type, but in the absence of CPU models it's the best we can
+do if we want to launch guests without all the host's CPU features enabled.
+
+Enabling KVM also affects the `query-cpu-model-expansion` QMP command.  The
+affect is not only limited to specific features, as pointed out in example
+(3) of "CPU Feature Probing", but also to which CPU types may be expanded.
+When KVM is enabled, only the `max`, `host`, and current CPU type may be
+expanded.  This restriction is necessary as it's not possible to know all
+CPU types that may work with KVM, but it does impose a small risk of users
+experiencing unexpected errors.  For example on a seattle, as mentioned
+above, the `cortex-a57` CPU type is also valid when KVM is enabled.
+Therefore a user could use the `host` CPU type for the current type, but
+then attempt to query `cortex-a57`, however that query will fail with our
+restrictions.  This shouldn't be an issue though as management layers and
+users have been preferring the `host` CPU type for use with KVM for quite
+some time.  Additionally, if the KVM-enabled QEMU instance running on a
+seattle host is using the `cortex-a57` CPU type, then querying `cortex-a57`
+will work.
+
+Using CPU Features
+==================
+
+After determining which CPU features are available and supported for a
+given CPU type, then they may be selectively enabled or disabled on the
+QEMU command line with that CPU type::
+
+  $ qemu-system-aarch64 -M virt -cpu max,pmu=off,sve=on,sve128=on,sve256=on
+
+The example above disables the PMU and enables the first two SVE vector
+lengths for the `max` CPU type.  Note, the `sve=on` isn't actually
+necessary, because, as we observed above with our probe of the `max` CPU
+type, `sve` is already on by default.  Also, based on our probe of
+defaults, it would seem we need to disable many SVE vector lengths, rather
+than only enabling the two we want.  This isn't the case, because, as
+disabling many SVE vector lengths would be quite verbose, the `sve<N>` CPU
+properties have special semantics (see "SVE CPU Property Parsing
+Semantics").
+
+KVM VCPU Features
+=================
+
+KVM VCPU features are CPU features that are specific to KVM, such as
+paravirt features or features that enable CPU virtualization extensions.
+The features' CPU properties are only available when KVM is enabled and
+are named with the prefix "kvm-".  KVM VCPU features may be probed,
+enabled, and disabled in the same way as other CPU features.  Below is
+the list of KVM VCPU features and their descriptions.
+
+  kvm-no-adjvtime          By default kvm-no-adjvtime is disabled.  This
+                           means that by default the virtual time
+                           adjustment is enabled (vtime is not *not*
+                           adjusted).
+
+                           When virtual time adjustment is enabled each
+                           time the VM transitions back to running state
+                           the VCPU's virtual counter is updated to ensure
+                           stopped time is not counted.  This avoids time
+                           jumps surprising guest OSes and applications,
+                           as long as they use the virtual counter for
+                           timekeeping.  However it has the side effect of
+                           the virtual and physical counters diverging.
+                           All timekeeping based on the virtual counter
+                           will appear to lag behind any timekeeping that
+                           does not subtract VM stopped time.  The guest
+                           may resynchronize its virtual counter with
+                           other time sources as needed.
+
+                           Enable kvm-no-adjvtime to disable virtual time
+                           adjustment, also restoring the legacy (pre-5.0)
+                           behavior.
+
+SVE CPU Properties
+==================
+
+There are two types of SVE CPU properties: `sve` and `sve<N>`.  The first
+is used to enable or disable the entire SVE feature, just as the `pmu`
+CPU property completely enables or disables the PMU.  The second type
+is used to enable or disable specific vector lengths, where `N` is the
+number of bits of the length.  The `sve<N>` CPU properties have special
+dependencies and constraints, see "SVE CPU Property Dependencies and
+Constraints" below.  Additionally, as we want all supported vector lengths
+to be enabled by default, then, in order to avoid overly verbose command
+lines (command lines full of `sve<N>=off`, for all `N` not wanted), we
+provide the parsing semantics listed in "SVE CPU Property Parsing
+Semantics".
+
+SVE CPU Property Dependencies and Constraints
+---------------------------------------------
+
+  1) At least one vector length must be enabled when `sve` is enabled.
+
+  2) If a vector length `N` is enabled, then, when KVM is enabled, all
+     smaller, host supported vector lengths must also be enabled.  If
+     KVM is not enabled, then only all the smaller, power-of-two vector
+     lengths must be enabled.  E.g. with KVM if the host supports all
+     vector lengths up to 512-bits (128, 256, 384, 512), then if `sve512`
+     is enabled, the 128-bit vector length, 256-bit vector length, and
+     384-bit vector length must also be enabled. Without KVM, the 384-bit
+     vector length would not be required.
+
+  3) If KVM is enabled then only vector lengths that the host CPU type
+     support may be enabled.  If SVE is not supported by the host, then
+     no `sve*` properties may be enabled.
+
+SVE CPU Property Parsing Semantics
+----------------------------------
+
+  1) If SVE is disabled (`sve=off`), then which SVE vector lengths
+     are enabled or disabled is irrelevant to the guest, as the entire
+     SVE feature is disabled and that disables all vector lengths for
+     the guest.  However QEMU will still track any `sve<N>` CPU
+     properties provided by the user.  If later an `sve=on` is provided,
+     then the guest will get only the enabled lengths.  If no `sve=on`
+     is provided and there are explicitly enabled vector lengths, then
+     an error is generated.
+
+  2) If SVE is enabled (`sve=on`), but no `sve<N>` CPU properties are
+     provided, then all supported vector lengths are enabled, which when
+     KVM is not in use means including the non-power-of-two lengths, and,
+     when KVM is in use, it means all vector lengths supported by the host
+     processor.
+
+  3) If SVE is enabled, then an error is generated when attempting to
+     disable the last enabled vector length (see constraint (1) of "SVE
+     CPU Property Dependencies and Constraints").
+
+  4) If one or more vector lengths have been explicitly enabled and at
+     at least one of the dependency lengths of the maximum enabled length
+     has been explicitly disabled, then an error is generated (see
+     constraint (2) of "SVE CPU Property Dependencies and Constraints").
+
+  5) When KVM is enabled, if the host does not support SVE, then an error
+     is generated when attempting to enable any `sve*` properties (see
+     constraint (3) of "SVE CPU Property Dependencies and Constraints").
+
+  6) When KVM is enabled, if the host does support SVE, then an error is
+     generated when attempting to enable any vector lengths not supported
+     by the host (see constraint (3) of "SVE CPU Property Dependencies and
+     Constraints").
+
+  7) If one or more `sve<N>` CPU properties are set `off`, but no `sve<N>`,
+     CPU properties are set `on`, then the specified vector lengths are
+     disabled but the default for any unspecified lengths remains enabled.
+     When KVM is not enabled, disabling a power-of-two vector length also
+     disables all vector lengths larger than the power-of-two length.
+     When KVM is enabled, then disabling any supported vector length also
+     disables all larger vector lengths (see constraint (2) of "SVE CPU
+     Property Dependencies and Constraints").
+
+  8) If one or more `sve<N>` CPU properties are set to `on`, then they
+     are enabled and all unspecified lengths default to disabled, except
+     for the required lengths per constraint (2) of "SVE CPU Property
+     Dependencies and Constraints", which will even be auto-enabled if
+     they were not explicitly enabled.
+
+  9) If SVE was disabled (`sve=off`), allowing all vector lengths to be
+     explicitly disabled (i.e. avoiding the error specified in (3) of
+     "SVE CPU Property Parsing Semantics"), then if later an `sve=on` is
+     provided an error will be generated.  To avoid this error, one must
+     enable at least one vector length prior to enabling SVE.
+
+SVE CPU Property Examples
+-------------------------
+
+  1) Disable SVE::
+
+     $ qemu-system-aarch64 -M virt -cpu max,sve=off
+
+  2) Implicitly enable all vector lengths for the `max` CPU type::
+
+     $ qemu-system-aarch64 -M virt -cpu max
+
+  3) When KVM is enabled, implicitly enable all host CPU supported vector
+     lengths with the `host` CPU type::
+
+     $ qemu-system-aarch64 -M virt,accel=kvm -cpu host
+
+  4) Only enable the 128-bit vector length::
+
+     $ qemu-system-aarch64 -M virt -cpu max,sve128=on
+
+  5) Disable the 512-bit vector length and all larger vector lengths,
+     since 512 is a power-of-two.  This results in all the smaller,
+     uninitialized lengths (128, 256, and 384) defaulting to enabled::
+
+     $ qemu-system-aarch64 -M virt -cpu max,sve512=off
+
+  6) Enable the 128-bit, 256-bit, and 512-bit vector lengths::
+
+     $ qemu-system-aarch64 -M virt -cpu max,sve128=on,sve256=on,sve512=on
+
+  7) The same as (6), but since the 128-bit and 256-bit vector
+     lengths are required for the 512-bit vector length to be enabled,
+     then allow them to be auto-enabled::
+
+     $ qemu-system-aarch64 -M virt -cpu max,sve512=on
+
+  8) Do the same as (7), but by first disabling SVE and then re-enabling it::
+
+     $ qemu-system-aarch64 -M virt -cpu max,sve=off,sve512=on,sve=on
+
+  9) Force errors regarding the last vector length::
+
+     $ qemu-system-aarch64 -M virt -cpu max,sve128=off
+     $ qemu-system-aarch64 -M virt -cpu max,sve=off,sve128=off,sve=on
+
+SVE CPU Property Recommendations
+--------------------------------
+
+The examples in "SVE CPU Property Examples" exhibit many ways to select
+vector lengths which developers may find useful in order to avoid overly
+verbose command lines.  However, the recommended way to select vector
+lengths is to explicitly enable each desired length.  Therefore only
+example's (1), (4), and (6) exhibit recommended uses of the properties.
+
diff --git a/docs/system/arm/integratorcp.rst b/docs/system/arm/integratorcp.rst
new file mode 100644
index 0000000000..e6f050f602
--- /dev/null
+++ b/docs/system/arm/integratorcp.rst
@@ -0,0 +1,16 @@
+Integrator/CP (``integratorcp``)
+================================
+
+The Arm Integrator/CP board is emulated with the following devices:
+
+-  ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
+
+-  Two PL011 UARTs
+
+-  SMC 91c111 Ethernet adapter
+
+-  PL110 LCD controller
+
+-  PL050 KMI with PS/2 keyboard and mouse.
+
+-  PL181 MultiMedia Card Interface with SD card.
diff --git a/docs/system/arm/musicpal.rst b/docs/system/arm/musicpal.rst
new file mode 100644
index 0000000000..9de380edf8
--- /dev/null
+++ b/docs/system/arm/musicpal.rst
@@ -0,0 +1,19 @@
+Freecom MusicPal (``musicpal``)
+===============================
+
+The Freecom MusicPal internet radio emulation includes the following
+elements:
+
+-  Marvell MV88W8618 Arm core.
+
+-  32 MB RAM, 256 KB SRAM, 8 MB flash.
+
+-  Up to 2 16550 UARTs
+
+-  MV88W8xx8 Ethernet controller
+
+-  MV88W8618 audio controller, WM8750 CODEC and mixer
+
+-  128x64 display with brightness control
+
+-  2 buttons, 2 navigation wheels with button function
diff --git a/docs/system/arm/nseries.rst b/docs/system/arm/nseries.rst
new file mode 100644
index 0000000000..cd9edf5d88
--- /dev/null
+++ b/docs/system/arm/nseries.rst
@@ -0,0 +1,33 @@
+Nokia N800 and N810 tablets (``n800``, ``n810``)
+================================================
+
+Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 /
+48) emulation supports the following elements:
+
+-  Texas Instruments OMAP2420 System-on-chip (ARM1136 core)
+
+-  RAM and non-volatile OneNAND Flash memories
+
+-  Display connected to EPSON remote framebuffer chip and OMAP on-chip
+   display controller and a LS041y3 MIPI DBI-C controller
+
+-  TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen
+   controllers driven through SPI bus
+
+-  National Semiconductor LM8323-controlled qwerty keyboard driven
+   through |I2C| bus
+
+-  Secure Digital card connected to OMAP MMC/SD host
+
+-  Three OMAP on-chip UARTs and on-chip STI debugging console
+
+-  Mentor Graphics \"Inventra\" dual-role USB controller embedded in a
+   TI TUSB6010 chip - only USB host mode is supported
+
+-  TI TMP105 temperature sensor driven through |I2C| bus
+
+-  TI TWL92230C power management companion with an RTC on
+   |I2C| bus
+
+-  Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
+   through CBUS
diff --git a/docs/system/arm/palm.rst b/docs/system/arm/palm.rst
new file mode 100644
index 0000000000..47ff9b36d4
--- /dev/null
+++ b/docs/system/arm/palm.rst
@@ -0,0 +1,23 @@
+Palm Tungsten|E PDA (``cheetah``)
+=================================
+
+The Palm Tungsten|E PDA (codename \"Cheetah\") emulation includes the
+following elements:
+
+-  Texas Instruments OMAP310 System-on-chip (ARM925T core)
+
+-  ROM and RAM memories (ROM firmware image can be loaded with
+   -option-rom)
+
+-  On-chip LCD controller
+
+-  On-chip Real Time Clock
+
+-  TI TSC2102i touchscreen controller / analog-digital converter /
+   Audio CODEC, connected through MicroWire and |I2S| busses
+
+-  GPIO-connected matrix keypad
+
+-  Secure Digital card connected to OMAP MMC/SD host
+
+-  Three on-chip UARTs
diff --git a/docs/system/arm/realview.rst b/docs/system/arm/realview.rst
new file mode 100644
index 0000000000..65f5be346b
--- /dev/null
+++ b/docs/system/arm/realview.rst
@@ -0,0 +1,34 @@
+Arm Realview boards (``realview-eb``, ``realview-eb-mpcore``, ``realview-pb-a8``, ``realview-pbx-a9``)
+======================================================================================================
+
+Several variants of the Arm RealView baseboard are emulated, including
+the EB, PB-A8 and PBX-A9. Due to interactions with the bootloader, only
+certain Linux kernel configurations work out of the box on these boards.
+
+Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
+enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board
+should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
+disabled and expect 1024M RAM.
+
+The following devices are emulated:
+
+-  ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
+
+-  Arm AMBA Generic/Distributed Interrupt Controller
+
+-  Four PL011 UARTs
+
+-  SMC 91c111 or SMSC LAN9118 Ethernet adapter
+
+-  PL110 LCD controller
+
+-  PL050 KMI with PS/2 keyboard and mouse
+
+-  PCI host bridge
+
+-  PCI OHCI USB controller
+
+-  LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM
+   devices
+
+-  PL181 MultiMedia Card Interface with SD card.
diff --git a/docs/system/arm/stellaris.rst b/docs/system/arm/stellaris.rst
new file mode 100644
index 0000000000..8af4ad79c7
--- /dev/null
+++ b/docs/system/arm/stellaris.rst
@@ -0,0 +1,26 @@
+Stellaris boards (``lm3s6965evb``, ``lm3s811evb``)
+==================================================
+
+The Luminary Micro Stellaris LM3S811EVB emulation includes the following
+devices:
+
+-  Cortex-M3 CPU core.
+
+-  64k Flash and 8k SRAM.
+
+-  Timers, UARTs, ADC and |I2C| interface.
+
+-  OSRAM Pictiva 96x16 OLED with SSD0303 controller on
+   |I2C| bus.
+
+The Luminary Micro Stellaris LM3S6965EVB emulation includes the
+following devices:
+
+-  Cortex-M3 CPU core.
+
+-  256k Flash and 64k SRAM.
+
+-  Timers, UARTs, ADC, |I2C| and SSI interfaces.
+
+-  OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via
+   SSI.
diff --git a/docs/system/arm/sx1.rst b/docs/system/arm/sx1.rst
new file mode 100644
index 0000000000..8bce30d4b2
--- /dev/null
+++ b/docs/system/arm/sx1.rst
@@ -0,0 +1,18 @@
+Siemens SX1 (``sx1``, ``sx1-v1``)
+=================================
+
+The Siemens SX1 models v1 and v2 (default) basic emulation. The
+emulation includes the following elements:
+
+-  Texas Instruments OMAP310 System-on-chip (ARM925T core)
+
+-  ROM and RAM memories (ROM firmware image can be loaded with
+   -pflash) V1 1 Flash of 16MB and 1 Flash of 8MB V2 1 Flash of 32MB
+
+-  On-chip LCD controller
+
+-  On-chip Real Time Clock
+
+-  Secure Digital card connected to OMAP MMC/SD host
+
+-  Three on-chip UARTs
diff --git a/docs/system/arm/versatile.rst b/docs/system/arm/versatile.rst
new file mode 100644
index 0000000000..51221c30a4
--- /dev/null
+++ b/docs/system/arm/versatile.rst
@@ -0,0 +1,29 @@
+Arm Versatile boards (``versatileab``, ``versatilepb``)
+=======================================================
+
+The Arm Versatile baseboard is emulated with the following devices:
+
+-  ARM926E, ARM1136 or Cortex-A8 CPU
+
+-  PL190 Vectored Interrupt Controller
+
+-  Four PL011 UARTs
+
+-  SMC 91c111 Ethernet adapter
+
+-  PL110 LCD controller
+
+-  PL050 KMI with PS/2 keyboard and mouse.
+
+-  PCI host bridge. Note the emulated PCI bridge only provides access
+   to PCI memory space. It does not provide access to PCI IO space. This
+   means some devices (eg. ne2k_pci NIC) are not usable, and others (eg.
+   rtl8139 NIC) are only usable when the guest drivers use the memory
+   mapped control registers.
+
+-  PCI OHCI USB controller.
+
+-  LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM
+   devices.
+
+-  PL181 MultiMedia Card Interface with SD card.
diff --git a/docs/system/arm/xscale.rst b/docs/system/arm/xscale.rst
new file mode 100644
index 0000000000..89ec93e904
--- /dev/null
+++ b/docs/system/arm/xscale.rst
@@ -0,0 +1,29 @@
+Sharp XScale-based PDA models (``akita``, ``borzoi``, ``spitz``, ``terrier``)
+=============================================================================
+
+The XScale-based clamshell PDA models (\"Spitz\", \"Akita\", \"Borzoi\"
+and \"Terrier\") emulation includes the following peripherals:
+
+-  Intel PXA270 System-on-chip (ARMv5TE core)
+
+-  NAND Flash memory
+
+-  IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in \"Akita\"
+
+-  On-chip OHCI USB controller
+
+-  On-chip LCD controller
+
+-  On-chip Real Time Clock
+
+-  TI ADS7846 touchscreen controller on SSP bus
+
+-  Maxim MAX1111 analog-digital converter on |I2C| bus
+
+-  GPIO-connected keyboard controller and LEDs
+
+-  Secure Digital card connected to PXA MMC/SD host
+
+-  Three on-chip UARTs
+
+-  WM8750 audio CODEC on |I2C| and |I2S| busses
diff --git a/docs/system/target-arm.rst b/docs/system/target-arm.rst
index d2a3b44ce8..1425bd5303 100644
--- a/docs/system/target-arm.rst
+++ b/docs/system/target-arm.rst
@@ -1,217 +1,86 @@
 .. _ARM-System-emulator:
 
-ARM System emulator
+Arm System emulator
 -------------------
 
-Use the executable ``qemu-system-arm`` to simulate a ARM machine. The
-ARM Integrator/CP board is emulated with the following devices:
-
--  ARM926E, ARM1026E, ARM946E, ARM1136 or Cortex-A8 CPU
-
--  Two PL011 UARTs
-
--  SMC 91c111 Ethernet adapter
-
--  PL110 LCD controller
-
--  PL050 KMI with PS/2 keyboard and mouse.
-
--  PL181 MultiMedia Card Interface with SD card.
-
-The ARM Versatile baseboard is emulated with the following devices:
-
--  ARM926E, ARM1136 or Cortex-A8 CPU
-
--  PL190 Vectored Interrupt Controller
-
--  Four PL011 UARTs
-
--  SMC 91c111 Ethernet adapter
-
--  PL110 LCD controller
-
--  PL050 KMI with PS/2 keyboard and mouse.
-
--  PCI host bridge. Note the emulated PCI bridge only provides access
-   to PCI memory space. It does not provide access to PCI IO space. This
-   means some devices (eg. ne2k_pci NIC) are not usable, and others (eg.
-   rtl8139 NIC) are only usable when the guest drivers use the memory
-   mapped control registers.
-
--  PCI OHCI USB controller.
-
--  LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM
-   devices.
-
--  PL181 MultiMedia Card Interface with SD card.
-
-Several variants of the ARM RealView baseboard are emulated, including
-the EB, PB-A8 and PBX-A9. Due to interactions with the bootloader, only
-certain Linux kernel configurations work out of the box on these boards.
-
-Kernels for the PB-A8 board should have CONFIG_REALVIEW_HIGH_PHYS_OFFSET
-enabled in the kernel, and expect 512M RAM. Kernels for The PBX-A9 board
-should have CONFIG_SPARSEMEM enabled, CONFIG_REALVIEW_HIGH_PHYS_OFFSET
-disabled and expect 1024M RAM.
-
-The following devices are emulated:
-
--  ARM926E, ARM1136, ARM11MPCore, Cortex-A8 or Cortex-A9 MPCore CPU
-
--  ARM AMBA Generic/Distributed Interrupt Controller
-
--  Four PL011 UARTs
-
--  SMC 91c111 or SMSC LAN9118 Ethernet adapter
-
--  PL110 LCD controller
-
--  PL050 KMI with PS/2 keyboard and mouse
-
--  PCI host bridge
-
--  PCI OHCI USB controller
-
--  LSI53C895A PCI SCSI Host Bus Adapter with hard disk and CD-ROM
-   devices
-
--  PL181 MultiMedia Card Interface with SD card.
-
-The XScale-based clamshell PDA models (\"Spitz\", \"Akita\", \"Borzoi\"
-and \"Terrier\") emulation includes the following peripherals:
-
--  Intel PXA270 System-on-chip (ARM V5TE core)
-
--  NAND Flash memory
-
--  IBM/Hitachi DSCM microdrive in a PXA PCMCIA slot - not in \"Akita\"
-
--  On-chip OHCI USB controller
-
--  On-chip LCD controller
-
--  On-chip Real Time Clock
-
--  TI ADS7846 touchscreen controller on SSP bus
-
--  Maxim MAX1111 analog-digital converter on |I2C| bus
-
--  GPIO-connected keyboard controller and LEDs
-
--  Secure Digital card connected to PXA MMC/SD host
-
--  Three on-chip UARTs
-
--  WM8750 audio CODEC on |I2C| and |I2S| busses
-
-The Palm Tungsten|E PDA (codename \"Cheetah\") emulation includes the
-following elements:
-
--  Texas Instruments OMAP310 System-on-chip (ARM 925T core)
-
--  ROM and RAM memories (ROM firmware image can be loaded with
-   -option-rom)
-
--  On-chip LCD controller
-
--  On-chip Real Time Clock
-
--  TI TSC2102i touchscreen controller / analog-digital converter /
-   Audio CODEC, connected through MicroWire and |I2S| busses
-
--  GPIO-connected matrix keypad
-
--  Secure Digital card connected to OMAP MMC/SD host
-
--  Three on-chip UARTs
-
-Nokia N800 and N810 internet tablets (known also as RX-34 and RX-44 /
-48) emulation supports the following elements:
-
--  Texas Instruments OMAP2420 System-on-chip (ARM 1136 core)
-
--  RAM and non-volatile OneNAND Flash memories
-
--  Display connected to EPSON remote framebuffer chip and OMAP on-chip
-   display controller and a LS041y3 MIPI DBI-C controller
-
--  TI TSC2301 (in N800) and TI TSC2005 (in N810) touchscreen
-   controllers driven through SPI bus
-
--  National Semiconductor LM8323-controlled qwerty keyboard driven
-   through |I2C| bus
-
--  Secure Digital card connected to OMAP MMC/SD host
-
--  Three OMAP on-chip UARTs and on-chip STI debugging console
-
--  Mentor Graphics \"Inventra\" dual-role USB controller embedded in a
-   TI TUSB6010 chip - only USB host mode is supported
-
--  TI TMP105 temperature sensor driven through |I2C| bus
-
--  TI TWL92230C power management companion with an RTC on
-   |I2C| bus
-
--  Nokia RETU and TAHVO multi-purpose chips with an RTC, connected
-   through CBUS
-
-The Luminary Micro Stellaris LM3S811EVB emulation includes the following
-devices:
-
--  Cortex-M3 CPU core.
-
--  64k Flash and 8k SRAM.
-
--  Timers, UARTs, ADC and |I2C| interface.
-
--  OSRAM Pictiva 96x16 OLED with SSD0303 controller on
-   |I2C| bus.
-
-The Luminary Micro Stellaris LM3S6965EVB emulation includes the
-following devices:
-
--  Cortex-M3 CPU core.
-
--  256k Flash and 64k SRAM.
-
--  Timers, UARTs, ADC, |I2C| and SSI interfaces.
-
--  OSRAM Pictiva 128x64 OLED with SSD0323 controller connected via
-   SSI.
-
-The Freecom MusicPal internet radio emulation includes the following
-elements:
-
--  Marvell MV88W8618 ARM core.
-
--  32 MB RAM, 256 KB SRAM, 8 MB flash.
-
--  Up to 2 16550 UARTs
-
--  MV88W8xx8 Ethernet controller
-
--  MV88W8618 audio controller, WM8750 CODEC and mixer
-
--  128x64 display with brightness control
-
--  2 buttons, 2 navigation wheels with button function
-
-The Siemens SX1 models v1 and v2 (default) basic emulation. The
-emulation includes the following elements:
-
--  Texas Instruments OMAP310 System-on-chip (ARM 925T core)
-
--  ROM and RAM memories (ROM firmware image can be loaded with
-   -pflash) V1 1 Flash of 16MB and 1 Flash of 8MB V2 1 Flash of 32MB
-
--  On-chip LCD controller
-
--  On-chip Real Time Clock
-
--  Secure Digital card connected to OMAP MMC/SD host
-
--  Three on-chip UARTs
-
-A Linux 2.6 test image is available on the QEMU web site. More
-information is available in the QEMU mailing-list archive.
+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::
+
+   arm/integratorcp
+   arm/versatile
+   arm/realview
+   arm/xscale
+   arm/palm
+   arm/nseries
+   arm/stellaris
+   arm/musicpal
+   arm/sx1
+
+Arm CPU features
+================
+
+.. toctree::
+   arm/cpu-features