Improve interrupt-delegation description

h/t @jhauser-us

1 files changed, 163 insertions, 116 deletions

diff --git a/src/machine.tex b/src/machine.tex
index b944b41..670595c 100644
--- a/src/machine.tex
+++ b/src/machine.tex
@@ -1309,36 +1309,81 @@ For exceptions that cannot occur in less privileged modes, the corresponding
 The {\tt mip} register is an MXLEN-bit read/write register containing
 information on pending interrupts, while {\tt mie} is the
 corresponding MXLEN-bit read/write register containing interrupt enable
-bits.  Only the bits corresponding to lower-privilege software
-interrupts (SSIP), timer interrupts (STIP),
-and external interrupts (SEIP) in {\tt mip}
-are writable through this CSR address; the remaining bits are
+bits.
+Interrupt cause number \textit{i} (as reported in CSR {\tt mcause},
+Section~\ref{sec:mcause}) corresponds with bit~\textit{i} in both
+{\tt mip} and {\tt mie}.
+Bits 15:0 are allocated to standard interrupt causes only, while bits 16
+and above are available for platform or custom use.
+
+\begin{figure}[h!]
+{\footnotesize
+\begin{center}
+\begin{tabular}{@{}U}
+\instbitrange{MXLEN-1}{0} \\
+\hline
+\multicolumn{1}{|c|}{Interrupts (\warl)} \\
+\hline
+MXLEN \\
+\end{tabular}
+\end{center}
+}
+\vspace{-0.1in}
+\caption{Machine Interrupt-Pending Register ({\tt mip}).}
+\label{mipreg}
+\end{figure}
+
+\begin{figure}[h!]
+{\footnotesize
+\begin{center}
+\begin{tabular}{@{}U}
+\instbitrange{MXLEN-1}{0} \\
+\hline
+\multicolumn{1}{|c|}{Interrupts (\warl)} \\
+\hline
+MXLEN \\
+\end{tabular}
+\end{center}
+}
+\vspace{-0.1in}
+\caption{Machine Interrupt-Enable Register ({\tt mie}).}
+\label{miereg}
+\end{figure}
+
+An interrupt \textit{i} will be taken if bit \textit{i} is set in both
+{\tt mip} and {\tt mie}, and if interrupts are globally enabled.  By
+default, M-mode interrupts are globally enabled if the hart's current
+privilege mode is less than M, or if the current privilege mode is M
+and the MIE bit in the {\tt mstatus} register is set.  If bit \textit{i}
+in {\tt mideleg} is set, however, interrupts are considered to be
+globally enabled if the hart's current privilege mode equals the
+delegated privilege mode and that mode's interrupt enable
+bit (\textit{x}\,IE in {\tt mstatus} for mode~\textit{x}) is set,
+or if the current
+privilege mode is less than the delegated privilege mode.
+
+Each individual bit in register {\tt mip} may be writable or may be
 read-only.
+When bit~\textit{i} in {\tt mip} is writable, a pending interrupt
+\textit{i} can be cleared by writing 0 to this bit.
+If interrupt \textit{i} can become pending but bit~\textit{i} in
+{\tt mip} is read-only, the implementation must provide some other
+mechanism for clearing the pending interrupt.
 
-\begin{commentary}
-  The machine-level interrupt registers handle a few root interrupt
-  sources which are assigned a fixed service priority for simplicity,
-  while separate external interrupt controllers can implement a more
-  complex prioritization scheme over a much larger set of interrupts
-  that are then muxed into the machine-level interrupt sources.
-\end{commentary}
+A bit in {\tt mie} must be writable if the corresponding interrupt can
+ever become pending.
+Bits of {\tt mie} that are not writable must be hardwired to zero.
 
