€•p>      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ-/translations/zh_CN/arch/s390/vfio-ap-locking”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/zh_TW/arch/s390/vfio-ap-locking”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/it_IT/arch/s390/vfio-ap-locking”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/ja_JP/arch/s390/vfio-ap-locking”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/ko_KR/arch/s390/vfio-ap-locking”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/sp_SP/arch/s390/vfio-ap-locking”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒG/var/lib/git/docbuild/linux/Documentation/arch/s390/vfio-ap-locking.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒVFIO AP Locks Overview”h]”hŒVFIO AP Locks Overview”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h KubhŒ	paragraph”“”)”}”(hŒá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:”h]”hŒá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:”…””}”(hhËhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khh¶hžhubhŒliteral_block”“”)”}”(hŒVstruct ap_matrix_dev *matrix_dev;
struct ap_matrix_mdev *matrix_mdev;
struct kvm *kvm;”h]”hŒVstruct ap_matrix_dev *matrix_dev;
struct ap_matrix_mdev *matrix_mdev;
struct kvm *kvm;”…””}”hhÛsbah}”(h]”h ]”h"]”h$]”h&]”h±h²Œforce”‰Œlanguage”Œc”Œhighlight_args”}”uh1hÙhŸh³h K
hh¶hžhubhµ)”}”(hhh]”(hº)”}”(hŒ?The Matrix Devices Lock (drivers/s390/crypto/vfio_ap_private.h)”h]”hŒ?The Matrix Devices Lock (drivers/s390/crypto/vfio_ap_private.h)”…””}”(hhñhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hhîhžhhŸh³h KubhÚ)”}”(hŒmstruct ap_matrix_dev {
      ...
      struct list_head mdev_list;
      struct mutex mdevs_lock;
      ...
}”h]”hŒmstruct ap_matrix_dev {
      ...
      struct list_head mdev_list;
      struct mutex mdevs_lock;
      ...
}”…””}”hhÿsbah}”(h]”h ]”h"]”h$]”h&]”h±h²hé‰hêhëhì}”uh1hÙhŸh³h KhhîhžhubhÊ)”}”(hX¯  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
controls access to all fields contained within each matrix_mdev
(matrix_dev->mdev_list). This lock must be held while reading from, writing to
or using the data from a field contained within a matrix_mdev instance
representing one of the vfio_ap device driver's mediated devices.”h]”hX±  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
controls access to all fields contained within each matrix_mdev
(matrix_dev->mdev_list). This lock must be held while reading from, writing to
or using the data from a field contained within a matrix_mdev instance
representing one of the vfio_ap device driverâ€™s mediated devices.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Khhîhžhubeh}”(h]”Œ=the-matrix-devices-lock-drivers-s390-crypto-vfio-ap-private-h”ah ]”h"]”Œ?the matrix devices lock (drivers/s390/crypto/vfio_ap_private.h)”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒ'The KVM Lock (include/linux/kvm_host.h)”h]”hŒ'The KVM Lock (include/linux/kvm_host.h)”…””}”(hj'  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj$  hžhhŸh³h K$ubhÚ)”}”(hŒ;struct kvm {
      ...
      struct mutex lock;
      ...
}”h]”hŒ;struct kvm {
      ...
      struct mutex lock;
      ...
}”…””}”hj5  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²hé‰hêhëhì}”uh1hÙhŸh³h K&hj$  hžhubhÊ)”}”(hŒí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,
domains or control domains are being plugged into or unplugged from the guest.”h]”hŒí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,
domains or control domains are being plugged into or unplugged from the guest.”…””}”(hjD  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K.hj$  hžhubhÊ)”}”(hŒªThe KVM pointer is stored in the in the matrix_mdev instance
(matrix_mdev->kvm = kvm) containing the state of the mediated device that has
been attached to the KVM guest.”h]”hŒªThe KVM pointer is stored in the in the matrix_mdev instance
(matrix_mdev->kvm = kvm) containing the state of the mediated device that has
been attached to the KVM guest.”…””}”(hjR  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h K2hj$  hžhubeh}”(h]”Œ%the-kvm-lock-include-linux-kvm-host-h”ah ]”h"]”Œ'the kvm lock (include/linux/kvm_host.h)”ah$]”h&]”uh1h´hh¶hžhhŸh³h K$ubhµ)”}”(hhh]”(hº)”}”(hŒ7The Guests Lock (drivers/s390/crypto/vfio_ap_private.h)”h]”hŒ7The Guests Lock (drivers/s390/crypto/vfio_ap_private.h)”…””}”(hjk  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjh  hžhhŸh³h K7ubhÚ)”}”(hŒnstruct ap_matrix_dev {
      ...
      struct list_head mdev_list;
      struct mutex guests_lock;
      ...
}”h]”hŒnstruct ap_matrix_dev {
      ...
      struct list_head mdev_list;
      struct mutex guests_lock;
      ...
}”…””}”hjy  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²hé‰hêhëhì}”uh1hÙhŸh³h K9hjh  hžhubhÊ)”}”(hŒûThe Guests Lock (matrix_dev->guests_lock) controls access to the
matrix_mdev instances (matrix_dev->mdev_list) that represent mediated devices
that hold the state for the mediated devices that have been attached to a
KVM guest. This lock must be held:”h]”hŒûThe Guests Lock (matrix_dev->guests_lock) controls access to the
matrix_mdev instances (matrix_dev->mdev_list) that represent mediated devices
that hold the state for the mediated devices that have been attached to a
KVM guest. This lock must be held:”…””}”(hjˆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KBhjh  hžhubhŒenumerated_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒŸTo control access to the KVM pointer (matrix_mdev->kvm) while the vfio_ap
device driver is using it to plug/unplug AP devices passed through to the KVM
guest.
”h]”hÊ)”}”(hŒžTo control access to the KVM pointer (matrix_mdev->kvm) while the vfio_ap
device driver is using it to plug/unplug AP devices passed through to the KVM
guest.”h]”hŒžTo control access to the KVM pointer (matrix_mdev->kvm) while the vfio_ap
device driver is using it to plug/unplug AP devices passed through to the KVM
guest.”…””}”(hj¡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KGhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j›  hj˜  hžhhŸh³h Nubjœ  )”}”(hXÛ  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 perused
to find an ap_matrix_mdev instance for the purpose of plugging/unplugging
AP 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 be
unplugged. In order to figure out whether the adapter is passed through,
the matrix_mdev object to which the queue is assigned will have to be
found. The KVM pointer (matrix_mdev->kvm) can then be used to determine if
the mediated device is passed through (matrix_mdev->kvm != NULL) and if so,
to unplug the adapter.
”h]”(hÊ)”}”(hX  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 perused
to find an ap_matrix_mdev instance for the purpose of plugging/unplugging
AP devices passed through to a KVM guest.”h]”hX  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 perused
to find an ap_matrix_mdev instance for the purpose of plugging/unplugging
AP devices passed through to a KVM guest.”…””}”(hj¹  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KKhjµ  ubhÊ)”}”(hXÌ  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 be
unplugged. In order to figure out whether the adapter is passed through,
the matrix_mdev object to which the queue is assigned will have to be
found. The KVM pointer (matrix_mdev->kvm) can then be used to determine if
the mediated device is passed through (matrix_mdev->kvm != NULL) and if so,
to unplug the adapter.”h]”hXÌ  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 be
unplugged. In order to figure out whether the adapter is passed through,
the matrix_mdev object to which the queue is assigned will have to be
found. The KVM pointer (matrix_mdev->kvm) can then be used to determine if
the mediated device is passed through (matrix_mdev->kvm != NULL) and if so,
to unplug the adapter.”…””}”(hjÇ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KPhjµ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j›  hj˜  hžhhŸh³h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œarabic”Œprefix”hŒsuffix”Œ.”uh1j–  hjh  hžhhŸh³h KGubhÊ)”}”(hXa  It is not necessary to take the Guests Lock to access the KVM pointer if the
pointer 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 be
held in order to access the KVM pointer since it is set and cleared under the
protection of the Matrix Devices Lock. A case in point is the function that
handles interception of the PQAP(AQIC) instruction sub-function. This handler
needs to access the KVM pointer only for the purposes of setting or clearing IRQ
resources, so only the matrix_dev->mdevs_lock needs to be held.”h]”hXa  It is not necessary to take the Guests Lock to access the KVM pointer if the
pointer 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 be
held in order to access the KVM pointer since it is set and cleared under the
protection of the Matrix Devices Lock. A case in point is the function that
handles interception of the PQAP(AQIC) instruction sub-function. This handler
needs to access the KVM pointer only for the purposes of setting or clearing IRQ
resources, so only the matrix_dev->mdevs_lock needs to be held.”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h KXhjh  hžhubeh}”(h]”Œ5the-guests-lock-drivers-s390-crypto-vfio-ap-private-h”ah ]”h"]”Œ7the guests lock (drivers/s390/crypto/vfio_ap_private.h)”ah$]”h&]”uh1h´hh¶hžhhŸh³h K7ubhµ)”}”(hhh]”(hº)”}”(hŒ5The PQAP Hook Lock (arch/s390/include/asm/kvm_host.h)”h]”hŒ5The PQAP Hook Lock (arch/s390/include/asm/kvm_host.h)”…””}”(hjÿ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjü  hžhhŸh³h KbubhÚ)”}”(hŒ¬typedef int (*crypto_hook)(struct kvm_vcpu *vcpu);

