[PATCH 0/4] Improve the introductory documentation

[PATCH 0/4] Improve the introductory documentation

[Alex Bennée]

I've split this off from my bigger branch for hopefully fast review
turnaround. This also includes the new semihsoting documentation and
takes into account feedback from Peter on IRC.

Let me know what you think.

Alex Bennée (4):
  docs: add hotlinks to about preface text
  docs: add a new section to outline emulation support
  semihosting: add semihosting section to the docs
  docs: add an introduction to the system docs

 docs/about/emulation.rst      | 183 ++++++++++++++++++++++++++++
 docs/about/index.rst          |  17 +--
 docs/devel/tcg-plugins.rst    |   2 +
 docs/interop/qemu-qmp-ref.rst |   2 +
 docs/system/arm/emulation.rst |   2 +
 docs/system/index.rst         |   4 +-
 docs/system/introduction.rst  | 216 ++++++++++++++++++++++++++++++++++
 docs/system/multi-process.rst |   2 +
 docs/system/quickstart.rst    |  21 ----
 docs/tools/index.rst          |   2 +
 docs/user/index.rst           |   2 +
 qemu-options.hx               |  30 ++---
 12 files changed, 436 insertions(+), 47 deletions(-)
 create mode 100644 docs/about/emulation.rst
 create mode 100644 docs/system/introduction.rst
 delete mode 100644 docs/system/quickstart.rst

-- 
2.34.1

[PATCH 1/4] docs: add hotlinks to about preface text

[Alex Bennée]

Make it easier to navigate the documentation.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/about/index.rst  | 16 ++++++++--------
 docs/system/index.rst |  2 ++
 docs/tools/index.rst  |  2 ++
 docs/user/index.rst   |  2 ++
 4 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/docs/about/index.rst b/docs/about/index.rst
index 5bea653c07..bae1309cc6 100644
--- a/docs/about/index.rst
+++ b/docs/about/index.rst
@@ -5,19 +5,19 @@ About QEMU
 QEMU is a generic and open source machine emulator and virtualizer.
 
 QEMU can be used in several different ways. The most common is for
-"system emulation", where it provides a virtual model of an
+:ref:`System Emulation`, where it provides a virtual model of an
 entire machine (CPU, memory and emulated devices) to run a guest OS.
-In this mode the CPU may be fully emulated, or it may work with
-a hypervisor such as KVM, Xen, Hax or Hypervisor.Framework to
-allow the guest to run directly on the host CPU.
+In this mode the CPU may be fully emulated, or it may work with a
+hypervisor such as KVM, Xen, Hax or Hypervisor.Framework to allow the
+guest to run directly on the host CPU.
 
-The second supported way to use QEMU is "user mode emulation",
+The second supported way to use QEMU is :ref:`User Mode Emulation`,
 where QEMU can launch processes compiled for one CPU on another CPU.
 In this mode the CPU is always emulated.
 
-QEMU also provides a number of standalone commandline utilities,
-such as the ``qemu-img`` disk image utility that allows you to create,
-convert and modify disk images.
+QEMU also provides a number of standalone :ref:`command line
+utilities<Tools>`, such as the ``qemu-img`` disk image utility that
+allows you to create, convert and modify disk images.
 
 .. toctree::
    :maxdepth: 2
diff --git a/docs/system/index.rst b/docs/system/index.rst
index e3695649c5..282b6ffb56 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -1,3 +1,5 @@
+.. _System Emulation:
+
 ----------------
 System Emulation
 ----------------
diff --git a/docs/tools/index.rst b/docs/tools/index.rst
index 1edd5a8054..2151adcf78 100644
--- a/docs/tools/index.rst
+++ b/docs/tools/index.rst
@@ -1,3 +1,5 @@
+.. _Tools:
+
 -----
 Tools
 -----
diff --git a/docs/user/index.rst b/docs/user/index.rst
index 2c4e29f3db..782d27cda2 100644
--- a/docs/user/index.rst
+++ b/docs/user/index.rst
@@ -1,3 +1,5 @@
+.. _User Mode Emulation:
+
 -------------------
 User Mode Emulation
 -------------------
-- 
2.34.1

Re: [PATCH 1/4] docs: add hotlinks to about preface text

[Peter Maydell]

On Fri, 13 Jan 2023 at 13:39, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> Make it easier to navigate the documentation.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  docs/about/index.rst  | 16 ++++++++--------
>  docs/system/index.rst |  2 ++
>  docs/tools/index.rst  |  2 ++
>  docs/user/index.rst   |  2 ++
>  4 files changed, 14 insertions(+), 8 deletions(-)
>
> diff --git a/docs/about/index.rst b/docs/about/index.rst
> index 5bea653c07..bae1309cc6 100644
> --- a/docs/about/index.rst
> +++ b/docs/about/index.rst
> @@ -5,19 +5,19 @@ About QEMU
>  QEMU is a generic and open source machine emulator and virtualizer.
>
>  QEMU can be used in several different ways. The most common is for
> -"system emulation", where it provides a virtual model of an
> +:ref:`System Emulation`, where it provides a virtual model of an
>  entire machine (CPU, memory and emulated devices) to run a guest OS.



> -In this mode the CPU may be fully emulated, or it may work with
> -a hypervisor such as KVM, Xen, Hax or Hypervisor.Framework to
> -allow the guest to run directly on the host CPU.
> +In this mode the CPU may be fully emulated, or it may work with a
> +hypervisor such as KVM, Xen, Hax or Hypervisor.Framework to allow the
> +guest to run directly on the host CPU.

