Merge pull request #1208 from ved-rivos/trap_handler_guidelines

Add note to guide trap handler design

1 files changed, 13 insertions, 0 deletions

diff --git a/src/machine.adoc b/src/machine.adoc
index 2e85dee..269607c 100644
--- a/src/machine.adoc
+++ b/src/machine.adoc
@@ -437,6 +437,19 @@ __y__≠M, __x__RET also sets MPRV=0.
 Setting __x__PP to the least-privileged supported mode on an __x__RET helps identify software bugs in the management of the two-level privilege-mode stack.
 ====
 
+[NOTE]
+====
+Trap handlers must be designed to neither enable interrupts nor cause exceptions
+during the phase of handling where the trap handler preserves the critical state
+information required to handle and resume from the trap. An exception or
+interrupt in this critical phase of trap handling may lead to a trap that can
+overwrite such critical state. This could result in the loss of data needed to
+recover from the initial trap. Further, if an exception occurs in the code path
+needed to handle traps, then such a situation may lead to an infinite loop of
+traps. To prevent this, trap handlers must be meticulously designed to identify
+and safely manage exceptions within their operational flow.
+====
+
 __x__PP fields are *WARL* fields that can hold only privilege mode _x_ and any implemented privilege mode lower than _x_. If privilege mode _x_ is not implemented, then __x__PP must be read-only 0.
 
 [NOTE]