Document new configuration for IRQ and PMPM extensions

doc/sections/configuration_and_integration.adoc

@@ -45,7 +45,7 @@ Bits set in <<param-MTVEC_WMASK>> can be written/set/cleared as normal.
 
 Default value: all-zeroes.
 
-==== RISC-V ISA support
+==== Standard RISC-V ISA support
 
 [[param-EXTENSION_A]]
 ===== EXTENSION_A
@@ -122,6 +122,25 @@ Custom bit manipulation instructions for Hazard3: `h3.bextm` and `h3.bextmi`. Se
 
 Default value: 1
 
+[[cfg-custom-extensions]]
+==== Custom Hazard3 Extensions
+
+[[param-EXTENSION_XH3IRQ]]
+===== EXTENSION_XH3IRQ
+
+Custom preemptive, prioritised interrupt support. Can be disabled if an
+external interrupt controller (e.g. PLIC) is used. If disabled, and
+NUM_IRQS > 1, the external interrupts are simply OR'd into mip.meip. See <<extension-xh3irq-section>>.
+
+Default value: 1
+
+
+[[param-EXTENSION_XH3PMPM]]
+===== EXTENSION_XH3PMPM
+
+Custom PMPCFGMx CSRs to enforce PMP regions in M-mode without locking. See <<extension-xh3pmpm-section>>.
+
+
 [[param-EXTENSION_XH3POWER]]
 ===== EXTENSION_XH3POWER
 
@@ -262,6 +281,14 @@ will have a severe effect on timing.
 
 Default value: 0
 
+[[param-IRQ_INPUT_BYPASS]]
+===== IRQ_INPUT_BYPASS
+
+Disable the input registers on the external interrupts, to reduce latency by
+one cycle. Can be done on an IRQ-by-IRQ basis.
+
+Default value: all-zeroes (not bypassed).
+
 ==== Identification Registers
 
 [[param-MVENDORID_VAL]]

doc/sections/csr.adoc

@@ -86,7 +86,7 @@ Read-only, constant. Value depends on which ISA extensions Hazard3 is configured
 |===
 | Bits | Name | Description
 | 31:30 | `mxl` | Always `0x1`. Indicates this is a 32-bit processor.
-| 23 | `x` | 1 if the core is configured to support trap-handling, otherwise 0. Hazard3 has nonstandard CSRs to enable/disable external interrupts on a per-interrupt basis, see <<reg-meiea>> and <<reg-meipa>>. The `misa.x` bit must be set to indicate their presence. Hazard3 does not implement any custom instructions.
+| 23 | `x` | 1 if any custom extension is enabled (<<cfg-custom-extensions>>), otherwise 0.
 | 20 | `u` | 1 if User mode is supported, otherwise 0.
 | 12 | `m` | 1 if the M extension is present, otherwise 0.
 | 2 | `c` | 1 if the C extension is present, otherwise 0.
@@ -148,6 +148,7 @@ The table below lists the fields which are _not_ hardwired to 0:
 
 NOTE: RISC-V reserves bits 16+ of `mie`/`mip` for platform use, which Hazard3 could use for external interrupt control. On RV32I this could only control 16 external interrupts, so Hazard3 instead adds nonstandard interrupt enable registers starting at <<reg-meiea>>, and keeps the upper half of `mie` reserved.
 
+[[reg-mip]]
 ==== mip
 
 Address: `0x344`
@@ -527,6 +528,7 @@ Bits can be cleared by software, and are cleared automatically by hardware upon
 | 4:0   | `index`  | Write-only, self-clearing field (no value is stored) used to control which window of the array appears in `window`. 
 |===
 
+[[reg-meipra]]
 ==== meipra
 
 Address: `0xbe3`
@@ -543,6 +545,7 @@ When an interrupt's priority is lower than the current preemption priority `meic
 | 6:0   | `index`  | Write-only, self-clearing field (no value is stored) used to control which window of the array appears in `window`. 
 |===
 
+[[reg-meinext]]
 ==== meinext
 
 Address: `0xbe4`
@@ -655,6 +658,7 @@ no_more_irqs:
 
 === Custom Memory Protection CSRs
 
+[[reg-pmpcfgm0]]
 ==== pmpcfgm0
 
 Address: 0xbd0

doc/sections/custom_extensions.adoc

@@ -4,6 +4,31 @@ Hazard3 implements a small number of custom extensions. All are optional: custom
 
 If any one of these extensions is enabled, the `x` bit in <<reg-misa>> is set to indicate the presence of a nonstandard extension.
 
+[[extension-xh3irq-section]]
+=== Xh3irq: Hazard3 interrupt controller
+
+This is a lightweight extension to control up to 512 external interrupts, with up to 16 levels of preemption.
+
+This extension does not add any instructions, but does add several CSRs:
+
+* <<reg-meiea>>
+* <<reg-meipa>>
+* <<reg-meifa>>
+* <<reg-meipra>>
+* <<reg-meinext>>
+* <<reg-meicontext>>
+
+If this extension is disabled then Hazard3 supports a single external interrupt input (or multiple inputs that it simply ORs together in an uncontrolled fashion), so an external PLIC can be used for standard interrupt support.
+
+Note that, besides the additional CSRs, this extension is effectively a slightly more complicated way of driving the standard `mip.meip` flag (<<reg-mip>>). The RISC-V trap handling CSRs themselves are always completely standard.
+
+[[extension-xh3pmpm-section]]
+=== Xh3pmpm: M-mode PMP regions
+
+This extension adds a new M-mode CSR, <<reg-pmpcfgm0>>, which allows a PMP region to be enforced in M-mode without locking the region.
+
+This is useful when the PMP is used for non-security-related purposes such as stack guarding, or trapping and emulation of peripheral accesses.
+
 [[extension-xh3power-section]]
 === Xh3power: Hazard3 power management