capability mode enables and register access controls for Zcheri_legacy (

#81) A CHERI mode enable for M-mode allows Zcheri_legacy to run full legacy software stacks, including firmware soon after reset. This also removes the behavioral difference between Zcheri_legacy and Zcheri_mode in terms of the instruction set in effect after reset, making Zcheri_mode a true extension of Zcheri_legacy. CHERI register access disables for S-mode and U-mode allow Zcheri_legacy to prevent cross-domain interference and covert channels within a legacy environment. These two are the strictly additive part of #39. --------- Signed-off-by: Tariq Kurd <[email protected]> Co-authored-by: Tariq Kurd <[email protected]>
riscv · Feb 20, 2024 · 885b0a8 · 885b0a8
1 parent 00211d1
commit 885b0a8
Show file tree

Hide file tree

Showing 5 changed files with 100 additions and 29 deletions.
diff --git a/src/img/menvcfgmodereg.edn b/src/img/menvcfgmodereg.edn
@@ -4,24 +4,26 @@
 (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" "3" "4" "5" "6" "" "7" "" "8" "" "" "" "" "" "" "27" "28" "" "29" "" "" "" "" "" "" "61" "" "62" "" "63"])})
+(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "1" "3" "4" "5" "6" "" "7" "" "8" "" "" "" "" "" "27" "28" "" "29" "" "30" "" "" "" "" "" "61" "" "62" "" "63"])})
 
 (draw-box "STCE" {:span 2})
 (draw-box "PBMTE" {:span 2})
-(draw-box (text "WPRI" {:font-weight "bold"}) {:span 8})
+(draw-box (text "WPRI" {:font-weight "bold"}) {:span 7})
+(draw-box "CRE" {:span 2})
 (draw-box "CME" {:span 2})
-(draw-box (text "WPRI" {:font-weight "bold"}) {:span 8})
+(draw-box (text "WPRI" {:font-weight "bold"}) {:span 7})
 (draw-box "CBZE" {:span 2})
 (draw-box "CBCFE" {:span 2})
 (draw-box "CBIE" {:span 2})
-(draw-box "WPRI" {:span 2})
+(draw-box (text "WPRI" {:font-weight "bold"}) {:span 2})
 (draw-box "FIOM" {:span 2})
 
 (draw-box "1" {:span 2 :borders {}})
 (draw-box "1" {:span 2 :borders {}})
-(draw-box "34" {:span 8 :borders {}})
+(draw-box "32" {:span 7 :borders {}})
 (draw-box "1" {:span 2 :borders {}})
-(draw-box "19" {:span 8 :borders {}})
+(draw-box "1" {:span 2 :borders {}})
+(draw-box "20" {:span 7 :borders {}})
 (draw-box "1" {:span 2 :borders {}})
 (draw-box "1" {:span 2 :borders {}})
 (draw-box "2" {:span 2 :borders {}})

diff --git a/src/img/mseccfgreg.edn 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" "" "3" "" "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 "4" {: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/img/senvcfgreg.edn b/src/img/senvcfgreg.edn
@@ -6,20 +6,22 @@
 (def left-margin 30)
 (def right-margin 30)
 (def boxes-per-row 32)
-(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "1" "3" "4" "5" "6" "" "7" "" "8" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "27" "28" "" "29" "" "" "SXLEN-1"])})
+(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "1" "3" "4" "5" "6" "" "7" "" "8" "" "" "" "" "" "" "" "" "" "" "" "" "27" "28" "" "29" "" "30" "" "" "SXLEN-1"])})
 
 (draw-box (text "WPRI" {:font-weight "bold" :font-size 20}) {:span 4})
+(draw-box "CRE" {:span 2})
 (draw-box "CME" {:span 2})
-(draw-box (text "WPRI" {:font-weight "bold" :font-size 20}) {:span 16})
+(draw-box (text "WPRI" {:font-weight "bold" :font-size 20}) {:span 14})
 (draw-box "CBZE" {:span 2})
 (draw-box "CBCFE" {:span 2})
 (draw-box "CBIE" {:span 2})
 (draw-box (text "WPRI" {:font-weight "bold" :font-size 20}) {:span 2})
 (draw-box "FIOM" {:span 2})
 
-(draw-box "SXLEN-29" {:span 4 :borders {}})
+(draw-box "SXLEN-30" {:span 4 :borders {}})
 (draw-box "1" {:span 2 :borders {}})
-(draw-box "20" {:span 16 :borders {}})
+(draw-box "1" {:span 2 :borders {}})
+(draw-box "20" {:span 14 :borders {}})
 (draw-box "1" {:span 2 :borders {}})
 (draw-box "1" {:span 2 :borders {}})
 (draw-box "2" {:span 2 :borders {}})

diff --git 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:
 
