Installing Coriolis2

Videos and links:

Automated Installation - One-liner

The new automated method of installing/setting up Coriolis2 is as follows:

  1. Clone the repo "dev-env-setup". https://git.libre-soc.org/?p=dev-env-setup.git;a=summary Tutorial assumes the directory is located under user's home.
  2. Run the script "coriolis2-chroot" to create a new chroot environment, and setup Coriolis2.
  3. Once cgt window appears, go to File, Open Cell, and type chip_r.
  4. You should now have a working Coriolis chroot!

In a terminal (of course you checked what this does before running it because it is "commands downloaded off the internet", and you of course take absolute and complete and full responsibility):

$ git clone https://git.libre-soc.org/git/dev-env-setup.git
$ cd ~/dev-env-setup
$ sudo bash
# ./coriolis2-chroot

And now you wait... (about 30-45min, depends on your CPU). I suggest occasionallly checking the status messages, especially after apt finished updating the packages and the script moves on to compiling yosys, coriolis2, alliance, as well as when alliance-check-toolkit generates the floorplan for you.

This is what the chip floorplan should look like:

Automated Installation - Separated Steps

The steps performed by "coriolis2-chroot" can be done manually and are:

  1. Run the script "mk-deb-chroot" to create a chroot environment. Tutorial assumes the name is "coriolis"
  2. Run the script "cp-scripts-to-chroot" to copy the dev-env-setup directory over to your new chroot environment.
  3. Login into the new scroot environment as a normal user (should be the same as your current user).
  4. Run the script "coriolis-install"

In a terminal:

$ cd ~/dev-env-setup
$ sudo bash
# ./mk-deb-chroot coriolis
# ./cp-scripts-to-chroot coriolis

In a separate terminal as normal user:

$ scroot -c coriolis
(coriolis)$ cd ~/dev-env-setup
(coriolis)$ ./coriolis-install

Further Details

Python3 Coriolis Support

A separate script will be written to use the latest development version of Coriolis2. For now however, a stable version is pulled in, which still uses Python2.

Chroot/Jail Environment

See devscripts for explanation of the "mk-deb-chroot" script.

Coriolis2 Setup

These are nominally taken from https://www-soc.lip6.fr/equipe-cian/logiciels/coriolis/ however there are errors in the original at the moment. Do not try qt5, it will not work.

In ~/.bash_profile add the following so that builds (rebuilds) if you need them will be quicker, and you can run the GUI from the chroot:

export PATH=/usr/lib/ccache:"$PATH"
export DISPLAY=:0.0

Second (or at a new terminal / xterm), log in as root on the host (not the chroot) then do schroot -c coriolis to get to be root in the chroot (or, you can install sudo in the chroot and then do "sudo bash" in the chroot).

Then run the following commands, as root, in the chroot:

apt-get update
apt-get install -y automake binutils-dev bison build-essential \
ccache clang cmake doxygen dvipng flex gcc git graphviz \
imagemagick libboost-all-dev libboost-python-dev libbz2-dev \
libmpfr-dev libgmp-dev libmotif-dev libreadline-dev \
libqwt-dev libtool libx11-dev libxaw7-dev libxml2-dev \
libxpm-dev libxt-dev python3.7 python3-jinja2 python3-pip \
python3-setuptools python-dev python-qt4 python-sphinx \
qt4-dev-tools rapidjson-dev tcl tcl-dev tcl-tclreadline \
texlive texlive-fonts-extra texlive-lang-french \
texlive-latex-extra texlive-pictures xfig yosys zlib1g-dev

Then, as the ordinary (non-root) user in the schroot:

mkdir -p ~/coriolis-2.x/src
cd ~/coriolis-2.x/src
git clone https://gitlab.lip6.fr/vlsi-eda/coriolis.git
cd coriolis
git checkout LS180_RC7_FINAL
./bootstrap/ccb.py --project=coriolis --make="-j$(nproc) install"

Note: Instead of "devel", "LS180_RC7_FINAL" is used as it is more stable. Once Python3 support is added, can switch to using "devel".

To set up the coriolis2 environment, run this:

