Alex Bennée <alex.ben...@linaro.org> writes:
> Markus Armbruster <arm...@redhat.com> writes:
>
>> Cc: QOM maintainers for additional eyes.
>>
>> Alex Bennée <alex.ben...@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.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
>>
>> 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.