Any particular reason for this change? As far as I can tell it's just
rewrapping these there lines?

Otherwise
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM

[PATCH 2/4] docs: add a new section to outline emulation support

[Alex Bennée]

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

Re: [PATCH 2/4] docs: add a new section to outline emulation support

[Peter Maydell]

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

[PATCH 3/4] semihosting: add semihosting section to the docs

[Alex Bennée]

The main reason to do this is to document our O_BINARY implementation
decision somewhere. However I've also moved some of the implementation
details out of qemu-options and added links between the two. As a
bonus I've highlighted the scary warnings about host access with the
appropriate RST tags.

Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---
v2
  - moved inside the generic emulation section
---
 docs/about/emulation.rst | 80 ++++++++++++++++++++++++++++++++++++++++
 qemu-options.hx          | 27 +++++---------
 2 files changed, 90 insertions(+), 17 deletions(-)

diff --git a/docs/about/emulation.rst b/docs/about/emulation.rst
index d919175b5e..4d978e697b 100644
--- a/docs/about/emulation.rst
+++ b/docs/about/emulation.rst
@@ -101,3 +101,83 @@ depending on the guest architecture.
 
 A number of features are are only available when running under
 emulation including :ref:`Record/Replay<replay>` and :ref:`TCG Plugins`.
+
+.. _Semihosting:
+
+Semihosting
+-----------
+
+Semihosting is a feature provided by a number of guests that allow the
+program running on the target to interact with the host system. On
+real hardware this is usually provided by a debugger hooked directly
+to the system.
+
+Generally semihosting makes it easier to bring up low level code before a
+more fully functional operating system has been enabled. On QEMU it
+also allows for embedded micro-controller code which typically doesn't
+have a full libc to be run as "bare-metal" code under QEMU's user-mode
+emulation. It is also useful for writing test cases and indeed a
+number of compiler suites as well as QEMU itself use semihosting calls
+to exit test code while reporting the success state.
+
+Semihosting is only available using TCG emulation. This is because the
+instructions to trigger a semihosting call are typically reserved
+causing most hypervisors to trap and fault on them.
+
+.. warning::
+   Semihosting inherently bypasses any isolation there may be between
+   the guest and the host. As a result a program using semihosting can
+   happily trash your host system. You should only ever run trusted
+   code with semihosting enabled.
+
+Redirection
+~~~~~~~~~~~
+
+Semihosting calls can be re-directed to a (potentially remote) gdb
+during debugging via the :ref:`gdbstub<GDB usage>`. Output to the
+semihosting console is configured as a ``chardev`` so can be
+redirected to a file, pipe or socket like any other ``chardev``
+device.
+
+See :ref:`Semihosting Options<Semihosting Options>` for details.
+
+Supported Targets
+~~~~~~~~~~~~~~~~~
+
+Most targets offer a similar semihosting implementations with some
+minor changes to define the appropriate instruction to encode the
+semihosting call and which registers hold the parameters. They tend to
+presents a simple POSIX-like API which allows your program to read and
+write files, access the console and some other basic interactions.
+
+.. note::
+   QEMU makes an implementation decision to implement all file access
+   in ``O_BINARY`` mode regardless of the host operating system. This
+   is because gdb semihosting support doesn't make the distinction
+   between the modes and magically processing line endings can be confusing.
+
+.. list-table:: Guest Architectures supporting Semihosting
+  :widths: 10 10 80
+  :header-rows: 1
+
+  * - Architecture
+    - Modes
+    - Specification
+  * - Arm
+    - System and User-mode
+    - https://github.com/ARM-software/abi-aa/blob/main/semihosting/semihosting.rst
+  * - m68k
+    - System
+    - https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=libgloss/m68k/m68k-semi.txt;hb=HEAD
+  * - mips
+    - System
+    - Unified Hosting Interface (MD01069)
+  * - Nios II
+    - System
+    - https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;a=blob;f=libgloss/nios2/nios2-semi.txt;hb=HEAD
+  * - RISC-V
+    - System and User-mode
+    - https://github.com/riscv/riscv-semihosting-spec/blob/main/riscv-semihosting-spec.adoc
+  * - Xtensa
+    - System
+    - Tensilica ISS SIMCALL
diff --git a/qemu-options.hx b/qemu-options.hx
index 3aa3a2f5a3..de3a368f58 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -4633,10 +4633,13 @@ DEF("semihosting", 0, QEMU_OPTION_semihosting,
     QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
 SRST
 ``-semihosting``
-    Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V only).
+    Enable :ref:`Semihosting` mode (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V only).
 
-    Note that this allows guest direct access to the host filesystem, so
-    should only be used with a trusted guest OS.
+    .. warning::
+      Note that this allows guest direct access to the host filesystem, so
+      should only be used with a trusted guest OS.
+
+    .. _Semihosting Options:
 
     See the -semihosting-config option documentation for further
     information about the facilities this enables.
@@ -4648,22 +4651,12 @@ QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA |
 QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
 SRST
 ``-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,userspace=on|off][,arg=str[,...]]``
-    Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V
+    Enable and configure :ref:`Semihosting` (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V
     only).
 
