[RFC PATCH 7/7] Documentation: arm64: Describe the support and expectations for PBHA

[James Morse]

PBHA isn't defined by the Arm CPU architecture, so may have surprising
side-effects.

Document what is, and what is not supported. List the arch code's
expectations regarding how PBHA behaves.

Signed-off-by: James Morse <james.morse at arm.com>
---
 Documentation/arm64/index.rst |  1 +
 Documentation/arm64/pbha.rst  | 86 +++++++++++++++++++++++++++++++++++
 2 files changed, 87 insertions(+)
 create mode 100644 Documentation/arm64/pbha.rst

diff --git a/Documentation/arm64/index.rst b/Documentation/arm64/index.rst
index 4f840bac083e..88fdfda86632 100644
--- a/Documentation/arm64/index.rst
+++ b/Documentation/arm64/index.rst
@@ -18,6 +18,7 @@ ARM64 Architecture
     legacy_instructions
     memory
     memory-tagging-extension
+    pbha
     perf
     pointer-authentication
     silicon-errata
diff --git a/Documentation/arm64/pbha.rst b/Documentation/arm64/pbha.rst
new file mode 100644
index 000000000000..0ba50a0df05f
--- /dev/null
+++ b/Documentation/arm64/pbha.rst
@@ -0,0 +1,86 @@
+=======================================================
+Page Based Hardware Attribute support for AArch64 Linux
+=======================================================
+
+Page Based Hardware Attributes (PBHA) allow the OS to trigger IMPLEMENTATION
+DEFINED behaviour associated with a memory access. For example, this may be
+taken as a hint to a System Cache whether it should cache the location that
+has been accessed.
+
+PBHA consists of four bits in the leaf page table entries for a virtual
+address, that are sent with any memory access via that virtual address.
+
+IMPLEMENTATION DEFINED behaviour is not specified by the arm-arm, meaning
+it varies between SoCs. There may be unexpected side effects when PBHA
+bits are used or combined.
+For example, a PBHA bit may be taken as a hint to the Memory Controller that
+it should encrypt/decrypt the memory in DRAM. If the CPU has multiple virtual
+aliases of the address, accesses that are made without this PBHA bit set may
+cause corruption.
+
+
+Use by virtual machines using KVM
+---------------------------------
+
+KVM allows an OS in a virtual machine to configure its own page tables. A
+virtual machine can also configure PBHA bits in its page tables. To prevent
+side effects that could affect the hypervisor, KVM will only allow
+combinations of PBHA bits that only affect performance. Values that cause
+changes to the data are forbidden as the Hypervisor and VMM have aliases of
+the guest memory, and may swap it to/from disk.
+
+The list of bits to allow is built from the firmware list of PBHA bit
+combinations that only affect performance. Because the guest can choose
+not to set all the bits in a value, (e.g. allowing 5 implicitly allows 1
+and 4), the values supported may differ between a host and guest.
+
+PBHA is only supported for a guest if KVM supports the mechanism the CPU uses
+to combine the values from stage1 and stage2 translation. The mechanism is not
+advertised, so which mechanism each CPU uses must also be known by the kernel.
+
+
+Use by device drivers
+---------------------
+
+Device drivers should discover the PBHA value to use for a mapping from the
+device's firmware description as these will vary between SoCs. If the value
+is also listed by firmware as only affecting performance, it can be added to
+the pgprot with pgprot_pbha().
+
+Values that require all other aliases to be removed are not supported.
+
+
+Linux's expectations around PBHA
+--------------------------------
+
+'IMPLEMENTATION DEFINED' describes a huge range of possible behaviours.
+Linux expects PBHA to behave in the same way as the read/write allocate hints
+for a memory type. Below is an incomplete list of expectations:
+
+ * PBHA values have the same meaning for all CPUs in the SoC.
+ * Use of the PBHA value does not cause mismatched type, shareability or
+   cacheability, it does not take precedence over the stage2 attributes, or
+   HCR_EL2 controls.
+ * If a PBHA value requires all other aliases to be removed, higher exception
+   levels do not have a concurrent alias. (This includes Secure World).
+ * Break before make is sufficient when changing the PBHA value.
+ * PBHA values used by a page can be changed independently without further side
+   effects.
+ * Save/restoring the page contents via a PBHA=0 mapping does not corrupt the
+   values once a non-zero PBHA mapping is re-created.
+ * The hypervisor may clean+invalidate to the PoC via a PBHA=0 mapping prior to
+   save/restore to cleanup mismatched attributes. This does not corrupt the
+   values after save/restore once a non-zero PBHA mapping is re-created.
+ * Cache maintenance via a PBHA=0 mapping to prevent stale data being visible
+   when mismatched attributes occur is sufficient even if the subsequent
+   mapping has a non-zero PBHA value.
+ * The OS/hypervisor can clean-up a page by removing all non-zero PBHA mappings,
+   then writing new data via PBHA=0 mapping of the same type, shareability and
+   cacheability. After this, only the new data is visible for data accesses.
+ * For instruction-fetch, the same maintenance as would be performed against a
+   PBHA=0 page is sufficient. (which with DIC+IDC, may be none at all).
+ * The behaviour enabled by PBHA should not depend on the size of the access, or
+   whether other SoC hardware under the control of the OS is enabled and
+   configured.
+ * EL2 is able to at least force stage1 PBHA bits to zero.
+
-- 
2.30.2