All automation, tooling, and helper scripts for the project.

This quick section shows the most common commands to build and run simulations and to use the Python helpers.

1. Create a Python virtual environment and install Python dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r script/python/requirements.txt

1. Build Verilated C++ model (from repository root):

make verilate

1. Run a single test using the wrapper (resolves MEM file automatically):

make run_verilator TEST_NAME=rv32ui-p-add MAX_CYCLES=100000

1. Full pipeline (RTL + Spike + compare):

make run TEST_NAME=rv32ui-p-add

Troubleshooting

• If you see Simulation binary not found, run make verilate first (builds $(OBJ_DIR)/V$(RTL_LEVEL)).
• If Verilator reports missing includes (e.g. level_defines.svh), ensure INC_DIR and include files are present and make verilate is invoked from the repo root so include paths resolve.
• Check logs under results/logs/verilator/<TEST_NAME>/:
  • verilator_run.log — console output of the simulation run
  • commit_trace.log — commit trace used by compare_logs.py
  • level.log — tracer pipeline log
  • summary.json — short machine-readable run summary (from the Verilator runner)

ASIC / OpenLane (SKY130)

make asic_subrepos
make asic_setup
make asic_prep
make asic_run
make asic_report

make asic_subrepos shallow-clones or updates the OpenLane/OpenROAD/Caravel repos under subrepo/asic-tools/.

Defaults:

• OPENLANE_IMAGE=efabless/openlane:2023.09.07
• PDK_ROOT=$HOME/.volare
• PDK=sky130A

Docker setup (Ubuntu 22.04):

chmod +x script/shell/setup_docker_engine_ubuntu.sh
sudo bash script/shell/setup_docker_engine_ubuntu.sh
newgrp docker
docker run --rm hello-world

Running OpenLane in Docker:

OPENLANE_MODE=docker make asic_setup
OPENLANE_MODE=docker make asic_run

If you'd like, I can add a short GitHub Actions workflow to run make verilator_static and basic Python checks on PRs.

ASIC / LibreLane (OpenLane successor)

python3 -m pip install --upgrade librelane
make librelane_setup
make librelane_run
make librelane_report

LibreLane flow details:

• Reuses the same source prep and design config under asic/openlane/designs/level_wrapper/.
• Uses LibreLane Classic flow via script/shell/librelane_flow.sh.
• Writes outputs under results/asic/librelane/level_wrapper/runs/.

Common overrides:

LIBRELANE_MODE=local make librelane_run
LIBRELANE_MODE=docker make librelane_run
ASIC_TAG=my_run make librelane_run
PDK_ROOT=$HOME/.volare PDK=sky130A make librelane_run

Running tests

After creating a virtual environment and installing dev requirements run:

source .venv/bin/activate
pip install -r script/python/requirements-dev.txt
pytest -q