From 136eb9d6b5379bb2acd9f4186b0d4714616701ea Mon Sep 17 00:00:00 2001
From: Stefan O'Rear <sorear@fastmail.com>
Date: Wed, 31 Jan 2024 07:12:23 -0500
Subject: [PATCH] add mseccfg.CME

A CHERI mode enable for M-mode allows Zcheri_legacy to run full legacy
software stacks, including firmware soon after reset.
---
 src/img/mseccfgreg.edn            | 30 ++++++++++++++++++++++++++++++
 src/riscv-legacy-integration.adoc | 27 +++++++++++++++++++++------
 src/riscv-mode-integration.adoc   |  4 ++--
 3 files changed, 53 insertions(+), 8 deletions(-)
 create mode 100644 src/img/mseccfgreg.edn

diff --git a/src/img/mseccfgreg.edn b/src/img/mseccfgreg.edn
new file mode 100644
index 00000000..12fc3357
--- /dev/null
+++ b/src/img/mseccfgreg.edn
@@ -0,0 +1,30 @@
+[bytefield]
+----
+(defattrs :plain [:plain {:font-family "M+ 1p Fallback"}])
+(def row-height 45)
+(def row-header-fn nil)
+(def boxes-per-row 32)
+(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["" "0" "" "1" "" "2" "" "2" "" "4" "" "7" "" "8" "" "" "9" "" "10" "" "" "" "31" "32" "" "33" "34" "" "" "" "" "" "" "63"])})
+
+(draw-box (text "WPRI" {:font-weight "bold"}) {:span 6})
+(draw-box "PMM" {:span 3})
+(draw-box (text "WPRI" {:font-weight "bold"}) {:span 5})
+(draw-box "SSEED" {:span 3})
+(draw-box "USEED" {:span 3})
+(draw-box (text "WPRI" {:font-weight "bold"}) {:span 3})
+(draw-box "CME" {:span 2})
+(draw-box "RLB" {:span 2})
+(draw-box "MMWP" {:span 3})
+(draw-box "MML" {:span 2})
+
+(draw-box "30" {:span 6 :borders {}})
+(draw-box "2" {:span 3 :borders {}})
+(draw-box "22" {:span 5 :borders {}})
+(draw-box "1" {:span 3 :borders {}})
+(draw-box "1" {:span 3 :borders {}})
+(draw-box "5" {:span 3 :borders {}})
+(draw-box "1" {:span 2 :borders {}})
+(draw-box "1" {:span 2 :borders {}})
+(draw-box "1" {:span 3 :borders {}})
+(draw-box "1" {:span 2 :borders {}})
+----
diff --git a/src/riscv-legacy-integration.adoc b/src/riscv-legacy-integration.adoc
index d401471c..c7dd3291 100644
--- a/src/riscv-legacy-integration.adoc
+++ b/src/riscv-legacy-integration.adoc
@@ -26,8 +26,8 @@ used to authorise all data memory accesses when the current CHERI mode is
 Legacy.
 
 The current CHERI execution mode is given by the current privilege level and
-the value of the CME bit in <<menvcfg>> and <<senvcfg>> for S-mode and U-mode.
-M-mode is always in Capability mode.
+the value of the CME bit in <<mseccfg>>, <<menvcfg>>, and <<senvcfg>> for
+M-mode, S-mode, and U-mode, respectively.
 
 The CHERI execution mode impacts the instruction set in the following ways:
 
@@ -53,8 +53,9 @@ The CHERI execution mode is key in providing backwards compatibility with the
 base RISC-V ISA. RISC-V software is able to execute unchanged in
 implementations supporting both {cheri_base_ext_name} and
 {cheri_legacy_ext_name} provided that the configured CHERI execution mode is
-Legacy by setting CME=0 in <<menvcfg>> or <<senvcfg>> as required, and the
-<<infinite-cap>> capability is installed in the <<pcc>> and <<ddc>> such that:
+Legacy by setting CME=0 in <<mseccfg>>, <<menvcfg>> or <<senvcfg>> as required,
+and the <<infinite-cap>> capability is installed in the <<pcc>> and <<ddc>>
+such that:
 
 * Tags are set
 * Capabilities are unsealed
@@ -262,8 +263,8 @@ cause illegal instruction exceptions
 addresses (xref:csr-numbers-section[xrefstyle=short]) cause illegal
 instruction exceptions
 * All allowed instructions execute as if the CHERI execution mode is Legacy.
-The CME bits in <<menvcfg>> and <<senvcfg>> have no effect whilst CHERI is
-disabled.
+The CME bits in <<mseccfg>>, <<menvcfg>>, and <<senvcfg>> have no effect whilst
+CHERI is disabled.
 
 Security checks continue to be enforced when CHERI is disabled regardless of
 the reason. The last capability installed in <<pcc>> and <<ddc>> before
@@ -331,6 +332,20 @@ value is the <<null-cap>> capability.
 .Machine-mode trap data capability register
 include::img/mtdcreg.edn[]
 
+[#mseccfg,reftext="mseccfg"]
+==== Machine Security Configuration Register (mseccfg)
+
+{cheri_legacy_ext_name} adds a new enable bit to <<mseccfg>> as shown in
+xref:mseccfgmodereg[xrefstyle=short].
+
+.Machine security configuration register (*mseccfg*)
+[#mseccfgmodereg]
+include::img/mseccfgreg.edn[]
+
+The CHERI Mode Enable (CME) bit controls whether M-mode executes in Capability
+or Legacy mode. When CME=1, the CHERI execution mode is Capability. When CME=0,
+the mode is Legacy.  Its reset value is 0.
+
 [#menvcfg,reftext="menvcfg"]
 ==== Machine Environment Configuration Register (menvcfg)
 
diff --git a/src/riscv-mode-integration.adoc b/src/riscv-mode-integration.adoc
index 4e8ccec0..1f57b288 100644
--- a/src/riscv-mode-integration.adoc
+++ b/src/riscv-mode-integration.adoc
@@ -11,8 +11,8 @@ between Capability and Legacy modes using indirect jump instructions.
 The mode bit is encoded as shown in
 xref:cap_encoding_xlen32_mode[xrefstyle=short] and
 xref:cap_encoding_xlen64_mode[xrefstyle=short]. The current CHERI execution
-mode is give by the M bit of the <<pcc>> and the CME bits in <<menvcfg>> and
-<<senvcfg>> as follows:
+mode is give by the M bit of the <<pcc>> and the CME bits in <<mseccfg>>,
+<<menvcfg>>, and <<senvcfg>> as follows:
 
 * The mode is Capability when the M bit of the <<pcc>> is 1 and the effective
 CME=1 for the current privilege level