riscv-formal-nmigen/README.md

# riscv-formal-nmigen

A port of [riscv-formal](https://github.com/SymbioticEDA/riscv-formal) to nMigen

## Breakdown

| File/Directory | Description |
| --- | --- |
| `shell.nix` | [nix-shell](https://nixos.wiki/wiki/Development_environment_with_nix-shell) configuration file |
| `rvfi` | RISC-V Formal Verification Framework (nMigen port) |
| `rvfi/insns` | Supported RISC-V instructions and ISAs |
| `rvfi/checks` | Checks for RISC-V compliant cores |
| `rvfi/cores` | Cores currently tested against this port of riscv-formal |
| `rvfi/cores/minerva/verify.py` | Verification tasks for the Minerva core |

## Running the Verification

First make sure you have [Nix](https://nixos.org/download.html) installed. Then `cd` to the root directory of this repo and run:

```bash
$ nix-shell
```

This should run the tests (cache, multiplier, divider) provided by Minerva itself and give you an environment with all the dependencies required for this project. Then, to run the main verification tasks for Minerva provided in this repo:

```bash
$ python -m rvfi.cores.minerva.verify
```

This should run in the order of a few minutes.

## Scope

Support for the RV32I base ISA and RV32M extension are planned and well underway. Support for other ISAs in the original riscv-formal such as RV32C and their 64-bit counterparts may also be added in the future as time permits.

## Known Issues

- 21/08/2020: Verification passes unconditionally, even in the presence of obvious bugs. This is due to the `rvfi.valid` signal from the CPU being held at constant 0. Suitable instruction and data buses as well as interrupt signals have not been wired to Minerva which is likely preventing the core and verification from functioning properly
- 25/08/2020: Interrupts have been hardwired to zero and instruction/data buses attached to the Minerva core; however, running the verification quickly exhausts available memory on a machine with 32G RAM. Possible culprit: huge number of `Assume` statements on memory values

## License

See [LICENSE](./LICENSE)
Initial commit 2020-07-14 10:30:37 +08:00			`# riscv-formal-nmigen`

Copy license from source 2020-07-14 10:42:06 +08:00			`A port of [riscv-formal](https://github.com/SymbioticEDA/riscv-formal) to nMigen`
Add LUI instruction for RV32I 2020-07-21 16:13:52 +08:00
Add Minerva core, to be integrated later 2020-08-13 17:38:04 +08:00			`## Breakdown`

Update README.md 2020-08-21 11:46:39 +08:00			`\| File/Directory \| Description \|`
Add Minerva core, to be integrated later 2020-08-13 17:38:04 +08:00			`\| --- \| --- \|`
Replace nMigen copy with shell.nix config file 2020-08-20 12:52:06 +08:00			\| `shell.nix` \| [nix-shell](https://nixos.wiki/wiki/Development_environment_with_nix-shell) configuration file \|
Update README.md 2020-08-17 12:05:39 +08:00			\| `rvfi` \| RISC-V Formal Verification Framework (nMigen port) \|
			\| `rvfi/insns` \| Supported RISC-V instructions and ISAs \|
Remove copy of Minerva 2020-08-20 15:32:10 +08:00			\| `rvfi/checks` \| Checks for RISC-V compliant cores \|
			\| `rvfi/cores` \| Cores currently tested against this port of riscv-formal \|
Update README.md 2020-08-21 11:46:39 +08:00			\| `rvfi/cores/minerva/verify.py` \| Verification tasks for the Minerva core \|
Add Minerva core, to be integrated later 2020-08-13 17:38:04 +08:00
Replace nMigen copy with shell.nix config file 2020-08-20 12:52:06 +08:00			`## Running the Verification`

			First make sure you have [Nix](https://nixos.org/download.html) installed. Then `cd` to the root directory of this repo and run:
Add LUI instruction for RV32I 2020-07-21 16:13:52 +08:00
Replace nMigen copy with shell.nix config file 2020-08-20 12:52:06 +08:00			```bash
			`$ nix-shell`
			```
Add build instructions for Minerva 2020-08-17 16:46:15 +08:00
Remove copy of Minerva 2020-08-20 15:32:10 +08:00			`This should run the tests (cache, multiplier, divider) provided by Minerva itself and give you an environment with all the dependencies required for this project. Then, to run the main verification tasks for Minerva provided in this repo:`
Add build instructions for Minerva 2020-08-17 16:46:15 +08:00
Replace nMigen copy with shell.nix config file 2020-08-20 12:52:06 +08:00			```bash
Add build instructions for Minerva 2020-08-17 16:46:15 +08:00			`$ python -m rvfi.cores.minerva.verify`
			```
Add LUI instruction for RV32I 2020-07-21 16:13:52 +08:00
Update README.md 2020-08-21 11:53:20 +08:00			`This should run in the order of a few minutes.`
Add tests for all RV32I instructions 2020-08-19 14:56:26 +08:00
Add README for instructions 2020-08-05 12:54:46 +08:00			`## Scope`
Mention expected scope of project in README 2020-07-21 17:55:28 +08:00
Add Minerva core, to be integrated later 2020-08-13 17:38:04 +08:00			`Support for the RV32I base ISA and RV32M extension are planned and well underway. Support for other ISAs in the original riscv-formal such as RV32C and their 64-bit counterparts may also be added in the future as time permits.`
Mention expected scope of project in README 2020-07-21 17:55:28 +08:00
Add "Known Issues" section to README 2020-08-21 16:58:33 +08:00			`## Known Issues`

Add prototype for instruction/data bus implementation 2020-08-25 12:41:30 +08:00			- 21/08/2020: Verification passes unconditionally, even in the presence of obvious bugs. This is due to the `rvfi.valid` signal from the CPU being held at constant 0. Suitable instruction and data buses as well as interrupt signals have not been wired to Minerva which is likely preventing the core and verification from functioning properly
Update README.md 2020-08-25 13:38:31 +08:00			- 25/08/2020: Interrupts have been hardwired to zero and instruction/data buses attached to the Minerva core; however, running the verification quickly exhausts available memory on a machine with 32G RAM. Possible culprit: huge number of `Assume` statements on memory values
Add prototype for instruction/data bus implementation 2020-08-25 12:41:30 +08:00
Add LUI instruction for RV32I 2020-07-21 16:13:52 +08:00			`## License`

			`See [LICENSE](./LICENSE)`