Re: [PATCH v2 02/21] docs: collect the disparate device emulation docs into one section

[Markus Armbruster]

Cc: QOM maintainers for additional eyes.

Alex Bennée <alex.bennee@linaro.org> writes:

> While we are at it add a brief preamble that explains some of the
> common concepts in QEMU's device emulation which will hopefully lead
> to less confusing about our dizzying command line options.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> Message-Id: <20210714093638.21077-3-alex.bennee@linaro.org>
> ---
>  docs/system/device-emulation.rst          | 78 +++++++++++++++++++++++
>  docs/system/{ => devices}/ivshmem.rst     |  0
>  docs/system/{ => devices}/net.rst         |  0
>  docs/system/{ => devices}/nvme.rst        |  0
>  docs/system/{ => devices}/usb.rst         |  0
>  docs/system/{ => devices}/virtio-pmem.rst |  0
>  docs/system/index.rst                     |  6 +-
>  7 files changed, 79 insertions(+), 5 deletions(-)
>  create mode 100644 docs/system/device-emulation.rst
>  rename docs/system/{ => devices}/ivshmem.rst (100%)
>  rename docs/system/{ => devices}/net.rst (100%)
>  rename docs/system/{ => devices}/nvme.rst (100%)
>  rename docs/system/{ => devices}/usb.rst (100%)
>  rename docs/system/{ => devices}/virtio-pmem.rst (100%)
>
> diff --git a/docs/system/device-emulation.rst 
> b/docs/system/device-emulation.rst
> new file mode 100644
> index 0000000000..3156eeac2d
> --- /dev/null
> +++ b/docs/system/device-emulation.rst
> @@ -0,0 +1,78 @@
> +.. _device-emulation:
> +
> +Device Emulation
> +----------------
> +
> +QEMU supports the emulation of a large number of devices from
> +peripherals such network cards and USB devices to integrated systems
> +on a chip (SoCs). Configuration of these is often a source of
> +confusion so it helps to have an understanding of some of the terms
> +used to describes devices within QEMU.
> +
> +Common Terms
> +~~~~~~~~~~~~
> +
> +Device Front End
> +================
> +
> +A device front end is how a device is presented to the guest. The type
> +of device presented should match the hardware that the guest operating
> +system is expecting to see. All devices can be specified with the
> +``--device`` command line option. Running QEMU with the command line
> +options ``--device help`` will list all devices it is aware of. Using
> +the command line ``--device foo,help`` will list the additional
> +configuration options available for that device.
> +
> +A front end is often paired with a back end, which describes how the
> +host's resources are used in the emulation.
> +
> +Device Buses
> +============
> +
> +All devices exist on a BUS. Depending on the machine model you choose

This isn't true anymore; there are bus-less devices.  To show the
user-pluggable ones, try

    $ qemu-system-FOO -device help | grep -v '", bus'

> +(``-M foo``) a number of buses will have been automatically created.
> +In most cases the BUS a device is attached to can be inferred, for
> +example PCI devices are generally automatically allocated to the next
> +free slot of the PCI bus. However in complicated configurations you

"The PCI bus" tacitly assumes there's just one.

We actually pick the first bus (in qtree pre-order) that can take
another device.  Best not to rely on the search order; if you care which
bus to plug into, specify it with bus=ID.

"Next free slot" is about the device address on the bus.  Should we
explain the concept "device address on a bus"?

> +can explicitly specify what bus a device is attached to and its
> +address. Some devices, for example a PCI SCSI host controller, will
> +add an additional bus to the system that other devices can be attached

A device can add more than one bus.

> +to.
> +
> +Device Back End
> +===============
> +
> +The back end describes how the data from the emulated device will be
> +processed by QEMU. The configuration of the back end is usually
> +specific to the class of device being emulated. For example serial
> +devices will be backed by a ``--chardev`` which can redirect the data
> +to a file or socket or some other system. Storage devices are handled
> +by ``--blockdev`` which will specify how blocks are handled, for
> +example being stored in a qcow2 file or accessing a raw host disk
> +partition. Back ends can sometimes be stacked to implement features
> +like snapshots.
> +
> +While the choice of back end is generally transparent to the guest

Comma, I think.

> +there are cases where features will not be reported to the guest if
> +the back end is unable to support it.
> +
> +Device Pass Through
> +===================
> +
> +Device pass through is where the device is actually given access to
> +the underlying hardware. This can be as simple as exposing a single
> +USB device on the host system to the guest or dedicating a video card
> +in a PCI slot to the exclusive use of the guest.

Thanks for writing this up!

> +
> +
> +Emulated Devices
> +~~~~~~~~~~~~~~~~
> +
> +.. toctree::
> +   :maxdepth: 1
> +
> +   devices/ivshmem.rst
> +   devices/net.rst
> +   devices/nvme.rst
> +   devices/usb.rst
> +   devices/virtio-pmem.rst
> diff --git a/docs/system/ivshmem.rst b/docs/system/devices/ivshmem.rst
> similarity index 100%
> rename from docs/system/ivshmem.rst
> rename to docs/system/devices/ivshmem.rst
> diff --git a/docs/system/net.rst b/docs/system/devices/net.rst
> similarity index 100%
> rename from docs/system/net.rst
> rename to docs/system/devices/net.rst
> diff --git a/docs/system/nvme.rst b/docs/system/devices/nvme.rst
> similarity index 100%
> rename from docs/system/nvme.rst
> rename to docs/system/devices/nvme.rst
> diff --git a/docs/system/usb.rst b/docs/system/devices/usb.rst
> similarity index 100%
> rename from docs/system/usb.rst
> rename to docs/system/devices/usb.rst
> diff --git a/docs/system/virtio-pmem.rst b/docs/system/devices/virtio-pmem.rst
> similarity index 100%
> rename from docs/system/virtio-pmem.rst
> rename to docs/system/devices/virtio-pmem.rst
> diff --git a/docs/system/index.rst b/docs/system/index.rst
> index 6092eb2d91..641d243ba4 100644
> --- a/docs/system/index.rst
> +++ b/docs/system/index.rst
> @@ -16,15 +16,12 @@ Contents:
>  
>     quickstart
>     invocation
> +   device-emulation
>     keys
>     mux-chardev
>     monitor
>     images
> -   net
>     virtio-net-failover
> -   usb
> -   nvme
> -   ivshmem
>     linuxboot
>     generic-loader
>     guest-loader
> @@ -35,7 +32,6 @@ Contents:
>     gdb
>     managed-startup
>     cpu-hotplug
> -   virtio-pmem
>     pr-manager
>     targets
>     security