Add some hints about "devno" rules.

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``.
+
+* 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``.
+
+* 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``.
+
+* 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.
diff --git a/docs/system/target-s390x.rst b/docs/system/target-s390x.rst
index 7d76ae97b401..37ca032d98ef 100644
--- a/docs/system/target-s390x.rst
+++ b/docs/system/target-s390x.rst
@@ -23,6 +23,7 @@ or vfio-ap is also available.
 
 .. toctree::
    s390x/vfio-ap
+   s390x/css
 
 Architectural features
 ======================
-- 
2.21.3

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

On Fri, 15 May 2020 09:04:13 +0200
Thomas Huth <thuth@redhat.com> wrote:

> On 05/05/2020 15.50, Cornelia Huck wrote:

> > +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".

Yes, that's a good idea.

> 
> > +* 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" ?

I wanted to provide the subchannel number in my examples as well. As
QEMU always picks the first free one (and you cannot specify it
manually), I wanted to make the examples build upon each other.

> 
> > +* 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.

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??

That won't show up in the guest, either -- do you think I should add an
example for that as well?

On 15/05/2020 10.51, Cornelia Huck wrote:
> On Fri, 15 May 2020 09:04:13 +0200
> Thomas Huth <thuth@redhat.com> wrote:
> 
>> On 05/05/2020 15.50, Cornelia Huck wrote:
[...]
>>> +
>>> +  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??
> 
> That won't show up in the guest, either -- do you think I should add an
> example for that as well?

It could help to clarify the question that came to my mind here. And
what would happen if the guest supported MCSS-E ? Would it then show up
as fe.0.1234 indeed?

 Thomas

On Fri, 15 May 2020 10:57:26 +0200
Thomas Huth <thuth@redhat.com> wrote:

> On 15/05/2020 10.51, Cornelia Huck wrote:
> > On Fri, 15 May 2020 09:04:13 +0200
> > Thomas Huth <thuth@redhat.com> wrote:
> >   
> >> On 05/05/2020 15.50, Cornelia Huck wrote:  
> [...]
> >>> +
> >>> +  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??  
> > 
> > That won't show up in the guest, either -- do you think I should add an
> > example for that as well?  
> 
> It could help to clarify the question that came to my mind here. And
> what would happen if the guest supported MCSS-E ? Would it then show up
> as fe.0.1234 indeed?

No, it would show up as 0.0.1234, and the devices in the default css
(0xfe) would show up as fe.x.yyyy.

But I have not seen a Linux kernel with support for MCSS-E in the wild
:) (nor any other OS, for that matter)