Documentation: s390: documentation fixes for vfio_ap driver
Subsystems (2)
cover Documentation: s390: documentation fixes for vfio_ap driver
Here is documentation fixes for vfio_ap driver, as recently reported in linux-next.
This series is based on next-20220721.
Bagas Sanjaya (8):
Documentation: s390: Use note directive for changing mask note
Documentation: s390: use note directive for remaining notes
Documentation: s390: sync heading underlines
Documentation: s390: use code blocks for virsh and qemu output
Documentation: s390: use code block for structs
Documentation: s390: escape *kvm->arch.crypto.pqap_hook pointer inside
inline code
Documentation: s390: extend underline for matrix devices lock
Documentation: s390: add vfio-ap-locking documentation to table of
contents index
Documentation/s390/index.rst | 1 + Documentation/s390/vfio-ap-locking.rst | 68 +++++----- Documentation/s390/vfio-ap.rst | 164 ++++++++++++++----------- 3 files changed, 132 insertions(+), 101 deletions(-)
base-commit: a3fd3ca134d9485a0f9a7bdcffd7f8bae27f79d3
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH 1/8 Documentation: s390: Use note directive for changing mask note
The changing mask note uses custom syntax (open asterisks), which triggers emphasis warnings as Sphinx confuses it as boldface:
Documentation/s390/vfio-ap.rst:684: WARNING: Inline strong start-string without end-string. Documentation/s390/vfio-ap.rst:684: WARNING: Inline emphasis start-string without end-string.
Use note directive instead.
--- Documentation/s390/vfio-ap.rst | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-)
Documentation/s390/vfio-ap.rst +10 -8
@@ -681,15 +681,17 @@ These are the steps: default drivers pool: adapter 0-15, domain 1 alternate drivers pool: adapter 16-255, domains 0, 2-255 - Note ***: - Changing a mask such that one or more APQNs will be taken from a vfio_ap - mediated device (see below) will fail with an error (EBUSY). A message - is logged to the kernel ring buffer which can be viewed with the 'dmesg' - command. The output identifies each APQN flagged as 'in use' and identifies - the vfio_ap mediated device to which it is assigned; for example: + .. note:: + + Changing a mask such that one or more APQNs will be taken from a vfio_ap + mediated device (see below) will fail with an error (EBUSY). A message + is logged to the kernel ring buffer which can be viewed with the 'dmesg' + command. The output identifies each APQN flagged as 'in use' and + identifies the vfio_ap mediated device to which it is assigned; for + example:: - Userspace may not re-assign queue 05.0054 already assigned to 62177883-f1bb-47f0-914d-32a22e3a8804 - Userspace may not re-assign queue 04.0054 already assigned to cef03c3c-903d-4ecc-9a83-40694cb8aee4 + Userspace may not re-assign queue 05.0054 already assigned to 62177883-f1bb-47f0-914d-32a22e3a8804 + Userspace may not re-assign queue 04.0054 already assigned to cef03c3c-903d-4ecc-9a83-40694cb8aee4 Securing the APQNs for our example ----------------------------------
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH 2/8 Documentation: s390: use note directive for remaining notes
In reply to Bagas SanjayaConvert remaining vfio-ap.rst notes to use note directive, while also fix maximum sysfs notes being rendered as definition lists instead.
--- Documentation/s390/vfio-ap.rst | 51 +++++++++++++++++++++------------- 1 file changed, 31 insertions(+), 20 deletions(-)
Documentation/s390/vfio-ap.rst +31 -20
@@ -475,24 +475,29 @@ following CPU model features: guest. This facility can be made available to the guest only if it is available on the host (i.e., facility bit 65 is set). -Note: If the user chooses to specify a CPU model different than the 'host' -model to QEMU, the CPU model features and facilities need to be turned on -explicitly; for example:: + .. note:: - /usr/bin/qemu-system-s390x ... -cpu z13,ap=on,apqci=on,apft=on,apqi=on + If the user chooses to specify a CPU model different than the 'host' + model to QEMU, the CPU model features and facilities need to be turned + on explicitly; for example:: -A guest can be precluded from using AP features/facilities by turning them off -explicitly; for example:: + /usr/bin/qemu-system-s390x ... -cpu z13,ap=on,apqci=on,apft=on,apqi=on - /usr/bin/qemu-system-s390x ... -cpu host,ap=off,apqci=off,apft=off,apqi=off + A guest can be precluded from using AP features/facilities by turning + them off explicitly; for example:: -Note: If the APFT facility is turned off (apft=off) for the guest, the guest -will not see any AP devices. The zcrypt device drivers on the guest that -register for type 10 and newer AP devices - i.e., the cex4card and cex4queue -device drivers - need the APFT facility to ascertain the facilities installed on -a given AP device. If the APFT facility is not installed on the guest, then no -adapter or domain devices will get created by the AP bus running on the -guest because only type 10 and newer devices can be configured for guest use. + /usr/bin/qemu-system-s390x ... -cpu host,ap=off,apqci=off,apft=off,apqi=off + + .. note:: + + If the APFT facility is turned off (apft=off) for the guest, the guest + will not see any AP devices. The zcrypt device drivers on the guest that + register for type 10 and newer AP devices - i.e., the cex4card and + cex4queue device drivers - need the APFT facility to ascertain the + facilities installed on a given AP device. If the APFT facility is not + installed on the guest, then no adapter or domain devices will get + created by the AP bus running on the guest because only type 10 and + newer devices can be configured for guest use. Example =======
@@ -802,8 +807,10 @@ Securing the APQNs for our example ----------------unassign_control_domain ----------------unassign_domain - Note *****: The vfio_ap mdevs do not persist across reboots unless the - mdevctl tool is used to create and persist them. + .. note:: + + The vfio_ap mdevs do not persist across reboots unless the + mdevctl tool is used to create and persist them. 4. The administrator now needs to configure the matrixes for the mediated devices $uuid1 (for Guest1), $uuid2 (for Guest2) and $uuid3 (for Guest3).
@@ -849,8 +856,10 @@ Securing the APQNs for our example higher than the maximum is specified, the operation will terminate with an error (ENODEV). - Note: The maximum adapter number can be obtained via the sysfs - /sys/bus/ap/ap_max_adapter_id attribute file. + .. note:: + + The maximum adapter number can be obtained via the sysfs + /sys/bus/ap/ap_max_adapter_id * Each APQN derived from the Cartesian product of the APID of the adapter being assigned and the APQIs of the domains previously assigned:
@@ -875,8 +884,10 @@ Securing the APQNs for our example higher than the maximum is specified, the operation will terminate with an error (ENODEV). - Note: The maximum domain number can be obtained via the sysfs - /sys/bus/ap/ap_max_domain_id attribute file. + .. note:: + + The maximum domain number can be obtained via the sysfs + /sys/bus/ap/ap_max_domain_id * Each APQN derived from the Cartesian product of the APQI of the domain being assigned and the APIDs of the adapters previously assigned:
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH 3/8 Documentation: s390: sync heading underlines
In reply to Bagas SanjayaTwo section headings ("Hot plug/unplug support" and "Overprovisioning ...") have too short underlines compared to the heading length, hence trigger repeated warnings:
Documentation/s390/vfio-ap.rst:943: WARNING: Title underline too short.
Hot plug/unplug support:
================Documentation/s390/vfio-ap.rst:943: WARNING: Title underline too short.
Hot plug/unplug support:
================Documentation/s390/vfio-ap.rst:965: WARNING: Title underline too short.
Over-provisioning of AP queues for a KVM guest:
==============================================Documentation/s390/vfio-ap.rst:965: WARNING: Title underline too short.
Over-provisioning of AP queues for a KVM guest:
==============================================
Adjust the underlines length to match the text. While at it, strip trailing colon on headings since these are redundant.
--- Documentation/s390/vfio-ap.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)
Documentation/s390/vfio-ap.rst +4 -3
@@ -952,8 +952,9 @@ remove it if no guest will use it during the remaining lifetime of the linux host. If the vfio_ap mdev is removed, one may want to also reconfigure the pool of adapters and queues reserved for use by the default drivers. -Hot plug/unplug support: -================ +Hot plug/unplug support +======================= + An adapter, domain or control domain may be hot plugged into a running KVM guest by assigning it to the vfio_ap mediated device being used by the guest if the following conditions are met:
@@ -974,7 +975,7 @@ An adapter, domain or control domain may be hot unplugged from a running KVM guest by unassigning it from the vfio_ap mediated device being used by the guest. -Over-provisioning of AP queues for a KVM guest: +Over-provisioning of AP queues for a KVM guest ============================================== Over-provisioning is defined herein as the assignment of adapters or domains to a vfio_ap mediated device that do not reference AP devices in the host's AP
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH 4/8 Documentation: s390: use code blocks for virsh and qemu output
In reply to Bagas Sanjayavirsh and qemu output blocks are formatted with definition lists, however Sphinx isn't happy with the formatting:
Documentation/s390/vfio-ap.rst:998: WARNING: Definition list ends without a blank line; unexpected unindent. Documentation/s390/vfio-ap.rst:999: WARNING: Definition list ends without a blank line; unexpected unindent. Documentation/s390/vfio-ap.rst:1038: WARNING: Definition list ends without a blank line; unexpected unindent. Documentation/s390/vfio-ap.rst:1039: WARNING: Definition list ends without a blank line; unexpected unindent.
Use code blocks instead, which are more appropriate. While at it, also describe virsh commands where --hmp flag is given.
--- Documentation/s390/vfio-ap.rst | 88 ++++++++++++++++++---------------- 1 file changed, 48 insertions(+), 40 deletions(-)
Documentation/s390/vfio-ap.rst +48 -40
@@ -995,70 +995,78 @@ the mdev is in use by a KVM guest. If the guest is being emulated by QEMU, its mdev can be hot unplugged from the guest in one of two ways: 1. If the KVM guest was started with libvirt, you can hot unplug the mdev via - the following commands: + the following commands:: virsh detach-device <guestname> <path-to-device-xml> - For example, to hot unplug mdev 62177883-f1bb-47f0-914d-32a22e3a8804 from - the guest named 'my-guest': + For example, to hot unplug mdev 62177883-f1bb-47f0-914d-32a22e3a8804 from + the guest named 'my-guest':: - virsh detach-device my-guest ~/config/my-guest-hostdev.xml + virsh detach-device my-guest ~/config/my-guest-hostdev.xml - The contents of my-guest-hostdev.xml: + The contents of my-guest-hostdev.xml: - <hostdev mode='subsystem' type='mdev' managed='no' model='vfio-ap'> - <source> - <address uuid='62177883-f1bb-47f0-914d-32a22e3a8804'/> - </source> - </hostdev> + .. code-block:: xml + <hostdev mode='subsystem' type='mdev' managed='no' model='vfio-ap'> + <source> + <address uuid='62177883-f1bb-47f0-914d-32a22e3a8804'/> + </source> + </hostdev> + + + To hot unplug the vfio_ap mediated device identified on the qemu command + line, use:: virsh qemu-monitor-command <guest-name> --hmp "device-del <device-id>" - For example, to hot unplug the vfio_ap mediated device identified on the - qemu command line with 'id=hostdev0' from the guest named 'my-guest': + For example, to hot unplug the vfio_ap mediated device identified on the + qemu command line with 'id=hostdev0' from the guest named 'my-guest':: - virsh qemu-monitor-command my-guest --hmp "device_del hostdev0" + virsh qemu-monitor-command my-guest --hmp "device_del hostdev0" 2. A vfio_ap mediated device can be hot unplugged by attaching the qemu monitor - to the guest and using the following qemu monitor command: + to the guest and using the following qemu monitor command:: (QEMU) device-del id=<device-id> - For example, to hot unplug the vfio_ap mediated device that was specified - on the qemu command line with 'id=hostdev0' when the guest was started: + For example, to hot unplug the vfio_ap mediated device that was specified + on the qemu command line with 'id=hostdev0' when the guest was started:: - (QEMU) device-del id=hostdev0 + (QEMU) device-del id=hostdev0 After live migration of the KVM guest completes, an AP configuration can be restored to the KVM guest by hot plugging a vfio_ap mediated device on the target system into the guest in one of two ways: 1. If the KVM guest was started with libvirt, you can hot plug a matrix mediated - device into the guest via the following virsh commands: + device into the guest via the following virsh commands:: - virsh attach-device <guestname> <path-to-device-xml> + virsh attach-device <guestname> <path-to-device-xml> - For example, to hot plug mdev 62177883-f1bb-47f0-914d-32a22e3a8804 into - the guest named 'my-guest': + For example, to hot plug mdev 62177883-f1bb-47f0-914d-32a22e3a8804 into + the guest named 'my-guest':: - virsh attach-device my-guest ~/config/my-guest-hostdev.xml + virsh attach-device my-guest ~/config/my-guest-hostdev.xml - The contents of my-guest-hostdev.xml: + The contents of my-guest-hostdev.xml: - <hostdev mode='subsystem' type='mdev' managed='no' model='vfio-ap'> - <source> - <address uuid='62177883-f1bb-47f0-914d-32a22e3a8804'/> - </source> - </hostdev> + .. code-block:: xml + <hostdev mode='subsystem' type='mdev' managed='no' model='vfio-ap'> + <source> + <address uuid='62177883-f1bb-47f0-914d-32a22e3a8804'/> + </source> + </hostdev> - virsh qemu-monitor-command <guest-name> --hmp \ - "device_add vfio-ap,sysfsdev=<path-to-mdev>,id=<device-id>" + To hot plug vfio_ap mediated device, use:: - For example, to hot plug the vfio_ap mediated device - 62177883-f1bb-47f0-914d-32a22e3a8804 into the guest named 'my-guest' with - device-id hostdev0: + virsh qemu-monitor-command <guest-name> --hmp \ + "device_add vfio-ap,sysfsdev=<path-to-mdev>,id=<device-id>" + + For example, to hot plug the vfio_ap mediated device + ``62177883-f1bb-47f0-914d-32a22e3a8804`` into the guest named 'my-guest' + with device-id hostdev0:: virsh qemu-monitor-command my-guest --hmp \ "device_add vfio-ap,\
@@ -1066,14 +1074,14 @@ system into the guest in one of two ways: id=hostdev0" 2. A vfio_ap mediated device can be hot plugged by attaching the qemu monitor - to the guest and using the following qemu monitor command: + to the guest and using the following qemu monitor command:: (qemu) device_add "vfio-ap,sysfsdev=<path-to-mdev>,id=<device-id>" - For example, to plug the vfio_ap mediated device - 62177883-f1bb-47f0-914d-32a22e3a8804 into the guest with the device-id - hostdev0: + For example, to plug the vfio_ap mediated device + ``62177883-f1bb-47f0-914d-32a22e3a8804`` into the guest with the device-id + hostdev0:: - (QEMU) device-add "vfio-ap,\ - sysfsdev=/sys/devices/vfio_ap/matrix/62177883-f1bb-47f0-914d-32a22e3a8804,\ - id=hostdev0" + (QEMU) device-add "vfio-ap,\ + sysfsdev=/sys/devices/vfio_ap/matrix/62177883-f1bb-47f0-914d-32a22e3a8804,\ + id=hostdev0"
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH 5/8 Documentation: s390: use code block for structs
In reply to Bagas SanjayaIn vfio-ap-locking documentation, struct code samples aren't inside code blocks, hence trigger many inline emphasis and definition list warnings.
Use code blocks for them.
--- Documentation/s390/vfio-ap-locking.rst | 64 +++++++++++++++----------- 1 file changed, 36 insertions(+), 28 deletions(-)
Documentation/s390/vfio-ap-locking.rst +36 -28
@@ -5,21 +5,23 @@ VFIO AP Locks Overview ====================== This document describes the locks that are pertinent to the secure operation of the vfio_ap device driver. Throughout this document, the following variables -will be used to denote instances of the structures herein described: +will be used to denote instances of the structures herein described:: -struct ap_matrix_dev *matrix_dev; -struct ap_matrix_mdev *matrix_mdev; -struct kvm *kvm; + struct ap_matrix_dev *matrix_dev; + struct ap_matrix_mdev *matrix_mdev; + struct kvm *kvm; The Matrix Devices Lock (drivers/s390/crypto/vfio_ap_private.h) -------------------------------------------------------------- -struct ap_matrix_dev { - ... - struct list_head mdev_list; - struct mutex mdevs_lock; - ... -} +:: + + struct ap_matrix_dev { + ... + struct list_head mdev_list; + struct mutex mdevs_lock; + ... + } The Matrix Devices Lock (matrix_dev->mdevs_lock) is implemented as a global mutex contained within the single object of struct ap_matrix_dev. This lock
@@ -31,11 +33,13 @@ representing one of the vfio_ap device driver's mediated devices. The KVM Lock (include/linux/kvm_host.h) --------------------------------------- -struct kvm { - ... - struct mutex lock; - ... -} +:: + + struct kvm { + ... + struct mutex lock; + ... + } The KVM Lock (kvm->lock) controls access to the state data for a KVM guest. This lock must be held by the vfio_ap device driver while one or more AP adapters,
@@ -48,12 +52,14 @@ been attached to the KVM guest. The Guests Lock (drivers/s390/crypto/vfio_ap_private.h) ----------------------------------------------------------- -struct ap_matrix_dev { - ... - struct list_head mdev_list; - struct mutex guests_lock; - ... -} +:: + + struct ap_matrix_dev { + ... + struct list_head mdev_list; + struct mutex guests_lock; + ... + } The Guests Lock (matrix_dev->guests_lock) controls access to the matrix_mdev instances (matrix_dev->mdev_list) that represent mediated devices
@@ -89,14 +95,16 @@ resources, so only the matrix_dev->mdevs_lock needs to be held. The PQAP Hook Lock (arch/s390/include/asm/kvm_host.h) ----------------------------------------------------- -typedef int (*crypto_hook)(struct kvm_vcpu *vcpu); +:: -struct kvm_s390_crypto { - ... - struct rw_semaphore pqap_hook_rwsem; - crypto_hook *pqap_hook; - ... -}; + typedef int (*crypto_hook)(struct kvm_vcpu *vcpu); + + struct kvm_s390_crypto { + ... + struct rw_semaphore pqap_hook_rwsem; + crypto_hook *pqap_hook; + ... + }; The PQAP Hook Lock is a r/w semaphore that controls access to the function pointer of the handler (*kvm->arch.crypto.pqap_hook) to invoke when the
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH 6/8 Documentation: s390: escape *kvm->arch.crypto.pqap_hook pointer inside inline code
In reply to Bagas SanjayaThe *kvm->arch.crypto.pqap_hook pointer triggers inline emphasis warning, due to unescaped asterisk. Escape it into inline code.
--- Documentation/s390/vfio-ap-locking.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/s390/vfio-ap-locking.rst +1 -1
@@ -107,7 +107,7 @@ The PQAP Hook Lock (arch/s390/include/asm/kvm_host.h) }; The PQAP Hook Lock is a r/w semaphore that controls access to the function -pointer of the handler (*kvm->arch.crypto.pqap_hook) to invoke when the +pointer of the handler (``*kvm->arch.crypto.pqap_hook``) to invoke when the PQAP(AQIC) instruction sub-function is intercepted by the host. The lock must be held in write mode when pqap_hook value is set, and in read mode when the pqap_hook function is called.
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH 7/8 Documentation: s390: extend underline for matrix devices lock
In reply to Bagas SanjayaThe underline heading for "The Matrix Devices Lock" section is off-short by a dash, hence:
Documentation/s390/vfio-ap-locking.rst:15: WARNING: Title underline too short.
The Matrix Devices Lock (drivers/s390/crypto/vfio_ap_private.h)
--------------------------------------------------------------
Extend the underline to match heading text length.
--- Documentation/s390/vfio-ap-locking.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/s390/vfio-ap-locking.rst +1 -1
@@ -12,7 +12,7 @@ will be used to denote instances of the structures herein described:: struct kvm *kvm; The Matrix Devices Lock (drivers/s390/crypto/vfio_ap_private.h) --------------------------------------------------------------- +--------------------------------------------------------------- ::
Signature · 1 line
An old man doll... just what I always wanted! - Clara
PATCH 8/8 Documentation: s390: add vfio-ap-locking documentation to table of contents index
In reply to Bagas Sanjayavfio-ap-locking.rst documentation is missing from s390 index, so:
Documentation/s390/vfio-ap-locking.rst: WARNING: document isn't included in any toctree
Add missing documentation to the index.
--- Documentation/s390/index.rst | 1 + 1 file changed, 1 insertion(+)
Documentation/s390/index.rst +1 -0
@@ -12,6 +12,7 @@ s390 Architecture qeth s390dbf vfio-ap + vfio-ap-locking vfio-ccw zfcpdump common_io
Signature · 1 line
An old man doll... just what I always wanted! - Clara
Alexander Gordeev
maintainerQuoted 4 lines · Bagas Sanjaya
Here is documentation fixes for
vfio_apdriver, as recently reported in linux-next.This series is based on next-20220721.
Hi Bagas,
The warnings have already fixed.
Please, send your style changes if you find it approprieate.
FWIW, patch #1 causes a whitespace trailing error.
Thanks!