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

[Markus Armbruster]

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.