eval `~/coriolis-2.x/src/coriolis/bootstrap/coriolisEnv.py`

For convenience that may be placed in a file and "sourced", to avoid having to look this page up every time

/bin/bash << EOF
/home/$USER/coriolis-2.x/src/coriolis/bootstrap/coriolisEnv.py > /home/$USER/coriolisenv
EOF
source ~/coriolisenv

For now a workaround must be used for coriolisEnv.py to correctly detect the shell (Bash in this case).

Testing coriolis2

To run the graphical editor go to the bin directory

cd ~/coriolis-2.x/Linux.MyARCH/Release.Shared/install/bin
./cgt

Then run the following commands from the menubar

Tutorials / Run Demo (Python Flavour)

If the following window appears you have an error.

click on the chicken several times

If you have the following, congratulations:

Upgrading to latest yosys in the chroot

yosys in debian may not be enough to work with nmigen, therefore it's probably a good idea to upgrade.

As root, in the chroot, run the following:

apt-get update
apt-get build-dep yosys
apt-get install clang
apt-get remove yosys

This will remove debian/buster yosys however getting the build dependencies is quick and easy enough.

As the ordinary user, the following instructions can be followed (https://github.com/YosysHQ/yosys)

cd ~
git clone https://github.com/YosysHQ/yosys
cd yosys
git checkout 049e3abf9baf795e69b9ecb9c4f19de6131f8418
make config-clang
make -j$(nproc)

Note: For now a stable version of yosys is used!

As root, run:

make install

Alliance

Adapted from https://www-soc.lip6.fr/en/team-cian/softwares/alliance/

In the chroot, as the ordinary schroot user, in ~/.bash_profile add the following so that builds (rebuilds, if you need them) will be quicker:

export PATH=/usr/lib/ccache:"$PATH"

In the chroot, as the ordinary schroot user:

mkdir -p alliance/build alliance/install
cd ~/alliance
git clone https://gitlab.lip6.fr/vlsi-eda/alliance.git
mv alliance/alliance/src alliance
rm -rf alliance/alliance
cd alliance/src
./autostuff
cd ~/alliance/build
export ALLIANCE_TOP=$HOME/alliance/install
export LD_LIBRARY_PATH=${ALLIANCE_TOP}/lib:${LD_LIBRARY_PATH}
export LD_LIBRARY_PATH=${ALLIANCE_TOP}/lib64:${LD_LIBRARY_PATH}
../alliance/src/configure --prefix=$ALLIANCE_TOP --enable-alc-shared
make -j1 install

The three exports are best added to ~/.bash_profile for later convenience

Tutorials and checks

Install alliance-check-toolkit in the chroot:

Run the following (if not done already):

source ~/coriolisenv

Git clone alliance-check-toolkit:

git clone https://gitlab.lip6.fr/vlsi-eda/alliance-check-toolkit.git

You must create a configuration for your user in alliance-check-toolkit to define where the various tools are installed:

touch alliance-check-toolkit/etc/mk/users.d/user-$USERNAME.mk
cat <<EOF >>alliance-check-toolkit/etc/mk/users.d/user-$USERNAME.mk
export CORIOLIS_TOP=/home/$USERNAME/coriolis-2.x/Linux.x86_64/Release.Shared/install
export ALLIANCE_TOP=/home/$USERNAME/alliance/install
export CHECK_TOOLKIT=/home/$USERNAME/alliance-check-toolkit
export YOSYS_TOP=/home/$USERNAME/yosys
EOF

You can try the user adder benchmark in alliance-check-toolkit:

cd alliance-check-toolkit/benchs/adder/cmos
make lvx

This should take about five minutes. It's symbolic, but should be a configuration compatible with 180nm. To actually see the results:

make cgt

Then:

Select File -> Open Cell or press CTRL + o

Enter as the cell name (without the single quotation marks):

'chip_r'

As a very rough approximation, you can say that one lambda equals 180nm.

It depends on the zoom level and of the fact that you ask to see the inside of the cells.

To actually see the transistors:

Tools -> Controller -> Filter Tab -> check "Process Terminal Cells"

You can also tweak the layer display by selecting:

Tools -> Controller -> Layers & Go

You can quicly hide/show the Controller with:

CTRL+I

The up-to-date documentation is supplied directly in the Coriolis repository:

coriolis/documentation/output/index.html

The links toward the doxygen doc will be invalid a this point, but everything else works.

After installation, it is put in:

coriolis-2.x/Linux.x86_64/Release.Shared/install/share/doc/coriolis2/en/html/index.html

More Information from Jean-Paul

There is a WIP documentation website for Alliance/Coriolis at http://coriolis.lip6.fr/.

There are also very cursory informations about installing Alliance here: https://www-soc.lip6.fr/en/team-cian/softwares/alliance/

You also have a third repository for various blocks/chip/examples here: https://gitlab.lip6.fr/jpc/alliance-check-toolkit

(with a basic doc under "doc/"...)

Clone "soclayout" repository and place and route a layout experiment

In order to do the physical layout of the logical netlists generated by yosys we use coriolis and alliace installed above by doing the following (using experiment9 as an example):

$ source ~/coriolisenv  # if not done already
$ cd ~/src
$ git clone https://git.libre-soc.org/git/soclayout.git
$ cd soclayout/
$ git submodule update --init --recursive
$ find . -type f -exec sed -i 's/'lkcl'/'"$USER"'/g' {} \;
$ ./mksym.sh
$ cd experiments9
$ ./mksym.sh
$ yosys
yosys> read_ilang test_issuer.il
yosys> heirarchy -check -top test_issuer
yosys> synth -top test_issuer
yosys> dfflibmap -liberty /home/USERNAME/alliance/install/cells/sxlib/sxlib.lib
yosys> abc -liberty /home/USERNAME/alliance/install/cells/sxlib/sxlib.lib
yosys> clean
yosys> write_blif test_issuer.blif
yosys> exit
$ make pinmux
$ make layout (will take between 20min and 2 hours depending on your hardware)
$ make view

A window should open with with contents that look like this (pretty isn't it?)

Issues running from (e.g.) archlinux as host and debian as a chroot

You may run into difficulties firing up GUI applications from the chroot. Try installing Xnest https://box.matto.nl/xnest.html which you should do in the host system. Also remember to install a "basic" window manager (twm, fvwm2)

On the host, run Xnest and a window manager:

Xnest :1 -ac &
twm -display :1 &

Then, in the chroot, change DISPLAY environment variable (permanently in ~/.bash_profile if desired)

export DISPLAY=:1.0

Then, in the chroot, follow the cgt instructions above, or use "make view" in any of the soclayout experiments or alliance-check-toolkit bench tests

Libre-SOC 180nm ASIC reproducible build

Prerequisites:

  • machine with debian/10 (or if you absolutely must, ubuntu)
  • minimum 32 GB RAM
  • minimum XEON processor or Intel i9 or IBM POWER9
  • enough time to complete the build in full
  • around 50 GB free space (this is more than enough)

WARNING! DO NOT TRY RUNNING CORIOLIS2 IN QEMU OR OTHER VM! VLSI builds are far too CPU and memory intensive.

Follow these instructions to build the ls180 GDS-II files

The FreePDK45 Chips4Makers FlexLib variant is slightly different, in that it builds GDS-II rather than Alliance Symbolic and so requires klayout to view the GDS-II. We do not yet have a build script for klayout, it will be in dev-env-setup when it is. In the meantime you can follow instructions on the website https://klayout.de/

Please check these scripts before running them. This is your responsibility. Also as explained in the HDL workflow the standard OS for reproducible builds is debian/10. It is just about possible to use ubuntu to run the debootstrap chroot setup but it is not recommended.

Commands to run:

$ git clone https://git.libre-soc.org/git/dev-env-setup.git
$ cd dev-env-setup
$ sudo bash
# ./coriolis2-chroot
# exit
$ schroot -c coriolis
$ source ~/coriolisenv
$ cd soclayout/experiments9
$ git checkout LS180_RC8_FINAL
$ ./build_full_4k_sram_recon.sh

(now do something else for the next 90 minutes)