-    Note that this allows guest direct access to the host filesystem, so
-    should only be used with a trusted guest OS.
-
-    On Arm this implements the standard semihosting API, version 2.0.
-
-    On M68K this implements the "ColdFire GDB" interface used by
-    libgloss.
-
-    Xtensa semihosting provides basic file IO calls, such as
-    open/read/write/seek/select. Tensilica baremetal libc for ISS and
-    linux platform "sim" use this interface.
-
-    On RISC-V this implements the standard semihosting API, version 0.2.
+    .. warning::
+      Note that this allows guest direct access to the host filesystem, so
+      should only be used with a trusted guest OS.
 
     ``target=native|gdb|auto``
         Defines where the semihosting calls will be addressed, to QEMU
-- 
2.34.1

Re: [PATCH 3/4] semihosting: add semihosting section to the docs

[Peter Maydell]

On Fri, 13 Jan 2023 at 13:39, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> The main reason to do this is to document our O_BINARY implementation
> decision somewhere. However I've also moved some of the implementation
> details out of qemu-options and added links between the two. As a
> bonus I've highlighted the scary warnings about host access with the
> appropriate RST tags.
>
> Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
> ---
> v2
>   - moved inside the generic emulation section
> ---
>  docs/about/emulation.rst | 80 ++++++++++++++++++++++++++++++++++++++++
>  qemu-options.hx          | 27 +++++---------
>  2 files changed, 90 insertions(+), 17 deletions(-)
>
> diff --git a/docs/about/emulation.rst b/docs/about/emulation.rst
> index d919175b5e..4d978e697b 100644
> --- a/docs/about/emulation.rst
> +++ b/docs/about/emulation.rst
> @@ -101,3 +101,83 @@ depending on the guest architecture.
>
>  A number of features are are only available when running under
>  emulation including :ref:`Record/Replay<replay>` and :ref:`TCG Plugins`.
> +
> +.. _Semihosting:
> +
> +Semihosting
> +-----------
> +
> +Semihosting is a feature provided by a number of guests that allow the

It's not provided by the guest, it's provided by QEMU... The
important thing here is that semihosting is an API defined by
somebody else, eg the owner of the architecture, and QEMU
offers an implementation of it.

> +program running on the target to interact with the host system. On
> +real hardware this is usually provided by a debugger hooked directly
> +to the system.
> +
> +Generally semihosting makes it easier to bring up low level code before a
> +more fully functional operating system has been enabled. On QEMU it
> +also allows for embedded micro-controller code which typically doesn't
> +have a full libc to be run as "bare-metal" code under QEMU's user-mode
> +emulation. It is also useful for writing test cases and indeed a
> +number of compiler suites as well as QEMU itself use semihosting calls
> +to exit test code while reporting the success state.
> +
> +Semihosting is only available using TCG emulation. This is because the
> +instructions to trigger a semihosting call are typically reserved
> +causing most hypervisors to trap and fault on them.
> +
> +.. warning::
> +   Semihosting inherently bypasses any isolation there may be between
> +   the guest and the host. As a result a program using semihosting can
> +   happily trash your host system. You should only ever run trusted
> +   code with semihosting enabled.

(One of these days I might write the patch for 'safe semihosting'
which limits support to only non-harmful functions like console
output and makes all the file access stuff return an error...)

> +
> +Redirection
> +~~~~~~~~~~~
> +
> +Semihosting calls can be re-directed to a (potentially remote) gdb
> +during debugging via the :ref:`gdbstub<GDB usage>`. Output to the
> +semihosting console is configured as a ``chardev`` so can be
> +redirected to a file, pipe or socket like any other ``chardev``
> +device.
> +
> +See :ref:`Semihosting Options<Semihosting Options>` for details.
> +
> +Supported Targets
> +~~~~~~~~~~~~~~~~~
> +
> +Most targets offer a similar semihosting implementations with some

"offer similar"

> +minor changes to define the appropriate instruction to encode the
> +semihosting call and which registers hold the parameters. They tend to
> +presents a simple POSIX-like API which allows your program to read and
> +write files, access the console and some other basic interactions.

"For full details of the ABI for a particular target, and the
set of calls it provides, you should consult the semihosting
specification for that architecture."

> +
> +.. note::
> +   QEMU makes an implementation decision to implement all file access
> +   in ``O_BINARY`` mode regardless of the host operating system.

We should say what the user-visible effect of this is (i.e. that even
if the semihosting API the guest uses makes a distinction between
"text" and "binary" mode files, QEMU does not, and no line-terminator
conversion is performed for input or output).

> This
> +   is because gdb semihosting support doesn't make the distinction
> +   between the modes and magically processing line endings can be confusing.
> +
> +.. list-table:: Guest Architectures supporting Semihosting
> +  :widths: 10 10 80
> +  :header-rows: 1
> +
> +  * - Architecture
> +    - Modes
> +    - Specification
> +  * - Arm
> +    - System and User-mode
> +    - https://github.com/ARM-software/abi-aa/blob/main/semihosting/semihosting.rst
> +  * - m68k
> +    - System
> +    - https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=libgloss/m68k/m68k-semi.txt;hb=HEAD
> +  * - mips
> +    - System
> +    - Unified Hosting Interface (MD01069)
> +  * - Nios II
> +    - System
> +    - https://sourceware.org/git/gitweb.cgi?p=newlib-cygwin.git;a=blob;f=libgloss/nios2/nios2-semi.txt;hb=HEAD
> +  * - RISC-V
> +    - System and User-mode
> +    - https://github.com/riscv/riscv-semihosting-spec/blob/main/riscv-semihosting-spec.adoc
> +  * - Xtensa
> +    - System
> +    - Tensilica ISS SIMCALL

