better readme

README.md

@@ -1,41 +1,39 @@
 # In-Field Testing Using MISR
 
-## Setup
+Research code for investigations of Silent Data Corruptions (SDCs) caused by hardware faults.
 
-After cloning this repository, run:
+## Quick Start
 
+This project has submodules. To ensure everything is up-to-date, run the following after `git clone`, `git pull` or `git checkout`:
 ```
 git submodule init
+git submodule sync
 git submodule update
 ```
 
-This project uses [Nix](https://nixos.org) to manage reproducible programming environments.
+This project manages reproducible programming environments with:
-
+- [uv](https://docs.astral.sh/uv/) for managing python environments.
-Run `nix develop` to enter a shell with all necessary software.
+- [nix](https://nixos.org) for managing non-python tools and benchmark designs. Follow [this guide](https://librelane.readthedocs.io/en/stable/installation/nix_installation/index.html) or [this guide](https://github.com/fossi-foundation/nix-eda/blob/main/docs/installation.md) to setup [nix-eda](https://github.com/fossi-foundation/nix-eda/tree/main) binary cache to avoid re-building EDA-related tools.
-
-If `nix` is not installed, follow this [guide](https://librelane.readthedocs.io/en/stable/installation/nix_installation/index.html). No need to clone `librelane` here, but it is good to set up the `extra-substituters` as described in the guide for using LibreLane for making layouts with SkyWater 130nm technology.
 
 ## Usage
 
+To access non-Python tools such as `iverilog`, run `nix develop` before any of the commands below to enter the appropriate shell environment. Commands that only rely on Python tools work also outside a `nix develop` shell if [uv](https://docs.astral.sh/uv/) is installed on the base system.
+
+### JPEG
+
 Compile jpeg decoder core using `iverilog` and run RTL simulation of the jpeg decoder core using `vvp`:
 ```
-nix develop
 make
 uv run jpeg_core_tb_run_plasma.py
 ```
-Call `uv run jpeg_core_tb_run_plasma.py --help` for more options.
+See `uv run jpeg_core_tb_run_plasma.py --help` for more options.
 
-Load synthesized circuits and display statistics (example code):
-```
-uv run load_sky130_circuits.py
-```
 
-Run picorv32's built-in testbench (generate `picorv32/testbench.vcd`):
+### PicoRV32
+
+Run picorv32's built-in testbenches (generate `picorv32/testbench.vcd`) with one of these commands:
 ```
 make test_vcd
-```
-or
-```
 make test_ez_vcd
 ```
 
@@ -43,8 +41,19 @@ Import generated VCD with kyupy and convert it to a pattern file for later fault
 ```
 uv run picorv32_vcd_import.py picorv32/testbench.vcd patterns.npy
 ```
-Call `uv run picorv32_vcd_import.py --help` for more options.
+See `uv run picorv32_vcd_import.py --help` for more options.
 
+### Other Benchmark Circuits
 
-Some `uv` commands work also outside a `nix develop` shell if [uv](https://docs.astral.sh/uv/) is installed on the base system. The script demonstrates how to obtain synthesized netlists via nix derivations [published in this github repository](https://github.com/s-holst/benchmark-circuits). These circuits along with layout and timings are built on-demand (using LibreLane) if not yet available in local nix store.
+Load synthesized circuits and display statistics (example code):
+```
+uv run load_sky130_circuits.py
+```
+This script demonstrates how to obtain synthesized netlists via nix derivations [published in this github repository](https://github.com/s-holst/benchmark-circuits). These circuits along with layout and timings are built on-demand using [LibreLane](https://fossi-foundation.org/librelane/) classic flow if not yet available in local nix store.
+
+To access the full design data (netlist, timing, layout, ...), call one of these:
+```
+nix build github:s-holst/benchmark-circuits#picorv32-sky130
+nix build github:s-holst/benchmark-circuits#jpeg_core-sky130
+```