This affects both system and user mode emulation so we should probably
list it up front.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/about/emulation.rst      | 103 ++++++++++++++++++++++++++++++++++
 docs/about/index.rst          |   1 +
 docs/devel/tcg-plugins.rst    |   2 +
 docs/system/arm/emulation.rst |   2 +
 4 files changed, 108 insertions(+)
 create mode 100644 docs/about/emulation.rst

diff --git a/docs/about/emulation.rst b/docs/about/emulation.rst
new file mode 100644
index 0000000000..d919175b5e
--- /dev/null
+++ b/docs/about/emulation.rst
@@ -0,0 +1,103 @@
+Emulation
+=========
+
+QEMU's Tiny Code Generator (TCG) gives it the ability to emulate a
+number of CPU architectures on any supported platform. Both
+:ref:`System Emulation` and :ref:`User Mode Emulation` are supported
+depending on the guest architecture.
+
+.. list-table:: Supported Guest Architectures for Emulation
+  :widths: 30 10 10 50
+  :header-rows: 1
+
+  * - Architecture (qemu name)
+    - System
+    - User-mode
+    - Notes
+  * - Alpha
+    - Yes
+    - Yes
+    - Legacy 64 bit RISC ISA developed by DEC
+  * - Arm (arm, aarch64)
+    - Yes
+    - Yes
+    - Wide range of features, see :ref:`Arm Emulation` for details
+  * - AVR
+    - Yes
+    - No
+    - 8 bit micro controller, often used in maker projects
+  * - Cris
+    - Yes
+    - Yes
+    - Embedded RISC chip developed by AXIS
+  * - Hexagon
+    - No
+    - Yes
+    - Family of DSPs by Qualcomm
+  * - PA-RISC (hppa)
+    - Yes
+    - Yes
+    - A legacy RISC system used in HPs old minicomputers
+  * - x86 (i386, x86_64)
+    - Yes
+    - Yes
+    - The ubiquitous desktop PC CPU architecture, 32 and 64 bit.
+  * - Loongarch
+    - Yes
+    - Yes
+    - A MIPs-like 64bit RISC architecture developed in China
+  * - m68k
+    - Yes
+    - Yes
+    - Motorola 68000 variants and ColdFire
+  * - Microblaze
+    - Yes
+    - Yes
+    - RISC based soft-core by Xilinx
+  * - MIPS (mips, mipsel, mips64, mips64el)
+    - Yes
+    - Yes
+    - Venerable RISC architecture originally out of Stanford University
+  * - Nios2
+    - Yes
+    - Yes
+    - 32 bit embedded soft-core by Altera
+  * - OpenRISC
+    - Yes
+    - Yes
+    - Open source RISC architecture developed by the OpenRISC community
+  * - Power (ppc, ppc64)
+    - Yes
+    - Yes
+    - A general purpose RISC architecture now managed by IBM
+  * - RISC-V
+    - Yes
+    - Yes
+    - An open standard RISC ISA maintained by RISC-V International
+  * - RX
+    - Yes
+    - No
+    - A 32 bit micro controller developed by Renesas
+  * - s390x
+    - Yes
+    - Yes
+    - A 64 bit CPU found in IBM's System Z mainframes
+  * - sh4
+    - Yes
+    - Yes
+    - A 32 bit RISC embedded CPU developed by Hitachi
+  * - SPARC (sparc, sparc64)
+    - Yes
+    - Yes
+    - A RISC ISA originally developed by Sun Microsystems
+  * - Tricore
+    - Yes
+    - No
+    - A 32 bit RISC/uController/DSP developed by Infineon
+  * - Xtensa
+    - Yes
+    - Yes
+    - A configurable 32 bit soft core now owned by Cadence
+
+A number of features are are only available when running under
+emulation including :ref:`Record/Replay<replay>` and :ref:`TCG Plugins`.
diff --git a/docs/about/index.rst b/docs/about/index.rst
index bae1309cc6..b00b584b31 100644
--- a/docs/about/index.rst
+++ b/docs/about/index.rst
@@ -23,6 +23,7 @@ allows you to create, convert and modify disk images.
    :maxdepth: 2
 
    build-platforms
+   emulation
    deprecated
    removed-features
    license
diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst
index 9740a70406..81dcd43a61 100644
--- a/docs/devel/tcg-plugins.rst
+++ b/docs/devel/tcg-plugins.rst
@@ -3,6 +3,8 @@
    Copyright (c) 2019, Linaro Limited
    Written by Emilio Cota and Alex Bennée
 
+.. _TCG Plugins:
+
 QEMU TCG Plugins
 ================
 
