[RFC PATCH v6 26/35] KVM: arm64: Add comment to explain how trapped SPE registers are handled

[Alexandru Elisei]

The SPE buffer registers are trapped, while the sampling control registers
are directly accessed by the guest. The in-memory value of PMBSR_EL1 can be
modified by both the guest, following a direct write, and the hardware,
following a hardware maintenence interrupt. The in-memory value is never
written to the hardware.

The rest of the buffer register are written to the hardware at different
times in the VCPU run loop.

Add a comment explaining all of this.

Signed-off-by: Alexandru Elisei <alexandru.elisei at arm.com>
---
 arch/arm64/kvm/spe.c | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/arch/arm64/kvm/spe.c b/arch/arm64/kvm/spe.c
index 6e8e0068e7e4..b138b564413b 100644
--- a/arch/arm64/kvm/spe.c
+++ b/arch/arm64/kvm/spe.c
@@ -126,6 +126,46 @@ u8 kvm_spe_get_pmsver_limit(void)
 	return min(pmsver, ID_AA64DFR0_EL1_PMSVer_V1P5);
 }
 
+/*
+ * Note on register handling:
+ *
+ * - Only the buffer registers (this includes PMBIDR_EL1) and PMSIDR_EL1 are
+ *   trapped, the rest of the registers the guest can access directly.
+ *
+ *  - PMBIDR_EL1 is trapped so KVM can advertise to the guest the maximum buffer
+ *  size set by userspace.
+ *
+ *  - PMSIDR_EL1 is trapped to hide the presence of features which the VM does
+ *  not have, but the hardware implements.
+ *
+ * - PMBLIMITR_EL1:
+ *   * Guest value is written to hardware only when
+ *   kvm_spe_profiling_buffer_enabled() is true. This is done after KVM enables
+ *   stage 2.
+ *   * KVM always disables the buffer (PMBLIMITR_EL1.E=0) when exiting the
+ *   guest. This is done before stage 2 is disabled.
+ *   * In-memory value of the register is updated following a direct write to
+ *   the register by the guest.
+ *
+ * - PMBSR_EL1:
+ *   * In-memory value of the register is never written to hardware.
+ *   * The hardware value of the register is cleared on guest exit if KVM
+ *   detects that the service bit is set.
+ *   * In-memory value of the register is updated in the following situations:
+ *     - Following a direct write to the register by the guest.
+ *     - When the buffer has been misprogrammed.
+ *     - When the hardware asserts the management event interrupt.
+ *
+ * - PMBPTR_EL1:
+ *   * Guest value is written to hardware:
+ *     - Before entering the guest, if kvm_spe_profiling_buffer_enabled() is
+ *     true.
+ *   * In-memory value of the register is updated:
+ *     - Following a direct write to the register by the guest.
+ *     - On each exit from the guest, if kvm_spe_profiling_buffer_enabled() was
+ *     true when the guest was entered.
+ */
+
 /* Implements OtherSPEManagementEvent() from ARM DDI0487L.b */
 static void kvm_spe_inject_other_event(struct kvm_vcpu *vcpu, u8 bsc)
 {
-- 
2.51.2