1 .. SPDX-License-Identifier: GPL-2.0
2
3 ======================
4 VFIO AP Locks Overview
5 ======================
6 This document describes the locks that are per
7 of the vfio_ap device driver. Throughout this
8 will be used to denote instances of the struct
9
10 .. code-block:: c
11
12 struct ap_matrix_dev *matrix_dev;
13 struct ap_matrix_mdev *matrix_mdev;
14 struct kvm *kvm;
15
16 The Matrix Devices Lock (drivers/s390/crypto/v
17 ----------------------------------------------
18
19 .. code-block:: c
20
21 struct ap_matrix_dev {
22 ...
23 struct list_head mdev_list;
24 struct mutex mdevs_lock;
25 ...
26 }
27
28 The Matrix Devices Lock (matrix_dev->mdevs_loc
29 mutex contained within the single object of st
30 controls access to all fields contained within
31 (matrix_dev->mdev_list). This lock must be hel
32 or using the data from a field contained withi
33 representing one of the vfio_ap device driver'
34
35 The KVM Lock (include/linux/kvm_host.h)
36 ---------------------------------------
37
38 .. code-block:: c
39
40 struct kvm {
41 ...
42 struct mutex lock;
43 ...
44 }
45
46 The KVM Lock (kvm->lock) controls access to th
47 lock must be held by the vfio_ap device driver
48 domains or control domains are being plugged i
49
50 The KVM pointer is stored in the in the matrix
51 (matrix_mdev->kvm = kvm) containing the state
52 been attached to the KVM guest.
53
54 The Guests Lock (drivers/s390/crypto/vfio_ap_p
55 ----------------------------------------------
56
57 .. code-block:: c
58
59 struct ap_matrix_dev {
60 ...
61 struct list_head mdev_list;
62 struct mutex guests_lock;
63 ...
64 }
65
66 The Guests Lock (matrix_dev->guests_lock) cont
67 matrix_mdev instances (matrix_dev->mdev_list)
68 that hold the state for the mediated devices t
69 KVM guest. This lock must be held:
70
71 1. To control access to the KVM pointer (matri
72 device driver is using it to plug/unplug AP
73 guest.
74
75 2. To add matrix_mdev instances to or remove t
76 This is necessary to ensure the proper lock
77 to find an ap_matrix_mdev instance for the
78 AP devices passed through to a KVM guest.
79
80 For example, when a queue device is removed
81 if the adapter is passed through to a KVM g
82 unplugged. In order to figure out whether t
83 the matrix_mdev object to which the queue i
84 found. The KVM pointer (matrix_mdev->kvm) c
85 the mediated device is passed through (matr
86 to unplug the adapter.
87
88 It is not necessary to take the Guests Lock to
89 pointer is not used to plug/unplug devices pas
90 however, in this case, the Matrix Devices Lock
91 held in order to access the KVM pointer since
92 protection of the Matrix Devices Lock. A case
93 handles interception of the PQAP(AQIC) instruc
94 needs to access the KVM pointer only for the p
95 resources, so only the matrix_dev->mdevs_lock
96
97 The PQAP Hook Lock (arch/s390/include/asm/kvm_
98 ----------------------------------------------
99
100 .. code-block:: c
101
102 typedef int (*crypto_hook)(struct kvm_vcpu *
103
104 struct kvm_s390_crypto {
105 ...
106 struct rw_semaphore pqap_hook_rwsem;
107 crypto_hook *pqap_hook;
108 ...
109 };
110
111 The PQAP Hook Lock is a r/w semaphore that con
112 pointer of the handler ``(*kvm->arch.crypto.pq
113 PQAP(AQIC) instruction sub-function is interce
114 held in write mode when pqap_hook value is set
115 pqap_hook function is called.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.