system/s390x/vfio-ap.rst

75 A KVM guest is started by executing the Start Interpretive Execution (SIE)
77 state information for a KVM guest and is supplied as input to the SIE
80 the adapters, usage domains and control domains assigned to the KVM guest:
83   to the KVM guest. Each bit in the mask, from left to right, corresponds to
85   use by the KVM guest.
88   assigned to the KVM guest. Each bit in the mask, from left to right,
90   corresponding queue is valid for use by the KVM guest.
93   assigned to the KVM guest. The ADM bit mask controls which domains can be
95   guest. Each bit in the mask, from left to right, corresponds to a domain from
106 assigned to a guest, the APQNs (1,5), (1,6), (2,5) and (2,6) will be valid for
107 the guest.
111 at most one guest or the linux host.
162 A linux system is a guest of the LPAR in which it is running and has access to
317 Configuring an AP matrix for a linux guest
320 The sysfs interfaces for configuring an AP matrix for a guest are built on the
321 VFIO mediated device framework. To configure an AP matrix for a guest, a
360 KVM guest::
471 Notes: No changes to the AP matrix will be allowed while a guest using
478 To provide a mediated matrix device for use by a guest, the following option
491 When the linux guest is started, the guest will open the mediated
494 the guest's CRYCB with the adapter, usage domain and control domains assigned
496 linux guest will then:
501    that are valid for use by the guest; meaning, AP commands can be sent by the
502    guest to any of these queues for processing.
505    identified in the ADM field of the guest's CRYCB. The AP command must be sent
510 Three CPU model features are available for controlling guest access to AP
516    guest. This feature will be exposed for use only if the AP facilities
525         is the CPU model defined for the guest (defaults to the model of
531         is ``ap=on``. AP facilities must be installed on the guest if a
533         for the guest, or the guest will fail to start.
537    The QCI facility is used by the AP bus running on the guest to query the
548         is the CPU model defined for the guest
556         (``ap=off``), an error message will be logged, but the guest
563         running on the guest.
567    The APFT facility is used by the AP bus running on the guest to test the
578         is the CPU model defined for the guest (defaults to the model of
588         (``ap=off``), an error message will be logged, but the guest
594         running on the guest will not detect CEX4 and newer devices
596         for guest usage, no AP devices can be made accessible to a
597         guest started without APFT installed.
599 Hot plug a vfio-ap device into a running guest
612 device to which AP resources to be used by the guest have been assigned.
618 guest.
624 * The CPU model features for controlling guest access to AP facilities are not
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
640 On a Linux guest, the AP devices will be removed from the ``/sys/bus/ap/devices``
641 directory on the guest when the AP bus subsequently performs its periodic scan,
643 the guest.
875 When the guest is shut down, the mediated matrix devices may be removed.
892 that the remove will fail if a guest using the mdev is still running.
895 remove it if no guest will use it during the remaining lifetime of the linux
904   device in use by a guest. It is incumbent upon the administrator to
905   ensure there is no mediated device in use by a guest to which the APQN is
907   device, such as a private key configured specifically for the guest.
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.
913 * Live guest migration is not supported for guests using AP devices. If a guest
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
916   running guest`_ section above.)