Getting Started¶

This page gets a fresh machine (tested on Ubuntu 24.04) ready to run the Flow A pipeline described in Flow A: Overview. It condenses the setup steps from the repository’s top-level README.md; see that file for the full troubleshooting table.

Every tool below lives in its own environment (venv or sourced shell script) and must be (re-)activated in every new terminal session before use.

1. FuseSoC¶

FuseSoC is the package/build manager that reads a design’s .core file and dispatches simulation/synthesis to the right backend (Edalize).

sudo apt install git iverilog

# one-time: conda (Miniforge), next to the other tools
cd ~/thesis/tools
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh -b -p ~/thesis/tools/miniforge3
~/thesis/tools/miniforge3/bin/conda init bash
source ~/.bashrc
conda config --set auto_activate_base false

# X-HEEP's environment (same FuseSoC/Edalize as the X-HEEP team)
git clone https://github.com/x-heep/x-heep.git ~/thesis/tools/x-heep
cd ~/thesis/tools/x-heep
make conda
conda activate x-heep

fusesoc --version   # tested: 0.2.dev3+gc36dffc85 (edalize 0.3.4.dev204+gabf56019c)

Clone X-HEEP into its final location before make conda: environments store absolute paths and break if the directory is moved afterwards. conda activate x-heep must be re-run in every new terminal session.

Tested versions. The complete flow (make check, sim, synth, gls, ppa, pnr, sdf, power, power-postsynth, gds) passes on examples/custom_myfir inside this environment, with FuseSoC 0.2.dev3+gc36dffc85, Edalize 0.3.4.dev204+gabf56019c and Python 3.12.15 (pinned commits of the x-heep forks). If X-HEEP changes its pins, re-run make check and make sim after updating the environment. The sim and synth targets were also verified with the latest x-heep/fusesoc master and with stock FuseSoC 2.4.7, but those are not required.

If you installed stock FuseSoC instead of X-HEEP’s environment and fusesoc tool list fails with ImportError: cannot import name 'walk_tool_packages' from 'edalize.edatool', the auto-installed Edalize is out of sync with FuseSoC — fix with pip install --upgrade edalize.

Validate the install with FuseSoC’s own “blinky” example (the “hello world” of this pipeline — it doesn’t test a real design, it just proves core file → FuseSoC → simulator → result works):

git clone https://github.com/olofk/fusesoc.git
cd fusesoc/tests/userguide/blinky
fusesoc --cores-root . run --target=sim fusesoc:examples:blinky

All 10 “Pulse N/10 OK!” lines passing confirms the toolchain works end-to-end.

2. oss-cad-suite (Yosys, Icarus, Verilator, GTKWave, nextpnr, …)¶

wget https://github.com/YosysHQ/oss-cad-suite-build/releases/download/<date>/oss-cad-suite-linux-x64-<date>.tgz
tar xzf oss-cad-suite-linux-x64-<date>.tgz
source oss-cad-suite/environment
yosys -V

source oss-cad-suite/environment must be re-run every new terminal session, same as the FuseSoC venv.

3. OpenROAD¶

Build from source (a Bazel build, ~installs to ../install/OpenROAD):

git clone --recursive https://github.com/The-OpenROAD-Project/OpenROAD.git
cd OpenROAD
sudo ./etc/DependencyInstaller.sh -base
./etc/DependencyInstaller.sh -common -local
./etc/Build.sh

echo 'export PATH="$HOME/thesis/tools/install/OpenROAD/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
openroad -version

4. KLayout¶

wget https://www.klayout.org/downloads/Ubuntu-22/klayout_<version>-1_amd64.deb
sudo apt install ./klayout_<version>-1_amd64.deb
klayout -v

This apt package only gives you the KLayout application (GUI + klayout binary). It does not expose pya to the system python3, which is what GDS-generation automation (gen_gds.sh, KLayout’s stream_out.py) needs. That requires the separate klayout pip package, in its own venv:

python3 -m venv ~/klayout-venv
source ~/klayout-venv/bin/activate
pip install klayout click
python3 -c "import pya; print(pya.__file__)"

Do not create this venv from a terminal that has oss-cad-suite/environment sourced. oss-cad-suite ships its own bundled python3, which shadows the system one on PATH and breaks python3 -m venv’s pip bootstrap (ensurepip ... exit status 127). Check which python3 first; if it resolves into oss-cad-suite/..., invoke the system interpreter explicitly instead (/usr/bin/python3.11 -m venv ~/klayout-venv). Re-activate this venv in every new terminal used for GDS generation, kept separate from the oss-cad-suite-sourced shell used for everything else.

5. PDK (Sky130, via ciel)¶

ciel is the PDK version manager used to fetch and pin a specific open_pdks-built revision of the PDK. Flow A reads PDK_ROOT/PDK (through flow-a/scripts/tech/sky130hd.tcl) to locate every PDK file.

python3 -m venv ~/pdk-venv
source ~/pdk-venv/bin/activate
pip install --upgrade ciel

export PDK_ROOT="$HOME/thesis/tools/pdk"
mkdir -p "$PDK_ROOT"
echo 'export PDK_ROOT="$HOME/thesis/tools/pdk"' >> ~/.bashrc

ciel ls-remote --pdk-family sky130
ciel enable --pdk-family sky130 <commit-hash>

export PDK=sky130A
echo 'export PDK=sky130A' >> ~/.bashrc

This creates $PDK_ROOT/sky130A containing libs.ref (Liberty, LEF, GDS, SPICE, Verilog views per standard-cell library) and libs.tech (per-tool tech setup: klayout/, magic/, ngspice/) — the layout every stage of the flow expects. See PDK Portability (e.g. Retargeting to 55 nm) for what to do when this PDK is not Sky130 (e.g. a closed 55 nm node for Flow B).

6. Verify the `read_slang` SystemVerilog frontend¶

Synthesis (Running Flow A on Your Own SV Design) uses Yosys’s read_slang command (also known as yosys-slang / sv-elab) to parse SystemVerilog directly, including multi-file/multi-package designs. It is not guaranteed to be bundled in every oss-cad-suite release — verify it explicitly rather than assuming:

yosys -p 'plugin -i slang; help read_slang' | tee /tmp/slang_check.log
echo "exit code: ${PIPESTATUS[0]}"

Expect the full read_slang option list to print and exit code 0. Do not pipe this through head or run it with Yosys’s -qq flag “to check quickly” — both suppress the error text that would distinguish a real plugin-load failure from a genuine success, making the two look identical. If it fails, this oss-cad-suite build doesn’t bundle the plugin — see https://github.com/povik/sv-elab for a from-source build before continuing.

Environment checklist¶

Before running anything, every new terminal needs:

conda activate x-heep
source ~/thesis/tools/oss-cad-suite/environment
echo "$PDK_ROOT"; echo "$PDK"
which openroad; which yosys; which iverilog; which klayout; which tclsh

tclsh (sudo apt install tcl) is used by the Makefile and gen_gds.sh to read the technology file. Once the PDK is installed, tclsh flow-a/scripts/tech_query.tcl check lists any PDK file the flow needs that is missing.

If any of these come back empty, re-source the relevant environment script or re-check ~/.bashrc.