diff mbox series

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

Message ID 20230113133923.1642627-5-alex.bennee@linaro.org
State Superseded
Headers show
Series Improve the introductory documentation | expand

Commit Message

Alex Bennée Jan. 13, 2023, 1:39 p.m. UTC
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

Comments

Kashyap Chamarthy Jan. 13, 2023, 3:09 p.m. UTC | #1
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>    


[...]
Peter Maydell Jan. 17, 2023, 2:01 p.m. UTC | #2
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
diff mbox series

Patch

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, \