clarify PTE fault exception priority, and add into instruction pages (#485)

Fixes #484

---------

Signed-off-by: Tariq Kurd <tariqandlaura@gmail.com>

Author: tariqkurd-repo

src/cheri-pte-ext.adoc

@@ -100,7 +100,7 @@ If the CW bit is clear then:
 
 * When a capability load or AMO instruction is executed, the implementation
  clears the tag bit of the capability read from the virtual page.
-* When CRG is clear, the "no capability state", a store page fault exception
+* When CRG is clear, the "no capability state", a store/AMO page fault exception
  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 <<section_hardware_pte_updates>>):
@@ -164,9 +164,16 @@ and the capability read from memory optionally has its tag set^1^.
  It is legal for the implementation to fault even if the tag is not set since this behavior is only an optimization for software.
  This means it is also legal to only check the tag under certain conditions and conservatively fault otherwise.
  Taking a trap when the tag is not set will introduce additional traps during revocation sweeps.
+ Checking the loaded tag affects the exception priority, see <<exception-priority>>.
 
 ^2^ See <<section_hardware_pte_updates>>.
 
+The exceptions added by {cheri_pte_ext_name} reuse the load page fault and store/AMO page fault exception cause values,
+and so the cause of the exception can be determined by software by checking the value in <<mtval2>>,
+<<stval2>> etc.
+
+The behavior when multiple page fault types are detected at once is shown in <<mtval2-page-fault>>.
+
 [#section_hardware_pte_updates]
 === Enabling Software or Hardware PTE updates
 

src/insns/load_exceptions.adoc

@@ -23,5 +23,11 @@ listed below; in this case, _CHERI data fault_ is reported in the <<mtval2>> or
 
 |==============================================================================
 +
+If {cheri_pte_ext_name} is implemented, and virtual memory is enabled, then the state of
+<<cheri_pte_ext,PTE>>.CW and <<cheri_pte_ext,PTE>>.CRG from the current virtual memory page,
+together with <<sstatusreg_pte,sstatus>>.CRG may cause a CHERI <<cheri_pte_ext,PTE>> page fault exception
+in addition to a normal RISC-V page fault exception.
+See <<mtval2-page-fault>> for the exception reporting in this case.
++
 :!load_res:
 :!has_cap_data:

src/insns/store_exceptions.adoc

@@ -22,5 +22,10 @@ listed below; in this case, _CHERI data fault_ is reported in the <<mtval2>> or
 | Bounds violation      | At least one byte accessed is outside the authority capability bounds, or the capability has <<section_cap_malformed,malformed>> bounds
 |==============================================================================
 +
+If {cheri_pte_ext_name} is implemented, and virtual memory is enabled, then the state of
+<<cheri_pte_ext,PTE>>.CW and <<cheri_pte_ext,PTE>>.CRG from the current virtual memory page may
+cause a CHERI <<cheri_pte_ext,PTE>> page fault exception in addition to a normal RISC-V page fault.
+See <<mtval2-page-fault>> for the exception reporting in this case.
++
 :!store_cond:
 :!has_cap_data:

src/riscv-integration.adoc

@@ -698,7 +698,7 @@ _Reserved_
 
 [[exception-priority]]
 .Synchronous exception priority in decreasing priority order. Entries added in {cheri_base_ext_name} are in *bold*
-[%autowidth,float="center",align="center",cols="<,>,<",options="header"]
+[float="center",align="center",cols="<1,>1,<8",options="header"]
 |===
 |Priority |Exc.Code |Description
 |_Highest_ |3 |Instruction address breakpoint
@@ -729,14 +729,21 @@ 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 page fault or access fault
+First encountered *CHERI PTE page fault*^12^, page fault or access fault
 | .>|5,7 .<|With physical address for an explicit memory access: +
 Load/store/AMO access fault
-.>|_Lowest_ .>|4,6 .<|If not higher priority: +
-Load/store/AMO address misaligned
+| .>|4,6 .<|If not higher priority: +
+.>|_Lowest_ .>|13 .<|If not higher priority: +
+CHERI load PTE fault^3^
 |===
 
-NOTE: The full details of the CHERI exceptions are in xref:cheri_exception_combs_descriptions[xrefstyle=short].
+^1^ The higher priority CHERI <<cheri_pte_ext,PTE>> 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^ CHERI <<cheri_pte_ext,PTE>> 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 <<cheri_pte_ext,PTE>> fault are both detected simultaneously, then both are recorded as shown in <<mtval2-page-fault>>.
+
+^3^ The lower priority <<cheri_pte_ext,PTE>> fault 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].
 
 [#medeleg,reftext="medeleg"]
 ==== Machine Trap Delegation Register (medeleg)
@@ -830,13 +837,24 @@ CHERI violations have the following order in priority:
 . Invalid address violation
 . Bounds violation (_Lowest_)
 
-===== mtval2 values for Load Page Faults
+===== mtval2 values for Load/Store/AMO Page Faults
 
-If a load page fault is caused by a CHERI <<cheri_pte_ext,PTE>> fault, then set bit zero of <<mtval2>> to 1 and all other bits to 0, otherwise set all bits to zero.
+Page faults can be caused by normal RISC-V page faults and also by CHERI <<cheri_pte_ext,PTE>> faults.
+If both are detected at once, then both are recorded.
 
-===== mtval2 values for Store Page Faults
+.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 <<cheri_pte_ext,PTE>> fault                       | 1
+| RISC-V page fault and CHERI <<cheri_pte_ext,PTE>> fault | 2
+|==============================================================================
 
-If a store page fault is caused by a CHERI <<cheri_pte_ext,PTE>> fault, then set bit zero of <<mtval2>> to 1 and all other bits to 0, otherwise set all bits to zero.
+NOTE: Reporting both allows the software the choice about which action to take first, for example a write to a
+ page with no write permission, _and_ the incorrect value of PTE.CRG requires two actions.
+ Software can then decide whether to prioritize the copy-on-write procedure to fix the lack of write
+ permission, or to sweep the page.
 
 [#supervisor-level-csrs-section]
 === Supervisor-Level CSRs
@@ -1051,7 +1069,7 @@ address is 0x14b.
 which are delegated to S-mode.
 
 The fields are identical to <<mtval2>> for CHERI exceptions, and for load and
-store page fault exceptions if {cheri_pte_ext_name} is implemented.
+store/AMO page fault exceptions if {cheri_pte_ext_name} is implemented.
 
 NOTE: <<stval2>> is not a standard RISC-V CSR, but <<mtval2>> is.
 

src/trigger-integration.adoc

@@ -7,7 +7,7 @@ shown in xref:trigger-exception-priority[xrefstyle=short].
 
 [[trigger-exception-priority]]
 .Synchronous exception priority (including triggers) in decreasing priority order. Entries added in {cheri_base_ext_name} are in *bold*
-[%autowidth,float="center",align="center",cols="<,>,<,<",options="header"]
+[float="center",align="center",cols="<1,>1,<4,<2",options="header"]
 |===
 |Priority |Exc. Code |Description |Trigger
 |_Highest_ |3 +
@@ -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 page fault or access fault |
+First encountered *CHERI PTE page fault*, page fault or access fault |
 | .>|1 .<|With physical address for instruction: +
 Instruction access fault |
 
@@ -49,10 +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 page fault or access fault |
+First encountered *CHERI <<cheri_pte_ext,PTE>> page fault*, 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 <<cheri_pte_ext,PTE>> fault |
 |_Lowest_ .>|3 .<| |mcontrol/mcontrol6 load data before
 |===
+
+NOTE: See the notes beneath <<exception-priority>> for details about CHERI <<cheri_pte_ext,PTE>> page fault priority.