We should be consistent in this table whether we're naming the
architectures by their official names (eg "RISC-V"), or by the
QEMU lowercase names for them (eg "mips").

> diff --git a/qemu-options.hx b/qemu-options.hx
> index 3aa3a2f5a3..de3a368f58 100644
> --- a/qemu-options.hx
> +++ b/qemu-options.hx
> @@ -4633,10 +4633,13 @@ DEF("semihosting", 0, QEMU_OPTION_semihosting,
>      QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
>  SRST
>  ``-semihosting``
> -    Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V only).
> +    Enable :ref:`Semihosting` mode (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V only).
>
> -    Note that this allows guest direct access to the host filesystem, so
> -    should only be used with a trusted guest OS.
> +    .. warning::
> +      Note that this allows guest direct access to the host filesystem, so
> +      should only be used with a trusted guest OS.
> +
> +    .. _Semihosting Options:

Does this render OK in the manpage version of this text ?

>      See the -semihosting-config option documentation for further
>      information about the facilities this enables.
> @@ -4648,22 +4651,12 @@ QEMU_ARCH_ARM | QEMU_ARCH_M68K | QEMU_ARCH_XTENSA |
>  QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
>  SRST
>  ``-semihosting-config [enable=on|off][,target=native|gdb|auto][,chardev=id][,userspace=on|off][,arg=str[,...]]``
> -    Enable and configure semihosting (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V
> +    Enable and configure :ref:`Semihosting` (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V
>      only).
>
> -    Note that this allows guest direct access to the host filesystem, so
> -    should only be used with a trusted guest OS.
> -
> -    On Arm this implements the standard semihosting API, version 2.0.
> -
> -    On M68K this implements the "ColdFire GDB" interface used by
> -    libgloss.
> -
> -    Xtensa semihosting provides basic file IO calls, such as
> -    open/read/write/seek/select. Tensilica baremetal libc for ISS and
> -    linux platform "sim" use this interface.
> -
> -    On RISC-V this implements the standard semihosting API, version 0.2.
> +    .. warning::
> +      Note that this allows guest direct access to the host filesystem, so
> +      should only be used with a trusted guest OS.
>
>      ``target=native|gdb|auto``
>          Defines where the semihosting calls will be addressed, to QEMU
> --
> 2.34.1
>



-- PMM

Re: [PATCH 3/4] semihosting: add semihosting section to the docs

[Alex Bennée]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Fri, 13 Jan 2023 at 13:39, Alex Bennée <alex.bennee@linaro.org> wrote:
>>
<snip>
>> diff --git a/qemu-options.hx b/qemu-options.hx
>> index 3aa3a2f5a3..de3a368f58 100644
>> --- a/qemu-options.hx
>> +++ b/qemu-options.hx
>> @@ -4633,10 +4633,13 @@ DEF("semihosting", 0, QEMU_OPTION_semihosting,
>>      QEMU_ARCH_MIPS | QEMU_ARCH_NIOS2 | QEMU_ARCH_RISCV)
>>  SRST
>>  ``-semihosting``
>> -    Enable semihosting mode (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V only).
>> +    Enable :ref:`Semihosting` mode (ARM, M68K, Xtensa, MIPS, Nios II, RISC-V only).
>>
>> -    Note that this allows guest direct access to the host filesystem, so
>> -    should only be used with a trusted guest OS.
>> +    .. warning::
>> +      Note that this allows guest direct access to the host filesystem, so
>> +      should only be used with a trusted guest OS.
>> +
>> +    .. _Semihosting Options:
>
> Does this render OK in the manpage version of this text ?

Seems to yes.

-- 
Alex Bennée
Virtualisation Tech Lead @ Linaro

[PATCH 4/4] docs: add an introduction to the system docs

[Alex Bennée]

Drop the frankly misleading quickstart section for a more rounded
introduction section. This new section gives an overview of the
accelerators and high level introduction to some of the key features
of the emulator. We also expand on a general form for a QEMU command
line with a hopefully not too scary worked example of what this looks
like.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 docs/interop/qemu-qmp-ref.rst |   2 +
 docs/system/index.rst         |   2 +-
 docs/system/introduction.rst  | 216 ++++++++++++++++++++++++++++++++++
 docs/system/multi-process.rst |   2 +
 docs/system/quickstart.rst    |  21 ----
 qemu-options.hx               |   3 +
 6 files changed, 224 insertions(+), 22 deletions(-)
 create mode 100644 docs/system/introduction.rst
 delete mode 100644 docs/system/quickstart.rst

diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst
index 357effd64f..f94614a0b2 100644
--- a/docs/interop/qemu-qmp-ref.rst
+++ b/docs/interop/qemu-qmp-ref.rst
@@ -1,3 +1,5 @@
+.. _QMP Ref:
+
 QEMU QMP Reference Manual
 =========================
 
diff --git a/docs/system/index.rst b/docs/system/index.rst
index 282b6ffb56..3605bbe1ce 100644
--- a/docs/system/index.rst
+++ b/docs/system/index.rst
@@ -12,7 +12,7 @@ or Hypervisor.Framework.
 .. toctree::
    :maxdepth: 3
 
-   quickstart
+   introduction
    invocation
    device-emulation
    keys
diff --git a/docs/system/introduction.rst b/docs/system/introduction.rst
new file mode 100644
index 0000000000..15e4cf773d
--- /dev/null
+++ b/docs/system/introduction.rst
@@ -0,0 +1,216 @@
+Introduction
+============
+
+Virtualisation Accelerators
+---------------------------
+
+QEMU's system emulation provides a virtual model of a machine (CPU,
+memory and emulated devices) to run a guest OS. It supports a number
+of hypervisors (known as accelerators) as well as a dynamic JIT known
+as the Tiny Code Generator (TCG) capable of emulating many CPUs.
+
+.. list-table:: Supported Accelerators
+  :header-rows: 1
+
+  * - Accelerator
+    - Host OS
+    - Host Architectures
+  * - KVM
+    - Linux
+    - Arm (64 bit only), MIPS, PPC, RISC-V, s390x, x86
+  * - Xen
+    - Linux (as dom0)
+    - Arm, x86
+  * - Intel HAXM (hax)
+    - Linux, Windows
+    - x86
+  * - Hypervisor Framework (hvf)
+    - MacOS
+    - x86 (64 bit only), Arm (64 bit only)
+  * - Windows Hypervisor Platform (wphx)
+    - Windows
+    - x86
+  * - NetBSD Virtual Machine Monitor (nvmm)
+    - NetBSD
+    - x86
+  * - Tiny Code Generator (tcg)
+    - Linux, other POSIX, Windows, MacOS
+    - Arm, x86, Loongarch64, MIPS, PPC, s390x, Sparc64
+
+Feature Overview
+----------------
+
+System emulation provides a wide range of device models to emulate
+various hardware components you may want to add to your machine. This
+includes a wide number of VirtIO devices which are specifically tuned
+for efficient operation under virtualisation. Some of the device
+emulation can be offloaded from the main QEMU process using either
+vhost-user (for VirtIO) or :ref:`Multi-process QEMU`. If the platform
+supports it QEMU also supports directly passing devices through to
+guest VMs to eliminate the device emulation overhead. See
+:ref:`device-emulation` for more details.
+
+There is a full featured block layer allows for construction of
+complex storage topology which can be stacked across multiple layers
+supporting redirection, networking, snapshots and migration support.
+
+The flexible ``chardev`` system allows for handling IO from character
+like devices using stdio, files, unix sockets and TCP networking.
+
+QEMU provides a number of management interfaces including a line based
+:ref:`Human Monitor Protocol (HMP)<QEMU monitor>` that allows you to
+dynamically add and remove devices as well as introspect the system
+state. The :ref:`QEMU Monitor Protocol<QMP Ref>` (QMP) is a well
+defined, versioned, machine usable API that presents a rich interface
+to other tools to create, control and manage Virtual Machines. This is
+the interface used by higher level tools interfaces such as `Virt
+Manager <https://virt-manager.org/>`_ using the `libvirt framework
+<https://libvirt.org>`_.
+
+For the common accelerators QEMU supported debugging with its
+:ref:`gdbstub<GDB usage>` which allows users to connect GDB and debug
+system software images.
+
+Running
+-------
+
+QEMU provides a rich and complex API which can be overwhelming to
+understand. While some architectures can boot something with just a
+disk image those examples elide a lot of details with defaults that
+may not be optimal for modern systems.
+
+For a non-x86 system where we emulate a broad range of machine types,
+the command lines are generally more explicit in defining the machine
+and boot behaviour. You will find often find example command lines in
+the :ref:`system-targets-ref` section of the manual.
+
+While the project doesn't want to discourage users from using the
+command line to launch VMs we do want to highlight there are a number
+of projects dedicated to providing a more user friendly experience.
+Those built around the ``libvirt`` framework can make use of feature
+probing to build modern VM images tailored to run on the hardware you
+have.
+
+That said the general form of a QEMU command line could be expressed
+as:
+
+.. parsed-literal::
+
+  $ |qemu_system| [machine opts] \\
+                  [cpu opts] \\
+                  [accelerator opts] \\
+                  [device opts] \\
+                  [backend opts] \\
+                  [interface opts] \\
+                  [boot opts] 
+
+Most options will generate some help information. So for example:
+
+.. parsed-literal::
+
+   $ |qemu_system| -M help
+
+will list the supported machine types by that QEMU binary. Help can
+also be passed as an argument to another option. For example:
+
+.. parsed-literal::
+
+  $ |qemu_system| -device scsi-hd,help
+
+will list the arguments and their default values of additional options
+that can control the behaviour of the ``scsi-hd`` device.
+
+.. list-table:: Options Overview
+  :header-rows: 1
+  :widths: 10, 90
+
+  * - Options
+    -
+  * - Machine
+    - Define the :ref:`machine type<Machine Options>`, amount of memory etc
+  * - CPU
+    - Type and number/topology of vCPUs. Most accelerators offer
+      a ``host`` cpu option which simply passes through your host CPU
+      configurtaion without filtering out any features.
+  * - Accelerator
+    - This will depend on the hypervisor you run, will fallback to
+      slow TCG emulation by default
+  * - Devices
+    - Additional devices that are not defined as default with the
+      machine type
+  * - Backends
+    - Backends are how QEMU deals with the guests data, for example
+      how a block device is stored, how network devices see the
+      network or a serial device is directed to the outside world.
+  * - Interfaces
+    - How the system is displayed, how it is managed and controlled or
+      debugged
+  * - Boot
+    - How the system boots, via firmware or direct kernel boot
+
+In the following example we first define a ``virt`` machine which is a
+general purpose platform for running Aarch64 guests. We enable
+virtualisation so we can use KVM inside the emulated guest
+
+.. code::
+
+ $ qemu-system-aarch64 \
+    -machine type=virt,virtualization=on \
+    -m 4096 \
+
+We then define the 4 vCPUs using the ``max`` option which gives us all
+the Arm features QEMU is capable of emulating. We enable a more
+emulation friendly implementation of Arm's pointer authentication
+algorithm. We specify TCG acceleration (although it would actually
+default to that)
+
+.. code::
+
+ -cpu max,pauth-impdef=on \
+ -smp 4 \
+ -accel tcg \
+
+As the ``virt`` platform doesn't have any default network or storage
+devices we need to define them. We give them ids so we can link them
+with the backend later on.
+
+.. code::
+
+ -device virtio-net-pci,netdev=unet \
+ -device virtio-scsi-pci \
+ -device scsi-hd,drive=hd \
+
+We connect the user-mode networking to our network device. As
+user-mode networking isn't directly accessible from the outside world
+we forward localhost port 2222 to the ssh port on the guest.
+
+.. code::
+
+ -netdev user,id=unet,hostfwd=tcp::2222-:22 \
+
+We connect the guest visible block device to an LVM partition we have
+set aside for our guest.
+
+.. code::
+
+ -blockdev driver=raw,node-name=hd,file.driver=host_device,file.filename=/dev/lvm-disk/debian-bullseye-arm64 \
+
+We then tell QEMU to multiplex the :ref:`QEMU monitor` with the serial
+port output (we can switch between the two using :ref:`keys in the
+character backend multiplexer`). As there is no default graphical
+device we disable the display as we can work entirely in the terminal.
+
+.. code::
+
+ -serial mon:stdio \
+ -display none \
+
+Finally we override the default firmware to ensure we have have some
+storage for EFI to persist its configuration. That firmware is
+responsible for finding the disk, booting grub and eventually running
+our system.
+
+.. code::
+
+ -drive if=pflash,file=(pwd)/pc-bios/edk2-aarch64-code.fd,format=raw,readonly=on \
+ -drive if=pflash,file=$HOME/images/qemu-arm64-efivars,format=raw
diff --git a/docs/system/multi-process.rst b/docs/system/multi-process.rst
index 210531ee17..16f0352416 100644
--- a/docs/system/multi-process.rst
+++ b/docs/system/multi-process.rst
@@ -1,3 +1,5 @@
+.. _Multi-process QEMU:
+
 Multi-process QEMU
 ==================
 
