Re: [PATCH v2 20/35] docs: add a new section to outline emulation support

[Thomas Huth]

On 24/01/2023 19.01, Alex Bennée wrote:
> This affects both system and user mode emulation so we should probably
> list it up front.
>
> Acked-by: Richard Henderson <richard.henderson@linaro.org>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
> ---
> v2
>    - HPs -> HP's
>    - MIPs-like -> MIPS-like
> ---
>   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..bdc0630b35
> --- /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

I'd maybe rather say "provides" instead of "gives it".

> +number of CPU architectures on any supported platform. Both

I'd maybe add a "host" between "supported" and "platform.

> +: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

Maybe just use "User" instead of "User-mode" to make the column smaller?

> +    - 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 HP's 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

Would it be possible to link the "Yes" entries in the "System" column to 
corresponding target-*.rst files? E.g. docs/system/target-m68k.rst for the 
m68k entry?

> +    - Yes
> +    - Motorola 68000 variants and ColdFire
> +  * - Microblaze
> +    - Yes
> +    - Yes
> +    - RISC based soft-core by Xilinx
> +  * - MIPS (mips, mipsel, mips64, mips64el)

The table renders very badly for me, the last column is cut off and you need 
to scroll to see its contents. This seems mainly to happen since this MIPS 
entry is very long. Could the information in the parentheses maybe be 
shortened to "(mips*)" or be dropped completely?

 Thomas