Merge pull request #727 from riscv/mseccfg

Add mseccfg and *envcfg CSRs

5 files changed, 393 insertions, 2 deletions

diff --git a/src/hypervisor.tex b/src/hypervisor.tex
index 6e1c62a..0e4a595 100644
--- a/src/hypervisor.tex
+++ b/src/hypervisor.tex
@@ -98,7 +98,7 @@ interrupt, and address-translation subsystems.
 Additional CSRs are provided to HS-mode, but not to VS-mode, to manage
 two-stage address translation and to control the behavior of a VS-mode guest:
 {\tt hstatus}, {\tt hedeleg}, {\tt hideleg}, {\tt hvip}, {\tt hip}, {\tt hie},
-{\tt hgeip}, {\tt hgeie},
+{\tt hgeip}, {\tt hgeie}, {\tt henvcfg}, {\tt henvcfgh},
 {\tt hcounteren}, {\tt htimedelta}, {\tt htimedeltah}, {\tt htval},
 {\tt htinst}, and {\tt hgatp}.
 
@@ -124,7 +124,8 @@ do so.
 Conversely, when V=0, the VS CSRs do not ordinarily affect the behavior of
 the machine other than being readable and writable by CSR instructions.
 
-Some standard supervisor CSRs ({\tt scounteren} and {\tt scontext},
+Some standard supervisor CSRs ({\tt senvcfg},
+{\tt scounteren}, and {\tt scontext},
 possibly others) have no matching VS CSR.
 These supervisor CSRs continue to have their usual function and
 accessibility even when V=1, except with VS-mode and VU-mode substituting for
@@ -808,6 +809,102 @@ cause a supervisor-level (HS-level) guest external interrupt.
 The enable bits in {\tt hgeie} do not affect the VS-level external
 interrupt signal selected from {\tt hgeip} by {\tt hstatus}.VGEIN.
 
+\subsection{%
+ Hypervisor Environment Configuration Registers
+ ({\tt henvcfg} and {\tt henvcfgh})%
+}
+
+The {\tt henvcfg} CSR is an HSXLEN-bit read/write register,
+formatted for HSXLEN=64 as shown in Figure~\ref{fig:henvcfg},
+that controls certain
+characteristics of the execution environment when virtualization mode
+V=1.
+
+\begin{figure}[h!]
+{\footnotesize
+\begin{center}
+\begin{tabular}{c@{}Kcc@{}W@{}Wc}
+\instbit{63} &
+\instbitrange{62}{8} &
+\instbit{7} &
+\instbit{6} &
+\instbitrange{5}{4} &
+\instbitrange{3}{1} &
+\instbit{0} \\
+\hline
+\multicolumn{1}{|c|}{VSTCD} &
+\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{CBZE} &
+\multicolumn{1}{c|}{CBCFE} &
+\multicolumn{1}{c|}{CBIE} &
+\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{FIOM} \\
+\hline
+1 & 55 & 1 & 1 & 2 & 3 & 1 \\
+\end{tabular}
+\end{center}
+}
+\vspace{-0.1in}
+\caption{Hypervisor environment configuration register ({\tt henvcfg}) for HSXLEN=64.}
+\label{fig:henvcfg}
+\end{figure}
+
+If bit FIOM (Fence of I/O implies Memory) is set to one in
+{\tt henvcfg}, FENCE instructions executed when V=1 are modified
+so the requirement to order accesses to device I/O implies also the
+requirement to order main memory accesses.
+Table~\ref{tab:henvcfg-FIOM} details the modified interpretation of
+FENCE instruction bits PI, PO, SI, and SO when FIOM=1 and V=1.
+
+Similarly, when FIOM=1 and V=1,
+if an atomic instruction that accesses a region ordered as device I/O
+has its {\em aq} and/or {\em rl} bit set, then that instruction is ordered
+as though it accesses both device I/O and memory.
+
+\begin{table}[h!]
+\begin{center}
+\begin{tabular}{|c|l|}
+\hline
+Instruction bit & Meaning when set \\
+\hline
+PI & Predecessor device input and memory reads   (PR implied) \\
+PO & Predecessor device output and memory writes (PW implied) \\
+\hline
+SI & Successor device input and memory reads     (SR implied) \\
+SO & Successor device output and memory writes   (SW implied) \\
+\hline
+\end{tabular}
+\end{center}
+\vspace{-0.1in}
+\caption{%
+Modified interpretation of FENCE predecessor and successor sets when
+FIOM=1 and virtualization mode V=1.%
+}
+\label{tab:henvcfg-FIOM}
+\end{table}
+
+The definition of the VSTCD field will be furnished by the
+forthcoming Sstc extension.
+Its allocation within {\tt henvcfg} may change prior to the ratification
+of that extension.
+
+The definition of the CBZE field will be furnished by the
+forthcoming Zicboz extension.
+Its allocation within {\tt henvcfg} may change prior to the ratification
+of that extension.
+
+The definitions of the CBCFE and CBIE fields will be furnished by the
+forthcoming Zicbom extension.
+Their allocations within {\tt henvcfg} may change prior to the ratification
+of that extension.
+
+When HSXLEN=32, {\tt henvcfg} contains the same fields as bits 31:0
+of {\tt henvcfg} when HSXLEN=64.
+Additionally, when HSXLEN=32, {\tt henvcfgh} is a 32-bit read/write register that
+contains the same fields as bits 63:32 of {\tt henvcfg} when
+HSXLEN=64.
+Register {\tt henvcfgh} does not exist when HSXLEN=64.
+
 \subsection{Hypervisor Counter-Enable Register ({\tt hcounteren})}
 
 The counter-enable register {\tt hcounteren} is a 32-bit register that
diff --git a/src/machine.tex b/src/machine.tex
index bad69d6..28c3dae 100644
--- a/src/machine.tex
+++ b/src/machine.tex
@@ -2306,6 +2306,163 @@ register that is programmed by the platform or by M-mode software towards the
 beginning of the boot process.
 \end{commentary}
 
+\subsection{%
+ Machine Environment Configuration Registers
+ ({\tt menvcfg} and {\tt menvcfgh})%
+}
+
+The {\tt menvcfg} CSR is an MXLEN-bit read/write register,
+formatted for MXLEN=64 as shown in Figure~\ref{fig:menvcfg},
+that controls certain characteristics of the execution environment
+for modes less privileged than M.
+
+\begin{figure}[h!]
+{\footnotesize
+\begin{center}
+\begin{tabular}{c@{}Kcc@{}W@{}Wc}
+\instbit{63} &
+\instbitrange{62}{8} &
+\instbit{7} &
+\instbit{6} &
+\instbitrange{5}{4} &
+\instbitrange{3}{1} &
+\instbit{0} \\
+\hline
+\multicolumn{1}{|c|}{STCD} &
+\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{CBZE} &
+\multicolumn{1}{c|}{CBCFE} &
+\multicolumn{1}{c|}{CBIE} &
+\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{FIOM} \\
+\hline
+1 & 55 & 1 & 1 & 2 & 3 & 1 \\
+\end{tabular}
+\end{center}
+}
+\vspace{-0.1in}
+\caption{Machine environment configuration register ({\tt menvcfg}) for MXLEN=64.}
+\label{fig:menvcfg}
+\end{figure}
+
+If bit FIOM (Fence of I/O implies Memory) is set to one in {\tt menvcfg},
+FENCE instructions executed in modes less privileged than M are modified so
+the requirement to order accesses to device I/O implies also the requirement
+to order main memory accesses.
+Table~\ref{tab:menvcfg-FIOM} details the modified interpretation of
+FENCE instruction bits PI, PO, SI, and SO for modes less privileged than M
+when FIOM=1.
+
+Similarly, for modes less privileged than M when FIOM=1,
+if an atomic instruction that accesses a region ordered as device I/O
+has its {\em aq} and/or {\em rl} bit set, then that instruction is ordered
+as though it accesses both device I/O and memory.
+
+If S-mode is not supported, or if {\tt satp}.MODE is hardwired to Bare,
+the implementation may hardwire FIOM to zero.
+
+\begin{table}[h!]
+\begin{center}
+\begin{tabular}{|c|l|}
+\hline
+Instruction bit & Meaning when set \\
+\hline
+PI & Predecessor device input and memory reads   (PR implied) \\
+PO & Predecessor device output and memory writes (PW implied) \\
+\hline
+SI & Successor device input and memory reads     (SR implied) \\
+SO & Successor device output and memory writes   (SW implied) \\
+\hline
+\end{tabular}
+\end{center}
+\vspace{-0.1in}
+\caption{%
+Modified interpretation of FENCE predecessor and successor sets
+for modes less privileged than M when FIOM=1.%
+}
+\label{tab:menvcfg-FIOM}
+\end{table}
+
+\begin{commentary}
+Bit FIOM is needed in {\tt menvcfg} so M-mode can emulate the
+hypervisor extension of Chapter~\ref{hypervisor}, which has an
+equivalent FIOM bit in the hypervisor CSR {\tt henvcfg}.
+\end{commentary}
+
+The definition of the STCD field will be furnished by the
+forthcoming Sstc extension.
+Its allocation within {\tt menvcfg} may change prior to the ratification
+of that extension.
+
+The definition of the CBZE field will be furnished by the
+forthcoming Zicboz extension.
+Its allocation within {\tt menvcfg} may change prior to the ratification
+of that extension.
+
+The definitions of the CBCFE and CBIE fields will be furnished by the
+forthcoming Zicbom extension.
+Their allocations within {\tt menvcfg} may change prior to the ratification
+of that extension.
+
+When MXLEN=32, {\tt menvcfg} contains the same fields as bits 31:0
+of {\tt menvcfg} when MXLEN=64.
+Additionally, when MXLEN=32, {\tt menvcfgh} is a 32-bit read/write register that
+contains the same fields as bits 63:32 of {\tt menvcfg} when
+MXLEN=64.
+Register {\tt menvcfgh} does not exist when MXLEN=64.
+
+If U-mode is not supported, then registers {\tt menvcfg} and {\tt menvcfgh} do
+not exist.
+
+\subsection{Machine Security Configuration Register ({\tt mseccfg})}
+\label{sec:mseccfg}
+
+{\tt mseccfg} is an optional MXLEN-bit read/write register, formatted as shown
+in Figure~\ref{fig:mseccfg}, that controls security features.
+
+When MXLEN=32 only, {\tt mseccfgh} is a 32-bit read/write register that
+contains the same fields as {\tt mseccfg} bits 63:32 when MXLEN=64.
+
+\begin{figure*}[h!]
+{\footnotesize
+\begin{center}
+\setlength{\tabcolsep}{4pt}
+\begin{tabular}{MccFccc}
+\instbitrange{XLEN-1}{10} &
+\instbit{9} &
+\instbit{8} &
+\instbitrange{7}{3} &
+\instbit{2} &
+\instbit{1} &
+\instbit{0} \\
+\hline
+\multicolumn{1}{|c|}{\wpri} &
+\multicolumn{1}{c|}{SSEED} &
+\multicolumn{1}{c|}{USEED} &
+\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{RLB} &
+\multicolumn{1}{c|}{MMWP} &
+\multicolumn{1}{c|}{MML} \\
+\hline
+XLEN-10 & 1 & 1 & 5 & 1 & 1 & 1 \\
+\end{tabular}
+\end{center}
+}
+\vspace{-0.1in}
+\caption{Machine security configuration register ({\tt mseccfg}).}
+\label{fig:mseccfg}
+\end{figure*}
+
+The definitions of the SSEED and USEED fields will be furnished by the
+forthcoming entropy-source extension, Zkr.
+Their allocations within {\tt mseccfg} may change prior to the ratification
+of that extension.
+
+The definitions of the RLB, MMWP, and MML fields will be furnished by the
+forthcoming PMP-enhancement extension, Smepmp.
+Their allocations within {\tt mseccfg} may change prior to the ratification
+of that extension.
+
 \section{Machine-Level Memory-Mapped Registers}
 
 \subsection{Machine Timer Registers ({\tt mtime} and {\tt mtimecmp})}
diff --git a/src/priv-csrs.tex b/src/priv-csrs.tex
index 9cff6d6..99db7ce 100644
--- a/src/priv-csrs.tex
+++ b/src/priv-csrs.tex
@@ -197,6 +197,10 @@ Number    & Privilege & Name & Description \\
 \tt 0x105 & SRW  &\tt stvec      & Supervisor trap handler base address. \\
 \tt 0x106 & SRW  &\tt scounteren & Supervisor counter enable. \\
 \hline
+\multicolumn{4}{|c|}{Supervisor Configuration} \\
+\hline
+\tt 0x10A & MRW  &\tt senvcfg    & Supervisor environment configuration register. \\
+\hline
 \multicolumn{4}{|c|}{Supervisor Trap Handling} \\
 \hline
 \tt 0x140 & SRW  &\tt sscratch   & Scratch register for supervisor trap handlers. \\
@@ -243,6 +247,11 @@ Number    & Privilege & Name & Description \\
 \tt 0x64A & HRW  &\tt htinst     & Hypervisor trap instruction (transformed). \\
 \tt 0xE12 & HRO  &\tt hgeip      & Hypervisor guest external interrupt pending. \\
 \hline
+\multicolumn{4}{|c|}{Hypervisor Configuration} \\
+\hline
+\tt 0x60A & MRW  &\tt henvcfg    & Hypervisor environment configuration register. \\
+\tt 0x61A & MRW  &\tt henvcfgh   & Additional hypervisor env. conf. register, RV32 only. \\
+\hline
 \multicolumn{4}{|c|}{Hypervisor Protection and Translation} \\
 \hline
 \tt 0x680 & HRW  &\tt hgatp      & Hypervisor guest address translation and protection. \\
@@ -310,6 +319,13 @@ Number    & Privilege & Name & Description \\
 \tt 0x34A & MRW  &\tt mtinst     & Machine trap instruction (transformed). \\
 \tt 0x34B & MRW  &\tt mtval2     & Machine bad guest physical address. \\
 \hline
+\multicolumn{4}{|c|}{Machine Configuration} \\
+\hline
+\tt 0x30A & MRW  &\tt menvcfg    & Machine environment configuration register. \\
+\tt 0x31A & MRW  &\tt menvcfgh   & Additional machine env. conf. register, RV32 only. \\
+\tt 0x747 & MRW  &\tt mseccfg    & Machine security configuration register. \\
+\tt 0x757 & MRW  &\tt mseccfgh   & Additional machine security conf. register, RV32 only. \\
+\hline
 \multicolumn{4}{|c|}{Machine Memory Protection} \\
 \hline
 %\tt 0x380 & MRW  &\tt mbase      & Base register. \\
diff --git a/src/priv-preface.tex b/src/priv-preface.tex
index 4b943a1..2365622 100644
--- a/src/priv-preface.tex
+++ b/src/priv-preface.tex
@@ -55,6 +55,11 @@ Additionally, the following compatible changes have been made since version
   most of the same fields as the upper 32 bits of RV64's {\tt mstatus}.
 \item Defined the mandatory CSR {\tt mconfigptr}, which if nonzero
   contains the address of a configuration data structure.
+\item Defined optional {\tt mseccfg} and {\tt mseccfgh} CSRs, which control
+ the machine's security configuration.
+\item Defined {\tt menvcfg}, {\tt henvcfg}, and {\tt senvcfg} CSRs
+  (and RV32-only {\tt menvcfgh} and {\tt henvcfgh} CSRs),
+  which control various characteristics of the execution environment.
 \item Designated part of SYSTEM major opcode for custom use.
 \item Permitted the unconditional delegation of less-privileged interrupts.
 \item Added optional big-endian and bi-endian support.
diff --git a/src/supervisor.tex b/src/supervisor.tex
index 8662613..966b483 100644
--- a/src/supervisor.tex
+++ b/src/supervisor.tex
@@ -800,6 +800,122 @@ If the feature to return the faulting instruction bits is implemented, {\tt
 stval} must also be able to hold all values less than $2^N$, where $N$ is the
 smaller of XLEN and ILEN.
 
+\subsection{Supervisor Environment Configuration Register ({\tt senvcfg})}
+
+The {\tt senvcfg} CSR is an SXLEN-bit read/write register,
+formatted as shown in Figure~\ref{fig:senvcfg},
+that controls certain characteristics of the U-mode execution environment.
+
+\begin{figure}[h!]
+{\footnotesize
+\begin{center}
+\begin{tabular}{@{}Kcc@{}W@{}Wc}
+\instbitrange{SXLEN-1}{8} &
+\instbit{7} &
+\instbit{6} &
+\instbitrange{5}{4} &
+\instbitrange{3}{1} &
+\instbit{0} \\
+\hline
+\multicolumn{1}{|c|}{\wpri} &
+\multicolumn{1}{c|}{CBZE} &
+\multicolumn{1}{c|}{CBCFE} &
+\multicolumn{1}{c|}{CBIE} &
+\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{FIOM} \\
+\hline
+SXLEN-8 & 1 & 1 & 2 & 3 & 1 \\
+\end{tabular}
+\end{center}
+}
+\vspace{-0.1in}
+\caption{Supervisor environment configuration register ({\tt senvcfg}).}
+\label{fig:senvcfg}
+\end{figure}
+
+If bit FIOM (Fence of I/O implies Memory) is set to one in {\tt senvcfg},
+FENCE instructions executed in U-mode are modified so
+the requirement to order accesses to device I/O implies also the requirement
+to order main memory accesses.
+Table~\ref{tab:senvcfg-FIOM} details the modified interpretation of
+FENCE instruction bits PI, PO, SI, and SO in U-mode when FIOM=1.
+
+Similarly, for U-mode when FIOM=1,
+if an atomic instruction that accesses a region ordered as device I/O
+has its {\em aq} and/or {\em rl} bit set, then that instruction is ordered
+as though it accesses both device I/O and memory.
+
+If {\tt satp}.MODE is hardwired to Bare, the implementation may hardwire FIOM to zero.
+
+\begin{table}[h!]
+\begin{center}
+\begin{tabular}{|c|l|}
+\hline
+Instruction bit & Meaning when set \\
+\hline
+PI & Predecessor device input and memory reads   (PR implied) \\
+PO & Predecessor device output and memory writes (PW implied) \\
+\hline
+SI & Successor device input and memory reads     (SR implied) \\
+SO & Successor device output and memory writes   (SW implied) \\
+\hline
+\end{tabular}
+\end{center}
+\vspace{-0.1in}
+\caption{%
+Modified interpretation of FENCE predecessor and successor sets in U-mode when FIOM=1.}
+\label{tab:senvcfg-FIOM}
+\end{table}
+
+\begin{commentary}
+Bit FIOM exists for a specific circumstance when an I/O device is
+being emulated for U-mode and both of the following are true:
+(a)~the emulated device has a memory buffer that should be I/O space
+but is actually mapped to main memory via address translation, and
+(b)~multiple physical harts are involved in accessing this emulated
+device from U-mode.
+
+A hypervisor running in S-mode without the benefit of the hypervisor
+extension of Chapter~\ref{hypervisor} may need to emulate a device for
+U-mode if paravirtualization cannot be employed.
+If the same hypervisor provides a virtual machine (VM) with multiple
+virtual harts, mapped one-to-one to real harts, then multiple harts may
+concurrently access the emulated device, perhaps because:
+(a)~the guest OS within the VM assigns device interrupt handling to one
+hart while the device is also accessed by a different hart outside of
+an interrupt handler, or
+(b)~control of the device (or partial control) is being migrated
+from one hart to another, such as for interrupt load balancing within
+the VM.
+For such cases, guest software within the VM is expected to properly
+coordinate access to the (emulated) device across multiple harts using
+mutex locks and/or interprocessor interrupts as usual, which in part
+entails executing I/O fences.
+But those I/O fences may not be sufficient if some of the device
+``I/O'' is actually main memory, unknown to the guest.
+Setting FIOM=1 modifies those fences (and all other I/O fences executed
+in U-mode) to include main memory, too.
+
+Software can always avoid the need to set FIOM by never using main
+memory to emulate a device memory buffer that should be I/O space.
+However, this choice usually requires trapping all U-mode accesses
+to the emulated buffer, which might have a noticeable impact on
+performance.
+The alternative offered by FIOM is sufficiently inexpensive to implement that
+we consider it worth supporting even if only rarely enabled.
+\end{commentary}
+
+
+The definition of the CBZE field will be furnished by the
+forthcoming Zicboz extension.
+Its allocation within {\tt senvcfg} may change prior to the ratification
+of that extension.
+
+The definitions of the CBCFE and CBIE fields will be furnished by the
+forthcoming Zicbom extension.
+Their allocations within {\tt senvcfg} may change prior to the ratification
+of that extension.
+
 \subsection{Supervisor Address Translation and Protection ({\tt satp}) Register}
 \label{sec:satp}