| Message ID | 20210720232703.10650-3-alex.bennee@linaro.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | various fixes pre-PR (metadata, docs, plugins, testing) | expand |
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: <20210714182056.25888-3-alex.bennee@linaro.org> > Cc: Markus Armbruster <armbru@redhat.com> > Cc: Paolo Bonzini <pbonzini@redhat.com> > Cc: Daniel P. Berrangé <berrange@redhat.com> > Cc: Eduardo Habkost <ehabkost@redhat.com> > > --- > v2 > - be a bit more precise about necessity of a buses > - add an example showing id/bus relations > --- > docs/system/device-emulation.rst | 89 +++++++++++++++++++++++ > 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, 90 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..7af5dbefab > --- /dev/null > +++ b/docs/system/device-emulation.rst > @@ -0,0 +1,89 @@ > +.. _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 > +============ > + > +Most devices will exist on a BUS of some sort. 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 address of first PCI bus found. However in > +complicated configurations you can explicitly specify what bus > +(``bus=ID``) a device is attached to along with its address > +(``addr=N``). > + > +Some devices, for example a PCI SCSI host controller, will add an > +additional buses to the system that other devices can be attached to. > +A hypothetical chain of devices might look like: > + > + --device foo,bus=pci.0,addr=0,id=foo > + --device bar,bus=foo.0,addr=1,id=baz PCI bus address 0 is the PCI bridge. Suggest to omit addr=0, or to use another, non-special PCI address. You might like addr=02.0 to hint at the fact that the syntax of bus addresses depends on the bus. > + > +which would be a bar device (with the ID of baz) which is attached to > +the first foo bus (foo.0) at address 1. The foo device which provides > +that bus is itself is attached to the first PCI bus (pci.0). > + > + > +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. > + > + > +Emulated Devices > +~~~~~~~~~~~~~~~~ > + > +.. toctree:: > + :maxdepth: 1 > + > + devices/ivshmem.rst > + devices/net.rst > + devices/nvme.rst > + devices/usb.rst > + devices/virtio-pmem.rst [...] Nothing serious, so Reviewed-by: Markus Armbruster <armbru@redhat.com>
diff --git a/docs/system/device-emulation.rst b/docs/system/device-emulation.rst new file mode 100644 index 0000000000..7af5dbefab --- /dev/null +++ b/docs/system/device-emulation.rst @@ -0,0 +1,89 @@ +.. _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 +============ + +Most devices will exist on a BUS of some sort. 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 address of first PCI bus found. However in +complicated configurations you can explicitly specify what bus +(``bus=ID``) a device is attached to along with its address +(``addr=N``). + +Some devices, for example a PCI SCSI host controller, will add an +additional buses to the system that other devices can be attached to. +A hypothetical chain of devices might look like: + + --device foo,bus=pci.0,addr=0,id=foo + --device bar,bus=foo.0,addr=1,id=baz + +which would be a bar device (with the ID of baz) which is attached to +the first foo bus (foo.0) at address 1. The foo device which provides +that bus is itself is attached to the first PCI bus (pci.0). + + +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 fda4b1b705..64a424ae99 100644 --- a/docs/system/index.rst +++ b/docs/system/index.rst @@ -11,15 +11,12 @@ or Hypervisor.Framework. quickstart invocation + device-emulation keys mux-chardev monitor images - net virtio-net-failover - usb - nvme - ivshmem linuxboot generic-loader guest-loader @@ -30,7 +27,6 @@ or Hypervisor.Framework. gdb managed-startup cpu-hotplug - virtio-pmem pr-manager targets security
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: <20210714182056.25888-3-alex.bennee@linaro.org> Cc: Markus Armbruster <armbru@redhat.com> Cc: Paolo Bonzini <pbonzini@redhat.com> Cc: Daniel P. Berrangé <berrange@redhat.com> Cc: Eduardo Habkost <ehabkost@redhat.com> --- v2 - be a bit more precise about necessity of a buses - add an example showing id/bus relations --- docs/system/device-emulation.rst | 89 +++++++++++++++++++++++ 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, 90 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%)