1 files changed, 598 insertions, 0 deletions
diff --git a/src/priv-preface.adoc b/src/priv-preface.adoc
new file mode 100644
index 0000000..22536de
--- /dev/null
+++ b/src/priv-preface.adoc
@@ -0,0 +1,598 @@
+[colophon]
+== Preface
+
+This document describes the RISC-V privileged architecture.
+It contains the following versions of the RISC-V ISA modules,
+all of which have been ratified:
+
+[%autowidth,float="center",align="center",cols="^,<",options="header",]
+|===
+|Module |Version
+|*Machine ISA* +
+*Smstateen Extension* +
+*Smcsrind/Sscsrind Extension* +
+*Smepmp Extension* +
+*Smcntrpmf Extension* +
+*Smrnmi Extension* +
+*Smcdeleg Extension* +
+*Smdbltrp Extension* +
+*Smctr Extension* +
+*Supervisor ISA* +
+*Svade Extension* +
+*Svnapot Extension* +
+*Svpbmt Extension* +
+*Svinval Extension* +
+*Svadu Extension* +
+*Svvptc Extension* +
+*Ssqosid Extension* +
+*Sstc Extension* +
+*Sscofpmf Extension* +
+*Ssdbltrp Extension* +
+*Ssqosid Extension* +
+*Hypervisor ISA* +
+*Shlcofideleg Extension* +
+*Svvptc Extension* +
+*Pointer-Masking Extensions* +
+*Svrsw60t59b Extension*
+
+|*1.13* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.13* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0*
+|===
+
+The following changes have been made since version 20250508:
+
+* Addition of the Svrsw60t59b extension for additional PTE reserved-for-software bits.
+
+// Had to make the above a level 1 heading (two equals signs) to avoid error when building
+// the ISA manual as a book with other "parts". This is opposite to what the adoc says to do
+// but otherwise asciidoctor creates the error message:
+//
+// asciidoctor: ERROR: ext/riscv-isa-manual/src/priv-preface.adoc: line 2: invalid part, must have at least one section (e.g., chapter, appendix, etc.)
+//
+// See asciidoctor doc which seems wrong: https://docs.asciidoctor.org/asciidoc/latest/sections/colophon/
+[.big]*_Preface to Version 20250508_*
+
+This document describes the RISC-V privileged architecture.
+
+The ISA modules marked *Ratified* have been ratified at this time. The
+modules marked _Frozen_ are not expected to change significantly before
+being put up for ratification. The modules marked _Draft_ are expected
+to change before ratification.
+
+The document contains the following versions of the RISC-V ISA modules:
+
+[%autowidth,float="center",align="center",cols="^,<,^",options="header",]
+|===
+|Module |Version |Status
+|*Machine ISA* +
+*Smstateen Extension* +
+*Smcsrind/Sscsrind Extension* +
+*Smepmp Extension* +
+*Smcntrpmf Extension* +
+*Smrnmi Extension* +
+*Smcdeleg Extension* +
+*Smdbltrp Extension* +
+*Smctr Extension* +
+*Supervisor ISA* +
+*Svade Extension* +
+*Svnapot Extension* +
+*Svpbmt Extension* +
+*Svinval Extension* +
+*Svadu Extension* +
+*Svvptc Extension* +
+*Ssqosid Extension* +
+*Sstc Extension* +
+*Sscofpmf Extension* +
+*Ssdbltrp Extension* +
+*Ssqosid Extension* +
+*Hypervisor ISA* +
+*Shlcofideleg Extension* +
+*Svvptc Extension* +
+*Pointer-Masking Extensions*
+
+|*1.13* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.13* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0*
+
+|*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified*
+|===
+
+The following changes have been made since version 20241101:
+
+* Addition of the Smctr Control Transfer Records extension.
+* Addition of the Svvptc Extension for Obviating Memory-Management Instructions after Marking PTEs Valid.
+* Addition of the Ssqosid Extension for Quality-of-Service Identifiers.
+* Addition of the Pointer-Masking Extensions.
+
+[.big]*_Preface to Version 20241101_*
+
+This document describes the RISC-V privileged architecture.
+
+The ISA modules marked *Ratified* have been ratified at this time. The
+modules marked _Frozen_ are not expected to change significantly before
+being put up for ratification. The modules marked _Draft_ are expected
+to change before ratification.
+
+The document contains the following versions of the RISC-V ISA modules:
+
+[%autowidth,float="center",align="center",cols="^,<,^",options="header",]
+|===
+|Module |Version |Status
+|*Machine ISA* +
+*Smstateen Extension* +
+*Smcsrind/Sscsrind Extension* +
+*Smepmp Extension* +
+*Smcntrpmf Extension* +
+*Smrnmi Extension* +
+*Smcdeleg Extension* +
+*Smdbltrp Extension* +
+*Supervisor ISA* +
+*Svade Extension* +
+*Svnapot Extension* +
+*Svpbmt Extension* +
+*Svinval Extension* +
+*Svadu Extension* +
+*Sstc Extension* +
+*Sscofpmf Extension* +
+*Ssdbltrp Extension* +
+*Ssqosid Extension* +
+*Hypervisor ISA* +
+*Shlcofideleg Extension* +
+*Svvptc Extension*
+
+|*1.13* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.13* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0*
+
+|*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified*
+|===
+
+[.big]*_Preface to Version 20241017_*
+
+This document describes the RISC-V privileged architecture. This
+release, version 20241017, contains the following versions of the RISC-V ISA
+modules:
+
+[%autowidth,float="center",align="center",cols="^,<,^",options="header",]
+|===
+|Module |Version |Status
+|*Machine ISA* +
+*Smstateen Extension* +
+*Smcsrind/Sscsrind Extension* +
+*Smepmp* +
+*Smcntrpmf* +
+*Smrnmi Extension* +
+*Smcdeleg* +
+*Smdbltrp* +
+*Supervisor ISA* +
+*Svade Extension* +
+*Svnapot Extension* +
+*Svpbmt Extension* +
+*Svinval Extension* +
+*Svadu Extension* +
+*Sstc* +
+*Sscofpmf* +
+*Ssdbltrp* +
+*Hypervisor ISA* +
+*Shlcofideleg* +
+*Svvptc*
+
+|*1.13* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.13* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0*
+
+|*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified*
+|===
+
+The following changes have been made since version 1.12 of the Machine and
+Supervisor ISAs, which, while not strictly backwards compatible, are not
+anticipated to cause software portability problems in practice:
+
+* Redefined `misa`.MXL to be read-only, making MXLEN a constant.
+* Added the constraint that SXLEN{ge}UXLEN.
+
+Additionally, the following compatible changes have been
+made to the Machine and Supervisor ISAs since version 1.12:
+
+* Defined the `misa`.B field to reflect that the B extension has been
+implemented.
+* Defined the `misa`.V field to reflect that the V extension has been
+implemented.
+* Defined the RV32-only `medelegh` and `hedelegh` CSRs.
+* Defined the misaligned atomicity granule PMA, superseding the proposed Zam
+  extension.
+* Allocated interrupt 13 for Sscofpmf LCOFI interrupt.
+* Defined hardware-error and software-check exception codes.
+* Specified synchronization requirements when changing the PBMTE and ADUE fields
+in `menvcfg` and `henvcfg`.
+* Exposed count-overflow interrupts to VS-mode via the Shlcofideleg extension.
+* Relaxed behavior of some HINTs when MXLEN > XLEN.
+* Defined the format of the memory-mapped `msip` registers.
+
+Finally, the following clarifications and document improvements have been made
+since the last document release:
+
+* Transliterated the document from LaTeX into AsciiDoc.
+* Included all ratified extensions through March 2024.
+* Clarified that "platform- or custom-use" interrupts are actually
+"platform-use interrupts", where the platform can choose to make some custom.
+* Clarified semantics of explicit accesses to CSRs wider than XLEN bits.
+* Clarified that MXLEN{ge}SXLEN.
+* Clarified that WFI is not a HINT instruction.
+* Clarified that VS-stage page-table accesses set G-stage A/D bits.
+* Clarified ordering rules when PBMT=IO is used on main-memory regions.
+* Clarified ordering rules for hardware A/D bit updates.
+* Clarified that, for a given exception cause, `__x__tval` might sometimes
+be set to a nonzero value but sometimes not.
+* Clarified exception behavior of unimplemented or inaccessible CSRs.
+* Clarified that Svpbmt allows implementations to override additional PMAs.
+* Replaced the concept of vacant memory regions with inaccessible memory or I/O regions.
+* Clarified that timer and count-overflow interrupts' arrival in
+  interrupt-pending registers is not immediate.
+* Clarified that MXR affects only explicit memory accesses.
+
+[.big]*_Preface to Version 20211203_*
+
+This document describes the RISC-V privileged architecture. This
+release, version 20211203, contains the following versions of the RISC-V
+ISA modules:
+
+[%autowidth,float="center",align="center",cols="^,<,^",options="header",]
+|===
+|Module |Version |Status
+|*Machine ISA* +
+*Supervisor ISA* +
+*Svnapot Extension* +
+*Svpbmt Extension* +
+*Svinval Extension* +
+*Hypervisor ISA* +
+|*1.12* +
+*1.12* +
+*1.0* +
+*1.0* +
+*1.0* +
+*1.0* +
+|*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified* +
+*Ratified*
+|===
+
+The following changes have been made since version 1.11, which, while
+not strictly backwards compatible, are not anticipated to cause software
+portability problems in practice:
+
+* Changed MRET and SRET to clear `mstatus`.MPRV when leaving M-mode.
+* Reserved additional `satp` patterns for future use.
+* Stated that the `scause` Exception Code field must implement bits 4–0
+at minimum.
+* Relaxed I/O regions have been specified to follow RVWMO. The previous
+specification implied that PPO rules other than fences and
+acquire/release annotations did not apply.
+* Constrained the LR/SC reservation set size and shape when using
+page-based virtual memory.
+* PMP changes require an SFENCE.VMA on any hart that implements
+page-based virtual memory, even if VM is not currently enabled.
+* Allowed for speculative updates of page table entry A bits.
+* Clarify that if the address-translation algorithm non-speculatively
+reaches a PTE in which a bit reserved for future standard use is set, a
+page-fault exception must be raised.
+
+Additionally, the following compatible changes have been made since
+version 1.11:
+
+* Removed the N extension.
+* Defined the mandatory RV32-only CSR `mstatush`, which contains most of
+the same fields as the upper 32 bits of RV64’s `mstatus`.
+* Defined the mandatory CSR `mconfigptr`, which if nonzero contains the
+address of a configuration data structure.
+* Defined optional `mseccfg` and `mseccfgh` CSRs, which control the
+machine’s security configuration.
+* Defined `menvcfg`, `henvcfg`, and `senvcfg` CSRs (and RV32-only
+`menvcfgh` and `henvcfgh` CSRs), which control various characteristics
+of the execution environment.
+* Designated part of SYSTEM major opcode for custom use.
+* Permitted the unconditional delegation of less-privileged interrupts.
+* Added optional big-endian and bi-endian support.
+* Made priority of load/store/AMO address-misaligned exceptions
+implementation-defined relative to load/store/AMO page-fault and
+access-fault exceptions.
+* PMP reset values are now platform-defined.
+* An additional 48 optional PMP registers have been defined.
+* Slightly relaxed the atomicity requirement for A and D bit updates
+performed by the implementation.
+* Clarify the architectural behavior of address-translation caches
+* Added Sv57 and Sv57x4 address translation modes.
+* Software breakpoint exceptions are permitted to write either 0 or the
+`pc` to `__x__tval`.
+* Clarified that bare S-mode need not support the SFENCE.VMA
+instruction.
+* Specified relaxed constraints for implicit reads of non-idempotent
+regions.
+* Added the Svnapot Standard Extension, along with the N bit in Sv39,
+Sv48, and Sv57 PTEs.
+* Added the Svpbmt Standard Extension, along with the PBMT bits in Sv39,
+Sv48, and Sv57 PTEs.
+* Added the Svinval Standard Extension and associated instructions.
+
+Finally, the hypervisor architecture proposal has been extensively
+revised.
+
+[.big]*_Preface to Version 1.11_*
+
+This is version 1.11 of the RISC-V privileged architecture. The document
+contains the following versions of the RISC-V ISA modules:
+
+[%autowidth,float="center",align="center",cols="^,<,^",options="header",]
+|===
+|Module |Version |Status
+|*Machine ISA* +
+*Supervisor ISA* +
+_Hypervisor ISA_
+|*1.11* +
+*1.11* +
+_0.3_
+|*Ratified* +
+*Ratified* +
+_Draft_
+|===
+
+Changes from version 1.10 include:
+
+* Moved Machine and Supervisor spec to *Ratified* status.
+* Improvements to the description and commentary.
+* Added a draft proposal for a hypervisor extension.
+* Specified which interrupt sources are reserved for standard use.
+* Allocated some synchronous exception causes for custom use.
+* Specified the priority ordering of synchronous exceptions.
+* Added specification that xRET instructions may, but are not required
+to, clear LR reservations if A extension present.
+* The virtual-memory system no longer permits supervisor mode to execute
+instructions from user pages, regardless of the SUM setting.
+* Clarified that ASIDs are private to a hart, and added commentary about
+the possibility of a future global-ASID extension.
+* SFENCE.VMA semantics have been clarified.
+* Made the `mstatus`.MPP field *WARL*, rather than *WLRL*.
+* Made the unused `__x__ip` fields *WPRI*, rather than *WIRI*.
+* Made the unused `misa` fields *WARL*, rather than *WIRI*.
+* Made the unused `pmpaddr` and `pmpcfg` fields *WARL*, rather than *WIRI*.
+* Required all harts in a system to employ the same PTE-update scheme as
+each other.
+* Rectified an editing error that misdescribed the mechanism by which
+`mstatus.__x__IE` is written upon an exception.
+* Described scheme for emulating misaligned AMOs.
+* Specified the behavior of the `misa` and `__x__epc` registers in systems
+with variable IALIGN.
+* Specified the behavior of writing self-contradictory values to the
+`misa` register.
+* Defined the `mcountinhibit` CSR, which stops performance counters from
+incrementing to reduce energy consumption.
+* Specified semantics for PMP regions coarser than four bytes.
+* Specified contents of CSRs across XLEN modification.
+* Moved PLIC chapter into its own document.
+
+[.big]*_Preface to Version 1.10_*
+
+This is version 1.10 of the RISC-V privileged architecture proposal.
+Changes from version 1.9.1 include:
+
+* The previous version of this document was released under a Creative
+Commons Attribution 4.0 International License by the original authors,
+and this and future versions of this document will be released under the
+same license.
+* The explicit convention on shadow CSR addresses has been removed to
+reclaim CSR space. Shadow CSRs can still be added as needed.
+* The `mvendorid` register now contains the JEDEC code of the core
+provider as opposed to a code supplied by the Foundation. This avoids
+redundancy and offloads work from the Foundation.
+* The interrupt-enable stack discipline has been simplified.
+* An optional mechanism to change the base ISA used by supervisor and
+user modes has been added to the `mstatus` CSR, and the field previously
+called Base in `misa` has been renamed to `MXL` for consistency.
+* Clarified expected use of XS to summarize additional extension state
+status fields in `mstatus`.
+* Optional vectored interrupt support has been added to the `mtvec` and
+`stvec` CSRs.
+* The SEIP and UEIP bits in the `mip` CSR have been redefined to support
+software injection of external interrupts.
+* The `mbadaddr` register has been subsumed by a more general `mtval`
+register that can now capture bad instruction bits on an illegal-instruction
+fault to speed instruction emulation.
+* The machine-mode base-and-bounds translation and protection schemes
+have been removed from the specification as part of moving the virtual
+memory configuration to `sptbr` (now `satp`). Some of the motivation for
+the base and bound schemes are now covered by the PMP registers, but
+space remains available in `mstatus` to add these back at a later date
+if deemed useful.
+* In systems with only M-mode, or with both M-mode and U-mode but
+without U-mode trap support, the `medeleg` and `mideleg` registers now
+do not exist, whereas previously they returned zero.
+* Virtual-memory page faults now have `mcause` values distinct from
+physical-memory access faults. Page-fault exceptions can now be
+delegated to S-mode without delegating exceptions generated by PMA and
+PMP checks.
+* An optional physical-memory protection (PMP) scheme has been proposed.
+* The supervisor virtual memory configuration has been moved from the
+`mstatus` register to the `sptbr` register. Accordingly, the `sptbr`
+register has been renamed to `satp` (Supervisor Address Translation and
+Protection) to reflect its broadened role.
+* The SFENCE.VM instruction has been removed in favor of the improved
+SFENCE.VMA instruction.
+* The `mstatus` bit MXR has been exposed to S-mode via `sstatus`.
+* The polarity of the PUM bit in `sstatus` has been inverted to shorten
+code sequences involving MXR. The bit has been renamed to SUM.
+* Hardware management of page-table entry Accessed and Dirty bits has
+been made optional; simpler implementations may trap to software to set
+them.
+* The counter-enable scheme has changed, so that S-mode can control
+availability of counters to U-mode.
+* H-mode has been removed, as we are focusing on recursive
+virtualization support in S-mode. The encoding space has been reserved
+and may be repurposed at a later date.
+* A mechanism to improve virtualization performance by trapping S-mode
+virtual-memory management operations has been added.
+* The Supervisor Binary Interface (SBI) chapter has been removed, so
+that it can be maintained as a separate specification.
+
+[.big]*_Preface to Version 1.9.1_*
+
+This is version 1.9.1 of the RISC-V privileged architecture proposal.
+Changes from version 1.9 include:
+
+* Numerous additions and improvements to the commentary sections.
+* Change configuration string proposal to be use a search process that
+supports various formats including Device Tree String and flattened
+Device Tree.
+* Made `misa` optionally writable to support modifying base and
+supported ISA extensions. CSR address of `misa` changed.
+* Added description of debug mode and debug CSRs.
+* Added a hardware performance monitoring scheme. Simplified the
+handling of existing hardware counters, removing privileged versions of
+the counters and the corresponding delta registers.
+* Fixed description of SPIE in presence of user-level interrupts.