116 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3======================4VFIO AP Locks Overview5======================6This document describes the locks that are pertinent to the secure operation7of the vfio_ap device driver. Throughout this document, the following variables8will be used to denote instances of the structures herein described:9 10.. code-block:: c11 12 struct ap_matrix_dev *matrix_dev;13 struct ap_matrix_mdev *matrix_mdev;14 struct kvm *kvm;15 16The Matrix Devices Lock (drivers/s390/crypto/vfio_ap_private.h)17---------------------------------------------------------------18 19.. code-block:: c20 21 struct ap_matrix_dev {22 ...23 struct list_head mdev_list;24 struct mutex mdevs_lock;25 ...26 }27 28The Matrix Devices Lock (matrix_dev->mdevs_lock) is implemented as a global29mutex contained within the single object of struct ap_matrix_dev. This lock30controls access to all fields contained within each matrix_mdev31(matrix_dev->mdev_list). This lock must be held while reading from, writing to32or using the data from a field contained within a matrix_mdev instance33representing one of the vfio_ap device driver's mediated devices.34 35The KVM Lock (include/linux/kvm_host.h)36---------------------------------------37 38.. code-block:: c39 40 struct kvm {41 ...42 struct mutex lock;43 ...44 }45 46The KVM Lock (kvm->lock) controls access to the state data for a KVM guest. This47lock must be held by the vfio_ap device driver while one or more AP adapters,48domains or control domains are being plugged into or unplugged from the guest.49 50The KVM pointer is stored in the in the matrix_mdev instance51(matrix_mdev->kvm = kvm) containing the state of the mediated device that has52been attached to the KVM guest.53 54The Guests Lock (drivers/s390/crypto/vfio_ap_private.h)55-----------------------------------------------------------56 57.. code-block:: c58 59 struct ap_matrix_dev {60 ...61 struct list_head mdev_list;62 struct mutex guests_lock;63 ...64 }65 66The Guests Lock (matrix_dev->guests_lock) controls access to the67matrix_mdev instances (matrix_dev->mdev_list) that represent mediated devices68that hold the state for the mediated devices that have been attached to a69KVM guest. This lock must be held:70 711. To control access to the KVM pointer (matrix_mdev->kvm) while the vfio_ap72 device driver is using it to plug/unplug AP devices passed through to the KVM73 guest.74 752. To add matrix_mdev instances to or remove them from matrix_dev->mdev_list.76 This is necessary to ensure the proper locking order when the list is perused77 to find an ap_matrix_mdev instance for the purpose of plugging/unplugging78 AP devices passed through to a KVM guest.79 80 For example, when a queue device is removed from the vfio_ap device driver,81 if the adapter is passed through to a KVM guest, it will have to be82 unplugged. In order to figure out whether the adapter is passed through,83 the matrix_mdev object to which the queue is assigned will have to be84 found. The KVM pointer (matrix_mdev->kvm) can then be used to determine if85 the mediated device is passed through (matrix_mdev->kvm != NULL) and if so,86 to unplug the adapter.87 88It is not necessary to take the Guests Lock to access the KVM pointer if the89pointer is not used to plug/unplug devices passed through to the KVM guest;90however, in this case, the Matrix Devices Lock (matrix_dev->mdevs_lock) must be91held in order to access the KVM pointer since it is set and cleared under the92protection of the Matrix Devices Lock. A case in point is the function that93handles interception of the PQAP(AQIC) instruction sub-function. This handler94needs to access the KVM pointer only for the purposes of setting or clearing IRQ95resources, so only the matrix_dev->mdevs_lock needs to be held.96 97The PQAP Hook Lock (arch/s390/include/asm/kvm_host.h)98-----------------------------------------------------99 100.. code-block:: c101 102 typedef int (*crypto_hook)(struct kvm_vcpu *vcpu);103 104 struct kvm_s390_crypto {105 ...106 struct rw_semaphore pqap_hook_rwsem;107 crypto_hook *pqap_hook;108 ...109 };110 111The PQAP Hook Lock is a r/w semaphore that controls access to the function112pointer of the handler ``(*kvm->arch.crypto.pqap_hook)`` to invoke when the113PQAP(AQIC) instruction sub-function is intercepted by the host. The lock must be114held in write mode when pqap_hook value is set, and in read mode when the115pqap_hook function is called.116