system/s390x/vfio-ap.rst

103 APQN is defined by the matrix calculated from the APM and AQM; it is the
163 the AP resources configured for the LPAR. The LPAR's AP matrix is
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
322 mediated matrix device must first be created for the ``/sys/devices/vfio_ap/matrix``
325 creating mediated matrix devices is created::
329   ......[matrix]
335 A mediated AP matrix device is created by writing a UUID to the attribute file
346 When a mediated AP matrix device is created, a sysfs directory named after
351   ......[matrix]
359 matrix device's sysfs directory to configure an AP matrix for the
364   ......[matrix]
373   ..................... matrix
379    To assign an AP adapter to the mediated matrix device, its APID is written
383    4, 5 and 16 to a mediated matrix device in decimal, hexadecimal and octal
405      previously assigned domains can be assigned to another mediated matrix
406      device. If an APQN is assigned to another mediated matrix device, the
418    4, 8, and 71 to a mediated matrix device in decimal, hexadecimal and octal
441      matrix device. If an APQN is assigned to another mediated matrix device,
454    example, to assign  control domains 4, 8, and 71 to  a mediated matrix device
471 Notes: No changes to the AP matrix will be allowed while a guest using
472 the mediated matrix device is running. Attempts to assign an adapter,
478 To provide a mediated matrix device for use by a guest, the following option
483 The sysfsdev parameter specifies the path to the mediated matrix device.
486   /sys/devices/vfio_ap/matrix/$uuid
489   /sys/devices/vfio_ap/matrix/mdev_supported_types/vfio_ap-passthrough/devices/$uuid
492 matrix device's file descriptor to get information about the mediated matrix
495 via the mediated matrix device's sysfs attribute files. Programs running on the
766      /sys/devices/vfio_ap/matrix/
768      ...... [vfio_ap-passthrough] (passthrough mediated matrix device type)
790      /sys/devices/vfio_ap/matrix/
798      ............... matrix
807      ............... matrix
816      ............... matrix
824    This is how the matrix is configured for Guest1::
838    To display the matrix configuration for Guest1::
840          cat matrix
851    This is how the matrix is configured for Guest2::
857    This is how the matrix is configured for Guest3::
865 ….. -cpu host,ap=on,apqci=on,apft=on -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid1 ...
869 ….. -cpu host,ap=on,apqci=on,apft=on -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid2 ...
873 ….. -cpu host,ap=on,apqci=on,apft=on -device vfio-ap,sysfsdev=/sys/devices/vfio_ap/matrix/$uuid3 ...
875 When the guest is shut down, the mediated matrix devices may be removed.
877 Using our example again, to remove the mediated matrix device $uuid1::
879    /sys/devices/vfio_ap/matrix/
889 This will remove all of the mdev matrix device's sysfs structures including
890 the mdev device itself. To recreate and reconfigure the mdev matrix device,
894 It is not necessary to remove an mdev matrix device, but one may want to
896 host. If the mdev matrix device is removed, one may want to also reconfigure
910   mediated matrix device - see `Configuring an AP matrix for a linux guest`_