| Message ID | 20200505135025.14614-2-cohuck@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | s390x: improve documentation | expand |
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)
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 ======================
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