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.ben...@linaro.org> Message-Id: <20210714093638.21077-3-alex.ben...@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 +(``-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 +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 +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 +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. + + +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 -- 2.20.1