Clarify how the current mode can be observed (#314)

See #302 This does not add a new instruction to read the mode from arbitrary capabilities but does add a suggested sequence to observe the effective mode of the current PCC. Co-authored-by: Andrés Amaya Garcia <[email protected]>
riscv · Jul 8, 2024 · 8f252ca · 8f252ca
1 parent 889c85e
commit 8f252ca
Show file tree

Hide file tree

Showing 3 changed files with 38 additions and 11 deletions.
diff --git a/src/insns/modesw_32bit.adoc b/src/insns/modesw_32bit.adoc
@@ -16,9 +16,6 @@ include::wavedrom/modesw_32bit.adoc[]
 
 include::modesw_common.adoc[]
 
-NOTE: Support of MODESW is optional in debug mode. If it is supported then
- it updates <<dinfc>>.M instead of <<pcc>>.M to show the currrent mode.
-
 Exceptions::
 include::require_cre.adoc[]
 

diff --git a/src/insns/modesw_common.adoc b/src/insns/modesw_common.adoc
@@ -2,8 +2,13 @@
 Description::
 Toggle the hart's current CHERI execution mode in <<pcc>>.
 +
-* If the current mode in <<pcc>> is pass:attributes,quotes[{cheri_int_mode_name}], then the mode bit (M) in <<pcc>> is set to pass:attributes,quotes[{cheri_cap_mode_name}].
-* If the current mode is pass:attributes,quotes[{cheri_cap_mode_name}], then the mode bit (M) in <<pcc>> is set to pass:attributes,quotes[{cheri_int_mode_name}].
-+
-In debug mode MODESW can still be used to change the operating mode, and the current
-mode is shown in the <<m_bit>> of <<dinfc>>.
+* If the current mode in <<pcc>> is pass:attributes,quotes[{cheri_int_mode_name}] ({INT_MODE_VALUE}), then the <<m_bit>> in <<pcc>> is set to pass:attributes,quotes[{cheri_cap_mode_name}] ({CAP_MODE_VALUE}).
+* If the current mode is pass:attributes,quotes[{cheri_cap_mode_name}] ({CAP_MODE_VALUE}), then the <<m_bit>> in <<pcc>> is set to pass:attributes,quotes[{cheri_int_mode_name}] ({INT_MODE_VALUE}).
+
+NOTE: The effective CHERI exection mode is give by the value of some CSRs and
+the <<pcc>>'s <<m_bit>>, so executing <<MODESW>> does not necessarily change
+the machine's current mode. The current, effective CHERI execution mode can be
+observed as described in xref:m_bit_observe[xrefstyle=short].
+
+NOTE: Implementations may optionally support executing <<C_MODESW>> from the
+program buffer while in debug mode.
diff --git a/src/riscv-hybrid-integration.adoc b/src/riscv-hybrid-integration.adoc
@@ -88,6 +88,32 @@ CRE=1 for the current privilege level
 
 When the <<m_bit>> can be set follows the rules defined by <<ACPERM>>.
 
+[#m_bit_observe,reftext="Observing the CHERI Execution Mode"]
+==== Observing the CHERI Execution Mode
+
+The effective CHERI execution mode is given by the values of some CSRs and the
+<<m_bit>> from the PCC. The following code sequences demonstrate how a program
+can observe the current, effective CHERI execution mode depending on the
+machine's privilege mode.
+
+In debug mode, the following sequence executed from the program buffer will
+write {CAP_MODE_VALUE} for pass:attributes,quotes[{cheri_cap_mode_name}] and
+{INT_MODE_VALUE} for pass:attributes,quotes[{cheri_int_mode_name}] to `x1`:
+
+```
+csrr  c1, dinfc
+gctag x1, c1
+```
+
+In any other privilege mode, the following sequence will write {CAP_MODE_VALUE}
+for pass:attributes,quotes[{cheri_cap_mode_name}] and {INT_MODE_VALUE} for
+pass:attributes,quotes[{cheri_int_mode_name}] to `x1`:
+
+```
+auipc c1, 0
+gctag x1, c1
+```
+
 [#section_hybrid_ext_instructions]
 === Zcherihybrid Instructions
 
@@ -247,9 +273,8 @@ shown in xref:default-csrnames-added[xrefstyle=short].
 {cheri_default_ext_name} optionally allows <<MODESW>> to execute in debug mode.
 
 When entering debug mode, the core always enters pass:attributes,quotes[{cheri_cap_mode_name}].
-
-. the mode can be optionally switched using <<MODESW>>.
-. the current mode can always be observed in <<dinfc>>.M.
+Implementations may optionally support switching CHERI execution mode by
+executing the <<MODESW>> from the program buffer.
 
 ifdef::cheri_v9_annotations[]
 NOTE: *CHERI v9 Note:* The mode change instruction <<MODESW>> is new