docs/system/s390x/css.rst

   1 The virtual channel subsystem
   2 =============================
   3
   4 QEMU implements a virtual channel subsystem with subchannels, (mostly
   5 functionless) channel paths, and channel devices (virtio-ccw, 3270, and
   6 devices passed via vfio-ccw). It supports multiple subchannel sets (MSS) and
   7 multiple channel subsystems extended (MCSS-E).
   8
   9 All channel devices support the ``devno`` property, which takes a parameter
  10 in the form ``<cssid>.<ssid>.<device number>``.
  11
  12 The default channel subsystem image id (``<cssid>``) is ``0xfe``. Devices in
  13 there will show up in channel subsystem image ``0`` to guests that do not
  14 enable MCSS-E. Note that devices with a different cssid will not be visible
  15 if the guest OS does not enable MCSS-E (which is true for all supported guest
  16 operating systems today).
  17
  18 Supported values for the subchannel set id (``<ssid>``) range from ``0-3``.
  19 Devices with a ssid that is not ``0`` will not be visible if the guest OS
  20 does not enable MSS (any Linux version that supports virtio also enables MSS).
  21 Any device may be put into any subchannel set, there is no restriction by
  22 device type.
  23
  24 The device number can range from ``0-0xffff``.
  25
  26 If the ``devno`` property is not specified for a device, QEMU will choose the
  27 next free device number in subchannel set 0, skipping to the next subchannel
  28 set if no more device numbers are free.
  29
  30 QEMU places a device at the first free subchannel in the specified subchannel
  31 set. If a device is hotunplugged and later replugged, it may appear at a
  32 different subchannel. (This is similar to how z/VM works.)
  33
  34
  35 Examples
  36 --------
  37
  38 * a virtio-net device, cssid/ssid/devno automatically assigned::
  39
  40     -device virtio-net-ccw
  41
  42   In a Linux guest (without default devices and no other devices specified
  43   prior to this one), this will show up as ``0.0.0000`` under subchannel
  44   ``0.0.0000``.
  45
  46   The auto-assigned-properties in QEMU (as seen via e.g. ``info qtree``)
  47   would be ``dev_id = "fe.0.0000"`` and ``subch_id = "fe.0.0000"``.
  48
  49 * a virtio-rng device in subchannel set ``0``::
  50
  51     -device virtio-rng-ccw,devno=fe.0.0042
  52
  53   If added to the same Linux guest as above, it would show up as ``0.0.0042``
  54   under subchannel ``0.0.0001``.
  55
  56   The properties for the device would be ``dev_id = "fe.0.0042"`` and
  57   ``subch_id = "fe.0.0001"``.
  58
  59 * a virtio-gpu device in subchannel set ``2``::
  60
  61     -device virtio-gpu-ccw,devno=fe.2.1111
  62
  63   If added to the same Linux guest as above, it would show up as ``0.2.1111``
  64   under subchannel ``0.2.0000``.
  65
  66   The properties for the device would be ``dev_id = "fe.2.1111"`` and
  67   ``subch_id = "fe.2.0000"``.
  68
  69 * a virtio-mouse device in a non-standard channel subsystem image::
  70
  71     -device virtio-mouse-ccw,devno=2.0.2222
  72
  73   This would not show up in a standard Linux guest.
  74
  75   The properties for the device would be ``dev_id = "2.0.2222"`` and
  76   ``subch_id = "2.0.0000"``.
  77
  78 * a virtio-keyboard device in another non-standard channel subsystem image::
  79
  80     -device virtio-keyboard-ccw,devno=0.0.1234
  81
  82   This would not show up in a standard Linux guest, either, as ``0`` is not
  83   the standard channel subsystem image id.
  84
  85   The properties for the device would be ``dev_id = "0.0.1234"`` and
  86   ``subch_id = "0.0.0000"``.