Merge remote-tracking branch 'remotes/cohuck/tags/s390x-20200605' into staging

--------------------

S390 general architecture support

M: Cornelia Huck <cohuck@redhat.com>

M: Thomas Huth <thuth@redhat.com>

S: Supported

F: default-configs/s390x-softmmu.mak

F: gdb-xml/s390*.xml

3270 devices

============

QEMU supports connecting an external 3270 terminal emulator (such as

``x3270``) to make a single 3270 device available to a guest. Note that this

supports basic features only.

To provide a 3270 device to a guest, create a ``x-terminal3270`` linked to

a ``tn3270`` chardev. The guest will see a 3270 channel device. In order

to actually be able to use it, attach the ``x3270`` emulator to the chardev.

Example configuration

---------------------

* Add a ``tn3270`` chardev and a ``x-terminal3270`` to the QEMU command line::

    -chardev socket,id=char_0,host=0.0.0.0,port=2300,nowait,server,tn3270

    -device x-terminal3270,chardev=char_0,devno=fe.0.000a,id=terminal_0

* Start the guest. In the guest, use ``chccwdev -e 0.0.000a`` to enable

  the device.

* On the host, start the ``x3270`` emulator::

    x3270 <host>:2300

* In the guest, locate the 3270 device node under ``/dev/3270/`` (say,

  ``tty1``) and start a getty on it::

    systemctl start serial-getty@3270-tty1.service

This should get you an addtional tty for logging into the guest.

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

Subchannel passthrough via vfio-ccw

===================================

vfio-ccw (based upon the mediated vfio device infrastructure) allows to

make certain I/O subchannels and their devices available to a guest. The

host will not interact with those subchannels/devices any more.

Note that while vfio-ccw should work with most non-QDIO devices, only ECKD

DASDs have really been tested.

Example configuration

---------------------

Step 1: configure the host device

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

As every mdev is identified by a uuid, the first step is to obtain one::

  [root@host ~]# uuidgen

  7e270a25-e163-4922-af60-757fc8ed48c6

Note: it is recommended to use the ``mdevctl`` tool for actually configuring

the host device.

To define the same device as configured below to be started

automatically, use

::

   [root@host ~]# driverctl -b css set-override 0.0.0313 vfio_ccw

   [root@host ~]# mdevctl define -u 7e270a25-e163-4922-af60-757fc8ed48c6 \

                  -p 0.0.0313 -t vfio-ccw_io -a

If using ``mdevctl`` is not possible or wanted, follow the manual procedure

below.

* Locate the subchannel for the device (in this example, ``0.0.2b09``)::

    [root@host ~]# lscss | grep 0.0.2b09 | awk '{print $2}'

    0.0.0313

* Unbind the subchannel (in this example, ``0.0.0313``) from the standard

  I/O subchannel driver and bind it to the vfio-ccw driver::

    [root@host ~]# echo 0.0.0313 > /sys/bus/css/devices/0.0.0313/driver/unbind

    [root@host ~]# echo 0.0.0313 > /sys/bus/css/drivers/vfio_ccw/bind

* Create the mediated device (identified by the uuid)::

    [root@host ~]# echo "7e270a25-e163-4922-af60-757fc8ed48c6" > \

    /sys/bus/css/devices/0.0.0313/mdev_supported_types/vfio_ccw-io/create

Step 2: configure QEMU

~~~~~~~~~~~~~~~~~~~~~~

* Reference the created mediated device and (optionally) pick a device id to

  be presented in the guest (here, ``fe.0.1234``, which will end up visible

  in the guest as ``0.0.1234``::

    -device vfio-ccw,devno=fe.0.1234,sysfsdev=\

    /sys/bus/mdev/devices/7e270a25-e163-4922-af60-757fc8ed48c6

* Start the guest. The device (here, ``0.0.1234``) should now be usable::

    [root@guest ~]# lscss -d 0.0.1234

    Device   Subchan.  DevType CU Type Use  PIM PAM POM  CHPID

    ----------------------------------------------------------------------

    0.0.1234 0.0.0007  3390/0e 3990/e9      f0  f0  ff   1a2a3a0a 00000000

    [root@guest ~]# chccwdev -e 0.0.1234

    Setting device 0.0.1234 online

    Done

    [root@guest ~]# dmesg -t

    (...)

    dasd-eckd 0.0.1234: A channel path to the device has become operational

    dasd-eckd 0.0.1234: New DASD 3390/0E (CU 3990/01) with 10017 cylinders, 15 heads, 224 sectors

    dasd-eckd 0.0.1234: DASD with 4 KB/block, 7212240 KB total size, 48 KB/track, compatible disk layout

    dasda:VOL1/  0X2B09: dasda1

.. toctree::

   s390x/vfio-ap

   s390x/css

   s390x/3270

   s390x/vfio-ccw

Architectural features

======================