Environment

Tool Environment Requirements

Many of the great tools for microelectronic design are functional only through Linux environments. This leads to an inherent barrier-to-entry for designers that have not used Linux before. However, it is important to note that not all tools require a Linux flow, and it is possible to do co-design at different stages in different environments. This could be useful to distributed teams, or at different stages of a design flow between prototyping a design and full optimisation iterations.

One of the main complexities of multi-tool open source design is the version management of the tools, and making sure they all speak to each other without conflicting tool environment requirements. In piel, we provide a set of environment solutions to guarantee the shared functionality between the toolsets. This means we forcibly tie down each tool version to what we know works and that our examples pass as a result. This means that if you want to upgrade to a latest version, you will need to do the upgrade and verification that the tool compatibility passes.

The implementation of this consists of tying down the requirements of the primary dependencies of the project, but not the secondary ones. This means that we expect the secondary dependencies to resolve through the dependency management system when providing a suitable primary dependency environment.

To guarantee full functionality of piel, we provide some customised environment installations, particularly through nix in Linux.

On each feature upgrade, piel has a github action that verifies the compatibility of the environments with some tools and platforms here <https://github.com/daquintero/piel/blob/develop/.github/workflows/test_import.yaml>. You can verify your OS platform and your tools with it.

Dependency Environment Breakdown

This table of tools compatibility is provided should you use a specific set of toolsets in a given environment. No complete functionality guarantees are provided in this case.

Tools Compatibility

Tool	Windows	Linux	OS X ?	Possible Integrations
cocotb	iverilog	iverilog, verilator, Cadence xcelium	iverilog	iverilog, verilator, Cadence xcelium
gdsfactory				Many
openlane	Not compatible
hdl21	ngspice & xyce	ngspice & xyce	ngspice & xyce	ngspice, xyce
sax
thewalrus

This is a preliminary table, I mostly develop on Linux, you need to verify your system configuration or use the recommended nix environment.

In the future, we will have custom installations for different types of users so they can install minimal dependencies for their use case.

Upgrading the tools versions

TODO add the instructions of how to upgrade the tool versions accordingly. TODO add links to the tests that need to be run in order not to break compatibility between tools.

piel CLI (Recommended - CI Tested)

piel is a command line interface (CLI) that is designed to be a simple and easy to use tool for managing the piel toolchain. It is necessary to first install piel in a given python environment and then the CLI tool should automatically be active in that environment. You then just need to run $ piel in the terminal to see the available commands.

piel Useful Commands

All commands are echoed to the terminal before they are executed. This is to help you understand what is happening under the hood.

nix Configuration (Recommended - CI Tested)

This is the recommended way to access the entire toolset environment. This will install all the external dependencies such as openlane, ngspice, cocotb and so on. It can be easily extended in a standard nix-pkgs flow. However, in order to run this flow you need to have nix installed which is feasible in Linux and MacOS. The entire piel package gets tested in this nix environment in the CI so it is reproducible to some level.

The quickstart in an ubuntu environment is just the following script. This will install nix with the correct configuration and build the nix-flake correctly. We use this script in the CI.

git clone https://github.com/daquintero/piel.git
source scripts/install_piel_nix.sh

If you just want to enter a nix development environment shell by default and you already have nix installed, then you just have to run:

nix develop .

This is the output set of instrructions provided by:

piel activate

If you want to enter the corresponding nix-shell environment which is extensible with further packages, you can run the following command which will print the updated command you just need to copy paste into your terminal to activate the nix-shell environment.

$ piel activate-custom-shell

It will print:

# Please run this in your shell:
cd ~/<path_to_piel>
nix shell . github:efabless/nix-eda#{ngspice,xschem,verilator,yosys} github:efabless/openlane2 nixpkgs#verilog nixpkgs#gtkwave

This is because, I believe, for security reasons it is very difficult to automatically enter a nix shell directly from python or a subprocess.

OpenLane 2 via nix have recently released another way to package their python-driven Openlane 2 digital chip layout flow. We have previously had issues reproducibly building the docker configuration, and because most users are likely to use these tools for developing their chips rather than distributing software, nix might be well suited for these applications.

nix Development Installation

