Attempt to explain SEIP discipline

Closes #53

3 files changed, 46 insertions, 12 deletions

diff --git a/src/machine.tex b/src/machine.tex
index 0a6f37a..2af3382 100644
--- a/src/machine.tex
+++ b/src/machine.tex
@@ -1124,7 +1124,8 @@ The {\tt mip} register is an XLEN-bit read/write register containing
 information on pending interrupts, while {\tt mie} is the
 corresponding XLEN-bit read/write register containing interrupt enable
 bits.  Only the bits corresponding to lower-privilege software
-interrupts (USIP, SSIP) and timer interrupts (UTIP, STIP) in {\tt mip}
+interrupts (USIP, SSIP), timer interrupts (UTIP, STIP),
+and external interrupts (UEIP, SEIP) in {\tt mip}
 are writable through this CSR address; the remaining bits are
 read-only.
 
@@ -1255,13 +1256,30 @@ using uncached I/O writes to memory-mapped control registers depending
 on the platform specification.
 \end{commentary}
 
-The MEIP, SEIP, UEIP bits correspond to external interrupt-pending
-bits for machine, supervisor, and user external interrupts,
-respectively.  These bits are read-only and are set and cleared by a
-platform-specific interrupt controller, such as the standard
-platform-level interrupt controller specified in Chapter~\ref{plic}.
-There is a separate external interrupt-enable bit, named MEIE, SEIE,
-and UEIE for M-mode, S-mode, and U-mode external interrupts
+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, such as the standard platform-level interrupt controller
+specified in Chapter~\ref{plic}.  The MEIE field in {\tt mie} enables machine
+external interrupts when set.
+
+The SEIP field in {\tt mip} is a read-write bit that indicates
+a supervisor-mode external interrupt is pending.  SEIP 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 supervior
+external interrupts.  When the SEIP bit is read with a CSRRW, CSRRS, or CSRRC
+instruction, it appears to contain the logical-OR of the software-writable bit
+and the interrupt signal from the interrupt controller.  However, when the
+SEIP bit is written with a CSRRS or CSRRC instruction, only the
+software-writable portion of the SEIP bit affects the new value written to the
+{\tt mip} CSR.  The signal from the interrupt controller does {\em not}
+participate in a CSRRS or CSRRC read-modify-write sequence.
+
+The UEIP field in {\tt mip} provides user-mode external interrupts when the
+N extension for user-mode interrupts is implemented.  It is defined
+analogously to SEIP.
+
+The MEIE, SEIE, and UEIE fields in the {\tt mie} CSR enable M-mode external
+interrupts, S-mode external interrupts, and U-mode external interrupts,
 respectively.
 
 \begin{commentary}
diff --git a/src/priv-preface.tex b/src/priv-preface.tex
index 31a6177..8d985be 100644
--- a/src/priv-preface.tex
+++ b/src/priv-preface.tex
@@ -20,6 +20,8 @@ architecture proposal.  Changes from version 1.9.1 include:
   and user modes has been added to the {\tt mstatus} CSR, and the
   field previously called Base in {\tt misa} has been renamed to {\tt
     MXL} for consistency.
+\item The SEIP and UEIP bits in the {\tt mip} CSR have been redefined
+  to support software injection of external interrupts.
   \item The {\tt mbadaddr} register has been subsumed by a more
     general {\tt mtval} register that can now capture bad
     instruction bits on an illegal instruction fault to speed
diff --git a/src/supervisor.tex b/src/supervisor.tex
index 9aa0cdb..6a2d7a5 100644
--- a/src/supervisor.tex
+++ b/src/supervisor.tex
@@ -345,7 +345,7 @@ USIP bit in {\tt sip}.  User-level software interrupts are disabled when the
 USIE bit in the {\tt sie} register is clear.  If user-level interrupts are not
 supported, USIP and USIE are hardwired to zero.
 
-All bits besides SSIP and USIP in the {\tt sip} register are read-only.
+All bits besides SSIP, USIP, and UEIP in the {\tt sip} register are read-only.
 
 A supervisor-level timer interrupt is pending if the STIP bit in the {\tt sip}
 register is set.  Supervisor-level timer interrupts are disabled when the STIE
@@ -365,9 +365,23 @@ when the SEIE bit in the {\tt sie} register is clear.  The SBI should provide
 facilities to mask, unmask, and query the cause of external interrupts.
 
 A user-level external interrupt is pending if the UEIP bit in the
-{\tt sip} register is set.  User-level external interrupts are disabled
-when the UEIE bit in the {\tt sie} register is clear.  If user-level
-interrupts are not supported, UEIP and UEIE are hardwired to zero.
+{\tt sip} register is set.
+
+The UEIP field in {\tt sip} is a read-write bit that indicates a user-mode
+external interrupt is pending.  UEIP may be written by S-mode software to
+indicate to S-mode that an external interrupt is pending.  Additionally, the
+platform-level interrupt controller may generate user-level external
+interrupts.  When the UEIP bit is read with a CSRRW, CSRRS, or CSRRC
+instruction, it appears to contain the logical-OR of the software-writable bit
+and the interrupt signal from the interrupt controller.  However, when the UEIP
+bit is written with a CSRRS or CSRRC instruction, only the software-writable
+portion of the UEIP bit affects the new value written to the {\tt sip} CSR.
+The user-level interrupt signal from the interrupt controller does {\em not}
+participate in a CSRRS or CSRRC read-modify-write sequence.
+
+User-level external interrupts are disabled when the UEIE bit in the {\tt sie}
+register is clear.  If the N extension for user-level interrupts is not
+implemented, UEIP and UEIE are hardwired to zero.
 
 \begin{commentary}
 The {\tt sip} and {\tt sie} registers are subsets of the {\tt mip} and {\tt