diff --git a/docs/system/quickstart.rst b/docs/system/quickstart.rst
deleted file mode 100644
index 681678c86e..0000000000
--- a/docs/system/quickstart.rst
+++ /dev/null
@@ -1,21 +0,0 @@
-.. _pcsys_005fquickstart:
-
-Quick Start
------------
-
-Download and uncompress a PC hard disk image with Linux installed (e.g.
-``linux.img``) and type:
-
-.. parsed-literal::
-
-   |qemu_system| linux.img
-
-Linux should boot and give you a prompt.
-
-Users should be aware the above example elides a lot of the complexity
-of setting up a VM with x86_64 specific defaults and assumes the
-first non switch argument is a PC compatible disk image with a boot
-sector. For a non-x86 system where we emulate a broad range of machine
-types, the command lines are generally more explicit in defining the
-machine and boot behaviour. You will find more example command lines
-in the :ref:`system-targets-ref` section of the manual.
diff --git a/qemu-options.hx b/qemu-options.hx
index de3a368f58..1568f1e496 100644
--- a/qemu-options.hx
+++ b/qemu-options.hx
@@ -20,6 +20,9 @@ DEF("version", 0, QEMU_OPTION_version,
 SRST
 ``-version``
     Display version information and exit
+
+    .. _Machine Options:
+
 ERST
 
 DEF("machine", HAS_ARG, QEMU_OPTION_machine, \
-- 
2.34.1

Re: [PATCH 4/4] docs: add an introduction to the system docs

[Kashyap Chamarthy]

On Fri, Jan 13, 2023 at 01:39:23PM +0000, Alex Bennée wrote:
> Drop the frankly misleading quickstart section for a more rounded
> introduction section. This new section gives an overview of the
> accelerators and high level introduction to some of the key features
> of the emulator. We also expand on a general form for a QEMU command
> line with a hopefully not too scary worked example of what this looks
> like.

Thank you for this improvement!

The rendered version you shared on IRC looks quite good already.

https://qemu-stsquad.readthedocs.io/en/docs-next/system/introduction.html

The only main comment I have is to use -blockdev (instead of '-drive')
for the examples of overriding default firmware further below.  Two
reasons: consistency and IIUC, '-drive' is slated for deprecation in the
future.

Besides that, just a couple of small nits below, feel free to pick and
choose what you prefer :-)

> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---

[...]

> +Introduction
> +============
> +
> +Virtualisation Accelerators
> +---------------------------
> +
> +QEMU's system emulation provides a virtual model of a machine (CPU,
> +memory and emulated devices) to run a guest OS. It supports a number
> +of hypervisors (known as accelerators) as well as a dynamic JIT known
> +as the Tiny Code Generator (TCG) capable of emulating many CPUs.