-Restricted views of the {\tt mip} and {\tt mie} registers appear as
-the {\tt sip} and {\tt sie} registers for supervisor level.
-If an interrupt is delegated to
-S-mode by setting a bit in the {\tt mideleg} register,
-it becomes visible in the {\tt sip} register and is maskable
-using the {\tt sie} register.  Otherwise, the corresponding
-bits in {\tt sip} and {\tt sie} appear to be hardwired
-to zero.
+The standard portions (bits 15:0) of registers {\tt mip} and {\tt mie}
+are formatted as shown in Figures \ref{mipreg-standard} and
+\ref{miereg-standard} respectively.
 
 \begin{figure*}[h!]
 {\footnotesize
 \begin{center}
 \setlength{\tabcolsep}{4pt}
-\scalebox{0.95}{
 \begin{tabular}{Rcccccccccccc}
-\instbitrange{MXLEN-1}{12} &
+\instbitrange{15}{12} &
 \instbit{11} &
 \instbit{10} &
 \instbit{9} &
@@ -1352,36 +1397,35 @@ to zero.
 \instbit{1} &
 \instbit{0} \\
 \hline
-\multicolumn{1}{|c|}{\wpri} &
+\multicolumn{1}{|c|}{0} &
 \multicolumn{1}{c|}{MEIP} &
-\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{0} &
 \multicolumn{1}{c|}{SEIP} &
-\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{0} &
 \multicolumn{1}{c|}{MTIP} &
-\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{0} &
 \multicolumn{1}{c|}{STIP} &
-\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{0} &
 \multicolumn{1}{c|}{MSIP} &
-\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{0} &
 \multicolumn{1}{c|}{SSIP} &
-\multicolumn{1}{c|}{\wpri} \\
+\multicolumn{1}{c|}{0} \\
 \hline
-MXLEN-12 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 \\
-\end{tabular}}
+4 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 \\
+\end{tabular}
 \end{center}
 }
 \vspace{-0.1in}
-\caption{Machine interrupt-pending register ({\tt mip}).}
-\label{mipreg}
+\caption{Standard portion (bits 15:0) of {\tt mip}.}
+\label{mipreg-standard}
 \end{figure*}
 
 \begin{figure*}[h!]
 {\footnotesize
 \begin{center}
 \setlength{\tabcolsep}{4pt}
-\scalebox{0.95}{
 \begin{tabular}{Rcccccccccccc}
-\instbitrange{MXLEN-1}{12} &
+\instbitrange{15}{12} &
 \instbit{11} &
 \instbit{10} &
 \instbit{9} &
@@ -1395,82 +1439,80 @@ MXLEN-12 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 \\
 \instbit{1} &
 \instbit{0} \\
 \hline
-\multicolumn{1}{|c|}{\wpri} &
+\multicolumn{1}{|c|}{0} &
 \multicolumn{1}{c|}{MEIE} &
-\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{0} &
 \multicolumn{1}{c|}{SEIE} &
-\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{0} &
 \multicolumn{1}{c|}{MTIE} &
-\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{0} &
 \multicolumn{1}{c|}{STIE} &
-\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{0} &
 \multicolumn{1}{c|}{MSIE} &
-\multicolumn{1}{c|}{\wpri} &
+\multicolumn{1}{c|}{0} &
 \multicolumn{1}{c|}{SSIE} &
-\multicolumn{1}{c|}{\wpri} \\
+\multicolumn{1}{c|}{0} \\
 \hline
-MXLEN-12 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 \\
-\end{tabular}}
+4 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 & 1 \\
+\end{tabular}
 \end{center}
 }
 \vspace{-0.1in}
-\caption{Machine interrupt-enable register ({\tt mie}).}
-\label{miereg}
+\caption{Standard portion (bits 15:0) of {\tt mie}.}
+\label{miereg-standard}
 \end{figure*}
 
-The MTIP and STIP bits correspond to timer interrupt-pending bits
-for machine and supervisor timer interrupts, respectively.  The
-MTIP bit is read-only and is cleared by writing to the memory-mapped
-machine-mode timer compare register.  The STIP bit may be
-written by M-mode software to deliver timer interrupts to S-mode.
-Supervisor software may clear the STIP bit with a call to the SEE.
+\begin{commentary}
+  The machine-level interrupt registers handle a few root interrupt
+  sources which are assigned a fixed service priority for simplicity,
+  while separate external interrupt controllers can implement a more
+  complex prioritization scheme over a much larger set of interrupts
+  that are then muxed into the machine-level interrupt sources.
+\end{commentary}
 
