Hazard3's source is written in Verilog 2005, and is self-contained. It can be found here: https://github.com/Wren6991/Hazard3/tree/master/hdl[github.com/Wren6991/Hazard3/blob/master/hdl]. The file https://github.com/Wren6991/Hazard3/blob/master/hdl/hazard3.f[hdl/hazard3.f] is a list of all the source files required to instantiate Hazard3.
* https://github.com/Wren6991/Hazard3/blob/master/hdl/hazard3_config.vh[hazard3_config.vh]: the main Hazard3 configuration header. Lists and describes Hazard3's global configuration parameters, such as ISA extension support
* https://github.com/Wren6991/Hazard3/blob/master/hdl/hazard3_config_inst.vh[hazard3_config_inst.vh]: a file which propagates configuration parameters through module instantiations, all the way down from Hazard3's top-level modules through the internals
Therefore there are two ways to configure Hazard3:
* Directly edit the parameter defaults in `hazard3_config.vh` in your local Hazard3 checkout (and then let the top-level parameters default when instantiating Hazard3)
* Set all configuration parameters in your Hazard3 instantiation, and let the parameters propagate down through the hierarchy
These are both thin wrappers around the https://github.com/Wren6991/Hazard3/blob/master/hdl/hazard3_core.v[hazard3_core] module. `hazard3_cpu_1port` has a single AHB5 bus port which is shared for instruction fetch, loads, stores and AMOs. `hazard3_cpu_2port` has two AHB5 bus ports, one for instruction fetch, and the other for loads, stores and AMOs. The 2-port wrapper has higher potential for performance, but the 1-port wrapper may be simpler to integrate, since there is no need to arbitrate multiple bus masters externally.
The core module `hazard3_core` can also be instantiated directly, which may be more efficient if support for some other bus standard is desired. However, the interface of `hazard3_core` will not be documented and is not guaranteed to be stable.
Address of the first instruction executed after Hazard3 comes out of reset.
Default value: all-zeroes.
===== MTVEC_INIT
Initial value of the machine trap vector base CSR (<<reg-mtvec>>).
Bits clear in <<param-MTVEC_WMASK>> will never change from this initial value.
Bits set in <<param-MTVEC_WMASK>> can be written/set/cleared as normal.
Default value: all-zeroes.
==== RISC-V ISA support
[[param-EXTENSION_A]]
===== EXTENSION_A
Support for the A extension: atomic read/modify/write. 0 for disable, 1 for enable.
Default value: 1
[[param-EXTENSION_C]]
===== EXTENSION_C
Support for the C extension: compressed (variable-width). 0 for disable, 1 for enable.
Default value: 1
[[param-EXTENSION_M]]
===== EXTENSION_M
Support for the M extension: hardware multiply/divide/modulo. 0 for disable, 1 for enable.
Default value: 1
[[param-EXTENSION_ZBA]]
===== EXTENSION_ZBA
Support for Zba address generation instructions. 0 for disable, 1 for enable.
Default value: 1
[[param-EXTENSION_ZBB]]
===== EXTENSION_ZBB
Support for Zbb basic bit manipulation instructions. 0 for disable, 1 for enable.
Default value: 1
[[param-EXTENSION_ZBC]]
===== EXTENSION_ZBC
Support for Zbc carry-less multiplication instructions. 0 for disable, 1 for enable.
Default value: 1
[[param-EXTENSION_ZBS]]
===== EXTENSION_ZBS
Support for Zbs single-bit manipulation instructions. 0 for disable, 1 for enable.
Default value: 1
[[param-EXTENSION_ZBKB]]
===== EXTENSION_ZBKB
Support for Zbkb basic bit manipulation for cryptography.
Requires: <<param-EXTENSION_ZBB>>. (Since Zbb and Zbkb have a large overlap, this flag enables only those instructions which are in Zbkb but aren't in Zbb. Therefore both flags must be set for full Zbkb support.)
Default value: 1
[[param-EXTENSION_ZIFENCEI]]
===== EXTENSION_ZIFENCEI
Support for the fence.i instruction. When the branch predictor is not present,
this instruction is optional, since a plain branch/jump is sufficient to
flush the instruction prefetch queue. When the branch predictor is enabled
(<<param-BRANCH_PREDICTOR>> is 1), this instruction must be implemented.
Custom bit manipulation instructions for Hazard3: `h3.bextm` and `h3.bextmi`. See <<extension-xh3bextm-section>>.
Default value: 1
[[param-EXTENSION_XH3POWER]]
===== EXTENSION_XH3POWER
Custom power management controls for Hazard3. This adds the <<reg-msleep>> CSR, and the `h3.block` and `h3.unblock` hint instructions. See <<extension-xh3power-section>>
NOTE: the Zicsr extension is implied by any of <<param-CSR_M_MANDATORY>>, <<param-CSR_M_TRAP>>,
<<param-CSR_COUNTER>>.
[[param-CSR_M_MANDATORY]]
===== CSR_M_MANDATORY
Bare minimum CSR support e.g. <<reg-misa>>. This flag is an absolute
requirement for compliance with the RISC-V privileged specification. However,
the privileged specification itself is an optional extension. Hazard3 allows
the mandatory CSRs to be disabled to save a small amount of area in
deeply-embedded implementations.
[[param-CSR_M_TRAP]]
===== CSR_M_TRAP
Include M-mode trap-handling CSRs, and enable trap support.
[[param-CSR_COUNTER]]
===== CSR_COUNTER
Include the basic performance counters (`cycle`/`instret`) and relevant CSRs. Note that these performance counters are now in their own separate extension (Zicntr) and are no longer mandatory.
[[param-U_MODE]]
===== U_MODE
Support the U (user) privilege level. In U-mode, the core performs unprivileged
bus accesses, and software's access to CSRs is restricted. Additionally, if
the PMP is included, the core may restrict U-mode software's access to
memory.
Requires: <<param-CSR_M_TRAP>>.
[[param-PMP_REGIONS]]
===== PMP_REGIONS
Number of physical memory protection regions, or 0 for no PMP. PMP is more
useful if U mode is supported, but this is not a requirement.
Hazard3's PMP supports only the NAPOT and(if <<param-PMP_GRAIN>> is 0) NA4
region types.
Requires: <<param-CSR_M_TRAP>>.
[[param-PMP_GRAIN]]
===== PMP_GRAIN
This is the _G_ parameter in the privileged spec, which defines the
granularity of PMP regions. Minimum PMP region size is 1 <<(_G_ + 2) bytes.
If _G_ > 0, `pmcfg.a` can not be set to NA4 (attempting to do so will set the
region to OFF instead).
If _G_ > 1, the _G_ - 1 LSBs of pmpaddr are read-only-0 when `pmpcfg.a` is
OFF, and read-only-1 when `pmpcfg.a` is NAPOT.
Default value: 0
[[param-PMP_HARDWIRED]]
===== PMP_HARDWIRED
PMPADDR_HARDWIRED: If a bit is 1, the corresponding region's pmpaddr and
pmpcfg registers are read-only, with their values fixed when the processor is
instantiated. PMP_GRAIN is ignored on hardwired regions.
Hardwired regions are far cheaper, both in area and comparison delay, than
dynamically configurable regions.
Hardwired PMP regions are a good option for setting default U-mode permissions
on regions which have access controls outside of the processor, such as
peripheral regions. For this case it's recommended to make hardwired regions
the highest-numbered, so they can be overridden by lower-numbered dynamic
regions.
Default value: all-zeroes.
[[param-PMP_HARDWIRED_ADDR]]
===== PMP_HARDWIRED_ADDR
Values of pmpaddr registers whose PMP_HARDWIRED bits are set to 1. Has no effect on PMP regions which are not hardwired.
Default value: all-zeroes.
[[param-PMP_HARDWIRED_CFG]]
===== PMP_HARDWIRED_CFG
Values of pmpcfg registers whose PMP_HARDWIRED bits are set to 1. Has no effect on PMP regions which are not hardwired.
Default value: all-zeroes.
[[param-DEBUG_SUPPORT]]
===== DEBUG_SUPPORT
Support for run/halt and instruction injection from an external Debug Module,
