On Fri, 13 Jan 2023 at 13:39, Alex Bennée <alex.ben...@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.ben...@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