diff --git a/docs/system/arm/emulation.rst b/docs/system/arm/emulation.rst
index b33d7c28dc..b87e064d9d 100644
--- a/docs/system/arm/emulation.rst
+++ b/docs/system/arm/emulation.rst
@@ -1,3 +1,5 @@
+.. _Arm Emulation:
+
 A-profile CPU architecture support
 ==================================
 
-- 
2.34.1

On Fri, 13 Jan 2023 at 13:39, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> This affects both system and user mode emulation so we should probably
> list it up front.

I'm not super-enthusiastic about this simply because it
breaks the current arrangement we have where everything
in about/ is relatively brief meta-information about QEMU:
build platforms, deprecated and removed features, license.

On the other hand I don't have an obvious better idea to
hand for where to put it.

> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  docs/about/emulation.rst      | 103 ++++++++++++++++++++++++++++++++++
>  docs/about/index.rst          |   1 +
>  docs/devel/tcg-plugins.rst    |   2 +
>  docs/system/arm/emulation.rst |   2 +
>  4 files changed, 108 insertions(+)
>  create mode 100644 docs/about/emulation.rst
>
> diff --git a/docs/about/emulation.rst b/docs/about/emulation.rst
> new file mode 100644
> index 0000000000..d919175b5e
> --- /dev/null
> +++ b/docs/about/emulation.rst
> @@ -0,0 +1,103 @@
> +Emulation
> +=========
> +
> +QEMU's Tiny Code Generator (TCG) gives it the ability to emulate a
> +number of CPU architectures on any supported platform. Both
> +:ref:`System Emulation` and :ref:`User Mode Emulation` are supported
> +depending on the guest architecture.
> +
> +.. list-table:: Supported Guest Architectures for Emulation
> +  :widths: 30 10 10 50
> +  :header-rows: 1
> +
> +  * - Architecture (qemu name)
> +    - System
> +    - User-mode
> +    - Notes
> +  * - Alpha
> +    - Yes
> +    - Yes
> +    - Legacy 64 bit RISC ISA developed by DEC
> +  * - Arm (arm, aarch64)
> +    - Yes
> +    - Yes
> +    - Wide range of features, see :ref:`Arm Emulation` for details
> +  * - AVR
> +    - Yes
> +    - No
> +    - 8 bit micro controller, often used in maker projects
> +  * - Cris
> +    - Yes
> +    - Yes
> +    - Embedded RISC chip developed by AXIS
> +  * - Hexagon
> +    - No
> +    - Yes
> +    - Family of DSPs by Qualcomm
> +  * - PA-RISC (hppa)
> +    - Yes
> +    - Yes
> +    - A legacy RISC system used in HPs old minicomputers

"HP's"

> +  * - x86 (i386, x86_64)
> +    - Yes
> +    - Yes
> +    - The ubiquitous desktop PC CPU architecture, 32 and 64 bit.
> +  * - Loongarch
> +    - Yes
> +    - Yes
> +    - A MIPs-like 64bit RISC architecture developed in China

"MIPS-like".

> +  * - m68k
> +    - Yes
> +    - Yes
> +    - Motorola 68000 variants and ColdFire
> +  * - Microblaze
> +    - Yes
> +    - Yes
> +    - RISC based soft-core by Xilinx
> +  * - MIPS (mips, mipsel, mips64, mips64el)
> +    - Yes
> +    - Yes
> +    - Venerable RISC architecture originally out of Stanford University
> +  * - Nios2
> +    - Yes
> +    - Yes
> +    - 32 bit embedded soft-core by Altera
> +  * - OpenRISC
> +    - Yes
> +    - Yes
> +    - Open source RISC architecture developed by the OpenRISC community
> +  * - Power (ppc, ppc64)
> +    - Yes
> +    - Yes
> +    - A general purpose RISC architecture now managed by IBM
> +  * - RISC-V
> +    - Yes
> +    - Yes
> +    - An open standard RISC ISA maintained by RISC-V International
> +  * - RX
> +    - Yes
> +    - No
> +    - A 32 bit micro controller developed by Renesas
> +  * - s390x
> +    - Yes
> +    - Yes
> +    - A 64 bit CPU found in IBM's System Z mainframes
> +  * - sh4
> +    - Yes
> +    - Yes
> +    - A 32 bit RISC embedded CPU developed by Hitachi
> +  * - SPARC (sparc, sparc64)
> +    - Yes
> +    - Yes
> +    - A RISC ISA originally developed by Sun Microsystems
> +  * - Tricore
> +    - Yes
> +    - No
> +    - A 32 bit RISC/uController/DSP developed by Infineon
> +  * - Xtensa
> +    - Yes
> +    - Yes
> +    - A configurable 32 bit soft core now owned by Cadence
> +

-- PMM