Re: [PATCH 1/3] docs/s390x: document the virtual css

[Thomas Huth <thuth@redhat.com>]

On 05/05/2020 15.50, Cornelia Huck wrote:
> Add some hints about "devno" rules.

Thanks a lot for doing this, some documentation in this area is
extremely useful!

> Signed-off-by: Cornelia Huck <cohuck@redhat.com>
> ---
>  docs/system/s390x/css.rst    | 64 ++++++++++++++++++++++++++++++++++++
>  docs/system/target-s390x.rst |  1 +
>  2 files changed, 65 insertions(+)
>  create mode 100644 docs/system/s390x/css.rst
> 
> diff --git a/docs/system/s390x/css.rst b/docs/system/s390x/css.rst
> new file mode 100644
> index 000000000000..8e18194a2f0a
> --- /dev/null
> +++ b/docs/system/s390x/css.rst
> @@ -0,0 +1,64 @@
> +The virtual channel subsystem
> +=============================
> +
> +QEMU implements a virtual channel subsystem with subchannels, (mostly
> +functionless) channel paths, and channel devices (virtio-ccw, 3270, and
> +devices passed via vfio-ccw). It supports multiple subchannel sets (MSS) and
> +multiple channel subsystems extended (MCSS-E).
> +
> +All channel devices support the ``devno`` property, which takes a parameter
> +in the form ``<cssid>.<ssid>.<device number>``.
> +
> +The default channel subsystem image id (``<cssid>``) is ``0xfe``. Devices in
> +there will show up in channel subsystem image ``0`` to guests that do not
> +enable MCSS-E. Note that devices with a different cssid will not be visible
> +if the guest OS does not enable MCSS-E (which is true of all supported guest
> +operating systems today).
> +
> +Supported values for the subchannel set id (``<ssid>``) range from ``0-3``.
> +Devices with a ssid that is not ``0`` will not be visible if the guest OS
> +does not enable MSS (any Linux version that supports virtio also enables MSS).
> +Any device may be put into any subchannel set, there is no restriction by
> +device type.
> +
> +The device number can range from ``0-0xffff``.
> +
> +If the ``devno`` property is not specified for a device, QEMU will choose the
> +next free device number in subchannel set 0, skipping to the next subchannel
> +set if no more device numbers are free.
> +
> +QEMU places a device at the first free subchannel in the specified subchannel
> +set. If a device is hotunplugged and later replugged, it may appear at a
> +different subchannel. (This is similar to how z/VM works.)
> +
> +
> +Examples
> +--------
> +
> +* a virtio-net device, cssid/ssid/devno automatically assigned::
> +
> +    -device virtio-net-ccw
> +
> +  In a Linux guest (without default devices and no other devices specified
> +  prior to this one), this will show up as ``0.0.0000`` under subchannel
> +  ``0.0.0000``.

Maybe mention the QEMU side again, e.g. that when you run "info qtree"
in the HMP monitor, you see the device with dev_id = "fe.0.0000".

> +* a virtio-rng device in subchannel set ``0``::
> +
> +    -device virtio-rng-ccw,devno=fe.0.0042
> +
> +  If added to the same Linux guest as above, it would show up as ``0.0.0042``
> +  under subchannel ``0.0.0001``.

Does "same" matter here? Otherwise, maybe just say "to a Linux guest" ?

> +* a virtio-gpu device in subchannel set ``2``::
> +
> +    -device virtio-gpu-ccw,devno=fe.2.1111
> +
> +  If added to the same Linux guest as above, it would show up as ``0.2.1111``
> +  under subchannel ``0.2.0000``.

Dito.

> +* a virtio-mouse device in a non-standard channel subsystem::
> +
> +    -device virtio-mouse-ccw,devno=2.0.2222
> +
> +  This would not show up in a standard Linux guest.

Ok ... and what happens if you use devno=0.0.1234 ? Will that then show
up under fe.0.1234 in the guest??

 Thomas