Nit: might want to expand JIT as well (although if someone is reading
this page, they'd already know what it is).  So up to you :-)

[...]

> +There is a full featured block layer allows for construction of

Nit: s/allows/that allows/

> +complex storage topology which can be stacked across multiple layers
> +supporting redirection, networking, snapshots and migration support.

Speaking of which, consider hyper-linking this doc:
https://qemu.readthedocs.io/en/latest/interop/live-block-operations.html

[...]

> +For the common accelerators QEMU supported debugging with its
> +:ref:`gdbstub<GDB usage>` which allows users to connect GDB and debug
> +system software images

Readability tweak for the first part of the sentence:

    For the common accelerators, QEMU supports debugging with its [...]

> +Running
> +-------

[...]

> +While the project doesn't want to discourage users from using the
> +command line to launch VMs we do want to highlight there are a number

Nit: small tweak:

    [...] to launch VMs, we do want to highlight that there are [...]


[...]

> +We then tell QEMU to multiplex the :ref:`QEMU monitor` with the serial
> +port output (we can switch between the two using :ref:`keys in the
> +character backend multiplexer`). As there is no default graphical
> +device we disable the display as we can work entirely in the terminal.
> +
> +.. code::
> +
> + -serial mon:stdio \
> + -display none \

Nice that you mention "-serial mon:stdio" which doesn't terminate QEMU
on Ctrl-c (while "-serial stdio" does :-)).

