From nobody Mon Jun 8 17:38:04 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 759B342848D; Wed, 27 May 2026 15:33:23 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896003; cv=none; b=UULM7JffvnuNdPNnIZnC0zjTXLR02wGDItC1G439XN1+1G3/mBHY9oPGAdaonj4po2R48Rc4r8CfGrxgg9aUXS7qZ+Mc/LY+5hHM4qWyozXO/uTWLABPw7coQFGoFwOrhX4YY8IRnWRv8/ha2nfkQ86DDljPCYZNcSoEjtOw/Tc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896003; c=relaxed/simple; bh=1p81ZNBxNEloWsHcf8g42JPwNVdcqsmbhHDMBs5xtuw=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=jWBxhAFGI96jn/PWynB4Q+WQQnVD2SYaF6z+w0yRIV2aT5+Ue5nbXnyl8USzgaAEUvC8UzUGPJM0A4BuD5c1RKkI+UyW61/imPwblWDtNzAn9fwYSNICuU3nBHfrn+ZO7xyYuJqG5i2VEoDWKePo9Np6GFxlbVb+vluA6KGdb/o= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=b/Plho0y; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="b/Plho0y" Received: by smtp.kernel.org (Postfix) with ESMTPS id 6B359C19425; Wed, 27 May 2026 15:33:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1779896002; bh=1p81ZNBxNEloWsHcf8g42JPwNVdcqsmbhHDMBs5xtuw=; h=From:Date:Subject:References:In-Reply-To:To:Cc:Reply-To:From; b=b/Plho0yw5DWCIGekeE4FNy/iu9QxKChox6T9jgJJ6SInBA5D8AB+tei6AV0Hh1Dc mVOWSlbsk0IpuLxTSg0XT2yi2Drme8jLzd1wJNo7vkiNLKDR4sAXM5+xn+BKrxd6/J YO4zZRASiGJNQmJIpdG+ZRTyiD4WJbgdBHQoLIKpXY5fiaG61bBT/kov6UTKIHUpPx g3l52lXZRksCvPrcWVl+xus0dU9vzPimpsWLSFoqzIL/tpUUFm7d0McRXA7iYbHN/x N4rE+Fy8kP4k0DD3coI+osifn8/+Z1NbjLy8NSWOqZY3VYw+Z0/lIX8I4TMPv7+wR6 WeNQDE1a+c6yQ== Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 63C12CD6E41; Wed, 27 May 2026 15:33:22 +0000 (UTC) From: Ackerley Tng via B4 Relay Date: Wed, 27 May 2026 08:33:13 -0700 Subject: [PATCH RFC 01/12] Documentation: KVM: Elaborate comment on kvm_usage_lock Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260527-kvm-locking-docs-v1-1-4fe8b602ff47@google.com> References: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> In-Reply-To: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> To: Paolo Bonzini , Jonathan Corbet , Shuah Khan , Tianrui Zhao , Bibo Mao , Huacai Chen , WANG Xuerui , Sean Christopherson , Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , Fuad Tabba , vannapurve@google.com, x86@kernel.org, "H. Peter Anvin" Cc: kvm@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, loongarch@lists.linux.dev, Ackerley Tng X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1779896001; l=1798; i=ackerleytng@google.com; s=20260225; h=from:subject:message-id; bh=1hH8Q0hBBnzb0IjHg5TBjPkm0Xu0Pb4r5XTBzAPfiqY=; b=fU+6+4GQIUI8X/J/BwojcC/g3/dZq9Cy1AdwRV6CsRk1oo420RJtTrBz08gADa92ThBWvtsKp 1qPdl0HarVvDiP2oochMmaqZ8lzASO49loGKy3NHXUUaWuDuMpMpnn4 X-Developer-Key: i=ackerleytng@google.com; a=ed25519; pk=sAZDYXdm6Iz8FHitpHeFlCMXwabodTm7p8/3/8xUxuU= X-Endpoint-Received: by B4 Relay for ackerleytng@google.com/20260225 with auth_id=649 X-Original-From: Ackerley Tng Reply-To: ackerleytng@google.com From: Ackerley Tng The original comment talks about cpus_read_lock() and kvm_usage_count, but doesn't explain why they are related. Elaborate comment on kvm_usage_lock to provide more context. Signed-off-by: Ackerley Tng --- Documentation/virt/kvm/locking.rst | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/lo= cking.rst index 662231e958a07..5564c8b38b9cc 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -248,8 +248,23 @@ time it will be set using the Dirty tracking mechanism= described above. :Arch: any :Protects: - kvm_usage_count - hardware virtualization enable/disable -:Comment: Exists to allow taking cpus_read_lock() while kvm_usage_count is - protected, which simplifies the virtualization enabling logic. +:Comment: ``kvm_usage_count`` serves to deduplicate hardware + virtualization enabling and disabling requests from different VMs + being created. + + Hardware virtualization enabling/disabling requires taking + ``cpus_read_lock()``. + + ``kvm_lock`` used to also protect ``kvm_usage_count``, but other + parts of the Linux kernel holding ``cpus_read_lock()`` need to + call into KVM to ensure that VM state remains consistent with the + host's state. For example, when the CPU frequency changes, KVM is + notified. ``kvmclock_cpufreq_notifier()`` takes ``kvm_lock`` to + iterate ``vm_list``. + + To decouple these, use different locks, ``kvm_lock`` for + ``vm_list`` and ``kvm_usage_lock`` for enabling/disabling hardware + virtualization. =20 ``kvm->mn_invalidate_lock`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^ --=20 2.54.0.823.g6e5bcc1fc9-goog From nobody Mon Jun 8 17:38:04 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 1CECB42EEDF; Wed, 27 May 2026 15:33:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896003; cv=none; b=dKoVtmmcx0gro4oyNm0RBVliEKXmMvcwXEH3BFOJw5L9TJ4ZC5jty7EzzYNysItvYUxJxd3oIIdOVawnjOyT7+CfIlUq8jMDP42zjPPHDg7U2IPuAsEN5dd25zJ13EbXjmRBDKk0E+6mUMdSCj596yb6Fq/HZ3gBaWU+rWuaaJo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896003; c=relaxed/simple; bh=HE/v0i2tFIOZQbBpx1VxOShX/QBPkKvyXiEneo0YBZE=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=EVQva++kT3VBTOfITtVTWxHPsUFrK/LIuFg+D4M1BtdpSYIsZg/dFmPudYIC8vTjbOzwQG7GmNvG6eqe2RodoF3e+0yHCMBa6nBzqZVAQw53x3MYPbNuH5WyJeRMQzN65SqFd2j5bZzGhupU50acacpoTZWPigYBvBcHVp0Qlmo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=CzLEmkIE; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="CzLEmkIE" Received: by smtp.kernel.org (Postfix) with ESMTPS id 7BC73C2BCC6; Wed, 27 May 2026 15:33:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1779896002; bh=HE/v0i2tFIOZQbBpx1VxOShX/QBPkKvyXiEneo0YBZE=; h=From:Date:Subject:References:In-Reply-To:To:Cc:Reply-To:From; b=CzLEmkIEmaPXWBcOq5XREbns2k0gr1S/4PckKgOu1jaSG/rihF0LOmKtpxEouu57E ZhgOGt3Dc2cuDKPXH4aKuY8EwuHD3dKuD8FTePc/MwO6kBvhzZ23H2RRqDFW7MM7eE iZdoOX8cl8E9gQzQhivCrHOxBnMSbppodYd1EqhyEeiB924t2f9CdStFR9cIiv5ufe ozpBxQa1k5HolT0yVj3J/BW16EbbjmYtiKJqPfyyoRoz9Ugr1t1Lvj2CSD0tVsnx3J 3V9sGthit+sF1ZnWgX878SM9iN+v4HKjsA3+J8Wl/QMqTJ/ldnkXg4/xNcYap9MOP7 aeqvF0fm6zEYQ== Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 73130CD6E46; Wed, 27 May 2026 15:33:22 +0000 (UTC) From: Ackerley Tng via B4 Relay Date: Wed, 27 May 2026 08:33:14 -0700 Subject: [PATCH RFC 02/12] Documentation: KVM: Consolidate notes about cpu_read_lock() and kvm_lock Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260527-kvm-locking-docs-v1-2-4fe8b602ff47@google.com> References: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> In-Reply-To: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> To: Paolo Bonzini , Jonathan Corbet , Shuah Khan , Tianrui Zhao , Bibo Mao , Huacai Chen , WANG Xuerui , Sean Christopherson , Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , Fuad Tabba , vannapurve@google.com, x86@kernel.org, "H. Peter Anvin" Cc: kvm@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, loongarch@lists.linux.dev, Ackerley Tng X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1779896001; l=1641; i=ackerleytng@google.com; s=20260225; h=from:subject:message-id; bh=g71wqImwKNA2W1d9aVPqMV7Uh2kOm/LmCZhr5oX9KEc=; b=tp9bB0rR932atLXHEHhRX+PGjo7Pn9ZSpQ3wo1LyHKIYaRGe/jBPOdCQfNdTxOyq8w9lMnUj6 msk2J3WyEuOBBi3gyIsz2NhLOdOGjuUnCy0Ux1Nd5x9Qy5tyibGzGaj X-Developer-Key: i=ackerleytng@google.com; a=ed25519; pk=sAZDYXdm6Iz8FHitpHeFlCMXwabodTm7p8/3/8xUxuU= X-Endpoint-Received: by B4 Relay for ackerleytng@google.com/20260225 with auth_id=649 X-Original-From: Ackerley Tng Reply-To: ackerleytng@google.com From: Ackerley Tng Move the detail about cpu_read_lock() and kvm_lock to where the acquisition order is mentioned. Signed-off-by: Ackerley Tng --- Documentation/virt/kvm/locking.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/lo= cking.rst index 5564c8b38b9cc..1e8cbbe3ba706 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -10,6 +10,11 @@ KVM Lock Overview The acquisition orders for mutexes are as follows: =20 - cpus_read_lock() is taken outside kvm_lock + - Taking cpus_read_lock() outside of kvm_lock is problematic, + despite it being the official ordering, as it is quite easy to + unknowingly trigger cpus_read_lock() while holding kvm_lock. + Use caution when walking vm_list, e.g. avoid complex operations + when possible. =20 - kvm_usage_lock is taken outside cpus_read_lock() =20 @@ -28,13 +33,6 @@ The acquisition orders for mutexes are as follows: are taken on the waiting side when modifying memslots, so MMU notifiers must not take either kvm->slots_lock or kvm->slots_arch_lock. =20 -cpus_read_lock() vs kvm_lock: - -- Taking cpus_read_lock() outside of kvm_lock is problematic, despite that - being the official ordering, as it is quite easy to unknowingly trigger - cpus_read_lock() while holding kvm_lock. Use caution when walking vm_li= st, - e.g. avoid complex operations when possible. - For SRCU: =20 - ``synchronize_srcu(&kvm->srcu)`` is called inside critical sections --=20 2.54.0.823.g6e5bcc1fc9-goog From nobody Mon Jun 8 17:38:04 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id E7465436376; Wed, 27 May 2026 15:33:23 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; cv=none; b=B4dUuwKpouLXF+MR9UHm/ParyeScgnzWEp5vxRwa0OakoO6t0CxfUsxx+wckYR1zzv1abtOsqSmWABiQ4pAXrYKBBGFWziZ/WSqwDvTEAoLVVkW1UmDYJKAejiUDc0jPcUs2RMGOCdZM1QWypUkatC9drJ6KQvgPg/soI5xGtZc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; c=relaxed/simple; bh=Fy7SviBXyfR5Bkm0PCeZ4kofves6M/GmlsfFUICPdbk=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=XVFMP+SFfd6MWbnqnfgkOiA5qedWbj+vO6e60BNkn+gNFjl2XDxObErmCJZDjDjaSRF2MkHWc7pBQH/8CuVbcDbdIAGVr9/xZ6QSpOxC0+pyonYjtQ95xcDG30snGyRxgFNw8Mcq3eyGrZ0VWE16CEfKrTKbBe5vVvibjDIW348= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Zsanj2tq; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="Zsanj2tq" Received: by smtp.kernel.org (Postfix) with ESMTPS id 8E8DCC2BCF7; Wed, 27 May 2026 15:33:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1779896002; bh=Fy7SviBXyfR5Bkm0PCeZ4kofves6M/GmlsfFUICPdbk=; h=From:Date:Subject:References:In-Reply-To:To:Cc:Reply-To:From; b=Zsanj2tqyi0TtgslAqA7S3Uu361R8oEGT24pGgf4cov0NxluFq6sxzsaFDngAbGNN Zwg41zTkvnfxV//sndSvH7qpnG2G1cFT9lca1WGhcWkPRtWTmTtJtYZywShxYWauEm XCFnRLnYrUYgOb/JeAKNO5MqeXu8x666GWAxPuFjx+hxgSZL3FjzKbsVLPe2LFmOMe hIVr82GfiZrQJmxHIJuZP3oOsk6DC8fFKaTq+LNoc3dqzYrKLRCYLfWn8pF0LgPye2 ZmYii46Bki8fZ4LClgbYLSuaG0uY0cT1h/G5nD/xHaoD+P/B72nse40Gv5AQ/v9Cvg QQFhv1HkqgrVA== Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 861D7CD4F54; Wed, 27 May 2026 15:33:22 +0000 (UTC) From: Ackerley Tng via B4 Relay Date: Wed, 27 May 2026 08:33:15 -0700 Subject: [PATCH RFC 03/12] Documentation: KVM: Consolidate notes about kvm->slots_lock and irq_lock Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260527-kvm-locking-docs-v1-3-4fe8b602ff47@google.com> References: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> In-Reply-To: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> To: Paolo Bonzini , Jonathan Corbet , Shuah Khan , Tianrui Zhao , Bibo Mao , Huacai Chen , WANG Xuerui , Sean Christopherson , Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , Fuad Tabba , vannapurve@google.com, x86@kernel.org, "H. Peter Anvin" Cc: kvm@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, loongarch@lists.linux.dev, Ackerley Tng X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1779896001; l=1205; i=ackerleytng@google.com; s=20260225; h=from:subject:message-id; bh=5xqYuflg/lHRaHVhIbofzsJqCQI4L326JDxGJuO8b0U=; b=/bIlnjfndGdNS+ll2dxYYvqLLoNppW84HDwXhvbpWFF04ZPlHUMWp75WsSLCcKYSYWt61B5P7 mXli/FQOdC4BvZ0ynYtyfQjBM8Q6lsysXNUKDjZXn5ui6jUMED+c4jb X-Developer-Key: i=ackerleytng@google.com; a=ed25519; pk=sAZDYXdm6Iz8FHitpHeFlCMXwabodTm7p8/3/8xUxuU= X-Endpoint-Received: by B4 Relay for ackerleytng@google.com/20260225 with auth_id=649 X-Original-From: Ackerley Tng Reply-To: ackerleytng@google.com From: Ackerley Tng Move the detail about ordering between kvm->slots_lock and kvm->irq_lock to where the two locks are first mentioned. Signed-off-by: Ackerley Tng --- Documentation/virt/kvm/locking.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/lo= cking.rst index 1e8cbbe3ba706..67dd2066f6d98 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -21,12 +21,11 @@ The acquisition orders for mutexes are as follows: - kvm->lock is taken outside vcpu->mutex =20 - kvm->lock is taken outside kvm->slots_lock and kvm->irq_lock + - kvm->slots_lock is taken outside kvm->irq_lock, though acquiring + them together is quite rare. =20 - vcpu->mutex is taken outside kvm->slots_lock and kvm->slots_arch_lock =20 -- kvm->slots_lock is taken outside kvm->irq_lock, though acquiring - them together is quite rare. - - kvm->mn_active_invalidate_count ensures that pairs of invalidate_range_start() and invalidate_range_end() callbacks use the same memslots array. kvm->slots_lock and kvm->slots_arch_lock --=20 2.54.0.823.g6e5bcc1fc9-goog From nobody Mon Jun 8 17:38:04 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id E2C58436374; Wed, 27 May 2026 15:33:23 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; cv=none; b=XtIZURHoalEuMafUD1y79sptHM4/IL5oLd5pKZtAac6/dyQlWtJvq/qZM3EbIpKBsJFgvNVHdSrF9q07a9UwFk3TYeXj/519IQeHfC18Qrj3yoqOiFxAAxzQCt73jRb/QcvUvGXyRNYQddmrjpkNj27N/CeQIc1Ji3O57XSv0JQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; c=relaxed/simple; bh=nVpl3TVZQU9iG/8SJ8PbEKLaQViBegpkV2M01+wMc30=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=AFXNkaHAYc5q3w6wfeapfT+bsiLcA5EPAU21aXmCa/WHWDCeUMfRN691bBLlnSZjJnVy9ykukOQgVKne9YwlUsRq4I0LIFVcp0+VygNcxET6bHvN4XkIEKM1pFi99BP0gpCh+rBh0hd3E9E2Ya8LJdSAXbU7wfrQVAsdAOqKfrY= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=H43ckgw1; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="H43ckgw1" Received: by smtp.kernel.org (Postfix) with ESMTPS id A5489C2BCF6; Wed, 27 May 2026 15:33:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1779896002; bh=nVpl3TVZQU9iG/8SJ8PbEKLaQViBegpkV2M01+wMc30=; h=From:Date:Subject:References:In-Reply-To:To:Cc:Reply-To:From; b=H43ckgw1K/X/LMmGirCLu6olwyKN+3u+/yP/z6bq4Ct4qvvq94RCjO4PnMuw80M68 8djH78hYQ/6RueZeAlOGbX/16eqZVSzD6saRHNkwrq5RgAfLSBcybMpNwVtSULUf00 p4iAOaCi1NFHMkYm9rAg0cDrDyfjyQVIs6FJC3oZdgg4LbiCo+7Il/17eSinXotCrL jBqtiGCtO1xpXV2OxG/7eZgVCon6zt6es2Xn/VF1t1m0DG8/8cQsNzraqRvYxd0y7G oziRXR42K0miODftx0GpKUUz2adWvK/lDhtgoD8kIhYjikZSvRJUdUEx5x0XEj9IFb u+EENixrJHRgw== Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 9C8C4CD6E45; Wed, 27 May 2026 15:33:22 +0000 (UTC) From: Ackerley Tng via B4 Relay Date: Wed, 27 May 2026 08:33:16 -0700 Subject: [PATCH RFC 04/12] Documentation: KVM: Turn - into bullet point Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260527-kvm-locking-docs-v1-4-4fe8b602ff47@google.com> References: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> In-Reply-To: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> To: Paolo Bonzini , Jonathan Corbet , Shuah Khan , Tianrui Zhao , Bibo Mao , Huacai Chen , WANG Xuerui , Sean Christopherson , Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , Fuad Tabba , vannapurve@google.com, x86@kernel.org, "H. Peter Anvin" Cc: kvm@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, loongarch@lists.linux.dev, Ackerley Tng X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1779896001; l=909; i=ackerleytng@google.com; s=20260225; h=from:subject:message-id; bh=CVJlxPT0bvHHOwHsW6J5heOXwU/ZjkdVD+6fUMJnWDE=; b=KkPJHF+eM7NDmHDSEhDOiOBWhwesjg7rIQXxnzpWgTB9I02vfYnNi5BaXX0a183XJ1mq7TDDx YhG5/AGb4N7Df+nmEUADJYfEvIEoR/I+w01Jm8766xS2x9bSTAeKxa+ X-Developer-Key: i=ackerleytng@google.com; a=ed25519; pk=sAZDYXdm6Iz8FHitpHeFlCMXwabodTm7p8/3/8xUxuU= X-Endpoint-Received: by B4 Relay for ackerleytng@google.com/20260225 with auth_id=649 X-Original-From: Ackerley Tng Reply-To: ackerleytng@google.com From: Ackerley Tng For the :Protects: section of kvm->mmu_lock, a missing space causes the - to render as a literal - instead of a bullet point. Add space to make it render as a bullet point. Signed-off-by: Ackerley Tng --- Documentation/virt/kvm/locking.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/lo= cking.rst index 67dd2066f6d98..e349c2cb94943 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -283,7 +283,7 @@ time it will be set using the Dirty tracking mechanism = described above. ^^^^^^^^^^^^^^^^^ :Type: spinlock_t or rwlock_t :Arch: any -:Protects: -shadow page/shadow tlb entry +:Protects: - shadow page/shadow tlb entry :Comment: it is a spinlock since it is used in mmu notifier. =20 ``kvm->srcu`` --=20 2.54.0.823.g6e5bcc1fc9-goog From nobody Mon Jun 8 17:38:04 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id ED4522D9EDC; Wed, 27 May 2026 15:33:23 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; cv=none; b=LuAIpVYgQKXjEDfi/laOYgDlvMiVdNMI23VkRw0Ym2zXXZL9iXiNU5KZdTkgqevT15MvhJupNTiGmDH/p3q0qaIRSM/gEZlU5CeaHY6gI6CJAwLrSXPrtEi2YpZZBLQ+qIQvDII9SEJUosgUS/8R/L7/AYk7GDG7keRTZgMGm40= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; c=relaxed/simple; bh=eF5fEOWZsn5iEd6JrTeFCCBK6A3UIngZ9wzCS6q9kjw=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=KLtRCQO4rlmK2FA/P1QLSRzF/tI/cWZ1BPsv8mMF+6MkDM8dDux4HCOz/mgH3XrXOo7DTSzIcEvqlgrbgI/6PklQLh5p1zNglZr+5OrqkMY4UP/vN3u+Xj0TKpgY8JdZgIpyutrAxIKGy7059Ej+84FVDyfTLFdXWrgpE4yNTio= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=HzNMKTnH; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="HzNMKTnH" Received: by smtp.kernel.org (Postfix) with ESMTPS id B526DC2BCFA; Wed, 27 May 2026 15:33:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1779896002; bh=eF5fEOWZsn5iEd6JrTeFCCBK6A3UIngZ9wzCS6q9kjw=; h=From:Date:Subject:References:In-Reply-To:To:Cc:Reply-To:From; b=HzNMKTnH7LjMRKl96vGWtzp8Ea9tjVE6pAzMj0dRt83r8yIQ1zFguN4GOSKbadFNp X2V3BjYTnEfG4XfGYNZwE8GzKCO2GfbR+QnLfhe+qIgu0omOj3Na0XjQ9KtoLOy7sA dTR8VbdGjrDZfTH6Ue7Rz/0RtzfZqU6b26KCLqbKZdUFYug2x2U+X5s320dAgGfJzR GgC+V2AartD7uP1VOAHvAwP9jDeAGyn84zzNh2JCFwebylEvozyLyPtiXJevW731yK Gi26+gSMbzdvjHM4gkr6sL+jaSNILuds2Ulwv8Ew0vaJaHUymwSDsS7CS95h28kzb/ 185uJlcton7/Q== Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id AD663CD5BD0; Wed, 27 May 2026 15:33:22 +0000 (UTC) From: Ackerley Tng via B4 Relay Date: Wed, 27 May 2026 08:33:17 -0700 Subject: [PATCH RFC 05/12] Documentation: KVM: Explain what rule the exception section is meant for Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260527-kvm-locking-docs-v1-5-4fe8b602ff47@google.com> References: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> In-Reply-To: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> To: Paolo Bonzini , Jonathan Corbet , Shuah Khan , Tianrui Zhao , Bibo Mao , Huacai Chen , WANG Xuerui , Sean Christopherson , Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , Fuad Tabba , vannapurve@google.com, x86@kernel.org, "H. Peter Anvin" Cc: kvm@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, loongarch@lists.linux.dev, Ackerley Tng X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1779896001; l=866; i=ackerleytng@google.com; s=20260225; h=from:subject:message-id; bh=UhewnEFTG+HebdABX6t5eYYm+bNGAkoVsLLrTGAOeg4=; b=H1OQEdfNpvGS7THThfrjojW6x13TvDlSiVDOrcNRwD6ECzNiF+y3cEqXlnDWAXTlLltd+N+OR mklc0Q4Qr+BDr5L6d/govG1pkusRLLY1/lYMOt9RtFH8pqsWyDfELTw X-Developer-Key: i=ackerleytng@google.com; a=ed25519; pk=sAZDYXdm6Iz8FHitpHeFlCMXwabodTm7p8/3/8xUxuU= X-Endpoint-Received: by B4 Relay for ackerleytng@google.com/20260225 with auth_id=649 X-Original-From: Ackerley Tng Reply-To: ackerleytng@google.com From: Ackerley Tng The Exception section describes some exceptions but not the rule the exception is for. Add a paragraph to clarify that detail. Signed-off-by: Ackerley Tng --- Documentation/virt/kvm/locking.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/lo= cking.rst index e349c2cb94943..5161636cec481 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -61,6 +61,10 @@ sections. 2. Exception ------------ =20 +The general rule in KVM is that any modification to shadow page tables +(and their entries (SPTEs)) must be protected by ``kvm->mmu_lock``, +with the exceptions described below. + Fast page fault: =20 Fast page fault is the fast path which fixes the guest page fault out of --=20 2.54.0.823.g6e5bcc1fc9-goog From nobody Mon Jun 8 17:38:04 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id EEE2443637D; Wed, 27 May 2026 15:33:23 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; cv=none; b=LVsPBKMIDlEuht3kcgmQ/Tx56GgFUiobP7OQDJh0kKw6aMiPcVoEQ9XHdMic1s81qkDUgDsA5m2hNJubu85ZC9o5JieiJ1x6m4EnAVu7to1ucaIsK/zxILd/4Mrh5aoT1cPtMB6Ql44wBEWrjUtTQSPoAoVSyUBuJrHyJmyQllU= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; c=relaxed/simple; bh=bLcxXHk+CcALqz/zzbA0F0Yybtdc+uNVe0wHT/tY7BQ=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=N1a/hydnCoKRyLnAl1BHz9CUIfCRCIgnd8ghQUFF6uPb2B0zGATp5CFXW4DUH6IkCGtljG+rPugxK0n4iYwXht52lOtlC4BhwGsS2Ym6OxIKVnbkbreUy1FdzlAIpWLk1B3DrFfmnqr5Tu0cC4H90OVT7wM1/QTJhjKum+Qvzv0= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ZugAWKNo; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="ZugAWKNo" Received: by smtp.kernel.org (Postfix) with ESMTPS id C532EC2BCFB; Wed, 27 May 2026 15:33:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1779896002; bh=bLcxXHk+CcALqz/zzbA0F0Yybtdc+uNVe0wHT/tY7BQ=; h=From:Date:Subject:References:In-Reply-To:To:Cc:Reply-To:From; b=ZugAWKNou/3hhdk3/0CuslHwBG12FxSCoiQDLoZeTluxV075OF9MTYMvYc/B3dwQE pYt4TldcdTo+0VF7VMlW8lw9NewWgyAdIWMbeWvIm80t/noX6uKVj8+YHOClMxaDVo SI9Lkr34NYgh7xriAcRUxu/oNZDa6C/QUyWV/aizcmrWJh0YRhl3JQXDarb/ZgIFxK lN8OjLatlFAtuSoxeVfB037tOrc4k+2l4CHZHZ13eO0wl6Db/kaaZEXq3ztR0j5H8K zTFb9qQNeo1OydUTwLbFBUwUiAR2+ZYGsaBbOMbsyntsioUdV3Ua50kmUrprl1JrM7 +H6gFaV3R5SOg== Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id BCF9BCD4F54; Wed, 27 May 2026 15:33:22 +0000 (UTC) From: Ackerley Tng via B4 Relay Date: Wed, 27 May 2026 08:33:18 -0700 Subject: [PATCH RFC 06/12] Documentation: KVM: Have actual headings for exceptions Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260527-kvm-locking-docs-v1-6-4fe8b602ff47@google.com> References: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> In-Reply-To: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> To: Paolo Bonzini , Jonathan Corbet , Shuah Khan , Tianrui Zhao , Bibo Mao , Huacai Chen , WANG Xuerui , Sean Christopherson , Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , Fuad Tabba , vannapurve@google.com, x86@kernel.org, "H. Peter Anvin" Cc: kvm@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, loongarch@lists.linux.dev, Ackerley Tng X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1779896001; l=1576; i=ackerleytng@google.com; s=20260225; h=from:subject:message-id; bh=omLCISL/Cs1+39lE29MDupCtm4WwTzGw7vDPKSySNYo=; b=hprWgud3QVI1IKRiPLGBIYGbG2occ7We7PsN9/HJiCR/0rZEaqlqEP39d5vxdyx0Gpkil7MJV OZNw5t9xeHOAhY9qTRJPjQQyqfcQdggNLhA0ARfSxEm8DrBNtkxx0PE X-Developer-Key: i=ackerleytng@google.com; a=ed25519; pk=sAZDYXdm6Iz8FHitpHeFlCMXwabodTm7p8/3/8xUxuU= X-Endpoint-Received: by B4 Relay for ackerleytng@google.com/20260225 with auth_id=649 X-Original-From: Ackerley Tng Reply-To: ackerleytng@google.com From: Ackerley Tng Exceptions documented are described but without headings, making it hard to identify where each exception description ended. Use actual headings at a lower level than that of the heading used for Exception to improve readability. Signed-off-by: Ackerley Tng --- Documentation/virt/kvm/locking.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/lo= cking.rst index 5161636cec481..fc4537a7659a9 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -65,7 +65,8 @@ The general rule in KVM is that any modification to shado= w page tables (and their entries (SPTEs)) must be protected by ``kvm->mmu_lock``, with the exceptions described below. =20 -Fast page fault: +2.1. Fast page fault +^^^^^^^^^^^^^^^^^^^^ =20 Fast page fault is the fast path which fixes the guest page fault out of the mmu-lock on x86. Currently, the page fault can be fast in one of the @@ -217,7 +218,8 @@ Since the spte is "volatile" if it can be updated out o= f mmu-lock, we always atomically update the spte and the race caused by fast page fault can be a= voided. See the comments in spte_needs_atomic_update() and mmu_spte_update(). =20 -Lockless Access Tracking: +2.2 Lockless Access Tracking +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ =20 This is used for Intel CPUs that are using EPT but do not support the EPT = A/D bits. In this case, PTEs are tagged as A/D disabled (using ignored bits), = and --=20 2.54.0.823.g6e5bcc1fc9-goog From nobody Mon Jun 8 17:38:04 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 27E3942E006; Wed, 27 May 2026 15:33:24 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; cv=none; b=QYb6f7/3V4cdY5IRep4qA7diP8LzEX6dfZ1qDLcf6RvhVY5nRi+VYKHCf3SvRyvGQ61rft4qhy9WLlbL+kfWEZTcp79NvvSvZSXjk6wVCYeCVKfJaSE8UI7OgDQosfvu5Vc3FPHsrleW0w4ST8JXNS5+OHWkknPVb2Vizf7pzxo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; c=relaxed/simple; bh=h01IvEuQZ+K42AKMdxiewPanmZZ8zWWzxrsO2ouqJeY=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=I4E/0mk5H4vlEL3xpfDQElEItACFHBqxNpaH6UTqtLao3DmL37NJYYRp314G2ttVSJlogswAHUfhcrF0i+nAEjnTcXZVIL4x4w523LxN6R33hlrMPRN6DiqtTC9pVrfPaaf23Kt3kuTNIEGZJ5FeAwliGnu7eUY45HxgfnvJ5o4= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=NLxxE+5T; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="NLxxE+5T" Received: by smtp.kernel.org (Postfix) with ESMTPS id D664EC2BCF5; Wed, 27 May 2026 15:33:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1779896002; bh=h01IvEuQZ+K42AKMdxiewPanmZZ8zWWzxrsO2ouqJeY=; h=From:Date:Subject:References:In-Reply-To:To:Cc:Reply-To:From; b=NLxxE+5TXWyGmCUriYDo0nlcDjOg11eebRj5wA4VyIXO/DwcAyCiu/c6VM5TPj9Y+ ubHjrvSWgdj+dBSWWKty3gMmxXQALoE0Bjgs5F5tp4BiciDWuZ5EMShKg/TV3rVK3h AD4XdDoaoSwzej8g3WWBKxYKVVMfdtetinaU7f2fjoYwnxiOgc74gEvV6nrt7nw1Fm wL6UFXtO+1q0OwnKNf76b1WHozB6JZqrFlzibphhfc06XvZv8gaS00T/uFZNvQBs0n HIJ9H2ir7VYTw2Ao7ibzAAlh+HDgEQJ3bDO8EDFwLKXJoBHVjX2HwemGr4lk0Lp+xD oX9QbbpMMpfwQ== Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id CEE42CD5BD0; Wed, 27 May 2026 15:33:22 +0000 (UTC) From: Ackerley Tng via B4 Relay Date: Wed, 27 May 2026 08:33:19 -0700 Subject: [PATCH RFC 07/12] Documentation: KVM: Drop mention of kvm->lock in SRCU documentation Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260527-kvm-locking-docs-v1-7-4fe8b602ff47@google.com> References: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> In-Reply-To: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> To: Paolo Bonzini , Jonathan Corbet , Shuah Khan , Tianrui Zhao , Bibo Mao , Huacai Chen , WANG Xuerui , Sean Christopherson , Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , Fuad Tabba , vannapurve@google.com, x86@kernel.org, "H. Peter Anvin" Cc: kvm@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, loongarch@lists.linux.dev, Ackerley Tng X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1779896001; l=1115; i=ackerleytng@google.com; s=20260225; h=from:subject:message-id; bh=AfvnWtgsVpXIKXd9EvhdAVtlR2WiGKaxMZJotHAsjr8=; b=q6xZf/5/u1rdMaAEebXfbdUD15CwiaRJEQv8wy+OHzvYq94cMmo+p9Vjs5r6IZMkazcCQ+cOA vGzpCQxTs4EDZVCNaYIQXAThy7QIfLWsIT9Wzdwv9O1z6Mi7/54mSVg X-Developer-Key: i=ackerleytng@google.com; a=ed25519; pk=sAZDYXdm6Iz8FHitpHeFlCMXwabodTm7p8/3/8xUxuU= X-Endpoint-Received: by B4 Relay for ackerleytng@google.com/20260225 with auth_id=649 X-Original-From: Ackerley Tng Reply-To: ackerleytng@google.com From: Ackerley Tng The original comment says that synchronize_srcu(&kvm->srcu) is called inside critical sections for kvm->lock, vcpu->mutex and kvm->slots_lock. Drop mention of kvm->lock since this is no longer true. Signed-off-by: Ackerley Tng --- Documentation/virt/kvm/locking.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/lo= cking.rst index fc4537a7659a9..437dbfa0030b9 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -35,8 +35,8 @@ The acquisition orders for mutexes are as follows: For SRCU: =20 - ``synchronize_srcu(&kvm->srcu)`` is called inside critical sections - for kvm->lock, vcpu->mutex and kvm->slots_lock. These locks _cannot_ - be taken inside a kvm->srcu read-side critical section; that is, the + for vcpu->mutex and kvm->slots_lock. These locks _cannot_ be taken + inside a kvm->srcu read-side critical section; that is, the following is broken:: =20 srcu_read_lock(&kvm->srcu); --=20 2.54.0.823.g6e5bcc1fc9-goog From nobody Mon Jun 8 17:38:04 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id EED0843637C; Wed, 27 May 2026 15:33:23 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; cv=none; b=Zi3mfwwCPHjsXMqcsqhce40/JgV1JRCsSqEo6Yn402RlfWlfKTAb9qtLkjMV6BOr8JwIXD6lClC3CqH9/fmmfeOWSEMA7EXPrIULjwfu6CSBYKLVRmAjwkj7GXAhgQg4bDjfQs/Bmd8StRswKY4ZDpSFDxfLGoNk4Zc522Jqixo= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; c=relaxed/simple; bh=FM8Btc31o9TaR7EqiHYe618vKH3Wed7vGJFONaprfAI=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=hwanluBIJRRy5i3Yd77eGuqUnujUPvSe8OmFzCneuIupuvQxCEgK3aUJN95IXlyziUlXMsvssGbdHBjfnTH/xzeNhCZXvOSkqKV6lDbEf2S33usDw7pWHcWe8al8htUE5YhuNVjtxPY1iS+qXZ7xoe3zkA1KEJPCjvvls/KYi9A= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=cb3eTT31; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="cb3eTT31" Received: by smtp.kernel.org (Postfix) with ESMTPS id EBD7CC2BCFD; Wed, 27 May 2026 15:33:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1779896003; bh=FM8Btc31o9TaR7EqiHYe618vKH3Wed7vGJFONaprfAI=; h=From:Date:Subject:References:In-Reply-To:To:Cc:Reply-To:From; b=cb3eTT31zpz/nZHSvWpZi2G3lV7/PG8GuvpqDMnpCNLEzF4JhdDbcWYAJO9ca8LFT ry4HSmNDiuULx9TVCwNd6zcXgHUStIrqtHO9e60u2Zo51oXI59oyjN37n1I6NvSO9n LoPHBnpnJDUgkfHCNYc2Spk/35Vtda359hWUU7FP1iNUamiQU4cPcLtapxsotLmx6L tGc6WfI5Jimv9MumQBURdzex37j9pDrsYXmDzX1e8cMZ3vNTfA4TLYtncjWXtRb7si N5E8nkrFMiQczD73R6dPa24MkT2g2rYmePXLsJR73p8mTCsvaA4ljoHxWKdHpg4bNi UFuUiRfYb4nvw== Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id E0362CD6E41; Wed, 27 May 2026 15:33:22 +0000 (UTC) From: Ackerley Tng via B4 Relay Date: Wed, 27 May 2026 08:33:20 -0700 Subject: [PATCH RFC 08/12] Documentation: KVM: Add example for kvm->srcu in relation to mutex/lock Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260527-kvm-locking-docs-v1-8-4fe8b602ff47@google.com> References: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> In-Reply-To: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> To: Paolo Bonzini , Jonathan Corbet , Shuah Khan , Tianrui Zhao , Bibo Mao , Huacai Chen , WANG Xuerui , Sean Christopherson , Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , Fuad Tabba , vannapurve@google.com, x86@kernel.org, "H. Peter Anvin" Cc: kvm@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, loongarch@lists.linux.dev, Ackerley Tng X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1779896001; l=1342; i=ackerleytng@google.com; s=20260225; h=from:subject:message-id; bh=IP6j6+0n9i5F75dc/JoOxvmpXpcBcDIU8T67NgzHpII=; b=iws+wuZgc1sF7u5EbOCCby1bgdlSn8bsv5rBl1ZlOezqhQaAFAgrzNaaUQz9E7paxNd7e92ji Xp+yzef8HISCWLzKvTmZVzrBQVHC5Z7MppBAVO69X2btpkTIfWrqhfF X-Developer-Key: i=ackerleytng@google.com; a=ed25519; pk=sAZDYXdm6Iz8FHitpHeFlCMXwabodTm7p8/3/8xUxuU= X-Endpoint-Received: by B4 Relay for ackerleytng@google.com/20260225 with auth_id=649 X-Original-From: Ackerley Tng Reply-To: ackerleytng@google.com From: Ackerley Tng Add example of where vcpu->mutex and kvm->slots_lock are held while calling synchronize_srcu(&kvm->srcu) to concretely show where the synchronization primitives overlap. Signed-off-by: Ackerley Tng --- Documentation/virt/kvm/locking.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/lo= cking.rst index 437dbfa0030b9..f12664443e913 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -35,9 +35,12 @@ The acquisition orders for mutexes are as follows: For SRCU: =20 - ``synchronize_srcu(&kvm->srcu)`` is called inside critical sections - for vcpu->mutex and kvm->slots_lock. These locks _cannot_ be taken - inside a kvm->srcu read-side critical section; that is, the - following is broken:: + for vcpu->mutex and kvm->slots_lock. (For example, when there is a + ``KVM_REQ_APICV_UPDATE`` request, ``vcpu->mutex`` is held in + ``kvm_vcpu_ioctl()``, and then when the memslots get updated, + ``kvm->slots_lock`` is taken.) These locks _cannot_ be taken inside + a kvm->srcu read-side critical section; that is, the following is + broken:: =20 srcu_read_lock(&kvm->srcu); mutex_lock(&kvm->slots_lock); --=20 2.54.0.823.g6e5bcc1fc9-goog From nobody Mon Jun 8 17:38:04 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 0F4123EF0C2; Wed, 27 May 2026 15:33:24 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; cv=none; b=Jo5MHjVgzz2uoxAis2FZBtgVLYz/04852tKP4Ypw7YhDT5ZZY/joWBDyhiOetjNmpK9zRE1w4/6cVh8bmnHwxz5tl8bDaxG2fkWplSL2MVIWThVE8Bsy9UMzqMdmQ4UOaGpRtuWMsv0BKvwQgEMQsoNkVLK6PywbR2eUh96WrRM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; c=relaxed/simple; bh=++rXmaxiJyBzVjijE4IdxKxLGi/JxM1MIFEf3U+1KhI=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=ExB/ObrtI9409YtjszN3UFymlFi9d8rs+00MO1kCZ1baAzr8WXvp8hlfnnhWaExYxbQ3tG2f8VCCo1SmBFq42uhXT6GZu4+j2DDau1mXhV7sGnvGUgljR0CUGZtS3jjWTtoY8z8lCaJsn96MoELxNbsx/OUJd4Zr1D1tKeeo2Lw= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=ZRrigFsw; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="ZRrigFsw" Received: by smtp.kernel.org (Postfix) with ESMTPS id 094B1C2BD00; Wed, 27 May 2026 15:33:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1779896003; bh=++rXmaxiJyBzVjijE4IdxKxLGi/JxM1MIFEf3U+1KhI=; h=From:Date:Subject:References:In-Reply-To:To:Cc:Reply-To:From; b=ZRrigFswXsoi16AGLKt1zdl3PkZOJsWCyB9bS40NaeY7aQLXdzjm1FiUJ0lVTQfCe xZtV4V5jFIoVGzoYLCPhl8d/kGgUcOxEBP5zyo0OgPP8THNlquPK9RYNXH2JZthQld pZl2jYyMc5uPYa59hTAVGMIMfR7T62lFgwZETEa0MeLGtv+P7EKrby7fiMEHe6IyTV e0BYW+0wM77ZwDd7duHDmM3QR/59k370ZqOojZeDTV7KIMOdBLEekVzKCU9Hxtug/q oRof45g/X/bBsyEXlSqGYS0dWzTLUfWnT+Fk1R273ORWFLDxMA1gFX378eddMfnUHb zGzhSzOZLsCgQ== Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 01016CD6E45; Wed, 27 May 2026 15:33:23 +0000 (UTC) From: Ackerley Tng via B4 Relay Date: Wed, 27 May 2026 08:33:21 -0700 Subject: [PATCH RFC 09/12] Documentation: KVM: Document synchronization for managing guest faults Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260527-kvm-locking-docs-v1-9-4fe8b602ff47@google.com> References: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> In-Reply-To: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> To: Paolo Bonzini , Jonathan Corbet , Shuah Khan , Tianrui Zhao , Bibo Mao , Huacai Chen , WANG Xuerui , Sean Christopherson , Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , Fuad Tabba , vannapurve@google.com, x86@kernel.org, "H. Peter Anvin" Cc: kvm@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, loongarch@lists.linux.dev, Ackerley Tng X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1779896001; l=6122; i=ackerleytng@google.com; s=20260225; h=from:subject:message-id; bh=qtMOxyeP5ch21YYzClGkI6coJJOBcrx7UDfHl0oxiyE=; b=ZLCGPfSxzOWhzxer3lPOoW8Xf+IoErNOQmSifHUvrPQo82wBll8m7eGZttpVwVQqj7yjyti43 78hYb4H5CmGDNYj5SKX4oT3LEEtKjKf4ovfwqD7TgaDcawPtUY/OgDc X-Developer-Key: i=ackerleytng@google.com; a=ed25519; pk=sAZDYXdm6Iz8FHitpHeFlCMXwabodTm7p8/3/8xUxuU= X-Endpoint-Received: by B4 Relay for ackerleytng@google.com/20260225 with auth_id=649 X-Original-From: Ackerley Tng Reply-To: ackerleytng@google.com From: Ackerley Tng Document how synchronization is used while managing guest faults centrally so code comments can point users at a central place. Signed-off-by: Ackerley Tng --- Documentation/virt/kvm/locking.rst | 108 +++++++++++++++++++++++++++++++++= ++++ 1 file changed, 108 insertions(+) diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/lo= cking.rst index f12664443e913..0663ccfe0633d 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -339,3 +339,111 @@ time it will be set using the Dirty tracking mechanis= m described above. cpu_hotplug_lock is held, e.g. from cpufreq_boost_trigger_state(), and= many operations need to take cpu_hotplug_lock when loading a vendor module,= e.g. updating static calls. + +4. Synchronization while managing guest faults +---------------------------------------------- + +This section explains the intersection of these synchronization mechanisms: + +- ``kvm->srcu`` (for memslots) +- ``kvm->mmu_invalidate_*`` (pending invalidations) +- ``kvm->mn_*`` (synchronization for ``kvm->mmu_invalidate_*``) + +4.1 Overview +^^^^^^^^^^^^ + +KVM resolves guest page faults by translating the Guest Frame Number (GFN)= into +a Page Frame Number (PFN) via memslots and then populating its shadow page +tables with the resulting mapping. + +While handling the guest page fault, KVM must ensure a consistent view of = the +active memslots container, so KVM takes ``srcu_read_lock(&kvm->srcu);``. + +Guest page fault handling can race with some request from host userspace to +invalidate shadow page tables. These requests originate from a few places,= such +as + +1. MMU Notifiers: KVM registers callbacks with the kernel=E2=80=99s memory= management + subsystem to know when there are changes to mappings in the host usersp= ace + page tables. +2. Memslot Updates: The host userspace VMM, such as QEMU may use the + ``KVM_SET_USER_MEMORY_REGION`` ioctl to add, delete, or move a memslot.= KVM + must zap the affected shadow page tables to ensure the guest doesn't ac= cess + stale mappings. +3. Memory Attribute Changes: The ``KVM_SET_MEMORY_ATTRIBUTES`` ioctl allows + userspace to change attributes for a range of guest memory (e.g., setti= ng a + range as "private" for Confidential Computing). This also requires + invalidating existing shadow mappings. + +When such a race occurs, KVM optimistically allows the faulting logic to +proceed, but just before committing the fault, KVM will check for a pending +invalidation, and retry the fault process if there is a pending invalidati= on +affecting the GFN where the fault occurred. + +4.2 Tracking pending invalidations with ``kvm->mmu_invalidate*`` fields +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A "pending invalidation" is determined using a combination of + +- ``kvm->mmu_invalidate_in_progress`` +- ``kvm->mmu_invalidate_range_start`` and ``kvm->mmu_invalidate_range_end`` +- ``kvm->mmu_invalidate_seq`` + +``is_page_fault_stale()`` shows how the above fields are used to determine= if +the page fault is stale and requires a retry. + +To protect the above combination of fields, a lock is used, which is the +``kvm->mmu_lock``. + +4.2.1 Derived information vs pending invalidations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Generally, the result of any information derived from GFN aka page +attribute/page metadata lookups may race with invalidations. Here are some +examples of lookups: + +- ``host_pfn_mapping_level()`` uses memslot information to find the mapping + level of pages in host userspace page tables. If there's an invalidation= , the + pages that were mapped would no longer be mapped and hence the mapping l= evel + result would be stale. + +There are several ways to ensure valid results: + +- Check ``mmu_invalidate_retry_gfn()`` after grabbing the result, before + consuming it. In this case, ``mmu_lock`` doesn't need to be held during = the + lookup, but it does need to be held while checking the MMU notifier. KVM= 's + guest page fault handling uses this option. +- Hold ``mmu_lock`` AND ensure there is no in-progress MMU notifier invali= dation + event for the hva. This can be done by explicit checking the MMU notifie= r or + by ensuring that KVM already has a valid mapping that covers the + hva. ``kvm_mmu_recover_huge_pages()`` uses this option. + +4.3 Further optimization: ignoring invalidations if there is no matching m= emslot +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^= ^^^^^^ + +Invalidation is only really required when the invalidated memory range ove= rlaps +with some memslot. Without a matching memslot, the invalidation request co= uld +actually just be ignored. Hence, KVM only updates the ``kvm->mmu_invalidat= e_*`` +fields and takes ``kvm->mmu_lock`` if it finds a matching memslot. + +This creates another problem: if memslots are updated while there is an on= going +invalidation, then the updates to the fields and the lock would be imbalan= ced. + +4.4 Synchronization for invalidation lock/fields: ``kvm->mn_*`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To make sure the updates to the invalidation lock/fields are balanced, KVM= has a +further layer of synchronization. ``kvm_swap_active_memslots()`` enforces = that +changes to memslots are only committed once all pending invalidations are +complete. + +In other words, ``kvm->mn_*`` ensures the following does not happen: + +1. Some memslot existed, causing a pending invalidation request to be reco= rded + in the ``kvm->mmu_invalidate_*`` fields +2. Memslot got removed, so the invalidation request was never removed from= the + ``kvm->mmu_invalidate_*`` fields. + +In addition, ``kvm_swap_active_memslots()`` also enforces that changes to +memslots are complete before doing ``synchronize_srcu(&kvm->srcu)`` to mak= e sure +running readers of the old memslots container are done before freeing it. --=20 2.54.0.823.g6e5bcc1fc9-goog From nobody Mon Jun 8 17:38:04 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id DA7EE43636B; Wed, 27 May 2026 15:33:23 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896003; cv=none; b=doP5rFdUWsptRpfDUsMptXiKI8NudCsN1HLZUBZdDKSTVx4kSTTYksOOONzuxjbeRodKtXy/T0eLISEe2X5Pr7qW1J0LqgIJy5FdPBhYDFIojjAshEBioOGvpQdk/kkkovvjdSGPRcnUuxdMVPgdp3ccnW0qLFUYAZOBKCut/d0= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896003; c=relaxed/simple; bh=vV27adI3mRPVfr/4KYQaQlitiyDAtNqd/scHlo4erV0=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=cuv/UHelnuqkSLtyz5m8TnZQKXnU5kBb5Vo/s8aHIivuxrh2DfPNjAMG6B+A34DYETld50nM2KAtsJSdHJQSFINYNCI4WoCQpKv1tfBDjlpw9mbA0sku7XCXgUzSrXIe6lD89wse7HotqW5RIYXpHdpeIZhh76uGH/LFWNQbf4U= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=QoxBHs0I; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="QoxBHs0I" Received: by smtp.kernel.org (Postfix) with ESMTPS id 1B40DC2BCC9; Wed, 27 May 2026 15:33:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1779896003; bh=vV27adI3mRPVfr/4KYQaQlitiyDAtNqd/scHlo4erV0=; h=From:Date:Subject:References:In-Reply-To:To:Cc:Reply-To:From; b=QoxBHs0I37EAn5nmfw28S+JbCmuHQCWJ+Trqa0V+r5G43t3SX/+IjftyWzp+5EWzH 1yE5K0yZaoAP38uxNdtsy6zbDNJ1zFP0iOscUFxy/t0Uz1nV6GWydGMKUs1xwI7lA4 IQQ1YYlAJDWi3JILliRZ2ge63nXRJknnH6/aN/F7UzfQZYAJhI/NjG/AZOYuuJN661 iDDwExYioGUoePVC+fdoadJlS0xZbGhyZQ8E+u6qQ12zFW0r+irKQlbSGTnMfho+tO OmrlMiLziHdh3A+8owGmvPmw6kqtsomkUAlFDXvTAb1Xfxxt7X5xn3QuJBujcY08Ea 54GGiEcgsMPLA== Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 132AFCD5BD0; Wed, 27 May 2026 15:33:23 +0000 (UTC) From: Ackerley Tng via B4 Relay Date: Wed, 27 May 2026 08:33:22 -0700 Subject: [PATCH RFC 10/12] KVM: guest_memfd: Clarify comment about gmem.file vs kvm->srcu Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260527-kvm-locking-docs-v1-10-4fe8b602ff47@google.com> References: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> In-Reply-To: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> To: Paolo Bonzini , Jonathan Corbet , Shuah Khan , Tianrui Zhao , Bibo Mao , Huacai Chen , WANG Xuerui , Sean Christopherson , Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , Fuad Tabba , vannapurve@google.com, x86@kernel.org, "H. Peter Anvin" Cc: kvm@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, loongarch@lists.linux.dev, Ackerley Tng X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1779896001; l=1303; i=ackerleytng@google.com; s=20260225; h=from:subject:message-id; bh=Tom9j4Egg9w53w5LFUq+AuZPef+PZPDtSajFqVBtT2Y=; b=zmWHHdOBn2VUHo/3MFGM+UFpeHWLnLuk5bbX+cVcR6fbgTn96QkVjabkLihMX7tye0SnmS6Tj 4yHcgDc5PfsADjhgoYLEkOnUJTwyvLLyJX53hXSzWi5YZ0QcGrBfAyn X-Developer-Key: i=ackerleytng@google.com; a=ed25519; pk=sAZDYXdm6Iz8FHitpHeFlCMXwabodTm7p8/3/8xUxuU= X-Endpoint-Received: by B4 Relay for ackerleytng@google.com/20260225 with auth_id=649 X-Original-From: Ackerley Tng Reply-To: ackerleytng@google.com From: Ackerley Tng Clarify the existing comment about synchronize_srcu() and kvm_gmem_get_pfn() to provide further context. Explain which synchronize_srcu() prevents races with how kvm_gmem_get_pfn() is used. Also point reader to documentation for better understanding. Signed-off-by: Ackerley Tng --- virt/kvm/guest_memfd.c | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/virt/kvm/guest_memfd.c b/virt/kvm/guest_memfd.c index 69c9d6d546b28..f2218db0af980 100644 --- a/virt/kvm/guest_memfd.c +++ b/virt/kvm/guest_memfd.c @@ -711,8 +711,13 @@ static void __kvm_gmem_unbind(struct kvm_memory_slot *= slot, struct gmem_file *f) xa_store_range(&f->bindings, start, end - 1, NULL, GFP_KERNEL); =20 /* - * synchronize_srcu(&kvm->srcu) ensured that kvm_gmem_get_pfn() - * cannot see this memslot. + * This is called when memslots are updated, after the old + * memslot container is no longer in + * use. synchronize_srcu(&kvm->srcu) was called there, so + * kvm_gmem_get_pfn() from KVM's guest fault handling cannot + * see this memslot. See Documentation/virt/kvm/locking.rst + * for more information about kvm->srcu and the memslots + * container. */ WRITE_ONCE(slot->gmem.file, NULL); } --=20 2.54.0.823.g6e5bcc1fc9-goog From nobody Mon Jun 8 17:38:04 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 627DF3ED12D; Wed, 27 May 2026 15:33:25 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896005; cv=none; b=sjn7V2i927jUk9K+lRcwLEx+7iHkKgc86pcgGGX97LFSAmkhv8XtijYODMbmqz+gRXNm1SkPoiIwvZBiGYgPyuP+M0WKFv0h+12ZPps6/o5ZGT5gmCt/jZarlI/xM3wAZVfKriF8bopEwtu76/9A3JcfeUe9x4RnUoEJpV6wMvc= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896005; c=relaxed/simple; bh=ZO5W64CtWNP+5gC9BrgLSE8kNQUV1QQDwxqRTcg7pnw=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=DACHGu6I9lWbVkswjsLPal1LGViydPWatJ6mH9EEzlfYz/2niUQTc64SUYKCD3cRqMJlkdTxg0cy8TcB1FCoPyo6T/SNuebA608ZOcIawUtyQElSHWxrw8kmHmbbPvkfvZIf1aJIfzWkjBTa6N/i5QcKIeQlKFYAkKP9XREYQMo= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=QIUu3fEi; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="QIUu3fEi" Received: by smtp.kernel.org (Postfix) with ESMTPS id 2EA7DC2BCB3; Wed, 27 May 2026 15:33:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1779896003; bh=ZO5W64CtWNP+5gC9BrgLSE8kNQUV1QQDwxqRTcg7pnw=; h=From:Date:Subject:References:In-Reply-To:To:Cc:Reply-To:From; b=QIUu3fEiAgxP9/bkAL0f5vClmUKDbY9O4nToSGoBgad7SmS656K4Tc8UiVM3tletV 7XJDLb4H2Q49LXECOgUHe3hrzAU4MmOOVZvKGYT34FtMP+P7F5sc+6tyOhruAkBRMv axmGyOV89V26ujTC20XVoRhiuPVgQxqdEYOmgrP8fapgHLqDQffjT8c0vQ4l8zWEUv dNTXYEieRlshzzz4tjqxAYAP7AVCGZPzo8Zn1aGTwJRX6+fcRcszCuzlfZnbS+LkV7 0mZROqmVLAHG0DBIMvyV64GR8NqO0Ux/VZ6PxyH85XSoKjuez0f9qyQvdIvusIRlkS 3Zj5jRRJbhzPA== Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 26D4DCD6E45; Wed, 27 May 2026 15:33:23 +0000 (UTC) From: Ackerley Tng via B4 Relay Date: Wed, 27 May 2026 08:33:23 -0700 Subject: [PATCH RFC 11/12] KVM: mmu: Point users of host_pfn_mapping_level() to docs Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260527-kvm-locking-docs-v1-11-4fe8b602ff47@google.com> References: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> In-Reply-To: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> To: Paolo Bonzini , Jonathan Corbet , Shuah Khan , Tianrui Zhao , Bibo Mao , Huacai Chen , WANG Xuerui , Sean Christopherson , Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , Fuad Tabba , vannapurve@google.com, x86@kernel.org, "H. Peter Anvin" Cc: kvm@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, loongarch@lists.linux.dev, Ackerley Tng X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1779896001; l=4206; i=ackerleytng@google.com; s=20260225; h=from:subject:message-id; bh=1Iv7rmsthjHBhqlZuqMTaGdIcDmY7dzZBn2M3n/QhfA=; b=DbFncF6doMBB+aSot4N9pP3MjdxICCeHux2pefhL0l/IYTSzt+vFHwnY3udE0SyelBPn1PfAQ H4IwkJf86J8D18K8SCuU30i5QSn926OUxaY1cKuJTR+oj3QTWScfu5d X-Developer-Key: i=ackerleytng@google.com; a=ed25519; pk=sAZDYXdm6Iz8FHitpHeFlCMXwabodTm7p8/3/8xUxuU= X-Endpoint-Received: by B4 Relay for ackerleytng@google.com/20260225 with auth_id=649 X-Original-From: Ackerley Tng Reply-To: ackerleytng@google.com From: Ackerley Tng After consolidating documentation for host_pfn_mapping_level() in Documentation/virt/kvm/locking.rst, point users of function to docs. Signed-off-by: Ackerley Tng --- arch/loongarch/kvm/mmu.c | 24 ++++-------------------- arch/x86/kvm/mmu/mmu.c | 24 ++++-------------------- 2 files changed, 8 insertions(+), 40 deletions(-) diff --git a/arch/loongarch/kvm/mmu.c b/arch/loongarch/kvm/mmu.c index a7fa458e33605..0313901171a2e 100644 --- a/arch/loongarch/kvm/mmu.c +++ b/arch/loongarch/kvm/mmu.c @@ -641,27 +641,11 @@ static bool fault_supports_huge_mapping(struct kvm_me= mory_slot *memslot, /* * Lookup the mapping level for @gfn in the current mm. * - * WARNING! Use of host_pfn_mapping_level() requires the caller and the e= nd - * consumer to be tied into KVM's handlers for MMU notifier events! + * WARNING! This derives information from the current state of memslots a= nd + * page mappings and may race with invalidations. * - * There are several ways to safely use this helper: - * - * - Check mmu_invalidate_retry_gfn() after grabbing the mapping level, be= fore - * consuming it. In this case, mmu_lock doesn't need to be held during = the - * lookup, but it does need to be held while checking the MMU notifier. - * - * - Hold mmu_lock AND ensure there is no in-progress MMU notifier invalid= ation - * event for the hva. This can be done by explicit checking the MMU not= ifier - * or by ensuring that KVM already has a valid mapping that covers the h= va. - * - * - Do not use the result to install new mappings, e.g. use the host mapp= ing - * level only to decide whether or not to zap an entry. In this case, i= t's - * not required to hold mmu_lock (though it's highly likely the caller w= ill - * want to hold mmu_lock anyways, e.g. to modify SPTEs). - * - * Note! The lookup can still race with modifications to host page tables= , but - * the above "rules" ensure KVM will not _consume_ the result of the walk = if a - * race with the primary MMU occurs. + * See Documentation/virt/kvm/locking.rst to understand how to consuming t= he + * result of this lookup safely. */ static int host_pfn_mapping_level(struct kvm *kvm, gfn_t gfn, const struct kvm_memory_slot *slot) diff --git a/arch/x86/kvm/mmu/mmu.c b/arch/x86/kvm/mmu/mmu.c index f8aa7eda661ee..20cdcdd20e78d 100644 --- a/arch/x86/kvm/mmu/mmu.c +++ b/arch/x86/kvm/mmu/mmu.c @@ -3214,27 +3214,11 @@ static void direct_pte_prefetch(struct kvm_vcpu *vc= pu, u64 *sptep) /* * Lookup the mapping level for @gfn in the current mm. * - * WARNING! Use of host_pfn_mapping_level() requires the caller and the e= nd - * consumer to be tied into KVM's handlers for MMU notifier events! + * WARNING! This derives information from the current state of memslots a= nd + * page mappings and may race with invalidations. * - * There are several ways to safely use this helper: - * - * - Check mmu_invalidate_retry_gfn() after grabbing the mapping level, be= fore - * consuming it. In this case, mmu_lock doesn't need to be held during = the - * lookup, but it does need to be held while checking the MMU notifier. - * - * - Hold mmu_lock AND ensure there is no in-progress MMU notifier invalid= ation - * event for the hva. This can be done by explicit checking the MMU not= ifier - * or by ensuring that KVM already has a valid mapping that covers the h= va. - * - * - Do not use the result to install new mappings, e.g. use the host mapp= ing - * level only to decide whether or not to zap an entry. In this case, i= t's - * not required to hold mmu_lock (though it's highly likely the caller w= ill - * want to hold mmu_lock anyways, e.g. to modify SPTEs). - * - * Note! The lookup can still race with modifications to host page tables= , but - * the above "rules" ensure KVM will not _consume_ the result of the walk = if a - * race with the primary MMU occurs. + * See Documentation/virt/kvm/locking.rst to understand how to consuming t= he + * result of this lookup safely. */ static int host_pfn_mapping_level(struct kvm *kvm, gfn_t gfn, const struct kvm_memory_slot *slot) --=20 2.54.0.823.g6e5bcc1fc9-goog From nobody Mon Jun 8 17:38:04 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 14F3C3D3D16; Wed, 27 May 2026 15:33:24 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; cv=none; b=QNhrG1KwbdLvLgk4DC3PTtYtg5Yy57ZM4++vgXuAIZ+dGB7/70QDTWkFG0x4WKRTGuYNECBydLP4FCfy8tJwSt5ewzwNcgVorX6J+QJN0A2TIcj8HAicXM63ziNMYywpuHWEQbchBI41HYTxknSGELV65mRgQLaecNeLUMwA94g= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1779896004; c=relaxed/simple; bh=SDxYegV3dg2hqetMhwdqeXXQOxrUizjq1F4c00wAdYo=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=mfTLjbiIpWRcbYR1Y8H3RdkiuYbjp2IcgzzXKMG8NXwzUsJqmxn4qjgOpnB+56tveIwKd5hmbEm5O3BDuYxTgTA2SWKvNSUH4aPmRnsgXrUAF9WzhjbW2KV9ET5SHJCRUT77D+83G2GkEncU5SKTssbkIeRvP5ELeVEirnGZQ3E= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=EfETLX8P; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="EfETLX8P" Received: by smtp.kernel.org (Postfix) with ESMTPS id 3F083C2BCB4; Wed, 27 May 2026 15:33:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1779896003; bh=SDxYegV3dg2hqetMhwdqeXXQOxrUizjq1F4c00wAdYo=; h=From:Date:Subject:References:In-Reply-To:To:Cc:Reply-To:From; b=EfETLX8PWPzNlXwhunKu2XOnMLme4YYCL6BQ7GyLGzlBVkXiHJ5p+CPHXS4Vs2/Vt e0Ea2Fn9zVa/EHLEpmzVQx4lT/7PLUzrW3wg+XlBzml/BEA0zfmc8zP7IwimsC0kZa zM0afIiLEyTXyl//yByWhVt4N0J3/624sMNnKQCCt+isw8BBRYsjajIKG52j5wKlYE GlxmP2Pz7m9NuGtzmev9SHLjRx5YBN2eN3GI7uGp1pqH6skHwk06FRD+i3ifLFi0ZS fuTBr+DSl5UDBs+g0Cm57fvpJAG1Tey44suE2iw8miMzFN0lou9WSnAAbZHsKWrHb1 MPhIwNSaQBmlA== Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 36B67CD4F54; Wed, 27 May 2026 15:33:23 +0000 (UTC) From: Ackerley Tng via B4 Relay Date: Wed, 27 May 2026 08:33:24 -0700 Subject: [PATCH RFC 12/12] Documentation: KVM: Focus acquisition order section on preventing deadlocks Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260527-kvm-locking-docs-v1-12-4fe8b602ff47@google.com> References: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> In-Reply-To: <20260527-kvm-locking-docs-v1-0-4fe8b602ff47@google.com> To: Paolo Bonzini , Jonathan Corbet , Shuah Khan , Tianrui Zhao , Bibo Mao , Huacai Chen , WANG Xuerui , Sean Christopherson , Thomas Gleixner , Ingo Molnar , Borislav Petkov , Dave Hansen , Fuad Tabba , vannapurve@google.com, x86@kernel.org, "H. Peter Anvin" Cc: kvm@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, loongarch@lists.linux.dev, Ackerley Tng X-Mailer: b4 0.14.3 X-Developer-Signature: v=1; a=ed25519-sha256; t=1779896001; l=1268; i=ackerleytng@google.com; s=20260225; h=from:subject:message-id; bh=AsaYP57e05UmB20wkvz2ac8XwGdrnAvpcLv6/4UIzSY=; b=/yniIvnWn4q3kTWgqqaHndF4zOmwJDCk3stxZhB8gkrHCBDyaGRJ5dgMjaI2FXpf3UqwGtqcK qwfmNRwB7dXCwu4GyjoIDe3TPOjN73gTHFFrxKkm4DEZmg1MiFAmPWK X-Developer-Key: i=ackerleytng@google.com; a=ed25519; pk=sAZDYXdm6Iz8FHitpHeFlCMXwabodTm7p8/3/8xUxuU= X-Endpoint-Received: by B4 Relay for ackerleytng@google.com/20260225 with auth_id=649 X-Original-From: Ackerley Tng Reply-To: ackerleytng@google.com From: Ackerley Tng Now that the first sentence is already described in more detail in the new section on synchronization while managing guest faults, drop the first sentence. Signed-off-by: Ackerley Tng --- Documentation/virt/kvm/locking.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/Documentation/virt/kvm/locking.rst b/Documentation/virt/kvm/lo= cking.rst index 0663ccfe0633d..f26ea3acd0b70 100644 --- a/Documentation/virt/kvm/locking.rst +++ b/Documentation/virt/kvm/locking.rst @@ -26,11 +26,9 @@ The acquisition orders for mutexes are as follows: =20 - vcpu->mutex is taken outside kvm->slots_lock and kvm->slots_arch_lock =20 -- kvm->mn_active_invalidate_count ensures that pairs of - invalidate_range_start() and invalidate_range_end() callbacks - use the same memslots array. kvm->slots_lock and kvm->slots_arch_lock - are taken on the waiting side when modifying memslots, so MMU notifiers - must not take either kvm->slots_lock or kvm->slots_arch_lock. +- kvm->slots_lock and kvm->slots_arch_lock are taken on the waiting side w= hen + modifying memslots, so MMU notifiers must not take either kvm->slots_loc= k or + kvm->slots_arch_lock. =20 For SRCU: =20 --=20 2.54.0.823.g6e5bcc1fc9-goog