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/20220721201058.2a276286@xxxxxxxxxxxxxxxx/ Fixes: e32d3827f3d5b2 ("s390/Docs: new doc describing lock usage by the vfio_ap device driver") Reported-by: Stephen Rothwell <sfr@xxxxxxxxxxxxxxxx> Signed-off-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx> --- 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