> +
> +Finally we override the default firmware to ensure we have have some
> +storage for EFI to persist its configuration. That firmware is
> +responsible for finding the disk, booting grub and eventually running
> +our system.
> +
> +.. code::
> +
> + -drive if=pflash,file=(pwd)/pc-bios/edk2-aarch64-code.fd,format=raw,readonly=on \
> + -drive if=pflash,file=$HOME/images/qemu-arm64-efivars,format=raw

Here, -blockdev.  (I don't have a replacement invocation off-hand,
afraid.)

Regardless of whether these are addressed, this is a strict improvement:

Reviewed-by: Kashyap Chamarthy <kchamart@redhat.com>    


[...]

-- 
/kashyap

Re: [PATCH 4/4] docs: add an introduction to the system docs

[Peter Maydell]

On Fri, 13 Jan 2023 at 13:39, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> Drop the frankly misleading quickstart section for a more rounded
> introduction section. This new section gives an overview of the
> accelerators and high level introduction to some of the key features
> of the emulator. We also expand on a general form for a QEMU command
> line with a hopefully not too scary worked example of what this looks
> like.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

Yes, the quickstart section is definitely something worth dumping.

> ---
>  docs/interop/qemu-qmp-ref.rst |   2 +
>  docs/system/index.rst         |   2 +-
>  docs/system/introduction.rst  | 216 ++++++++++++++++++++++++++++++++++
>  docs/system/multi-process.rst |   2 +
>  docs/system/quickstart.rst    |  21 ----
>  qemu-options.hx               |   3 +
>  6 files changed, 224 insertions(+), 22 deletions(-)
>  create mode 100644 docs/system/introduction.rst
>  delete mode 100644 docs/system/quickstart.rst
>
> diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst
> index 357effd64f..f94614a0b2 100644
> --- a/docs/interop/qemu-qmp-ref.rst
> +++ b/docs/interop/qemu-qmp-ref.rst
> @@ -1,3 +1,5 @@
> +.. _QMP Ref:
> +
>  QEMU QMP Reference Manual
>  =========================
>
> diff --git a/docs/system/index.rst b/docs/system/index.rst
> index 282b6ffb56..3605bbe1ce 100644
> --- a/docs/system/index.rst
> +++ b/docs/system/index.rst
> @@ -12,7 +12,7 @@ or Hypervisor.Framework.
>  .. toctree::
>     :maxdepth: 3
>
> -   quickstart
> +   introduction
>     invocation
>     device-emulation
>     keys
> diff --git a/docs/system/introduction.rst b/docs/system/introduction.rst
> new file mode 100644
> index 0000000000..15e4cf773d
> --- /dev/null
> +++ b/docs/system/introduction.rst
> @@ -0,0 +1,216 @@
> +Introduction
> +============
> +
> +Virtualisation Accelerators
> +---------------------------
> +
> +QEMU's system emulation provides a virtual model of a machine (CPU,
> +memory and emulated devices) to run a guest OS. It supports a number
> +of hypervisors (known as accelerators) as well as a dynamic JIT known
> +as the Tiny Code Generator (TCG) capable of emulating many CPUs.
> +
> +.. list-table:: Supported Accelerators
> +  :header-rows: 1
> +
> +  * - Accelerator
> +    - Host OS
> +    - Host Architectures
> +  * - KVM
> +    - Linux
> +    - Arm (64 bit only), MIPS, PPC, RISC-V, s390x, x86
> +  * - Xen
> +    - Linux (as dom0)
> +    - Arm, x86
> +  * - Intel HAXM (hax)
> +    - Linux, Windows
> +    - x86
> +  * - Hypervisor Framework (hvf)
> +    - MacOS
> +    - x86 (64 bit only), Arm (64 bit only)
> +  * - Windows Hypervisor Platform (wphx)
> +    - Windows
> +    - x86
> +  * - NetBSD Virtual Machine Monitor (nvmm)
> +    - NetBSD
> +    - x86
> +  * - Tiny Code Generator (tcg)
> +    - Linux, other POSIX, Windows, MacOS
> +    - Arm, x86, Loongarch64, MIPS, PPC, s390x, Sparc64
> +
> +Feature Overview
> +----------------
> +
> +System emulation provides a wide range of device models to emulate
> +various hardware components you may want to add to your machine. This
> +includes a wide number of VirtIO devices which are specifically tuned
> +for efficient operation under virtualisation. Some of the device
> +emulation can be offloaded from the main QEMU process using either
> +vhost-user (for VirtIO) or :ref:`Multi-process QEMU`. If the platform
> +supports it QEMU also supports directly passing devices through to
> +guest VMs to eliminate the device emulation overhead. See
> +:ref:`device-emulation` for more details.
> +
> +There is a full featured block layer allows for construction of

