From: Quentin Perret <qperret@google.com>
Date: Wed, 16 Apr 2025 15:26:42 +0000 (+0000)
Subject: KVM: arm64: Fix pKVM page-tracking comments
X-Git-Tag: v6.16-rc1~129^2~2^2~6^2~11^2~5
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=ba637018ca67224fa21dc2212cb4457b357a5455;p=thirdparty%2Flinux.git

KVM: arm64: Fix pKVM page-tracking comments

Most of the comments relating to pKVM page-tracking in nvhe/memory.h are
now either slightly outdated or outright wrong. Fix the comments.

Signed-off-by: Quentin Perret <qperret@google.com>
Link: https://lore.kernel.org/r/20250416152648.2982950-3-qperret@google.com
Signed-off-by: Marc Zyngier <maz@kernel.org>
---

diff --git a/arch/arm64/kvm/hyp/include/nvhe/memory.h b/arch/arm64/kvm/hyp/include/nvhe/memory.h
index 34233d5860607..178028172c0b3 100644
--- a/arch/arm64/kvm/hyp/include/nvhe/memory.h
+++ b/arch/arm64/kvm/hyp/include/nvhe/memory.h
@@ -8,20 +8,29 @@
 #include <linux/types.h>
 
 /*
- * Bits 0-1 are reserved to track the memory ownership state of each page:
- *   00: The page is owned exclusively by the page-table owner.
- *   01: The page is owned by the page-table owner, but is shared
- *       with another entity.
- *   10: The page is shared with, but not owned by the page-table owner.
- *   11: Reserved for future use (lending).
+ * Bits 0-1 are used to encode the memory ownership state of each page from the
+ * point of view of a pKVM "component" (host, hyp, guest, ... see enum
+ * pkvm_component_id):
+ *   00: The page is owned and exclusively accessible by the component;
+ *   01: The page is owned and accessible by the component, but is also
+ *       accessible by another component;
+ *   10: The page is accessible but not owned by the component;
+ * The storage of this state depends on the component: either in the
+ * hyp_vmemmap for the host state or in PTE software bits for the hypervisor
+ * and guests.
  */
 enum pkvm_page_state {
 	PKVM_PAGE_OWNED			= 0ULL,
 	PKVM_PAGE_SHARED_OWNED		= BIT(0),
 	PKVM_PAGE_SHARED_BORROWED	= BIT(1),
-	__PKVM_PAGE_RESERVED		= BIT(0) | BIT(1),
-
-	/* Meta-states which aren't encoded directly in the PTE's SW bits */
+	__PKVM_PAGE_RESERVED            = BIT(0) | BIT(1),
+
+	/*
+	 * 'Meta-states' are not stored directly in PTE SW bits for hyp and
+	 * guest states, but inferred from the context (e.g. invalid PTE
+	 * entries). For the host, meta-states are stored directly in the
+	 * struct hyp_page.
+	 */
 	PKVM_NOPAGE			= BIT(2),
 };
 #define PKVM_PAGE_META_STATES_MASK	(~__PKVM_PAGE_RESERVED)
@@ -44,7 +53,7 @@ struct hyp_page {
 	u16 refcount;
 	u8 order;
 
-	/* Host (non-meta) state. Guarded by the host stage-2 lock. */
+	/* Host state. Guarded by the host stage-2 lock. */
 	enum pkvm_page_state host_state : 8;
 
 	u32 host_share_guest_count;