arch/s390/vfio-ap.rst

122 Let's now take a look at how AP instructions executed on a guest are interpreted
128 control domains assigned to the KVM guest:
131   to the KVM guest. Each bit in the mask, from left to right, corresponds to
133   use by the KVM guest.
136   assigned to the KVM guest. Each bit in the mask, from left to right,
138   corresponding queue is valid for use by the KVM guest.
141   assigned to the KVM guest. The ADM bit mask controls which domains can be
143   guest. Each bit in the mask, from left to right, corresponds to a domain from
153 adapters 1 and 2 and usage domains 5 and 6 are assigned to a guest, the APQNs
154 (1,5), (1,6), (2,5) and (2,6) will be valid for the guest.
158 at most one guest or to the linux host::
202    domains, and control domains comprising the matrix for a KVM guest.
205    by a KVM guest's SIE state description to grant the guest access to a matrix
249 The process for reserving an AP queue for use by a KVM guest is:
254    all vfio_ap mediated devices used to configure an AP matrix for a guest.
271    used by a guest
273     to be exclusively used by a guest.
371       fields respectively of the KVM guest's CRYCB. This may differ from the
419     * Store the reference to the KVM structure for the guest using the mdev
423       domains available to a guest. A guest may not be provided access to APQNs
429     This will be allowed only if a running guest is not using the mdev.
438     KVM structure used to configure the KVM guest is provided via this callback.
439     The KVM structure, is used to configure the guest's access to the AP matrix
444     matrix mdev device and deconfigures the guest's AP matrix.
450 Configure the guest's AP resources
452 Configuring the AP resources for a KVM guest will be performed when the
454 function is called when userspace connects to KVM. The guest's AP resources are
464 The linux device model precludes passing a device through to a KVM guest that
467 driver will not be assigned to a KVM guest's matrix. The AP architecture,
468 however, does not provide a means to filter individual APQNs from the guest's
472 configuration to a guest:
481   plugged into the guest (i.e., the bit corresponding to its APID will not be
482   set in the APM of the guest's APCB).
489 facility. These features/facilities are made available to a KVM guest via the
492 1. ap: Indicates whether the AP instructions are installed on the guest. This
496 2. apft: Indicates the APFT facility is available on the guest. This facility
497    can be made available to the guest only if it is available on the host (i.e.,
500 3. apqci: Indicates the AP QCI facility is available on the guest. This facility
501    can be made available to the guest only if it is available on the host (i.e.,
505    guest. This facility can be made available to the guest only if it is
514 A guest can be precluded from using AP features/facilities by turning them off
519 Note: If the APFT facility is turned off (apft=off) for the guest, the guest
520 will not see any AP devices. The zcrypt device drivers on the guest that
523 a given AP device. If the APFT facility is not installed on the guest, then no
525 guest because only type 10 and newer devices can be configured for guest use.
945 When the guest is shut down, the vfio_ap mediated devices may be removed.
963 that the remove will fail if a guest using the vfio_ap mdev is still running.
966 remove it if no guest will use it during the remaining lifetime of the linux
973 guest by assigning it to the vfio_ap mediated device being used by the guest if
989 guest by unassigning it from the vfio_ap mediated device being used by the
990 guest.
992 Over-provisioning of AP queues for a KVM guest:
997 available, it will be automatically hot-plugged into the KVM guest using
1024 |              | guest when the mdev is attached to it.                        |
1027 |              | domains for a guest to which the mdev is attached.            |
1034 Live guest migration is not supported for guests using AP devices without
1035 intervention by a system administrator. Before a KVM guest can be migrated,
1038 the mdev is in use by a KVM guest. If the guest is being emulated by QEMU,
1039 its mdev can be hot unplugged from the guest in one of two ways:
1041 1. If the KVM guest was started with libvirt, you can hot unplug the mdev via
1047       the guest named 'my-guest':
1049          virsh detach-device my-guest ~/config/my-guest-hostdev.xml
1051             The contents of my-guest-hostdev.xml:
1062       virsh qemu-monitor-command <guest-name> --hmp "device-del <device-id>"
1065       qemu command line with 'id=hostdev0' from the guest named 'my-guest':
1069          virsh qemu-monitor-command my-guest --hmp "device_del hostdev0"
1072    to the guest and using the following qemu monitor command:
1077       on the qemu command line with 'id=hostdev0' when the guest was started:
1081 After live migration of the KVM guest completes, an AP configuration can be
1082 restored to the KVM guest by hot plugging a vfio_ap mediated device on the target
1083 system into the guest in one of two ways:
1085 1. If the KVM guest was started with libvirt, you can hot plug a matrix mediated
1086    device into the guest via the following virsh commands:
1091       the guest named 'my-guest':
1093          virsh attach-device my-guest ~/config/my-guest-hostdev.xml
1095             The contents of my-guest-hostdev.xml:
1106    virsh qemu-monitor-command <guest-name> --hmp \
1110       62177883-f1bb-47f0-914d-32a22e3a8804 into the guest named 'my-guest' with
1113       virsh qemu-monitor-command my-guest --hmp \
1119    to the guest and using the following qemu monitor command:
1124       62177883-f1bb-47f0-914d-32a22e3a8804 into the guest with the device-id