| Message ID | 20210714182056.25888-3-alex.bennee@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | documentation and metadata updates | expand |
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
Markus Armbruster <armbru@redhat.com> writes: > 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' Are they user-pluggable though? Aside from strange cases like loaders most of them look like SoC specific adornments which I suspect would make no sense to attach to another machine type. x86_64 seems to be a special case has all the various CPU types show up as non-bus devices. > >> +(``-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. So how about: 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.0 --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 foo bus foo.0 which itself is attached to the first slot of a PCI bus pci.0 Maybe we should add a section about device IDs? -- Alex Bennée
Alex Bennée <alex.bennee@linaro.org> writes: > Markus Armbruster <armbru@redhat.com> writes: > >> 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' > > > Are they user-pluggable though? Aside from strange cases like loaders > most of them look like SoC specific adornments which I suspect would > make no sense to attach to another machine type. qdev_device_add() has code for plugging bus-less devices. Goes back to 2f7bd829db "qdev: Fix device_add bus assumptions", 2013-04-16. > x86_64 seems to be a > special case has all the various CPU types show up as non-bus devices. The CPU types are non-bus devices everywhere. For some targets, they're pluggable. Check out ppc64 and s390x. >>> +(``-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. > > So how about: > > 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``). Maybe break the paragraph here? > 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.0 > --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 foo bus foo.0 which itself is attached to the first slot of a PCI > bus pci.0 Uh, the naming is... more complicated %-} $ ../qemu/bld/qemu-system-x86_64 -device lsi,id=foo.0 -device scsi-cd,bus=foo.0 qemu-system-x86_64: -device scsi-cd,bus=foo.0: Bus 'foo.0' not found The bus ID is commonly derived from the ID of the device that provides it, here 'foo.0'. The first bus is named ID.0, here 'foo.0.0'. A second bus would be named ID.1, and so forth. The example should say --device foo,bus=pci.0,addr=0,id=foo --device bar,bus=foo.0,addr=1,id=baz > Maybe we should add a section about device IDs? We can always improve on top.
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
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%) -- 2.20.1