[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH 4/4] docs: add an introduction to the system docs
From: |
Peter Maydell |
Subject: |
Re: [PATCH 4/4] docs: add an introduction to the system docs |
Date: |
Tue, 17 Jan 2023 14:01:39 +0000 |
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
- [PATCH 0/4] Improve the introductory documentation, Alex Bennée, 2023/01/13
- [PATCH 1/4] docs: add hotlinks to about preface text, Alex Bennée, 2023/01/13
- [PATCH 2/4] docs: add a new section to outline emulation support, Alex Bennée, 2023/01/13
- [PATCH 4/4] docs: add an introduction to the system docs, Alex Bennée, 2023/01/13
- [PATCH 3/4] semihosting: add semihosting section to the docs, Alex Bennée, 2023/01/13
- Re: [PATCH 0/4] Improve the introductory documentation, Richard Henderson, 2023/01/13