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
--
An old man doll... just what I always wanted! - Clara
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.
Link: https://lore.kernel.org/linux-next/[email protected]/
Fixes: cb269e0aba7c3f ("s390/vfio-ap: update docs to include dynamic config support")
Reported-by: Stephen Rothwell <[email protected]>
Signed-off-by: Bagas Sanjaya <[email protected]>
---
Documentation/s390/vfio-ap.rst | 18 ++++++++++--------
1 file changed, 10 insertions(+), 8 deletions(-)
diff --git a/Documentation/s390/vfio-ap.rst b/Documentation/s390/vfio-ap.rst
index f4b8748ab9a8cd..7aea0afe2ef390 100644
--- a/Documentation/s390/vfio-ap.rst
+++ b/Documentation/s390/vfio-ap.rst
@@ -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
----------------------------------
--
An old man doll... just what I always wanted! - Clara
In 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.
Link: https://lore.kernel.org/linux-next/[email protected]/
Fixes: e32d3827f3d5b2 ("s390/Docs: new doc describing lock usage by the vfio_ap device driver")
Reported-by: Stephen Rothwell <[email protected]>
Signed-off-by: Bagas Sanjaya <[email protected]>
---
Documentation/s390/vfio-ap-locking.rst | 64 +++++++++++++++-----------
1 file changed, 36 insertions(+), 28 deletions(-)
diff --git a/Documentation/s390/vfio-ap-locking.rst b/Documentation/s390/vfio-ap-locking.rst
index c4e1eeec79a0f5..4194b78ace0e94 100644
--- a/Documentation/s390/vfio-ap-locking.rst
+++ b/Documentation/s390/vfio-ap-locking.rst
@@ -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
--
An old man doll... just what I always wanted! - Clara
Convert remaining vfio-ap.rst notes to use note directive, while also
fix maximum sysfs notes being rendered as definition lists instead.
Fixes: cb269e0aba7c3f ("s390/vfio-ap: update docs to include dynamic config support")
Signed-off-by: Bagas Sanjaya <[email protected]>
---
Documentation/s390/vfio-ap.rst | 51 +++++++++++++++++++++-------------
1 file changed, 31 insertions(+), 20 deletions(-)
diff --git a/Documentation/s390/vfio-ap.rst b/Documentation/s390/vfio-ap.rst
index 7aea0afe2ef390..5bf15d117c4ba0 100644
--- a/Documentation/s390/vfio-ap.rst
+++ b/Documentation/s390/vfio-ap.rst
@@ -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:
--
An old man doll... just what I always wanted! - Clara
vfio-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.
Link: https://lore.kernel.org/linux-next/[email protected]/
Fixes: e32d3827f3d5b2 ("s390/Docs: new doc describing lock usage by the vfio_ap device driver")
Reported-by: Stephen Rothwell <[email protected]>
Signed-off-by: Bagas Sanjaya <[email protected]>
---
Documentation/s390/index.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/Documentation/s390/index.rst b/Documentation/s390/index.rst
index b10ca919255738..73c79bf586fd60 100644
--- a/Documentation/s390/index.rst
+++ b/Documentation/s390/index.rst
@@ -12,6 +12,7 @@ s390 Architecture
qeth
s390dbf
vfio-ap
+ vfio-ap-locking
vfio-ccw
zfcpdump
common_io
--
An old man doll... just what I always wanted! - Clara
Two 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.
Link:https://lore.kernel.org/linux-next/[email protected]/
Fixes: cb269e0aba7c3f ("s390/vfio-ap: update docs to include dynamic config support")
Reported-by: Stephen Rothwell <[email protected]>
Signed-off-by: Bagas Sanjaya <[email protected]>
---
Documentation/s390/vfio-ap.rst | 7 ++++---
1 file changed, 4 insertions(+), 3 deletions(-)
diff --git a/Documentation/s390/vfio-ap.rst b/Documentation/s390/vfio-ap.rst
index 5bf15d117c4ba0..c0d76a959ed583 100644
--- a/Documentation/s390/vfio-ap.rst
+++ b/Documentation/s390/vfio-ap.rst
@@ -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
--
An old man doll... just what I always wanted! - Clara
The 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.
Link:https://lore.kernel.org/linux-next/[email protected]/
Fixes: e32d3827f3d5b2 ("s390/Docs: new doc describing lock usage by the vfio_ap device driver")
Reported-by: Stephen Rothwell <[email protected]>
Signed-off-by: Bagas Sanjaya <[email protected]>
---
Documentation/s390/vfio-ap-locking.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/s390/vfio-ap-locking.rst b/Documentation/s390/vfio-ap-locking.rst
index cfbb661ea72e63..ab41b0e5dca40e 100644
--- a/Documentation/s390/vfio-ap-locking.rst
+++ b/Documentation/s390/vfio-ap-locking.rst
@@ -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)
---------------------------------------------------------------
+---------------------------------------------------------------
::
--
An old man doll... just what I always wanted! - Clara
On Fri, Jul 22, 2022 at 03:49:39PM +0700, Bagas Sanjaya wrote:
> Here is documentation fixes for vfio_ap driver, 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!