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