This process sets up a nix development environment, good for when developing examples. Make sure to follow the nix installation instructions for your platform. Follow the latest openlane2 instructions if interested.

The Fast Lane

Assuming you already have piel installed in a local environment, you can simply run the commands to perform the installation.

piel environment # To see all commands
piel environment install-nix # To install nix
piel environment install-openlane # To install openlane

To enter the nix environment that uses all the tools used within piel, run:

piel environment activate

An important thing to note is that, for openlane to work properly, its nix configured binaries need to be untouched. This means we need to make sure that the virtualenviron

System requirements

Before starting, make sure you system has:

• curl

• git

• bash

nix installation

The Fast Lane

Assuming you already have piel installed in a local environment, you can simply run:

piel environment install-nix

The Detailed Lane

First, install nix. The approach below is not the recommended install method, as it creates a ‘single-user’ installation, with the /nix cache owned by the invoking user, rather than shared between all users. The recommended ‘multi-user’ method, however, doesn’t work well on systems with SELinux, i.e. Fedora, so we’ll live with this alternative for now.

sh <(curl -L https://nixos.org/nix/install) --no-daemon

Provide your user password when prompted.

The following line should have been added to both your ~/.bash_profile and ~/.bashrc:

if [ -e /users/<youruser>/.nix-profile/etc/profile.d/nix.sh ]; then . /users/<youruser>/.nix-profile/etc/profile.d/nix.sh; fi

This ensures that nix-shell will be available in $PATH whether you’re starting a shell in “login” mode or in “non-login” mode. More info can be found here.

After verifying this, to update the changes to $PATH either close and reopen your terminal, or run:

. ~/.nix-profile/etc/profile.d/nix.sh

OpenLane2 installation

The Fast Lane

Assuming you already have piel installed in a local environment, you can simply run:

piel environment install-openlane

The Detailed Lane

Before installing piel, let’s first get OpenLane2, as it will automatically also give us OpenROAD, Yosys, Magic, KLayout, and Verilator. The instructions below are copied from here.

Cachix allows the reproducible Nix builds to be stored on a cloud server so you do not have to build OpenLane’s dependencies from scratch on every computer, which will take a long time.

First, you want to install Cachix by running the following in your terminal:

nix-env -f "<nixpkgs>" -iA cachix

Then set up the OpenLane binary cache as follows:

cachix use openlane

cd to a working directory of choice, and clone down openlane2:

git clone https://github.com/efabless/openlane2

OpenLane Nix environment

The Fast Lane

Assuming you already have piel installed in a local environment, you can simply run:

piel environment activate-openlane-nix

**The Detailed Lane - (Depreciated) Pre-Flakes Migration **

Now move inside the folder:

cd openlane2

And build the environment of dependencies. Wait for it to fetch and cache the dependencies.

nix-shell

Piel Nix environment

The Fast Lane

Assuming you already have piel installed in a local environment and have followed the previous installation process, you can simply run:

piel environment activate-piel-nix

The Detailed Lane

We are now using nix-flakes to manage the nix environment. This is an experimental nix feature, but far more powerful than the previous nix-shell approach. To learn more about nix-flakes, see here.

To run our nix flakes environment run the following:

cd environment/nix
nix develop --extra-experimental-features nix-command --extra-experimental-features flakes

This will take some time as it is both installing the openlane2 nix dependencies and the piel ones, and building them into a specific environment. The total installation size is approximately 4 Gb. All the python packages that are dependencies of pip are installed from the wheels in PyPi from the versions defined by the poetry.lock file.

In my computer, running this command for the first time took about 20 minutes. Eventually we will distribute this in a binary.

**The Detailed Lane - (Depreciated) Pre-Flakes Migration **

We’ll similarly use nix to grab all the compiled dependencies for piel, including:

• ngspice: 41 (latest)

• gtkwave: 3.3.117, from Aug 2023 (latest)

• Xyce: 7.6, from Nov 2022 (7.7 is latest)

• verilog: 12.0, from Jun 2023 (latest)

Do do this, simply move inside of the piel directory:

cd piel/environment/nix

And run the command below, which implicitly reads in the local shell.nix file:

nix-shell

Piel Python environment

The Fast Lane

piel environment # TODO

The Detailed Lane - Depreciated

For the time being, PyPI and pip isn’t easily compatible with Nix. See the complexity here.. machnix used to solve this problem, but it’s unmaintained/deprecated in favor of the migration to dream2nix. So hopefully in a couple months, this whole section below will be rolled into shell.nix file mentioned above.

Anyways, in the interim, we’ll use the requirements_dev.txt file to fetch all the Python dependencies for piel.

While still inside of the nix-shell, check you’re using python 3.10.9:

python --version

This is essential because we want all of our piel Python virtual environment to be on the same version as Openlane. Create and activate this venv on the top level of the .piel directory:

python -m venv ~/.piel/.venv

source ~/.piel/.venv/bin/activate

And fetch the dependencies via:

pip install -e .[develop]

The .venv folder should be created inside the top level of the .piel in your home directory.

You’re now done!

Subsequent usage - Depreciated

cd /path/to/piel

And implicitly load the piel shell.nix environment via:

nix-shell

This will automatically add to $PATH the packages , but it will also add to path the packages managed the pip venv by the OpenLane2 nix environment. This is accomplished via a the shell hook in shell.nix:

  shellHook = ''
    export LD_LIBRARY_PATH=${pkgs.lib.makeLibraryPath [
      pkgs.stdenv.cc.cc
    ]}
      # Reinstalling the pacakges should guarantee a reproducible build every time
      set -e
      echo "Running: micromamba shell hook --shell=bash"
      eval "$(micromamba shell hook --shell=bash)"
      echo "Running: micromamba shell init --shell=bash --prefix=~/micromamba"
      micromamba shell init --shell=bash --prefix=~/micromamba
      echo "Running: micromamba create --yes -q -n pielenv -c conda-forge python=3.10"
      micromamba create --yes -q -n pielenv -c conda-forge python=3.10
      echo "Running: micromamba activate pielenv --yes"
      micromamba activate pielenv --yes
      set +e
      export PATH="$PATH:$HOME/.local/bin/"
      echo "Running: micromamba run -n pielenv pip install -r $HOME/.piel/openlane2/requirements_dev.txt --user --break-system-packages;"
      micromamba run -n pielenv pip install -r $HOME/.piel/openlane2/requirements_dev.txt --user --break-system-packages;
      echo "Running: micromamba run -n pielenv pip install ../../[develop] --user --break-system-packages;"
      micromamba run -n pielenv pip install -e "../../[develop]" --user --break-system-packages;
      source $HOME/.piel/.venv/bin/activate;
    fi
    nix-shell ~/.piel/openlane2/shell.nix
  '';
  LOCALE_ARCHIVE="/usr/lib/locale/locale-archive";  # let's nix read the LOCALE, to silence warning messages
}

