Hazard3 is a three stage RISC-V core with the debug and PMP machinery silicon work actually needs

A three stage pipeline with a deliberately small base ISA

Hazard3 is described as a 3-stage RISC-V processor, and the base instruction set is either RV32I or RV32E, which is a choice worth understanding before anything else. RV32E is the sixteen register variant of the base integer set, so the same core can be built for a smaller register file where code size matters more than performance. Everything above that base is optional and listed extension by extension: M for integer multiply, divide and modulo, A for atomic memory operations with AHB5 global exclusives, C for compressed instructions, Zicsr for CSR access, Zilsd for load and store pair instructions, and the bit manipulation family including Zba for address generation, Zbb for basic bit manipulation, Zbc for carry-less multiplication, Zbs for single-bit manipulation, Zbkb for bit manipulation aimed at scalar cryptography, Zbkx for crossbar permutation instructions, Zcb for additional compressed instructions, Zclsd for compressed load and store pairs, and Zcmp for push and pop instructions. The breadth of that list is the point of the project, since a core that can be configured for a particular extension set is reusable across designs that need different mixes.

Debug, machine mode and PMP are in the core rather than bolted on later

The features that usually appear as an afterthought in a hobby processor are listed as first class here. The core supports Debug, Machine and User privilege and execution modes, and implements the privileged instructions ecall, ebreak, mret and wfi. Physical memory protection is supported with up to sixteen regions, and the configuration can be NAPOT and/or TOR matching, which are the two ways RISC-V defines region boundaries. External debug support is available over JTAG or APB, and there is an instruction address trigger unit, which is the hardware breakpoint mechanism. Putting PMP and the trigger unit inside the core rather than bolting them on afterwards is what makes the core usable in a design with real privilege requirements, and it is also what makes the debug story work, since the debugger needs a way to see memory and stop the core without the software cooperation that a simple simulator lacks.

Cloning recursively is the difference between a core and a working simulation

The repository separates what you need to use the core from what you need to simulate it, and the instructions make that split explicit. For using Hazard3 in a design, the repository is self-contained. For the simulation scripts, the tests and the example SoC components, you need the submodules, and in that case the documentation asks for a recursive clone.

git clone --recursive https://github.com/Wren6991/Hazard3.git hazard3

If you already have a plain clone, the submodules are initialised separately.

git submodule update --init --recursive

The top level tree explains the layout: hdl holds the design, example_soc holds the integration example, test holds the test infrastructure, scripts holds helper scripts, doc holds documentation, and two build helpers sit at the root, project_env.sh and project_paths.mk. The .gitmodules and .gitignore files are present alongside them. The example integration is a specific file, example_soc/soc/example_soc.v, and the documentation says what it assembles: a JTAG enabled RISC-V processor, some RAM, a serial port and a platform timer. That is the minimum you need to run real software, and it is a useful reference for how the components are meant to be wired together.

The default branch is stable, and the documentation reserves it for tapeouts

There is an unusual branch policy here that deserves attention. The default branch for clones is stable, and the documentation strongly recommends this branch for ASIC tapeouts. The head of stable is always the latest non-development release, which in this repository is tracked under releases rather than under a develop branch. The develop branch is where you try the latest features and optimisations. So the recommended workflow is that a production user takes the stable branch and consumes the released artefacts, and a development user tracks develop to get new work. The reference manual is distributed with the releases, with a PDF linked from the release page and the same documentation readable online, and the release list shows v1.1.1 on 2026-03-12, v1.1 on 2025-11-17, and a v1.1-rc1 release candidate from 2025-06-08. The branch policy, the release discipline and the documentation hosting are all aligned around the idea that a tapeout is a one shot, expensive event.

Building the simulator takes Yosys, a RISC-V toolchain and a pinned clang

The hello world walkthrough needs three tools, and the version notes are unusually specific. You need a recent Yosys build to process the Verilog, with the instructions last tested against commit a0e94e506, a riscv32-unknown-elf- toolchain to build software for the core, and a native clang-16 to build the simulator. The clang note is the interesting one. clang-17 is also known to work fine, but clang-18 does work with a serious compile time regression in the CXXRTL output, which is why the tb_cxxrtl Makefile explicitly selects clang-16. That is a concrete, hard-won detail that you would otherwise rediscover the slow way. The instructions target Ubuntu 24.04, and Windows users are told they may have some success with Ubuntu under WSL. The Yosys build itself is a conventional from source sequence.

git clone https://github.com/YosysHQ/yosys.git
cd yosys
git submodule update --init
make -j$(nproc)
sudo make install

On macOS the same dependency set is installed with brew, and the documentation lists the packages for that path separately.

A multilib toolchain is recommended over a prebuilt one

The toolchain recommendation is a preference for building it yourself, and the reason given is ISA coverage rather than convenience. The documentation recommends building a toolchain to get libraries with the correct ISA support, specifically a 32-bit build of the RISC-V GNU toolchain with a multilib setup suitable for Hazard3 development. The configure step pins the architecture and ABI with --with-arch=rv32ia_zicsr_zifencei and --with-abi=ilp32, and installs into a /opt/riscv/gcc15 prefix. The multilib generator string is where the extension coverage becomes visible, since it enumerates the combinations the toolchain can produce: the rv32i through rv32imac families, each with the zicsr and zifencei baseline, then variants adding zba, zbb, zbs, zbkb, zbkx and zbc, and separately zca and zcb for the compressed extensions. If you build a plain toolchain with a single arch, you will be unable to compile the right libc for a core that has, say, the bit manipulation extensions but not the compressed ones. The prerequisite list for the build is long and platform specific, and it assumes you are comfortable compiling a cross toolchain from source.

Three stage means the performance ceiling is set, and that is the design

Let us be direct about what a three stage pipeline costs. The core implements RV32I or RV32E, so it is 32-bit, with a compressed extension set and no 64-bit or vector support in the listed features. For a control processor, a security co-processor, or an FPGA design where the point is to prove out a concept, those limits are irrelevant and the small pipeline is an advantage, because a short pipeline is easier to verify, easier to simulate quickly, and easier to reason about at the register transfer level. For anything compute bound, they are decisive. The other cost of the small design is that the optional extension list has to be configured at build time rather than discovered at runtime, since the extension mix is fixed when the core is built. The documentation also points readers to Contributing.md before raising an issue or a pull request, which is worth honouring given that the project is written by a single author and the review expectations are set there. The last push was on 2026-08-29 and the repository is not archived.

Editorial conclusion

Hazard3 suits engineers who want a small RISC-V core they can read end to end, simulate quickly, and take through the debug and privilege requirements of a real design, and it suits FPGA prototypes that need JTAG debug rather than a simulator-only flow. It is the wrong choice if you need a high performance core, since three stages and a 32-bit base say clearly where it sits, and it is the wrong choice if you want the RISC-V vector or 64-bit extensions, which are not in the supported list. Before committing to it, clone the stable branch rather than develop, because the documentation reserves stable for tapeouts, and read the reference manual PDF for the details the README does not carry. The licence is Apache-2.0, v1.1.1 was released on 2026-03-12, and the last push was on 2026-08-29.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. Wren6991/Hazard3 on GitHub