[v2,1/3] docs/s390x: document the virtual css

Commit Message

Cornelia Huck May 15, 2020, 3:15 p.m. UTC

Add some hints about "devno" rules.

Signed-off-by: Cornelia Huck <[e-mail]>
---
 docs/system/s390x/css.rst    | 86 ++++++++++++++++++++++++++++++++++++
 docs/system/target-s390x.rst |  1 +
 2 files changed, 87 insertions(+)
 create mode 100644 docs/system/s390x/css.rst

Comments

Thomas Huth May 17, 2020, 5:39 p.m. UTC | #1

On 15/05/2020 17.15, Cornelia Huck wrote:
> Add some hints about "devno" rules.
> 
> Signed-off-by: Cornelia Huck <[e-mail]>
> ---
>  docs/system/s390x/css.rst    | 86 ++++++++++++++++++++++++++++++++++++
>  docs/system/target-s390x.rst |  1 +
>  2 files changed, 87 insertions(+)
>  create mode 100644 docs/system/s390x/css.rst
[...]
> +if the guest OS does not enable MCSS-E (which is true of all
supported guest

Maybe s/true of/true for/ ? Not sure, your English is normally better
than mine ;-)

Anyway,
Reviewed-by: Thomas Huth <[e-mail]>

Cornelia Huck May 18, 2020, 6:28 a.m. UTC | #2

On Sun, 17 May 2020 19:39:24 +0200
Thomas Huth <[e-mail]> wrote:

> On 15/05/2020 17.15, Cornelia Huck wrote:
> > Add some hints about "devno" rules.
> > 
> > Signed-off-by: Cornelia Huck <[e-mail]>
> > ---
> >  docs/system/s390x/css.rst    | 86 ++++++++++++++++++++++++++++++++++++
> >  docs/system/target-s390x.rst |  1 +
> >  2 files changed, 87 insertions(+)
> >  create mode 100644 docs/system/s390x/css.rst  
> [...]
> > +if the guest OS does not enable MCSS-E (which is true of all  
> supported guest
> 
> Maybe s/true of/true for/ ? Not sure, your English is normally better
> than mine ;-)

"for" is better :)

> 
> Anyway,
> Reviewed-by: Thomas Huth <[e-mail]>

Thanks!

Patch

diff --git a/docs/system/s390x/css.rst b/docs/system/s390x/css.rst
new file mode 100644
index 000000000000..9e472b7813ec
--- /dev/null
+++ b/docs/system/s390x/css.rst
@@ -0,0 +1,86 @@ 
+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``.
+
+  The auto-assigned-properties in QEMU (as seen via e.g. ``info qtree``)
+  would be ``dev_id = "fe.0.0000"`` and ``subch_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``.
+
+  The properties for the device would be ``dev_id = "fe.0.0042"`` and
+  ``subch_id = "fe.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``.
+
+  The properties for the device would be ``dev_id = "fe.2.1111"`` and
+  ``subch_id = "fe.2.0000"``.
+
+* a virtio-mouse device in a non-standard channel subsystem image::
+
+    -device virtio-mouse-ccw,devno=2.0.2222
+
+  This would not show up in a standard Linux guest.
+
+  The properties for the device would be ``dev_id = "2.0.2222"`` and
+  ``subch_id = "2.0.0000"``.
+
+* a virtio-keyboard device in another non-standard channel subsystem image::
+
+    -device virtio-keyboard-ccw,devno=0.0.1234
+
+  This would not show up in a standard Linux guest, either, as ``0`` is not
+  the standard channel subsystem image id.
+
+  The properties for the device would be ``dev_id = "0.0.1234"`` and
+  ``subch_id = "0.0.0000"``.
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
 ======================