-There is a separate timer interrupt-enable bit, named MTIE and STIE,
-for M-mode and S-mode timer interrupts respectively.
+\begin{commentary}
+The non-maskable interrupt is not made visible via the {\tt mip}
+register as its presence is implicitly known when executing the NMI
+trap handler.
+\end{commentary}
 
-Supervisor level has a software interrupt-pending
-bit (SSIP), which can be both read and written by CSR accesses
-from code running on the local hart in S-mode or M-mode.
-The machine-level MSIP bit is written by accesses
-to memory-mapped control registers, which are used by remote harts to
-provide machine-mode interprocessor interrupts.  Interprocessor
-interrupts at supervisor level are implemented through
-implementation-specific mechanisms, e.g., via calls to an SEE,
-which might ultimately result in
-a machine-mode write to the receiving hart's MSIP bit.  A hart can write its
-own MSIP bit using the same memory-mapped control register.
+Bits {\tt mip}.MEIP and {\tt mie}.MEIE are the interrupt-pending and
+interrupt-enable bits for machine-level external interrupts.
+MEIP is read-only in {\tt mip}, and is set and cleared by a
+platform-specific interrupt controller.
 
-The MSIE and SSIE fields in the {\tt mie} CSR enable M-mode software
-interrupts and S-mode software interrupts, respectively.
+Bits {\tt mip}.MTIP and {\tt mie}.MTIE are the interrupt-pending and
+interrupt-enable bits for machine timer interrupts.
+MTIP is read-only in {\tt mip}, and is cleared by writing to the memory-mapped
+machine-mode timer compare register.
 
-\begin{commentary}
-We allow a hart to directly write only its own SSIP bit, not those of other
-harts, as other harts might be
-virtualized and possibly descheduled by higher privilege levels.  We
-rely on calls to the SEE to provide interprocessor interrupts
-for this reason.  Machine-mode harts are not virtualized and can
-directly interrupt other harts by setting their MSIP bits, typically
-using uncached I/O writes to memory-mapped control registers depending
-on the platform specification.
-\end{commentary}
+Bits {\tt mip}.MSIP and {\tt mie}.MSIE are the interrupt-pending and
+interrupt-enable bits for machine-level software interrupts.
+MSIP is read-only in {\tt mip}, and is written by accesses
+to memory-mapped control registers, which are used by remote harts to
+provide machine-level interprocessor interrupts.
+A hart can write its
+own MSIP bit using the same memory-mapped control register.
 
-The MEIP field in {\tt mip} is a read-only bit that indicates a machine-mode
-external interrupt is pending.  MEIP is set and cleared by a platform-specific
-interrupt controller.  The MEIE field in {\tt mie} enables machine
-external interrupts when set.
+If supervisor mode is not implemented, bits SEIP, STIP, and SSIP of
+{\tt mip} and SEIE, STIE, and SSIE of {\tt mie} are hardwired to zeros.
 
-The SEIP field in {\tt mip} contains a single read-write bit.  SEIP
+If supervisor mode is implemented, bits {\tt mip}.SEIP and {\tt mie}.SEIE
+are the interrupt-pending and interrupt-enable bits for supervisor-level
+external interrupts.
+SEIP is writable in {\tt mip}, and
 may be written by M-mode software to indicate to S-mode that an
 external interrupt is pending.  Additionally, the platform-level
-interrupt controller may generate supervisor-level external interrupts.  The
-logical-OR of the software-writable bit and the signal from the
-external interrupt controller is used to generate external interrupts
-to the supervisor.  When the SEIP bit is read with a CSRRW, CSRRS, or
-CSRRC instruction, the value returned in the {\tt rd} destination
-register contains the logical-OR of the software-writable bit and the
+interrupt controller may generate supervisor-level external interrupts.
+Supervisor-level external interrupts are made pending based on the
+logical-OR of the software-writable SEIP bit and the signal from the
+external interrupt controller.
+When {\tt mip} is read with a CSR instruction,
+the value of the SEIP bit returned in the {\tt rd} destination
+register is the logical-OR of the software-writable bit and the
 interrupt signal from the interrupt controller.  However, the value
 used in the read-modify-write sequence of a CSRRS or CSRRC instruction
