Updated trap section with feedback from jhauser.

1 files changed, 47 insertions, 22 deletions

diff --git a/src/intro.tex b/src/intro.tex
index 20782fd..ddfea66 100644
--- a/src/intro.tex
+++ b/src/intro.tex
@@ -559,21 +559,6 @@ depends on the enclosing execution environment.  From the perspective
 of software running inside an execution environment, traps encountered
 by a hart at runtime can have four different effects:
 \begin{description}
-  \item[Invisible Trap:] The trap is handled transparently by the
-    execution environment and execution resumes normally after the
-    trap is handled.  Examples include emulating missing instructions,
-    handling non-resident page faults in a demand-paged virtual-memory
-    system, or handling device interrupts for a different job in a
-    multiprogrammed machine.  In these cases, the software running
-    inside the execution environment is not aware of the trap (we
-    ignore timing effects in these definitions).
-  \item[Environment Trap:] The trap is a synchronous exception that is
-    an explicit call to the execution environment requesting an action
-    of behalf of software inside the execution environment.  An
-    example is a system call.  In this case, execution may or may not
-    resume on the hart after the requested action is taken by the
-    execution environment.  For example, a system call could remove the
-    hart or cause an orderly exit of the entire execution environment.
   \item[Contained Trap:] The trap is visible to, and handled by,
     software running inside the execution environment.  For example,
     in an execution environment providing both supervisor and user
@@ -582,6 +567,21 @@ by a hart at runtime can have four different effects:
     the same hart.  Similarly, in the same environment, when a hart is
     interrupted, an interrupt handler will be run in supervisor mode
     on the hart.
+  \item[Requested Trap:] The trap is a synchronous exception that is
+    an explicit call to the execution environment requesting an action
+    of behalf of software inside the execution environment.  An
+    example is a system call.  In this case, execution may or may not
+    resume on the hart after the requested action is taken by the
+    execution environment.  For example, a system call could remove the
+    hart or cause an orderly termination of the entire execution environment.
+  \item[Invisible Trap:] The trap is handled transparently by the
+    execution environment and execution resumes normally after the
+    trap is handled.  Examples include emulating missing instructions,
+    handling non-resident page faults in a demand-paged virtual-memory
+    system, or handling device interrupts for a different job in a
+    multiprogrammed machine.  In these cases, the software running
+    inside the execution environment is not aware of the trap (we
+    ignore timing effects in these definitions).
   \item[Fatal Trap:] The trap represents a fatal failure and causes
     the execution environment to terminate execution.  Examples
     include failing a virtual-memory page-protection check or allowing a
@@ -590,12 +590,37 @@ by a hart at runtime can have four different effects:
     environment.
 \end{description}
 
+The following table shows the characteristics of each kind of trap:
+
+\begin{table}[hbt]
+  \centering
+  \begin{tabular}{|l|c|c|c|c|}
+      \hline
+      & Contained & Requested & Invisible & Fatal\\
+      \hline
+      Execution terminates? & N & N$^{1}$ & N & Y \\
+      Software is oblivious? & N & N & Y & Y$^{2}$ \\
+      Handled by environment? & N & Y & Y & Y \\
+      \hline
+  \end{tabular}
+  \caption{Characteristics of traps. Notes 1), termination may be
+    requested, 2) imprecise fatal traps might be observable by software.}
+\end{table}
+
 The execution environment defines for each trap whether it is handled
 precisely, though the recommendation is to maintain preciseness where
-possible.  Invisible traps, by definition, cannot be observed to be
-precise or imprecise by software running inside the execution
-environment.  Environment and contained traps can be observed to be
-imprecise by software inside the execution environment.  Fatal traps
-can be observed to be imprecise by software running inside the
-execution environment, if known-errorful instructions do not cause
-immediate termination.
+possible.  Contained and requested traps can be observed to be
+imprecise by software inside the execution environment.  Invisible
+traps, by definition, cannot be observed to be precise or imprecise by
+software running inside the execution environment.  Fatal traps can be
+observed to be imprecise by software running inside the execution
+environment, if known-errorful instructions do not cause immediate
+termination.
+
+Because this document describes unprivileged instructions, traps are
+rarely mentioned.  Architectural means to handle contained traps are
+defined in the privileged architecture manual.  Unprivileged
+instructions that are defined solely to cause requested traps are
+documented here.  Invisible traps are, by their nature, out of scope
+for this document.  Instruction encodings that are not defined here
+and not defined by some other means may cause a fatal trap.