diff --git a/Makefile b/Makefile index b1b8a3f1..9fbdba17 100644 --- a/Makefile +++ b/Makefile @@ -18,7 +18,7 @@ GEN_SCRIPT = $(SCRIPTS_DIR)/generate_tables.py # Version and date DATE ?= $(shell date +%Y-%m-%d) -VERSION ?= v0.9.3 +VERSION ?= v0.9.4 REVMARK ?= Draft # Directories and files diff --git a/readme.adoc b/readme.adoc index 32c5e5b7..f0df1e8b 100644 --- a/readme.adoc +++ b/readme.adoc @@ -21,9 +21,13 @@ For guidelines on how to contribute, refer to the link:CONTRIBUTING.md[CONTRIBUT To build the document, you'll need the following tools installed on your system: * Make -* asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, and asciidoctor-mathematical * Docker + +If you want to build outside of Docker, you'll need some more tools: * Python3 +* asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram, asciidoctor-mathematical and asciidoctor-sail +* bytefield-svg +* wavedrom-cli === Cloning the Repository diff --git a/src/cap-description.adoc b/src/cap-description.adoc index 1cbc126a..1cef3b15 100644 --- a/src/cap-description.adoc +++ b/src/cap-description.adoc @@ -445,12 +445,17 @@ Reconstituting the top two bits of T: T[MW - 1:MW - 2] = B[MW - 1:MW - 2] + LCout + LMSB ``` -Decoding the bounds: +The bounds are decoded as shown in xref:top_bound_dec[xrefstyle=short] and +xref:base_bound_dec[xrefstyle=short]. + +.Decoding of the MXLEN+1 wide top (_t_) bound +[#top_bound_dec] +include::img/top-bound-dec.edn[] + +.Decoding of the MXLEN wide base (_b_) bound +[#base_bound_dec] +include::img/base-bound-dec.edn[] -``` -top: t = { {1'b0, a[MXLEN - 1:E + MW]} + ct, T[MW - 1:0], {E{1'b0}} } -base: b = { a[MXLEN - 1:E + MW] + cb, B[MW - 1:0], {E{1'b0}} } -``` The corrections c~t~ and c~b~ are calculated as as shown below using the definitions in xref:cap_encoding_ct[xrefstyle=short] and xref:cap_encoding_cb[xrefstyle=short]. diff --git a/src/cheri-pte-ext.adoc b/src/cheri-pte-ext.adoc index fdcb13bb..6ba25a19 100644 --- a/src/cheri-pte-ext.adoc +++ b/src/cheri-pte-ext.adoc @@ -107,6 +107,9 @@ The CW bit indicates whether reading or writing capabilities with the tag set to the virtual page is permitted. When the CW bit is set, capabilities are written as usual, and capability reads are controlled by the CRG bit. +NOTE: The tag bit of the stored capability is checked _after_ it is potentially +cleared <>. + If the CW bit is clear then: * When a capability load or AMO instruction is executed, the implementation @@ -115,10 +118,6 @@ If the CW bit is clear then: is raised when a capability store or AMO instruction is executed and the tag bit of the capability being written is set. * When CRG is set, the "pre-CW state", two schemes are permitted (also see <>): - -NOTE: The tag bit of the stored capability is checked _after_ it is potentially -cleared <>. - ** The same behavior as when CRG is clear, allowing software interpretation of this state. ** When a capability store or AMO instruction is executed diff --git a/src/csv/CHERI_CSR.csv b/src/csv/CHERI_CSR.csv index 9dfdc193..9d10265e 100644 --- a/src/csv/CHERI_CSR.csv +++ b/src/csv/CHERI_CSR.csv @@ -37,9 +37,6 @@ direct write if address didn't change","✔","","","","Zcmt","Jump Vector Table "dddc","0x7bc","","D","DRW","tag=0, otherwise undefined","Apply <>. Always update the CSR with <> even if the address didn't change.","Apply <> and update the CSR with the result if the address changed, direct write if address didn't change","","✔","","","{cheri_default_ext_name}, Sdext","Debug Default Data Capability (saved/restored on debug mode entry/exit)","","","","","","","","","","","","","","","","","","","","","" -"mtdc","0x74c","","M","MRW, <>","tag=0, otherwise undefined","Update the CSR using <>.","direct write","","","","","{cheri_default_ext_name}, M-mode","Machine Trap Data Capability (scratch register)","","","","","","","","","","","","","","","","","","","","","" -"stdc","0x163","","S","SRW, <>","tag=0, otherwise undefined","Update the CSR using <>.","direct write","","","","","{cheri_default_ext_name}, S-mode","Supervisor Trap Data Capability (scratch register)","","","","","","","","","","","","","","","","","","","","","" -"vstdc","0x245","","VS","HRW, <>","tag=0, otherwise undefined","Update the CSR using <>.","direct write","","","","","{cheri_default_ext_name}, H","Virtual Supervisor Trap Data Capability (scratch register)","","","","","","","","","","","","","","","","","","","","","" "ddc","0x416","","U","URW","<>","Apply <>. Always update the CSR with <> even if the address didn't change.","Apply <> and update the CSR with the result if the address changed, direct write if address didn't change","","✔","","","{cheri_default_ext_name}","User Default Data Capability","","","","","","","","","","","","","","","","","","","","","" diff --git a/src/hypervisor-integration.adoc b/src/hypervisor-integration.adoc index e996788a..7c3eb94e 100644 --- a/src/hypervisor-integration.adoc +++ b/src/hypervisor-integration.adoc @@ -146,22 +146,6 @@ The <> register is as defined in cite:[riscv-priv-spec]. It must additionally support the new exception code for CHERI exceptions that <> supports. -[#vstdc,reftext="vstdc"] -=== Virtual Supervisor Trap Default Capability Register (vstdc) - -The <> register is a capability width read/write register that is -VS-mode's version of supervisor register <>. This register is only -present when the implementation supports {cheri_default_ext_name}. - -{TAG_RESET_CSR} - -{REQUIRE_CRE_CSR} - -{REQUIRE_HYBRID_CSR} - -.Virtual supervisor trap default capability register -include::img/vstdcreg.edn[] - [#vstval,reftext="vstval"] === Virtual Supervisor Trap Value Register (vstval) @@ -182,7 +166,9 @@ part of {cheri_base_ext_name} when the hypervisor extension is supported. Its CSR address is 0x24b. <> is updated following the same rules as <> for CHERI exceptions -which are taken in VS-mode. +and <> which are delegated to VS-mode. +It is written to zero for all other exceptions, except as listed otherwise by other +future extensions. The fields are identical to <> for CHERI exceptions. diff --git a/src/img/base-bound-dec.edn b/src/img/base-bound-dec.edn new file mode 100644 index 00000000..cc386938 --- /dev/null +++ b/src/img/base-bound-dec.edn @@ -0,0 +1,16 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 25}]) +(def row-height 80) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 50 :font-size 22 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "E" "" "" "" "" "" "" "" "" "" "E+MW" "" "" "" "" "" "" "" "" "" "" "MXLEN-1"])}) + +(draw-box "a[MXLEN - 1:E + MW] + cb" {:span 12}) +(draw-box "B[MW - 1:0]" {:span 10}) +(draw-box "0" {:span 10}) + +(draw-box "MXLEN" {:span 32 :borders {}}) +---- diff --git a/src/img/mtdcreg.edn b/src/img/mtdcreg.edn deleted file mode 100644 index ba5d74da..00000000 --- a/src/img/mtdcreg.edn +++ /dev/null @@ -1,22 +0,0 @@ -[bytefield] ----- -(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 21}]) -(def row-height 40) -(def row-header-fn nil) -(def left-margin 100) -(def right-margin 100) -(def boxes-per-row 34) -(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "MXLEN-1" "" ""])}) - -(draw-box "Tag" {:span 1}) -(draw-box "" {:span 1 :borders {}}) - -(draw-box "mtdc (Metadata)" {:span 32}) - -(draw-box "" {:span 2 :borders {}}) - -(draw-box "mtdc (Address)" {:span 32}) - -(draw-box "" {:span 2 :borders {}}) -(draw-box "MXLEN" {:span 32 :borders {}}) ----- diff --git a/src/img/stdcreg.edn b/src/img/stdcreg.edn deleted file mode 100644 index 3aeff145..00000000 --- a/src/img/stdcreg.edn +++ /dev/null @@ -1,22 +0,0 @@ -[bytefield] ----- -(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 21}]) -(def row-height 40) -(def row-header-fn nil) -(def left-margin 100) -(def right-margin 100) -(def boxes-per-row 34) -(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "MXLEN-1" "" ""])}) - -(draw-box "Tag" {:span 1}) -(draw-box "" {:span 1 :borders {}}) - -(draw-box "stdc (Metadata)" {:span 32}) - -(draw-box "" {:span 2 :borders {}}) - -(draw-box "stdc (Address)" {:span 32}) - -(draw-box "" {:span 2 :borders {}}) -(draw-box "MXLEN" {:span 32 :borders {}}) ----- diff --git a/src/img/top-bound-dec.edn b/src/img/top-bound-dec.edn new file mode 100644 index 00000000..eabef03d --- /dev/null +++ b/src/img/top-bound-dec.edn @@ -0,0 +1,16 @@ +[bytefield] +---- +(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 25}]) +(def row-height 80) +(def row-header-fn nil) +(def left-margin 100) +(def right-margin 100) +(def boxes-per-row 32) +(draw-column-headers {:height 50 :font-size 22 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "E" "" "" "" "" "" "" "" "" "" "E+MW" "" "" "" "" "" "" "" "" "" "" "MXLEN"])}) + +(draw-box "{1'b0, a[MXLEN - 1:E + MW]} + ct" {:span 12}) +(draw-box "T[MW - 1:0]" {:span 10}) +(draw-box "0" {:span 10}) + +(draw-box "MXLEN+1" {:span 32 :borders {}}) +---- diff --git a/src/img/vstdcreg.edn b/src/img/vstdcreg.edn deleted file mode 100644 index e1b5180c..00000000 --- a/src/img/vstdcreg.edn +++ /dev/null @@ -1,22 +0,0 @@ -[bytefield] ----- -(defattrs :plain [:plain {:font-family "M+ 1p Fallback" :font-size 21}]) -(def row-height 40) -(def row-header-fn nil) -(def left-margin 100) -(def right-margin 100) -(def boxes-per-row 34) -(draw-column-headers {:height 20 :font-size 18 :labels (reverse ["0" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "" "MXLEN-1" "" ""])}) - -(draw-box "Tag" {:span 1}) -(draw-box "" {:span 1 :borders {}}) - -(draw-box "vstdc (Metadata)" {:span 32}) - -(draw-box "" {:span 2 :borders {}}) - -(draw-box "vstdc (Address)" {:span 32}) - -(draw-box "" {:span 2 :borders {}}) -(draw-box "MXLEN" {:span 32 :borders {}}) ----- diff --git a/src/insns/addi16sp_16bit.adoc b/src/insns/addi16sp_16bit.adoc index 03645123..f8b14179 100644 --- a/src/insns/addi16sp_16bit.adoc +++ b/src/insns/addi16sp_16bit.adoc @@ -26,6 +26,8 @@ include::wavedrom/c-int-reg-immed.adoc[] Add the non-zero sign-extended 6-bit immediate to the value in the stack pointer (`csp=c2`), where the immediate is scaled to represent multiples of 16 in the range (-512,496). Clear the tag if the resulting capability is unrepresentable or `csp` is sealed. +include::malformed_clear_tag_csp.adoc[] + {cheri_int_mode_name} Description:: Add the non-zero sign-extended 6-bit immediate to the value in the stack pointer (`sp=x2`), where the immediate is scaled to represent multiples of 16 in the range (-512,496). diff --git a/src/insns/addi4spn_16bit.adoc b/src/insns/addi4spn_16bit.adoc index 324049a8..f5223e6e 100644 --- a/src/insns/addi4spn_16bit.adoc +++ b/src/insns/addi4spn_16bit.adoc @@ -25,6 +25,8 @@ include::wavedrom/c-ciw.adoc[] Add a zero-extended non-zero immediate, scaled by 4, to the stack pointer, `csp`, and writes the result to `cd'`. This instruction is used to generate pointers to stack-allocated variables. Clear the tag if the resulting capability is unrepresentable or `csp` is sealed. +include::malformed_clear_tag_csp.adoc[] + {cheri_int_mode_name} Description:: Add a zero-extended non-zero immediate, scaled by 4, to the stack pointer, `sp`, and writes the result to `rd'`. This instruction is used to generate pointers to stack-allocated variables. diff --git a/src/insns/atomic_exceptions.adoc b/src/insns/atomic_exceptions.adoc index a05916dd..68650b21 100644 --- a/src/insns/atomic_exceptions.adoc +++ b/src/insns/atomic_exceptions.adoc @@ -24,7 +24,7 @@ All misaligned atomics cause a store/AMO address misaligned exception to allow s + When these instructions cause CHERI exceptions, _CHERI data fault_ is reported in the TYPE field and the following codes may be -reported in the CAUSE field of <> or <>: +reported in the CAUSE field of <>, <> or <>: <<< diff --git a/src/insns/cbo_exceptions.adoc b/src/insns/cbo_exceptions.adoc index 1f79a737..8c21779d 100644 --- a/src/insns/cbo_exceptions.adoc +++ b/src/insns/cbo_exceptions.adoc @@ -1,7 +1,7 @@ Exceptions:: CHERI fault exceptions occur when the authorizing capability fails one of the checks -listed below; in this case, _CHERI data fault_ is reported in the <> or -<> TYPE field and the corresponding code is written to CAUSE. +listed below; in this case, _CHERI data fault_ is reported in the <>, +<> or <> TYPE field and the corresponding code is written to CAUSE. + ifdef::cbo_inval[] The CBIE bit in <> and <> indicates whether @@ -33,7 +33,6 @@ ifdef::cbo_inval[] endif::[] | Invalid address violation | The effective address is invalid according to xref:section_invalid_addr_conv[xrefstyle=short] | Bounds violation | None of the bytes accessed are within the bounds, or the capability has <> bounds - |============================================================================== diff --git a/src/insns/condbr_common.adoc b/src/insns/condbr_common.adoc index 129861ad..03fb7849 100644 --- a/src/insns/condbr_common.adoc +++ b/src/insns/condbr_common.adoc @@ -2,4 +2,4 @@ Exceptions:: When the target address is not within the <>'s bounds, and the branch is taken, a _CHERI jump or branch fault_ is reported in the TYPE field and Bounds violation is reported in -the CAUSE field of <> or <>: +the CAUSE field of <>, <> or <>: diff --git a/src/insns/hypv-virt-loadx.adoc b/src/insns/hypv-virt-loadx.adoc index 60b4249d..3e004aa4 100644 --- a/src/insns/hypv-virt-loadx.adoc +++ b/src/insns/hypv-virt-loadx.adoc @@ -42,8 +42,8 @@ to `rd`. Exceptions:: CHERI fault exceptions occur when the authorizing capability fails one of the checks -listed below; in this case, _CHERI data fault_ is reported in the <> or -<> TYPE field and the corresponding code is written to CAUSE. +listed below; in this case, _CHERI data fault_ is reported in the <>, +<> or <>> TYPE field and the corresponding code is written to CAUSE. + [%autowidth,options=header,align=center] |============================================================================== diff --git a/src/insns/jalr_32bit.adoc b/src/insns/jalr_32bit.adoc index a9d9ca8a..89965525 100644 --- a/src/insns/jalr_32bit.adoc +++ b/src/insns/jalr_32bit.adoc @@ -44,7 +44,7 @@ instruction following the jump is written to `rd`. Exceptions:: When these instructions cause CHERI exceptions, _CHERI jump or branch fault_ is reported in the TYPE field and the following codes may be -reported in the CAUSE field of <> or <>: +reported in the CAUSE field of <>, <> or <>: [%autowidth,options=header,align=center] |============================================================================== diff --git a/src/insns/load_exceptions.adoc b/src/insns/load_exceptions.adoc index ab714c9d..5166be6f 100644 --- a/src/insns/load_exceptions.adoc +++ b/src/insns/load_exceptions.adoc @@ -9,8 +9,8 @@ to CLEN/8. + endif::[] CHERI fault exceptions occur when the authorizing capability fails one of the checks -listed below; in this case, _CHERI data fault_ is reported in the <> or -<> TYPE field and the corresponding code is written to CAUSE. +listed below; in this case, _CHERI data fault_ is reported in the <>, +<> or <> TYPE field and the corresponding code is written to CAUSE. + [%autowidth,options=header,align=center] |============================================================================== @@ -20,12 +20,11 @@ listed below; in this case, _CHERI data fault_ is reported in the <> or | Permission violation | Authority capability does not grant <>, or the AP field could not have been produced by <> | Invalid address violation | The effective address is invalid according to xref:section_invalid_addr_conv[xrefstyle=short] | Bounds violation | At least one byte accessed is outside the authority capability bounds, or the capability has <> bounds - |============================================================================== + If virtual memory is enabled, then the state of <>.CW, and, if {cheri_pte_ext_name} is implemented, <>.CRG, <>.U and <>.UCRG, -may cause a CHERI <> page fault exception in addition to a normal RISC-V page fault exception. +may cause a <> exception in addition to a normal RISC-V page fault exception. See <> for the exception reporting in this case. + :!load_res: diff --git a/src/insns/malformed_clear_tag_csp.adoc b/src/insns/malformed_clear_tag_csp.adoc new file mode 100644 index 00000000..e29be66c --- /dev/null +++ b/src/insns/malformed_clear_tag_csp.adoc @@ -0,0 +1,2 @@ +NOTE: This instruction sets `cd.tag=0` if `csp` 's bounds are <>, +or if any of the reserved fields are set. diff --git a/src/insns/malformed_top_range_clear_tag.adoc b/src/insns/malformed_top_range_clear_tag.adoc new file mode 100644 index 00000000..7710a2f8 --- /dev/null +++ b/src/insns/malformed_top_range_clear_tag.adoc @@ -0,0 +1,2 @@ +NOTE: This instruction sets `cd.tag=0` if `cs1` 's bounds are <> +or if any of the reserved fields are set. diff --git a/src/insns/mret_sret.adoc b/src/insns/mret_sret.adoc index 1e8d7002..55789490 100644 --- a/src/insns/mret_sret.adoc +++ b/src/insns/mret_sret.adoc @@ -27,8 +27,8 @@ Exceptions:: CHERI fault exceptions occur when <> does not grant <> because <> and <> require access to privileged CSRs. When that exception occurs, _CHERI instruction fetch fault_ is reported in the TYPE field and the -Permission violation code is reported in the CAUSE field of <> or -<>. +Permission violation code is reported in the CAUSE field of <>, +<> or <>. Operation:: [source,SAIL,subs="verbatim,quotes"] diff --git a/src/insns/store_exceptions.adoc b/src/insns/store_exceptions.adoc index 5518ffde..c5573206 100644 --- a/src/insns/store_exceptions.adoc +++ b/src/insns/store_exceptions.adoc @@ -9,8 +9,8 @@ to CLEN/8. + endif::[] CHERI fault exceptions occur when the authorizing capability fails one of the checks -listed below; in this case, _CHERI data fault_ is reported in the <> or -<> TYPE field and the corresponding code is written to CAUSE. +listed below; in this case, _CHERI data fault_ is reported in the <>, +<> or <> TYPE field and the corresponding code is written to CAUSE. + [%autowidth,options=header,align=center] |============================================================================== @@ -24,7 +24,7 @@ listed below; in this case, _CHERI data fault_ is reported in the <> or + If {cheri_pte_ext_name} is implemented, and virtual memory is enabled, then the state of <>.CW and <>.CRG from the current virtual memory page may -cause a CHERI <> page fault exception in addition to a normal RISC-V page fault +cause a <> exception in addition to a normal RISC-V page fault when operating in user mode. See <> for the exception reporting in this case. + diff --git a/src/insns/zcmt_cmjalt.adoc b/src/insns/zcmt_cmjalt.adoc index 40bd00db..2cbca9a2 100644 --- a/src/insns/zcmt_cmjalt.adoc +++ b/src/insns/zcmt_cmjalt.adoc @@ -41,7 +41,7 @@ Requires <> to be tagged, not sealed, have <> and for the full XLE {cheri_cap_mode_name} Exceptions:: When these instructions cause CHERI exceptions, _CHERI instruction fetch fault_ is reported in the TYPE field and the following codes may be -reported in the CAUSE field of <> or <>: +reported in the CAUSE field of <>, <> or <>: [width="50%",options=header,cols="2,^1",align=center] |============================================================================== diff --git a/src/insns/zcmt_cmjt.adoc b/src/insns/zcmt_cmjt.adoc index f873f1ad..73ca4e2e 100644 --- a/src/insns/zcmt_cmjt.adoc +++ b/src/insns/zcmt_cmjt.adoc @@ -41,7 +41,7 @@ Requires <> to be tagged, not sealed, have <> and for the full XLE {cheri_cap_mode_name} Exceptions:: When these instructions cause CHERI exceptions, _CHERI instruction fetch fault_ is reported in the TYPE field and the following codes may be -reported in the CAUSE field of <> or <>: +reported in the CAUSE field of <>, <> or <>: [width="50%",options=header,cols="2,^1",align=center] |============================================================================== diff --git a/src/instructions.adoc b/src/instructions.adoc index 9c7f8ff7..c501399f 100644 --- a/src/instructions.adoc +++ b/src/instructions.adoc @@ -22,6 +22,8 @@ extensions will eventually be listed in a CHERI profile. <<< === "{cheri_base_ext_name}" and "{cheri_default_ext_name}" Extensions for CHERI +These are the main instructions that are added by CHERI. + include::insns/cmv_32bit.adoc[] include::insns/modesw_32bit.adoc[] @@ -71,6 +73,8 @@ include::insns/store_32bit_cap.adoc[] <<< === RV32I/E and RV64I/E Base Integer Instruction Sets +There are a number of instructions that are already in RISC-V that have modified behavior when CHERI is included. + include::insns/auipc_32bit.adoc[] include::insns/condbr_32bit.adoc[] @@ -90,6 +94,8 @@ include::insns/dret.adoc[] <<< === "A" Standard Extension for Atomic Instructions +Atomic instructions and their interactions with CHERI. + include::insns/amo_32bit.adoc[] include::insns/amoswap_32bit_cap.adoc[] @@ -105,6 +111,8 @@ include::insns/store_cond_cap_32bit.adoc[] <<< === "Zicsr", Control and Status Register (CSR) Instructions +CSR instructions and how they interact with CHERI. + include::insns/csrrw_32bit.adoc[] include::insns/csrr_32bit.adoc[] @@ -112,6 +120,8 @@ include::insns/csrr_32bit.adoc[] <<< === "Zfh", "Zfhmin", "F" and "D" Standard Extension for Floating-Point +Floating point instructions and how CHERI affects them. + include::insns/load_32bit_fp.adoc[] include::insns/store_32bit_fp.adoc[] @@ -243,6 +253,8 @@ include::insns/store_16bit_cap_sprel.adoc[] <<< === "Zicbom", "Zicbop", "Zicboz" Standard Extensions for Base Cache Management Operations +Cache-related instructions and how CHERI affects them. + include::insns/cbo.clean.adoc[] include::insns/cbo.flush.adoc[] @@ -260,6 +272,8 @@ include::insns/prefetch.w.adoc[] <<< === "Zba" Extension for Bit Manipulation Instructions +Bit manipulation instruction reference. + include::insns/adduw_32bit.adoc[] include::insns/sh123add_32bit.adoc[] @@ -274,6 +288,8 @@ include::insns/sh4adduw_32bit.adoc[] [#Zcb,reftext="Zcb"] === "Zcb" Standard Extension For Code-Size Reduction +Code-size reduction instructions and how they interact with CHERI. + include::insns/load_16bit_Zcb.adoc[] include::insns/store_16bit_Zcb.adoc[] @@ -368,6 +384,8 @@ include::insns/zcmt_cmjt.adoc[] === "H" Extension for Hypervisor Support +Hypervisor instructions and the CHERI extensions. + include::insns/hypv-virt-load.adoc[] include::insns/hypv-virt-load-cap.adoc[] diff --git a/src/riscv-hybrid-integration.adoc b/src/riscv-hybrid-integration.adoc index 3bd15786..78841c9d 100644 --- a/src/riscv-hybrid-integration.adoc +++ b/src/riscv-hybrid-integration.adoc @@ -429,22 +429,6 @@ Setting the MBE, SBE, or UBE field to a value that is not the reset value of MBE disables most CHERI features and instructions, as described in xref:section_cheri_disable[xrefstyle=short], while in that privilege mode. -[#mtdc,reftext="mtdc"] -==== Machine Trap Default Capability Register (mtdc) - -The <> register is a capability width read/write register dedicated -for use by machine mode. Typically, it is used to hold a data capability to a -machine-mode hart-local context space, to load into <>. - -{TAG_RESET_CSR} - -{REQUIRE_CRE_CSR} - -{REQUIRE_HYBRID_CSR} - -.Machine-mode trap data capability register -include::img/mtdcreg.edn[] - [#mseccfg,reftext="mseccfg"] ==== Machine Security Configuration Register (mseccfg) @@ -482,22 +466,6 @@ xref:section_cheri_disable[xrefstyle=short]. The reset value is 0. -[#stdc,reftext="stdc"] -==== Supervisor Trap Default Capability Register (stdc) - -The <> register is a capability width read/write register dedicated -for use by supervisor mode. Typically, it is used to hold a data capability to -a supervisor-mode hart-local context space, to load into <>. - -{TAG_RESET_CSR} - -{REQUIRE_CRE_CSR} - -{REQUIRE_HYBRID_CSR} - -.Supervisor trap data capability register (*stdc*) -include::img/stdcreg.edn[] - [#senvcfg,reftext="senvcfg"] ==== Supervisor Environment Configuration Register (senvcfg) diff --git a/src/riscv-integration.adoc b/src/riscv-integration.adoc index 6db65d92..3d793f36 100644 --- a/src/riscv-integration.adoc +++ b/src/riscv-integration.adoc @@ -26,25 +26,23 @@ privileged architecture specified in the RISC-V ISA. === Memory A hart supporting {cheri_base_ext_name} has a single byte-addressable address -space of 2^XLEN^ bytes for all memory accesses. Each memory region capable of +space of 2^MXLEN^ bytes for all memory accesses. Each memory region capable of holding a capability also stores a tag bit for each naturally aligned CLEN bits (e.g. 16 bytes in RV64), so that capabilities with their tag set can only be stored in naturally aligned addresses. Tags must be atomically bound to the data they protect. The memory address space is circular, so the byte at address -2^XLEN^ - 1 is adjacent to the byte at address zero. A capability's +2^MXLEN^ - 1 is adjacent to the byte at address zero. A capability's <> described in xref:section_cap_encoding[xrefstyle=short] is also circular, so address 0 is within the <> of a capability where address 2^MXLEN^ - 1 is within the bounds. However, the decoded top field of a capability is MXLEN + 1 bits wide and does *not* wrap, so a capability with base 2^MXLEN^ - 1 and top 2^MXLEN^ + 1 is not a subset of the <> capability and does not authorize access to the byte at address 0. -Like malformed bounds (see xref:section_cap_malformed[xrefstyle=short]), it is impossible for +The top bound being out of range is similar to malformed bounds (see xref:section_cap_malformed[xrefstyle=short]), it is impossible for a CHERI core to generate a tagged capability with top > 2^MXLEN^. If such a capability exists then it must have been caused by a logic or memory fault. -Unlike malformed bounds, the top overflowing is not treated as a special case in the -architecture: normal bounds check rules should be followed. [#section_riscv_programmers_model] === Programmer's Model for {cheri_base_ext_name} @@ -224,8 +222,9 @@ capability written to memory is cleared if the authorizing capability does not grant permission to write capabilities (i.e. both <> and <> must be set in AP). -WARNING: #TODO: these cases may cause exceptions in the future - we need a way -for software to discover and/or control the behavior# +NOTE: Future extensions to {cheri_base_ext_name} may add mechanisms that cause +stores to raise exceptions when the authorizing capability does not grant both +<> and <>. [#section_existing_riscv_insns] === Existing RISC-V Instructions @@ -424,6 +423,25 @@ include::generated/csr_renamed_purecap_mode_vs_table_body.adoc[] include::generated/csr_renamed_purecap_mode_u_table_body.adoc[] |=== +=== CHERI fault reporting + +CHERI faults require additional information to be reported. +The CSRs updated depend on the mode the trap is taken into, as shown in +<>. + +The additional information is written for CHERI faults and <>, and +is otherwise written to zero for all other exceptions, except as listed otherwise by other +future extensions. + +.CHERI fault reporting +[#cheri-fault-reporting,width=65%,float="center",align="center",options=header,cols="1,1,1"] +|============================================================================== +| Trap taken into | Faulting address | Additional CHERI fault information +| M-mode | <> | <> +| HS-mode / S-mode | <> | <> +| VS-mode | <> | <> +|============================================================================== + === Machine-Level CSRs {cheri_base_ext_name} extends some M-mode CSRs to hold capabilities or @@ -737,7 +755,7 @@ Load/store/AMO address breakpoint Optionally: + Load/store/AMO address misaligned | .>|13, 15, 5, 7 .<|During address translation for an explicit memory access: + -First encountered *CHERI PTE page fault*^23^, page fault or access fault +First encountered *<>*^23^, page fault or access fault | .>|5,7 .<|With physical address for an explicit memory access: + Load/store/AMO access fault | .>|4,6 .<|If not higher priority: + @@ -748,11 +766,11 @@ CHERI load PTE fault^4^ ^1^ PCC bounds are intended to be checked against all the bytes of fetched instructions. In the case of variable length instruction encoding, and that the fetch has failed to return any data, then only a minimum length instruction is checked against the PCC bounds. -^2^ The higher priority CHERI <> page fault covers capability loads or atomics where the loaded tag _is not_ checked, and all capability stores and atomics where the stored tag is set. +^2^ The higher priority <> covers capability loads or atomics where the loaded tag _is not_ checked, and all capability stores and atomics where the stored tag is set. -^3^ CHERI <> page fault exceptions have the same priority against access faults as normal RISC-V page faults. If a normal RISC-V page fault _and_ a CHERI <> fault are both detected simultaneously, then both are recorded as shown in <>. +^3^ <> exceptions have the same priority against access faults as normal RISC-V page faults. If a normal RISC-V page fault _and_ a <> are both detected simultaneously, then both are recorded as shown in <>. -^4^ The lower priority <> fault only covers capability loads and atomics where the loaded tag _is_ checked. +^4^ The lower priority <> only covers capability loads and atomics where the loaded tag _is_ checked. NOTE: The full details of the CHERI exceptions with cause value {cheri_excep_mcause} are in xref:cheri_exception_combs_descriptions[xrefstyle=short]. @@ -797,10 +815,16 @@ endif::[] The <> register is an MXLEN-bit read-write register, which is added as part of the Hypervisor extension cite:[riscv-priv-spec]. {cheri_base_ext_name} also requires the implementation of this CSR. -When a CHERI fault is taken into M-mode, <> is written +When a CHERI fault, or <>, is taken into M-mode, <> is written with additional CHERI-specific exception information with the format shown in xref:mtval2-format[xrefstyle=short] to assist software in handling the trap. +<> is written to zero for all other exceptions, except as listed otherwise by +the Hypervisor extension in cite:[riscv-priv-spec], or by other future extensions. + +NOTE: the use of <>/<>/<> may be irregular as the Hypervisor uses + <> and _htval_ for guest page addresses on guest page fault, and CHERI has no use for _htval_. + If <> is read-only zero for CHERI exceptions then <> is also read-only zero for CHERI exceptions. @@ -856,10 +880,10 @@ If both are detected at once, then both are recorded. .mtval2 for page faults [#mtval2-page-fault,width=70%,float="center",align="center",cols="2,1",options=header] |============================================================================== -| Fault | Value -| RISC-V page fault | 0 -| CHERI <> fault | 1 -| RISC-V page fault and CHERI <> fault | 2 +| Fault | Value +| RISC-V page fault | 0 +| <> | 1 +| RISC-V page fault and <> | 2 |============================================================================== NOTE: Reporting both allows the software the choice about which action to take first, for example a write to a @@ -1077,7 +1101,9 @@ part of {cheri_base_ext_name} when the implementation supports S-mode. Its CSR address is 0x14b. <> is updated following the same rules as <> for CHERI exceptions -which are delegated to S-mode. +and <> which are delegated to HS-mode or S-mode. +It is written to zero for all other exceptions, except as listed otherwise by other +future extensions. The fields are identical to <> for CHERI exceptions, and for load and store/AMO page fault exceptions if {cheri_pte_ext_name} is implemented. @@ -1267,8 +1293,8 @@ the instruction's behavior. . If T is invalid and A does not have infinite bounds (see xref:section_cap_encoding[xrefstyle=short]), then the instruction gives rise to a CHERI fault; the _CHERI jump or branch_ fault is reported in the TYPE field -and invalid address violation is reported in the CAUSE field of <> or -<>. +and invalid address violation is reported in the CAUSE field of <>, +<> or <>. . If T is invalid and A has infinite bounds (see xref:section_cap_encoding[xrefstyle=short]), then A's tag is unchanged and T is written into A's address field. Attempting to execute the instruction at @@ -1292,7 +1318,7 @@ instruction's behavior. . If any byte in R is invalid and A does not have infinite bounds (see xref:section_cap_encoding[xrefstyle=short]), then the instruction gives rise to a CHERI fault; the _CHERI data_ fault is reported in the TYPE field and invalid -address violation is reported in the CAUSE field of <> or <>. +address violation is reported in the CAUSE field of <>, <> or <>. . If any byte in R is invalid and A has infinite bounds (see xref:section_cap_encoding[xrefstyle=short]), the hart will raise an access fault or page fault as is usual in RISC-V. . Otherwise all bytes in R are valid and the instruction behaves as normal. diff --git a/src/trigger-integration.adoc b/src/trigger-integration.adoc index 12a798c1..7dbd1c2d 100644 --- a/src/trigger-integration.adoc +++ b/src/trigger-integration.adoc @@ -22,7 +22,7 @@ mcontrol/mcontrol6 after (on previous instruction) | .>|*{cheri_excep_mcause}* .<|*Prior to instruction address translation:* + *CHERI fault due to PCC checks (tag, execute permission, invalid address and bounds)* | | .>|12, 1 .<|During instruction address translation: + -First encountered *CHERI PTE page fault*, page fault or access fault | +First encountered *<>*, page fault or access fault | | .>|1 .<|With physical address for instruction: + Instruction access fault | @@ -49,14 +49,14 @@ Environment break | | .>|4,6 .<|Optionally: + Load/store/AMO address misaligned | | .>|13, 15, 5, 7 .<|During address translation for an explicit memory access: + -First encountered *CHERI <> page fault*, page fault or access fault | +First encountered *<>*, page fault or access fault | | .>|5,7 .<|With physical address for an explicit memory access: + Load/store/AMO access fault | | .>|4,6 .<|If not higher priority: + Load/store/AMO address misaligned | | .>|13 .<|If not higher priority: + -CHERI load <> fault | +<> | |_Lowest_ .>|3 .<| |mcontrol/mcontrol6 load data before |=== -NOTE: See the notes beneath <> for details about CHERI <> page fault priority. +NOTE: See the notes beneath <> for details about <> priority. diff --git a/src/vector-integration.adoc b/src/vector-integration.adoc index a8cd3e23..88c03376 100644 --- a/src/vector-integration.adoc +++ b/src/vector-integration.adoc @@ -28,7 +28,7 @@ on _active_ elements. In the case of fault-only-first loads, a CHERI bounds violation is only taken if any bytes of element 0 are out of bounds, or if the CHERI bounds are <> and there are any _active_ elements. If another _active_ element causes a CHERI bounds violation then it is treated the same way as other exceptions, the trap is not taken and instead vl is reduced. -All other CHERI fault types, such as tag violations, are taken if there are any _active_ elements. +All other CHERI fault types, such as tag violations, are only taken if element zero is _active_. NOTE: Indexed loads in {cheri_cap_mode_name} check the bounds of every access against the authority capability in `cs1`. Therefore the approach of having a zero base