system/s390x/vfio-ap.rst

7 ------------
19 -------------------------
47       example, to set a secure private key for the domain.
51   An AP queue is the means by which an AP command-request message is sent to an
53   comprised of an AP adapter ID (APID) and an AP queue index (APQI). The
57   which the AP command-request message is to be sent for processing.
63   * NQAP: to enqueue an AP command-request message to a queue
64   * DQAP: to dequeue an AP command-reply message from a queue
73 ----------------------------------------------
84   an APID from 0-255. If a bit is set, the corresponding adapter is valid for
89   corresponds to  an AP queue index (APQI) from 0-255. If a bit is set, the
94   changed by an AP command-request message sent to a usage domain from the
96   0-255. If a bit is set, the corresponding domain can be modified by an AP
97   command-request message sent to a usage domain.
100 an APQN to identify the AP adapter and AP queue to which an AP command-request
102 command-reply message is to be received (DQAP instruction). The validity of an
109 The APQNs can provide secure key functionality - i.e., a private key is stored
110 on the adapter card for each of its domains - so each APQN must be assigned to
116 +----------+--------+--------+
120 +----------+--------+--------+
122 +----------+--------+--------+
132 +----------+--------+--------+
136 +----------+--------+--------+
138 +----------+--------+--------+
148 +----------+--------+--------+
152 +----------+--------+--------+
154 +----------+--------+--------+
160 -------------------------------------
227 The ``apmask`` is a 256-bit mask that identifies a set of AP adapter IDs
230 0-255. If a bit is set, the APID is marked as usable only by the default AP
234 The ``aqmask`` is a 256-bit mask that identifies a set of AP queue indexes
237 0-255. If a bit is set, the APQI is marked as usable only by the default AP
247       1, 2, 3, 4, 5, and 7-255 belong to the default drivers' pool, and 0 and 6
262     * An absolute hex string starting with 0x - like "0x12345678" - sets
278       number string must be prepended with a (``+``) or minus (``-``) to indicate
279       the corresponding bit is to be switched on (``+``) or off (``-``). Some
283            "-13"   switches bit 13 off
285            "-0xff" switches bit 255 off
289               +0,-6,+0x47,-0xf0
314             default drivers pool:    adapter 0-15, domain 1
315             alternate drivers pool:  adapter 16-255, domains 0, 2-255
331   ............ [vfio_ap-passthrough]
353   ............ [vfio_ap-passthrough]
366   ............ [vfio_ap-passthrough]
397    * All APQNs that can be derived from the adapter ID being assigned and the
404    * No APQN that can be derived from the adapter ID and the IDs of the
432    * All APQNs that can be derived from the domain ID being assigned and the IDs
439    * No APQN that can be derived from the domain ID being assigned and the IDs
481    -device vfio_ap,sysfsdev=$path-to-mdev
489   /sys/devices/vfio_ap/matrix/mdev_supported_types/vfio_ap-passthrough/devices/$uuid
517    are installed on the host system. The feature is s390-specific and is
518    represented as a parameter of the -cpu option on the QEMU command line::
520       qemu-system-s390x -cpu $model,ap=on|off
532         vfio-ap device (``-device vfio-ap,sysfsdev=$path``) is configured
540    s390-specific and is represented as a parameter of the -cpu option on the
543       qemu-system-s390x -cpu $model,apqci=on|off
570    s390-specific and is represented as a parameter of the -cpu option on the
573       qemu-system-s390x -cpu $model,apft=on|off
599 Hot plug a vfio-ap device into a running guest
602 Only one vfio-ap device can be attached to the virtual machine's ap-bus, so a
603 vfio-ap device can be hot plugged if and only if no vfio-ap device is attached
607 To hot plug a vfio-ap device, use the QEMU ``device_add`` command::
609     (qemu) device_add vfio-ap,sysfsdev="$path-to-mdev",id="$id"
611 Where the ``$path-to-mdev`` value specifies the absolute path to a mediated
613 ``$id`` is the name value for the optional id parameter.
622 * A vfio-ap device has already been attached to the virtual machine's ap-bus.
627 Hot unplug a vfio-ap device from a running guest
630 A vfio-ap device can be unplugged from a running KVM guest if a vfio-ap device
631 has been attached to the virtual machine's ap-bus via the QEMU command line
634 To hot unplug a vfio-ap device, use the QEMU ``device_del`` command::
636     (qemu) device_del "$id"
638 Where ``$id`` is the same id that was specified at device creation.
645 The command will fail if the ``$path-to-mdev`` specified on the ``device_del`` command
646 does not match the value specified when the vfio-ap device was attached to
647 the virtual machine's ap-bus.
650 -----------------------------------------------------
660   ------------------------------
661   05          CEX5C CCA-Coproc
662   05.0004     CEX5C CCA-Coproc
663   05.00ab     CEX5C CCA-Coproc
666   06.00ab     CEX5C CCA-Coproc
671   ------------------------------
679   ------------------------------
689    * iommu
710      -> Device Drivers
711         -> IOMMU Hardware Support
712            select S390 AP IOMMU Support
713         -> VFIO Non-Privileged userspace driver framework
714            -> Mediated device driver framework
715               -> VFIO driver for Mediated devices
716      -> I/O subsystem
717         -> VFIO support for AP devices
719 2. Secure the AP queues to be used by the three guests so that the host can not
720    access them. To secure the AP queues 05.0004, 05.0047, 05.00ab, 05.00ff,
725       echo -5,-6 > /sys/bus/ap/apmask
727       echo -4,-0x47,-0xab,-0xff > /sys/bus/ap/aqmask
752    The administrator, therefore, must take care to secure only AP queues that
768      ...... [vfio_ap-passthrough] (passthrough mediated matrix device type)
792      ...... [vfio_ap-passthrough]
865 …/usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on -device vfio-ap,sysfsdev=/sys/devi…
869 …/usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on -device vfio-ap,sysfsdev=/sys/devi…
873 …/usr/bin/qemu-system-s390x ... -cpu host,ap=on,apqci=on,apft=on -device vfio-ap,sysfsdev=/sys/devi…
881    ...... [vfio_ap-passthrough]
900 -----------
910   mediated matrix device - see `Configuring an AP matrix for a linux guest`_
911   section above - while a running guest is using it is currently not supported.
914   is using AP devices, the vfio-ap device configured for the guest must be
915   unplugged before migrating the guest (see `Hot unplug a vfio-ap device from a