RISCV-DV: Random RISC-V Instruction Generation for Verification

What RISCV-DV Does for Processor Verification

RISCV-DV targets RISC-V processor verification through randomized and directed instruction generation. Its intended users are verification engineers building regressions, stress environments, or testbenches that need more varied stimulus than handwritten assembly alone. The documented instruction-set scope is RV32IMAFDC and RV64IMAFDC, covering integer, multiply, atomic, floating-point, and compressed instructions for 32-bit and 64-bit processors.

The generator supports machine, supervisor, and user modes. This matters because privileged control and status registers, page tables, traps, interrupts, and MMU behavior interact in ways that are difficult to cover with a small collection of handwritten tests. RISCV-DV includes privileged CSR setup randomization and a privileged CSR test suite. It also provides page table randomization, exception generation, and a test suite intended to stress the MMU.

This is not a processor design or a complete verification environment by itself. The README describes an SV/UVM-based instruction generator, while the repository contains Python generation code, SystemVerilog source, simulator integration files, tests, sample content, and documentation. A user therefore needs an RTL simulator and a surrounding testbench capable of receiving generated stimulus and evaluating the design under test.

RISCV-DV Generation and Testbench Flow

The repository uses a hybrid Python and SystemVerilog/UVM architecture. Python entry points such as `run.py` and `cov.py` coordinate usage of the generator, while the `pygen/`, `euvm/`, and `src/` directories contain distinct parts of the generation and execution environment. The exact control flow depends on the target integration, but the README identifies handshake communication with the testbench as a supported capability.

RISCV-DV can mix directed instructions with a random instruction stream. This is more useful than choosing one approach for an entire regression. A verification engineer can retain predictable assembly cases for a specific architectural behavior while adding randomized sequences to explore combinations that are tedious to write by hand. Handcoded assembly support is documented explicitly, as are sub-program generation and random program calls.

The project includes an instruction generation coverage model. Its coverage scope extends beyond sequential instruction classes. Page table randomization and exception generation target address-translation behavior, while trap and interrupt handling exercise control transfer caused by architectural events. Debug mode support includes a fully randomized debug ROM, giving the testbench additional debug-path stimulus.

The README lists Spike, riscv-ovpsim, Whisper, and Sail-RISC-V as co-simulation options. This allows generated execution to be associated with one or more instruction set simulators when the target flow supports it. The README does not provide a universal command for selecting an ISS or a complete matrix of supported simulator and ISS combinations, so those connections remain part of the user's verification environment.

Installing RISCV-DV for Development or Normal Use

The README presents two installation paths. Developers who may work with multiple clones in parallel are advised to run scripts directly through Python. First, obtain the source using the command printed in the README:

git clone https://github.com/google/riscv-dv.git

The clone URL uses the `google` organization even though this repository is identified as `chipsalliance/riscv-dv`. That discrepancy is visible in the README and should be resolved against current CHIPS Alliance project guidance before use.

For direct Python execution, install the dependency file and check the generator entry point:

pip3 install -r requirements.txt
python3 run.py --help

The first command installs packages from `requirements.txt`. The second should print command-line help if Python can load the project. This method keeps scripts attached to the cloned directory, which fits developers moving among multiple checkouts.

For normal users, the README recommends an editable package installation. Change to the cloned directory, add the user executable directory to `PATH`, and install the package:

export PATH=$HOME/.local/bin/:$PATH
pip3 install --user -e .

Because the package is installed in editable mode, repository changes are available without repeatedly running `pip3 install .`. The documented entry points can then be checked with:

run --help
cov --help

Successful help output confirms that the package commands start, but it does not confirm simulator compatibility or complete testbench setup.

Simulator and ISS Requirements for Execution

Running the instruction generator requires an RTL simulator that supports SystemVerilog and UVM 1.2. The README says RISCV-DV has been verified with Synopsys VCS, Cadence Incisive/Xcelium, Mentor Questa, and Aldec Riviera-PRO. It also requires the EDA tool environment to be configured correctly. Installing the Python dependencies does not remove the need for the simulator, its license, and its environment setup.

The repository contains target-specific integration files, including `vcs.compile.option.f`, `questa_sim.tcl`, and `riviera_sim.tcl`. Their presence shows that simulator integration is part of the project layout. It does not mean that every existing testbench can run without modification. The README does not provide one universal compile command covering all supported simulators, so target selection belongs in the integration flow used by the verification team.

Co-simulation has another boundary. Spike, riscv-ovpsim, Whisper, and Sail-RISC-V are named as supported ISS tools, but the README does not document a single switch that selects among them. A team using co-simulation must match the generator, DUT simulator, testbench, and ISS through its own configuration. A team that only needs program generation can treat this as a separate integration concern rather than assuming it is part of Python package installation.

Privileged, MMU, Trap, and Debug Coverage

RISCV-DV's main value is its collection of RISC-V-specific stimulus categories. It can generate random forward and backward branches, illegal instructions, and HINT instructions. These capabilities allow a regression to vary control flow and instruction encodings instead of relying on a fixed sequence of valid arithmetic operations.

