The Matrix Devices Lock (drivers/s390/crypto/vfio_ap_private.h)¶

structap_matrix_dev{...structlist_headmdev_list;structmutexmdevs_lock;...}

The Matrix Devices Lock (matrix_dev->mdevs_lock) is implemented as a globalmutex contained within the single object ofstructap_matrix_dev. This lockcontrols access to all fields contained within each matrix_mdev(matrix_dev->mdev_list). This lock must be held while reading from, writing toor using the data from a field contained within a matrix_mdev instancerepresenting one of the vfio_ap device driver’s mediated devices.

The KVM Lock (include/linux/kvm_host.h)¶

structkvm{...structmutexlock;...}

The KVM Lock (kvm->lock) controls access to the state data for a KVM guest. Thislock must be held by the vfio_ap device driver while one or more AP adapters,domains or control domains are being plugged into or unplugged from the guest.

The KVM pointer is stored in the in the matrix_mdev instance(matrix_mdev->kvm = kvm) containing the state of the mediated device that hasbeen attached to the KVM guest.

The Guests Lock (drivers/s390/crypto/vfio_ap_private.h)¶

structap_matrix_dev{...structlist_headmdev_list;structmutexguests_lock;...}

The Guests Lock (matrix_dev->guests_lock) controls access to thematrix_mdev instances (matrix_dev->mdev_list) that represent mediated devicesthat hold the state for the mediated devices that have been attached to aKVM guest. This lock must be held:

1. To control access to the KVM pointer (matrix_mdev->kvm) while the vfio_apdevice driver is using it to plug/unplug AP devices passed through to the KVMguest.

2. To add matrix_mdev instances to or remove them from matrix_dev->mdev_list.This is necessary to ensure the proper locking order when the list is perusedto find an ap_matrix_mdev instance for the purpose of plugging/unpluggingAP devices passed through to a KVM guest.

   For example, when a queue device is removed from the vfio_ap device driver,if the adapter is passed through to a KVM guest, it will have to beunplugged. In order to figure out whether the adapter is passed through,the matrix_mdev object to which the queue is assigned will have to befound. The KVM pointer (matrix_mdev->kvm) can then be used to determine ifthe mediated device is passed through (matrix_mdev->kvm != NULL) and if so,to unplug the adapter.

It is not necessary to take the Guests Lock to access the KVM pointer if thepointer is not used to plug/unplug devices passed through to the KVM guest;however, in this case, the Matrix Devices Lock (matrix_dev->mdevs_lock) must beheld in order to access the KVM pointer since it is set and cleared under theprotection of the Matrix Devices Lock. A case in point is the function thathandles interception of the PQAP(AQIC) instruction sub-function. This handlerneeds to access the KVM pointer only for the purposes of setting or clearing IRQresources, so only the matrix_dev->mdevs_lock needs to be held.

The PQAP Hook Lock (arch/s390/include/asm/kvm_host.h)¶

typedefint(*crypto_hook)(structkvm_vcpu*vcpu);structkvm_s390_crypto{...structrw_semaphorepqap_hook_rwsem;crypto_hook*pqap_hook;...};

The PQAP Hook Lock is a r/w semaphore that controls access to the functionpointer of the handler(*kvm->arch.crypto.pqap_hook) to invoke when thePQAP(AQIC) instruction sub-function is intercepted by the host. The lock must beheld in write mode when pqap_hook value is set, and in read mode when thepqap_hook function is called.