VSCode support for nix

There is a useful plugin for automatically running the top-level shell.nix file after setup. More info can be found in this blog.

Creating your own nix Installation - Depreciated

You might have your own set of tools that you are using alongside piel. One common complexity in using multiple open-source tools is distributing them and guaranteeing that they run consistently between different machines.

We follow some of the principles in the Setting up the OpenLane Nix Cache page .

Relevant tools and commands:

• cachix Binary Cache platform for open source and business.

• nix-shell “Build the dependencies of the specified derivation, but not the derivation itself”.

You might want to clone only the maintained nix configuration of the openlane2 design flow.

Find out what is a git sparse-checkout

What we would like to do is have a version controlled installation that tracks the version controlled nix configuration in openlane 2.

git clone https://github.com/efabless/openlane2.git
cd openlane2/nix/
# TODO We want to track this directory only, how?

Useful nix commands

Description	Command
Build with all available CPU cores	nix-shell --cores 0

nix Useful Commands

Useful nix commands

Description	Command
Build production shell with all available CPU cores	nix-build --cores 0
Build development shell with all available CPU cores	nix-shell --cores 0
Install a nix environment package eg. mach-nix	nix-env -if https://github.com/DavHau/mach-nix/tarball/3.5.0 -A mach-nix
List all available packages	nix-env -qaP --description
Search for a specific <package>	nix-env -qaP <package>