@@ -52,8 +52,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
@@ -231,17 +232,16 @@ As shown in xref:CSR_exevectors[xrefstyle=short], <<dddc>> is a data pointer,
 so it does not need to be able to hold all possible invalid addresses.
 
 [#section_cheri_disable]
-=== Disabling CHERI Features
+=== Disabling CHERI Registers
 
 ifdef::cheri_v9_annotations[]
 NOTE: *CHERI v9 Note:* The rules for excepting have been tightened here. Also,
 it is not possible to disable CHERI checks completely.
 endif::[]
 
-{cheri_legacy_ext_name} includes functions to disable most CHERI features. For
-example, executing in a privilege mode where the effective XLEN is less than
-XLENMAX. The following occurs when executing code in a privileged mode that has
-CHERI disabled:
+{cheri_legacy_ext_name} includes functions to disable explicit access to CHERI
+registers.  The following occurs when executing code in a privilege mode that
+has CHERI register access disabled:
 
 * The CHERI instructions in xref:section_cap_instructions[xrefstyle=short] (and
 xref:instruction-modes[xrefstyle=short] if {cheri_mode_ext_name} is supported)
@@ -250,13 +250,21 @@ 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 register access 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
-disabling CHERI will be used to authorise instruction execution and data memory
-accesses.
+CHERI register access is disabled if XLEN in the current mode is less than
+XLENMAX or if CRE active at the current mode (<<menvcfg>>.CRE for S-mode or
+<<senvcfg>>.CRE for U-mode) is 0.
+
+Disabling CHERI register access has no effect on implicit accesses or security
+checks.  The last capability installed in <<pcc>> and <<ddc>> before disabling
+CHERI register access will be used to authorise instruction execution and data
+memory accesses.
+
+NOTE: Disabling CHERI register access prevents a low-privileged Legacy mode
+from interfering with the correct operation of higher-privileged Legacy modes
+that do not perform <<ddc>> switches on trap entry and return.
 
 === Added CLEN-wide CSRs
 
@@ -296,6 +304,9 @@ Setting the SXL or UXL field to a value that is not XLENMAX disables most
 CHERI features and instructions, as described in
 xref:section_cheri_disable[xrefstyle=short], while in that privilege mode.
 
+NOTE: If CHERI register access must be disabled in a mode for security reasons,
+software should set CRE to 0 regardless of the SXL and UXL fields.
+
 Whenever XLEN in any mode is set to a value less than XLENMAX, standard RISC-V
 rules from cite:[riscv-unpriv-spec] are followed. This means that all operations
 must ignore source operand register bits above the configured XLEN, and must
@@ -331,10 +342,24 @@ 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)
 
-{cheri_legacy_ext_name} adds a new enable bit to <<menvcfg>> as shown in
+{cheri_legacy_ext_name} adds two new enable bits to <<menvcfg>> as shown in
 xref:menvcfgmodereg[xrefstyle=short].
 
 .Machine environment configuration register (*menvcfg*)
@@ -345,6 +370,12 @@ The CHERI Mode Enable (CME) bit controls whether less privileged levels (e.g.
 S-mode and U-mode) execute in Capability or Legacy mode. When CME=1, the
 CHERI execution mode is Capability. When CME=0, the mode is Legacy.
 
+The CHERI Register Enable (CRE) bit controls whether less privileged levels can
+perform explicit accesses to CHERI registers.  When CRE=1, CHERI registers can
+be read and written by less privileged levels.  When CRE=0, CHERI registers are
+disabled in less privileged levels as described in
+xref:section_cheri_disable[xrefstyle=short].
+
 [#stdc,reftext="stdc"]
 ==== Supervisor Trap Default Capability Register (stdc)
 
@@ -361,7 +392,7 @@ include::img/stdcreg.edn[]
 ==== Supervisor Environment Configuration Register (senvcfg)
 
 The *senvcfg* register operates as described in the RISC-V Privileged
-Specification. {cheri_legacy_ext_name} adds one new enable bit as shown in
+Specification. {cheri_legacy_ext_name} adds two new enable bits as shown in
 xref:senvcfgreg[xrefstyle=short].
 
 .Supervisor environment configuration register (*senvcfg*)
@@ -372,6 +403,12 @@ The CHERI Mode Enable (CME) bit controls whether U-mode executes in Capability
 or Legacy mode. When CME=1, the CHERI execution mode is Capability. When CME=0,
 the mode is Legacy.
 
+The CHERI Register Enable (CRE) bit controls whether U-mode can perform
+explicit accesses to CHERI registers.  When CRE=1, CHERI registers can be read
+and written by U-mode.  When CRE=0, CHERI registers are in U-mode disabled as
+described in xref:section_cheri_disable[xrefstyle=short].  CRE is read-only
+zero if <<menvcfg>>.CRE=0.
+
 [#ddc,reftext="ddc"]
 ==== Default Data Capability (ddc)
 

diff --git a/src/riscv-mode-integration.adoc b/src/riscv-mode-integration.adoc
@@ -12,8 +12,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