Move Smmpm and Smnpm to machine and Ssnpm to machine/supervisor/hypervisor chapter (#2494)

* Move Smnpm to machine chapter

* Move Smmpm to Machine chapter

* Move Ssnpm to supervisor chapter

* Move Ssnpm additions to H to hypervisor chapter

* Clean up the movement of extension details

Author: ved-rivos

src/hypervisor.adoc

@@ -262,6 +262,24 @@ greater protection against software bugs, while still retaining access
 to a virtual machine’s memory.
 ====
 
+When Ssnpm extension is implemented, the `HUPMM` field enables or disables
+pointer masking (see <<Zpm>>) for `HLV.\*` and `HSV.*` instructions in U-mode,
+according to the values in <<henvcfg-pmm-values>>, when their explicit memory
+access is performed as though in VU-mode. In HS- and M-modes, pointer masking
+for these instructions is enabled or disabled by `senvcfg.PMM`, when their
+explicit memory access is performed as though in VU-mode. Setting `henvcfg.PMM`
+enables or disables pointer masking for `HLV.\*` and `HSV.*` when their
+explicit memory access is performed as though in VS-mode. When the Ssnpm
+extension is not implemented, the `HUPMM` field is read-only zero. The `HUPMM`
+field is read-only zero for RV32.
+
+[NOTE]
+====
+The hypervisor should copy the value written to `senvcfg.PMM` by the guest to
+the `hstatus.HUPMM` field prior to invoking `HLV.\*` or `HSV.*` instructions in
+U-mode.
+====
+
 The SPV bit (Supervisor Previous Virtualization mode) is written by the
 implementation whenever a trap is taken into HS-mode. Just as the SPP
 bit in `sstatus` is set to the (nominal) privilege mode at the time of
@@ -689,7 +707,22 @@ The definition of the CBZE field is furnished by the Zicboz extension.
 
 The definitions of the CBCFE and CBIE fields are furnished by the Zicbom extension.
 
-The definition of the PMM field is furnished by the Ssnpm extension.
+If the Ssnpm extension is implemented, the `PMM` field enables or disables
+pointer masking (see <<Zpm>>) for VS-mode, according to the values in
+<<henvcfg-pmm-values>>. When the Ssnpm extension is not implemented, the `PMM`
+field is read-only zero. The `PMM` field is read-only zero for RV32.
+
+[[henvcfg-pmm-values]]
+
+[%header, cols="25%,75%", options="header"]
+.Legal values of `PMM` WARL field
+|===
+|Value|Description
+|00|Pointer masking is disabled (PMLEN = 0)
+|01|Reserved
+|10|Pointer masking is enabled with PMLEN = XLEN - 57 (PMLEN = 7 on RV64)
+|11|Pointer masking is enabled with PMLEN = XLEN - 48 (PMLEN = 16 on RV64)
+|===
 
 The Zicfilp extension adds the `LPE` field in `henvcfg`. When the `LPE` field
 is set to 1, the Zicfilp extension is enabled in VS-mode. When the `LPE` field
@@ -1307,6 +1340,17 @@ HLVX.WU is valid for RV32, even though LWU and HLV.WU are not. (For
 RV32, HLVX.WU can be considered a variant of HLV.W, as sign extension is
 irrelevant for 32-bit values.)
 
+The memory accesses performed by the `HLVX.*` instructions are not subject to
+pointer masking (see <<Zpm>>).
+
+[NOTE]
+====
+`HLVX.*` instructions, designed for emulating implicit access to fetch
+instructions from guest memory, perform memory accesses that are exempt from
+pointer masking to facilitate this emulation. For the same reason, pointer
+masking does not apply when MXR is set.
+====
+
 Attempts to execute a virtual-machine load/store instruction (HLV, HLVX,
 or HSV) when V=1 cause a virtual-instruction exception. Attempts to execute
 one of these same instructions from U-mode when `hstatus`.HU=0 cause an
@@ -1863,6 +1907,42 @@ code should zero `vsatp`, then swap `hgatp`, then finally write the new
 should be switched after zeroing `vsatp` but before writing the new `vsatp`
 value, obviating the need to execute an HFENCE.VVMA instruction.
 
+[[pm-two-stage]]
+==== Interaction with Pointer Masking
+
+Guest physical addresses (GPAs) are 2 bits wider than the corresponding virtual
+address translation modes, resulting in additional address translation schemes
+Sv32x4, Sv39x4, Sv48x4, and Sv57x4 for translating guest physical addresses to
+supervisor physical addresses. When running with virtualization in VS/VU mode
+with `vsatp.MODE` = Bare, this means that those two bits may be subject to
+pointer masking, depending on `hgatp.MODE` and `senvcfg.PMM`/`henvcfg.PMM` (for
+VU/VS mode). If `vsatp.MODE` != BARE, this issue does *not* apply.
+
+[NOTE]
+====
+An implementation could mask those two bits on the TLB access path, but this can
+have a significant timing impact. Alternatively, an implementation may choose to
+"waste" TLB capacity by having up to 4 duplicate entries for each page. In this
+case, the pointer masking operation can be applied on the TLB refill path, where
+it is unlikely to affect timing. To support this approach, some TLB entries need
+to be flushed when PMLEN changes in a way that may affect these duplicate
+entries.
+====
+
+To support implementations where (XLEN-PMLEN) can be less than the GPA width
+supported by `hgatp.MODE`, hypervisors should execute an `HFENCE.GVMA` with
+_rs1_=`x0` if the `henvcfg.PMM` is changed from or to a value where (XLEN-PMLEN)
+is less than GPA width supported by the `hgatp` translation mode of that guest.
+Specifically, these cases are:
+
+* `PMLEN=7` and `hgatp.MODE=sv57x4`
+* `PMLEN=16` and `hgatp.MODE=sv57x4`
+* `PMLEN=16` and `hgatp.MODE=sv48x4`
+
+Implementation of an address-specific `HFENCE.GVMA` should either ignore the
+address argument, or should ignore the top masked GPA bits of entries when
+comparing for an address match.
+
 === Traps
 
 [[sec:hcauses]]

src/machine.adoc

@@ -2224,7 +2224,23 @@ The definition of the CBZE field is furnished by the Zicboz extension.
 
 The definitions of the CBCFE and CBIE fields are furnished by the Zicbom extension.
 
-The definition of the PMM field is furnished by the Smnpm extension.
+If the Smnpm extension is implemented, the `PMM` field enables or disables
+pointer masking (see <<Zpm>>) for the next-lower privilege mode (S-/HS-mode if
+S-mode is implemented, or U-mode otherwise), according to the values in
+<<menvcfg-pmm-values>>. If Smnpm is not implemented, `PMM` is read-only zero.
+The `PMM` field is read-only zero for RV32.
+
+[[menvcfg-pmm-values]]
+
+[%header, cols="25%,75%", options="header"]
+.Legal values of `PMM` WARL field
+|===
+|Value|Description
+|00|Pointer masking is disabled (PMLEN = 0)
+|01|Reserved
+|10|Pointer masking is enabled with PMLEN = XLEN - 57 (PMLEN = 7 on RV64)
+|11|Pointer masking is enabled with PMLEN = XLEN - 48 (PMLEN = 16 on RV64)
+|===
 
 The Zicfilp extension adds the `LPE` field in `menvcfg`. When the `LPE` field is
 set to 1 and S-mode is implemented, the Zicfilp extension is enabled in S-mode.
@@ -2260,6 +2276,7 @@ The `menvcfgh` register does not exist when XLEN=64.
 If U-mode is not supported, then registers `menvcfg` and `menvcfgh` do
 not exist.
 
+[[sec:mseccfg]]
 ==== Machine Security Configuration (`mseccfg`) Register
 
 `mseccfg` is an optional 64-bit read/write register, formatted as
@@ -2275,7 +2292,29 @@ entropy-source extension, Zkr.
 The definitions of the RLB, MMWP, and MML fields are furnished by the
 PMP-enhancement extension, Smepmp.
 
-The definition of the PMM field is furnished by the Smmpm extension.
+If the Smmpm extension is implemented, the `PMM` field enables or disables
+pointer masking (see <<Zpm>>) for M-mode according to the values in
+<<mseccfg-pmm-values>>. If Smmpm is not implemented, `PMM` is read-only zero.
+The `PMM` field is read-only zero for RV32.
+
+[[mseccfg-pmm-values]]
+
+[%header, cols="25%,75%", options="header"]
+.Legal values of `PMM` WARL field
+|===
+|Value|Description
+|00|Pointer masking is disabled (PMLEN = 0)
+|01|Reserved
+|10|Pointer masking is enabled with PMLEN = XLEN - 57 (PMLEN = 7 on RV64)
+|11|Pointer masking is enabled with PMLEN = XLEN - 48 (PMLEN = 16 on RV64)
+|===
+
+[NOTE]
+====
+`Smmpm` implementations need to satisfy max(largest supported virtual address
+size, largest supported supervisor physical address size) <= (XLEN - PMLEN)
+bits to avoid any masking logic on the TLB access path.
+====
 
 The Zicfilp extension adds the `MLPE` field in `mseccfg`. When `MLPE` field is
 1, Zicfilp extension is enabled in M-mode. When the `MLPE` field is 0, the

src/supervisor.adoc

@@ -834,7 +834,23 @@ The definition of the CBZE field is furnished by the Zicboz extension.
 The definitions of the CBCFE and CBIE fields are furnished by the Zicbom
 extension.
 
-The definition of the PMM field is furnished by the Ssnpm extension.
+If the Ssnpm extension is implemented, the `PMM` field enables or disables
+pointer masking (see <<Zpm>>) for the next-lower privilege mode (U/VU),
+according to the values in <<senvcfg-pmm-values>>. If Ssnpm is not
+implemented, `PMM` is read-only zero. The `PMM` field is read-only zero for
+RV32.
+
+[[senvcfg-pmm-values]]
+
+[%header, cols="25%,75%", options="header"]
+.Legal values of `PMM` WARL field
+|===
+|Value|Description
+|00|Pointer masking is disabled (PMLEN = 0)
+|01|Reserved
+|10|Pointer masking is enabled with PMLEN = XLEN - 57 (PMLEN = 7 on RV64)
+|11|Pointer masking is enabled with PMLEN = XLEN - 48 (PMLEN = 16 on RV64)
+|===
 
 The Zicfilp extension adds the `LPE` field in `senvcfg`. When the `LPE` field is
 set to 1, the Zicfilp extension is enabled in VU/U-mode. When the `LPE` field is
@@ -1260,6 +1276,10 @@ For implementations that make `satp`.MODE read-only zero (always Bare),
 attempts to execute an SFENCE.VMA instruction might raise an
 illegal-instruction exception.
 
+No SFENCE.VMA is required after enabling or disabling pointer masking
+(see <<Zpm>>), as pointer masking applies to the effective address only and
+does not affect any memory-management data structures.
+
 [[sv32]]
 === Sv32: Page-Based 32-bit Virtual-Memory Systems
 

src/zpm.adoc

@@ -131,7 +131,7 @@ Pointer masking applies to all explicit memory accesses. Currently, in the Base
 * **Atomics**: All instructions in RV32A and RV64A.
 * **Floating Point**: FLW, FLD, FLQ, FSW, FSD, FSQ.
 * **Compressed**: All instructions mapping to any of the above, and C.LWSP, C.LDSP, C.FLWSP, C.FLDSP, C.SWSP, C.SDSP, C.FSWSP, C.FSDSP.
-* **Hypervisor Extension**: HLV.\*, HSV.* (in some cases; see <<_ssnpm>>).
+* **Hypervisor Extension**: HLV.\*, HSV.* (in some cases; see <<sec:hstatus>>).
 * **Cache Management Operations**: All instructions in Zicbom, Zicbop and Zicboz.
 * **Vector Extension**: All vector load and store instructions in the ratified RVV 1.0 spec.
 * **Zicfiss Extension**: SSPUSH, C.SSPUSH, SSPOPCHK, C.SSPOPCHK, SSAMOSWAP.W/D.
@@ -190,11 +190,9 @@ Pointer masking refers to a number of separate extensions, all of which are priv
 
 **Extensions**:
 
-* **Ssnpm**: A supervisor-level extension that provides pointer masking for the next lower privilege mode (U-mode), and for VS- and VU-modes if the H extension is present.
-* **Smnpm**: A machine-level extension that provides pointer masking for the next lower privilege mode (S/HS if S-mode is implemented, or U-mode otherwise).
-* **Smmpm**: A machine-level extension that provides pointer masking for M-mode.
-
-See <<_isa_extensions>> for details on how each of these extensions is configured.
+* **Ssnpm**: A supervisor-level extension that provides pointer masking for the next lower privilege mode (U-mode), and for VS- and VU-modes if the H extension is present. See <<sec:senvcfg>>, <<sec:henvcfg>>, <<sec:hstatus>>, and <<pm-two-stage>>.
+* **Smnpm**: A machine-level extension that provides pointer masking for the next lower privilege mode (S/HS if S-mode is implemented, or U-mode otherwise). See <<sec:menvcfg>>.
+* **Smmpm**: A machine-level extension that provides pointer masking for M-mode. See <<sec:mseccfg>>.
 
 In addition, the pointer masking standard defines two extensions that describe an execution environment but have no bearing on hardware implementations. These extensions are intended to be used in profile specifications where a User profile or a Supervisor profile can only reference User level or Supervisor level pointer masking functionality, and not the associated CSR controls that exist at a higher privilege level (i.e., in the execution environment).
 
@@ -203,95 +201,18 @@ In addition, the pointer masking standard defines two extensions that describe a
 
 The precise nature of these facilities is left to the respective execution environment.
 
-Pointer masking only applies to RV64. In RV32, trying to enable pointer masking will result in an illegal WARL write and not update the pointer masking configuration bits (see <<_isa_extensions>> for details). The same is the case on RV64 or larger systems when UXL/SXL/MXL is set to 1 for the corresponding privilege mode. Note that in RV32, the CSR bits introduced by pointer masking are still present, for compatibility between RV32 and larger systems with UXL/SXL/MXL set to 1. Setting UXL/SXL/MXL to 1 will clear the corresponding pointer masking configuration bits.
+Pointer masking only applies to RV64. In RV32, trying to enable pointer masking will result in an illegal WARL write and not update the pointer masking configuration bits (see <<sec:mseccfg>>, <<sec:menvcfg>>, <<sec:henvcfg>>, and <<sec:senvcfg>> for details). The same is the case on RV64 or larger systems when UXL/SXL/MXL is set to 1 for the corresponding privilege mode. Note that in RV32, the CSR bits introduced by pointer masking are still present, for compatibility between RV32 and larger systems with UXL/SXL/MXL set to 1. Setting UXL/SXL/MXL to 1 will clear the corresponding pointer masking configuration bits.
 
 [NOTE]
 ====
 Note that setting UXL/SXL/MXL to 1 and back to 0 does not preserve the previous values of the PMM bits. This includes the case of entering an RV32 virtual machine from an RV64 hypervisor and returning.
 ====
 
-=== ISA Extensions
-
-This section describes the pointer masking extensions `Smmpm`, `Smnpm` and `Ssnpm`. All of these extensions are privileged ISA extensions and do not add any new CSRs. For the definitions of `Sspm` and `Supm`, see <<_pointer_masking_extensions>>.
-
 [NOTE]
 ====
 Future extensions may introduce additional CSRs to allow different privilege modes to modify their own pointer masking settings. This may be required for future use cases in managed runtime systems that are not currently addressed as part of this extension.
 ====
 
-Each extension introduces a 2-bit WARL field (`PMM`) that may take on the following values to set the pointer masking settings for a particular privilege mode.
-
-[[pmm-values]]
-
-[%header, cols="25%,75%", options="header"]
-.Possible values of `PMM` WARL field.
-|===
-|Value|Description
-|00|Pointer masking is disabled (PMLEN=0)
-|01|Reserved
-|10|Pointer masking is enabled with PMLEN=XLEN-57 (PMLEN=7 on RV64)
-|11|Pointer masking is enabled with PMLEN=XLEN-48 (PMLEN=16 on RV64)
-|===
-
-All of these fields are read-only 0 on RV32 systems.
-
-==== Ssnpm
-
-`Ssnpm` adds a new 2-bit WARL field (`PMM`) to bits 33:32 of `senvcfg`. Setting `PMM` enables or disables pointer masking for the next lower privilege mode (U/VU mode), according to the values in <<pmm-values>>.
-
-In systems where the H Extension is present, `Ssnpm` also adds a new 2-bit WARL field (`PMM`) to bits 33:32 of `henvcfg`. Setting `PMM` enables or disables pointer masking for VS-mode, according to the values in <<pmm-values>>. Further, a 2-bit WARL field (`HUPMM`) is added to bits 49:48 of `hstatus`. Setting `hstatus.HUPMM` enables or disables pointer masking for `HLV.\*` and `HSV.*` instructions in U-mode, according to the values in <<pmm-values>>, when their explicit memory access is performed as though in VU-mode. In HS- and M-modes, pointer masking for these instructions is enabled or disabled by `senvcfg.PMM`, when their explicit memory access is performed as though in VU-mode. Setting `henvcfg.PMM` enables or disables pointer masking for `HLV.\*` and `HSV.*` when their explicit memory access is performed as though in VS-mode.
-
-[NOTE]
-====
-The hypervisor should copy the value written to `senvcfg.PMM` by the guest to the `hstatus.HUPMM` field prior to invoking `HLV.\*` or `HSV.*` instructions in U-mode.
-====
-
-The memory accesses performed by the `HLVX.*` instructions are not subject to pointer masking.
-
-[NOTE]
-====
-`HLVX.*` instructions, designed for emulating implicit access to fetch instructions from guest memory, perform memory accesses that are exempt from pointer masking to facilitate this emulation. For the same reason, pointer masking does not apply when MXR is set.
-====
-
-==== Smnpm
-
-`Smnpm` adds a new 2-bit WARL field (`PMM`) to bits 33:32 of `menvcfg`. Setting `PMM` enables or disables pointer masking for the next lower privilege mode (S-/HS-mode if S-mode is implemented, or U-mode otherwise), according to the values in <<pmm-values>>.
-
-[NOTE]
-====
-The type of address determines which type of pointer masking is applied. For example, when running with virtualization in VS/VU mode with `vsatp.MODE` = Bare, physical address pointer masking (zero extension) applies.
-====
-
-==== Smmpm
-
-`Smmpm` adds a new 2-bit WARL field (`PMM`) to bits 33:32 of `mseccfg`. The presence of `Smmpm` implies the presence of the `mseccfg` register, even if it would not otherwise be present. Setting `PMM` enables or disables pointer masking for M mode, according to the values in <<pmm-values>>.
-
-==== Interaction with SFENCE.VMA
-
-Since pointer masking applies to the effective address only and does not affect any memory-management data structures, no SFENCE.VMA is required after enabling/disabling pointer masking.
-
-==== Interaction with Two-Stage Address Translation
-
-Guest physical addresses (GPAs) are 2 bits wider than the corresponding virtual address translation modes, resulting in additional address translation schemes Sv32x4, Sv39x4, Sv48x4, and Sv57x4 for translating guest physical addresses to supervisor physical addresses. When running with virtualization in VS/VU mode with `vsatp.MODE` = Bare, this means that those two bits may be subject to pointer masking, depending on `hgatp.MODE` and `senvcfg.PMM`/`henvcfg.PMM` (for VU/VS mode). If `vsatp.MODE` != BARE, this issue does *not* apply.
-
-[NOTE]
-====
-An implementation could mask those two bits on the TLB access path, but this can have a significant timing impact. Alternatively, an implementation may choose to "waste" TLB capacity by having up to 4 duplicate entries for each page. In this case, the pointer masking operation can be applied on the TLB refill path, where it is unlikely to affect timing. To support this approach, some TLB entries need to be flushed when PMLEN changes in a way that may affect these duplicate entries.
-====
-
-To support implementations where (XLEN-PMLEN) can be less than the GPA width supported by `hgatp.MODE`, hypervisors should execute an `HFENCE.GVMA` with _rs1_=`x0` if the `henvcfg.PMM` is changed from or to a value where (XLEN-PMLEN) is less than GPA width supported by the `hgatp` translation mode of that guest. Specifically, these cases are:
-
-* `PMLEN=7` and `hgatp.MODE=sv57x4`
-* `PMLEN=16` and `hgatp.MODE=sv57x4`
-* `PMLEN=16` and `hgatp.MODE=sv48x4`
-
-[NOTE]
-====
-`Smmpm` implementations need to satisfy max(largest supported virtual address size, largest supported supervisor physical address size) <= (XLEN - PMLEN) bits to avoid any masking logic on the TLB access path.
-====
-
-Implementation of an address-specific `HFENCE.GVMA` should either ignore the address argument, or should ignore the top masked GPA bits of entries when comparing for an address match.
-
 ==== Number of Masked Bits
 
 As described in <<_determining_the_value_of_pmlen>>, the supported values of PMLEN may depend on the effective privilege mode. The current standard only defines PMLEN=XLEN-48 and PMLEN=XLEN-57, but this assumption may be relaxed in future extensions and profiles. Trying to enable pointer masking in an unsupported scenario represents an illegal write to the corresponding pointer masking enable bit and follows WARL semantics. Future profiles may choose to define certain combinations of privilege modes and supported values of PMLEN as mandatory.