For virtual-memory verification, page table randomization and exception generation target the MMU. The README also identifies a dedicated test suite for MMU stress. These cases depend on a testbench and design configuration capable of exercising the relevant memory and privilege behavior. The presence of an MMU stress feature does not establish that every generated case will produce meaningful architectural coverage in an arbitrary DUT.

Machine, supervisor, and user mode support makes the generator useful for privileged-software scenarios. Privileged CSR setup randomization and a privileged CSR test suite provide ways to generate configuration and test stimulus around those modes. Trap and interrupt handling are separately supported, allowing a team to focus on control transfer and exception state.

Debug-mode support includes a fully randomized debug ROM. That extends coverage into the debug subsystem rather than limiting RISCV-DV to the normal execution path. The README does not publish a formal coverage target, expected test count, or convergence requirement. A project must define its own coverage goals and assess whether the generated sequences reach them in the intended design configuration.

Documentation, Style Checks, and Change Scope

The README directs users to the full documentation under `docs` for setup and customization. It says the documentation can be generated with the makefile and points to a prebuilt copy at `docs/build/singlehtml/index.html`. This is the main documented route for understanding generator configuration beyond the short installation commands.

The repository also includes Verible-related scripts for checking Verilog style. The build command printed in the README is:

verilog_style/build-verible.sh

After building or installing the required tool through that script, style violations can be checked with:

verilog_style/run.sh

The README recommends resolving style violations before submitting a pull request. These checks concern contributions to Verilog source. They do not automatically resolve functional failures in generated tests.

A typical change can touch several parts of this repository. Python packaging is defined through `setup.py` and `setup.cfg`, command-line behavior begins in `run.py`, and generation code is divided among directories such as `pygen/`, `euvm/`, `src/`, and `target/`. The repository also includes `test/`, `sample/`, YAML configuration, and simulator-specific files. This breadth means an upgrade or customization should account for the complete target configuration rather than only the Python package version.

Upgrade Boundaries and RISCV-DV Maintenance Status

The repository is not archived, and its last push was on 2026-09-21. The README states that RISCV-DV is now contributed to CHIPS Alliance and points contributors to a working-group mailing group for status, feature priorities, and development progress. These facts indicate recent repository activity, but they do not provide a release cadence or compatibility guarantee for individual simulator versions.

No GitHub releases are listed. No stable release checkpoint is identified in the repository information. Engineers must inspect repository history, configuration changes, and target integration files when deciding whether to update an existing checkout.

The repository identifies Apache-2.0 as its license. The `setup.py` file also carries the Apache License, Version 2.0 header, and the README refers license questions to `CONTRIBUTING.md`. Apache-2.0 permits broad use, modification, and distribution subject to its conditions, but this review does not provide legal advice. Organizations should inspect `LICENSE.txt`, `CONTRIBUTING.md`, and their own compliance requirements when integrating the code.

The absence of GitHub releases also means that dependency compatibility requires direct inspection. `requirements.txt` includes Python packages such as PyYAML, bitstring, pyvsc, pyucis, pyboolector, and pandas, with some versions constrained or pinned. Upgrading the repository can therefore affect both Python dependencies and the surrounding simulator environment.

Cases Where RISCV-DV Is the Wrong Tool

RISCV-DV is the wrong choice when the target environment does not support SystemVerilog and UVM 1.2. It is also unsuitable for a team seeking a standalone software-only RISC-V test framework, because the documented flow depends on an RTL simulator, UVM components, and testbench communication.

Its documented scope may not cover an arbitrary implementation. The README states support for RV32IMAFDC and RV64IMAFDC and for machine, supervisor, and user modes. It does not claim unrestricted coverage of every RISC-V extension. Although the repository contains a `user_extension/` directory, the README does not explain how a particular custom extension must be integrated. Projects with custom instructions need to inspect the relevant source and configuration before assuming support.

Randomized generation also creates reproducibility questions. The README describes randomization and coverage, but it does not document a seed option, deterministic replay contract, failure artifact format, or procedure for regenerating an exact failing sequence. Engineers who require reproducible cross-machine or cross-version regressions should not infer that capability from the project description. The correct initial check is whether the intended simulator and testbench can compile and exchange the generated stimulus at all.

Editorial conclusion

RISCV-DV fits RISC-V verification engineers who need randomized instruction streams, privileged-mode stimulus, or MMU and trap stress tests, especially when simulator integration already exists. It is unsuitable for teams without SystemVerilog and UVM support or for engineers seeking a standalone testbench. Verify simulator compatibility, instruction-set coverage, ISS integration, and the customization path under docs before adoption. The repository is not archived and its last push was on 2026-09-21, but it has no GitHub releases, so upgrades must be assessed through repository history rather than release tags.

Frequently asked questions

Official sources

1. chipsalliance/riscv-dv on GitHub
2. Issues
3. License: Apache-2.0
4. README