-is only the software-writable SEIP bit, ignoring the interrupt value
+contains only the software-writable SEIP bit, ignoring the interrupt value
 from the external interrupt controller.
 
 \begin{commentary}
@@ -1480,37 +1522,33 @@ from the external interrupt controller.
   slightly modified from regular CSR accesses as a result.
 \end{commentary}
 
-The MEIE and SEIE fields in the {\tt mie} CSR enable M-mode external
-interrupts and S-mode external interrupts, respectively.
-
-\begin{commentary}
-The non-maskable interrupt is not made visible via the {\tt mip}
-register as its presence is implicitly known when executing the NMI
-trap handler.
-\end{commentary}
+If supervisor mode is implemented, bits {\tt mip}.STIP and {\tt mie}.STIE
+are the interrupt-pending and interrupt-enable bits for supervisor-level
+timer interrupts.
+STIP is writable in {\tt mip}, and may be
+written by M-mode software to deliver timer interrupts to S-mode.
 
-For all the various interrupt types (software, timer, and external),
-if a privilege level is not supported, then the associated pending and
-interrupt-enable bits are hardwired to zero in the {\tt mip} and {\tt
-  mie} registers respectively.  Hence, these are all effectively
-\warl\ fields.
+If supervisor mode is implemented, bits {\tt mip}.SSIP and {\tt mie}.SSIE
+are the interrupt-pending and interrupt-enable bits for supervisor-level
+software interrupts.
+SSIP is writable in {\tt mip}.
 
-Implementations may add additional platform-specific interrupt sources to bits
-16 and above of the {\tt mip} and {\tt mie} registers.  Some platforms may
-make custom use of these interrupts.  The other unallocated interrupt
-sources (0, 2, 4, 6, 8, 10, and 12--15) are reserved for other possible
-standardized uses.
+\begin{commentary}
+Interprocessor
+interrupts at supervisor level are implemented through
+implementation-specific mechanisms, e.g., via calls to an SEE,
+which might ultimately result in
+a machine-mode write to the receiving hart's MSIP bit.
 
-An interrupt {\em i} will be taken if bit {\em i} is set in both {\tt
-  mip} and {\tt mie}, and if interrupts are globally enabled.  By
-default, M-mode interrupts are globally enabled if the hart's current
-privilege mode is less than M, or if the current privilege mode is M
-and the MIE bit in the {\tt mstatus} register is set.  If bit {\em i}
-in {\tt mideleg} is set, however, interrupts are considered to be
-globally enabled if the hart's current privilege mode equals the
-delegated privilege mode and that mode's interrupt enable
-bit ({\em x}\,IE in {\tt mstatus} for mode~{\em x}) is set, or if the current
-privilege mode is less than the delegated privilege mode.
+We allow a hart to directly write only its own SSIP bit, not those of other
+harts, as other harts might be
+virtualized and possibly descheduled by higher privilege levels.  We
+rely on calls to the SEE to provide interprocessor interrupts
+for this reason.  Machine-mode harts are not virtualized and can
+directly interrupt other harts by setting their MSIP bits, typically
+using uncached I/O writes to memory-mapped control registers depending
+on the platform specification.
+\end{commentary}
 
 Multiple simultaneous interrupts destined for different privilege modes are
 handled in decreasing order of destined privilege mode.  Multiple simultaneous
@@ -1548,6 +1586,15 @@ Synchronous exceptions are of lower priority than all interrupts.
   worst-case interrupt latency.
 \end{commentary}
 
+Restricted views of the {\tt mip} and {\tt mie} registers appear as
+the {\tt sip} and {\tt sie} registers for supervisor level.
+If an interrupt is delegated to
+S-mode by setting a bit in the {\tt mideleg} register,
+it becomes visible in the {\tt sip} register and is maskable
+using the {\tt sie} register.  Otherwise, the corresponding
+bits in {\tt sip} and {\tt sie} appear to be hardwired
+to zero.
+
 \subsection{Machine Timer Registers ({\tt mtime} and {\tt mtimecmp})}
 
 Platforms provide a real-time counter, exposed as a memory-mapped