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

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

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>    


[...]

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