[PATCH] arm64: mpam: Document when to set arm64.nompam

[Fuad Tabba <fuad.tabba@linux.dev>]

arm64.nompam skips the MPAM2_EL2 and MPAMHCR_EL2 writes in
finalise_el2_state and leaves the ARM64_MPAM cpucap unset. Where EL3
firmware has enabled MPAM, the EL2 trap controls are left unwritten, at
reset values that are UNKNOWN, and KVM still hides MPAM from the guest
but no longer enables the traps that stop a guest from using it. The
kernel cannot restore the writes: they trap to EL3 on the firmware the
option exists for, and MPAM3_EL3.TRAPLOWER cannot be read below EL3.

Say so in mpam.rst, and add the rule and a pointer to the
kernel-parameters entry.

No functional change intended.

Suggested-by: Ben Horgan <ben.horgan@arm.com>
Link: https://lore.kernel.org/all/CA+EHjTxeWxZiuSmnKLGLxTBXP4oJT7-LuffbPAyCSZZ5TW=5Ew@mail.gmail.com/
Signed-off-by: Fuad Tabba <fuad.tabba@linux.dev>
---
 Documentation/admin-guide/kernel-parameters.txt |  3 ++-
 Documentation/arch/arm64/mpam.rst               | 17 +++++++++++++++++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 68647ff4bdd24..e6d543de3cde5 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -575,7 +575,8 @@ Kernel parameters
 			Set instructions support
 
 	arm64.nompam	[ARM64] Unconditionally disable Memory Partitioning And
-			Monitoring support
+			Monitoring support. Only for a machine that does not
+			boot without it. See Documentation/arch/arm64/mpam.rst
 
 	arm64.nomte	[ARM64] Unconditionally disable Memory Tagging Extension
 			support
diff --git a/Documentation/arch/arm64/mpam.rst b/Documentation/arch/arm64/mpam.rst
index 67fe515ed501c..67c8a95391171 100644
--- a/Documentation/arch/arm64/mpam.rst
+++ b/Documentation/arch/arm64/mpam.rst
@@ -87,6 +87,23 @@ The supported features are:
   MBWU monitors can be exposed to the user after support for more monitoring
   scopes is added to resctrl.
 
+arm64.nompam
+============
+Firmware must enable MPAM at the highest implemented exception level and
+leave the MPAM system registers accessible to the kernel, or trap the
+accesses and emulate MPAM as disabled. Where it does neither, the CPUs
+still advertise MPAM in the ID registers, the first kernel access to an
+MPAM register traps to EL3, and the boot fails. ``arm64.nompam`` exists
+for that firmware: it makes the kernel treat the CPUs as not implementing
+MPAM, so no MPAM system register is accessed. Set it only on a machine
+that does not boot without it.
+
+It is not a way to turn MPAM off. On a system whose firmware has enabled
+MPAM at EL3, the option leaves the trap controls in MPAM2_EL2 and
+MPAMHCR_EL2 unwritten, and their reset values are UNKNOWN. KVM still
+hides MPAM from guests but no longer enables the traps that stop a guest
+from using it, so a guest may be able to choose its own PARTID and PMG.
+
 Reporting Bugs
 ==============
 If you are not seeing the counters or controls you expect please share the
-- 
2.39.5