struct kvm_s390_crypto {
      ...
      struct rw_semaphore pqap_hook_rwsem;
      crypto_hook *pqap_hook;
      ...
};”h]”hŒ¬typedef int (*crypto_hook)(struct kvm_vcpu *vcpu);

struct kvm_s390_crypto {
      ...
      struct rw_semaphore pqap_hook_rwsem;
      crypto_hook *pqap_hook;
      ...
};”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²hé‰hêhëhì}”uh1hÙhŸh³h Kdhjü  hžhubhÊ)”}”(hXO  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
PQAP(AQIC) instruction sub-function is intercepted by the host. The lock must be
held in write mode when pqap_hook value is set, and in read mode when the
pqap_hook function is called.”h]”(hŒbThe PQAP Hook Lock is a r/w semaphore that controls access to the function
pointer of the handler ”…””}”(hj  hžhhŸNh NubhŒliteral”“”)”}”(hŒ!``(*kvm->arch.crypto.pqap_hook)``”h]”hŒ(*kvm->arch.crypto.pqap_hook)”…””}”(hj&  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j$  hj  ubhŒÌ to invoke when the
PQAP(AQIC) instruction sub-function is intercepted by the host. The lock must be
held in write mode when pqap_hook value is set, and in read mode when the
pqap_hook function is called.”…””}”(hj  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÉhŸh³h Kohjü  hžhubeh}”(h]”Œ3the-pqap-hook-lock-arch-s390-include-asm-kvm-host-h”ah ]”h"]”Œ5the pqap hook lock (arch/s390/include/asm/kvm_host.h)”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kbubeh}”(h]”Œvfio-ap-locks-overview”ah ]”h"]”Œvfio ap locks overview”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jq  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jK  jH  j!  j  je  jb  jù  jö  jC  j@  uŒ	nametypes”}”(jK  ‰j!  ‰je  ‰jù  ‰jC  ‰uh}”(jH  h¶j  hîjb  j$  jö  jh  j@  jü  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.