"which allows"

> +complex storage topology which can be stacked across multiple layers
> +supporting redirection, networking, snapshots and migration support.
> +
> +The flexible ``chardev`` system allows for handling IO from character
> +like devices using stdio, files, unix sockets and TCP networking.
> +
> +QEMU provides a number of management interfaces including a line based
> +:ref:`Human Monitor Protocol (HMP)<QEMU monitor>` that allows you to
> +dynamically add and remove devices as well as introspect the system
> +state. The :ref:`QEMU Monitor Protocol<QMP Ref>` (QMP) is a well
> +defined, versioned, machine usable API that presents a rich interface
> +to other tools to create, control and manage Virtual Machines. This is
> +the interface used by higher level tools interfaces such as `Virt
> +Manager <https://virt-manager.org/>`_ using the `libvirt framework
> +<https://libvirt.org>`_.
> +
> +For the common accelerators QEMU supported debugging with its
> +:ref:`gdbstub<GDB usage>` which allows users to connect GDB and debug
> +system software images.
> +
> +Running
> +-------
> +
> +QEMU provides a rich and complex API which can be overwhelming to
> +understand. While some architectures can boot something with just a
> +disk image those examples elide a lot of details with defaults that

"disk image, "

> +may not be optimal for modern systems.
> +
> +For a non-x86 system where we emulate a broad range of machine types,
> +the command lines are generally more explicit in defining the machine
> +and boot behaviour. You will find often find example command lines in
> +the :ref:`system-targets-ref` section of the manual.
> +
> +While the project doesn't want to discourage users from using the
> +command line to launch VMs we do want to highlight there are a number

"VMs, "

"highlight that"

> +of projects dedicated to providing a more user friendly experience.
> +Those built around the ``libvirt`` framework can make use of feature
> +probing to build modern VM images tailored to run on the hardware you
> +have.
> +
> +That said the general form of a QEMU command line could be expressed

"That said, ". "can be expressed"

> +as:
> +
> +.. parsed-literal::
> +
> +  $ |qemu_system| [machine opts] \\
> +                  [cpu opts] \\
> +                  [accelerator opts] \\
> +                  [device opts] \\
> +                  [backend opts] \\
> +                  [interface opts] \\
> +                  [boot opts]
> +
> +Most options will generate some help information. So for example:
> +
> +.. parsed-literal::
> +
> +   $ |qemu_system| -M help
> +
> +will list the supported machine types by that QEMU binary. Help can

"the machine types supported by that QEMU binary"

"``help`` can"

> +also be passed as an argument to another option. For example:
> +
> +.. parsed-literal::
> +
> +  $ |qemu_system| -device scsi-hd,help
> +
> +will list the arguments and their default values of additional options
> +that can control the behaviour of the ``scsi-hd`` device.
> +
> +.. list-table:: Options Overview
> +  :header-rows: 1
> +  :widths: 10, 90
> +
> +  * - Options
> +    -
> +  * - Machine
> +    - Define the :ref:`machine type<Machine Options>`, amount of memory etc
> +  * - CPU
> +    - Type and number/topology of vCPUs. Most accelerators offer
> +      a ``host`` cpu option which simply passes through your host CPU
> +      configurtaion without filtering out any features.

"configuration"

> +  * - Accelerator
> +    - This will depend on the hypervisor you run, will fallback to
> +      slow TCG emulation by default

"Note that the default is TCG, which is purely emulated, so
you must specify an accelerator type to take advantage of
hardware virtualization."


> +  * - Devices
> +    - Additional devices that are not defined as default with the

"by default"

> +      machine type
> +  * - Backends
> +    - Backends are how QEMU deals with the guests data, for example

"guest's"

> +      how a block device is stored, how network devices see the
> +      network or a serial device is directed to the outside world.

"or how"

> +  * - Interfaces
> +    - How the system is displayed, how it is managed and controlled or
> +      debugged

We should be consistent about whether we end these bullet points
with a full stop or not.

> +  * - Boot
> +    - How the system boots, via firmware or direct kernel boot
> +
> +In the following example we first define a ``virt`` machine which is a
> +general purpose platform for running Aarch64 guests. We enable
> +virtualisation so we can use KVM inside the emulated guest

Missing full stop.


thanks
-- PMM

Re: [PATCH 0/4] Improve the introductory documentation

[Richard Henderson]

On 1/13/23 05:39, Alex Bennée wrote:
> Alex Bennée (4):
>    docs: add hotlinks to about preface text
>    docs: add a new section to outline emulation support
>    semihosting: add semihosting section to the docs
>    docs: add an introduction to the system docs

Looks ok.

Acked-by: Richard Henderson <richard.henderson@linaro.org>


r~