(no commit message)

[libreriscv.git] / HDL_workflow / coriolis2.mdwn

# Installing Coriolis2

## debootstrap

First set up an schroot debootstrap jail with debian 10.
These instructions are based on information taken from here:
<https://www.debian.org/releases/stretch/amd64/apds03.html.en>

In advance, on the host system, edit /etc/fstab and add mount points:

(edit: personally I prefer using mount --bind points.  however if doing
that then after a reboot the chroot will lose the bind mountpoints
and the commands need to be re-run, without which the chroot is
unusable)

    /dev    /home/chroot/coriolis/dev   none    bind    0   0
    /dev/pts /home/chroot/coriolis/dev/pts  none    bind    0   0
    /proc   /home/chroot/coriolis/proc  none    bind    0   0
    /sys    /home/chroot/coriolis/sys   none    bind    0   0
    /tmp    /home/chroot/coriolis/tmp   none    bind    0   0

Then run these commands:

    sudo bash
    apt-get install debootstrap schroot
    mkdir /opt/chroot/coriolis
    /usr/sbin/debootstrap buster !$ http://ftp.us.debian.org/debian
    mount /home/chroot/coriolis/dev
    mount /home/chroot/coriolis/dev/pts
    mount   /home/chroot/coriolis/proc
    mount   /home/chroot/coriolis/sys
    mount   /home/chroot/coriolis/tmp
    echo "coriolis2" > /home/chroot/coriolis/etc/debian_chroot

To do some preparation (users):

    chroot /home/chroot/coriolis2 /bin/bash
    adduser {yourpreferredusername}

It is best to make the username the same as the first user that
was added during the *main* (non-chroot) debian install, so that
uid 1000 matches between both main and chroot.  You can check
this by looking at /etc/passwd as root, or by typing "id".

    lkcl@fizzy:~$ id
    uid=1000(lkcl) gid=1000(lkcl) groups=1000(lkcl),5(tty),....

Alternatively, /etc/passwd and /etc/group may
be mount-bound as well as /home however if you later forget you did
this and decide to delete the chroot, you will delete the entire /home
of your main system, as well as /etc/passwd.

You may wish to follow some of the other things such as configuring apt,
locales and keyboard, from the above-linked debian-admin HOWTO.
bootloader, kernel, ssh access, all these are
unnecessary.  do run "apt clean" to clear out /var/cache/apt/archives
in the chroot.

## schroot

Create an schroot file section for the coriolis chroot by
editing /etc/schroot/schroot.conf:

    [coriolis]
    description=Debian Buster for Coriolis
    directory=/home/chroot/coriolis
    groups=sbuild-security,lkcl,users

Now as an *ordinary* user - not as root - you may type:

    lkcl@fizzy:~$ schroot -c coriolis

and, due to the contents of /etc/debian\_chroot, and that you were in
fact logged in as uid 1000 and did in fact add a user to the chroot
as uid 1000, the prompt should become:

    (coriolis2)lkcl@fizzy:~$

If however you need to run as root, then from outside the chroot,
as *root*, you run this:

    lkcl@fizzy:~# schroot -c coriolis

and you will see this as a result:

    (coriolis2)lkcl@fizzy:~#

## check out alliance and alliance-check-toolkit

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

in the schroot:

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

TODO: document how to build alliance, basically this:

In the chroot, as root:

    apt-get update
    apt-get install ccache git build-essential libtool automake \
             flex bison xfig imagemagick \
             texlive texlive-pictures texlive-latex-extra \
             libx11-dev libxt-dev libxaw7-dev libxpm-dev libmotif-dev

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
    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 two exports are best added to ~/.bash_profile for later convenience

## coriolis2

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 ccache build-essential binutils-dev          \
                  git cmake bison flex gcc python-dev               \
                  libboost-all-dev libboost-python-dev               \
                  zlib1g-dev                                         \
                  libbz2-dev libxml2-dev rapidjson-dev libbz2-dev     \
                  doxygen dvipng graphviz python-sphinx               \
                  texlive-fonts-extra texlive-lang-french            \
                  libqwt-dev qt4-dev-tools python-qt4               \
                   libxt-dev libxpm-dev libmotif-dev                \
                   yosys

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 devel
    ./bootstrap/ccb.py --project=coriolis --make="-j4 install"

In debian/buster at the moment, this will fail half-way through, due to
libraries not being found.  When that happens run this:

    ln -s ~/coriolis-2.x/Linux.x86_64/Release.Shared/install/lib64 \
          ~/coriolis-2.x/Linux.x86_64/Release.Shared/install/lib

Then carry on with the build.

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

    echo "eval `~/coriolis-2.x/src/coriolis/bootstrap/coriolisEnv.py`" > \
            ~/coriolisenv
    source ~/coriolisenv

## 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.

[[!img chicken.png ]]

click on the chicken several times

If you have the following, congratulations:

[[!img demo_cell.png ]]

# Tutorials and checks

Install alliance-check-toolkit in the chroot:

* <https://gitlab.com/Chips4Makers/alliance-check-toolkit>
* See coriolis-2.x/Linux.x86_64/Release.Shared/install/share/doc/coriolis2/en/html/main/PythonTutorial/index.html

Run the following (if not done already):

    source ~/coriolisenv

Then, picking a random example:

    cd alliance-check-toolkit/benchs/AM2901/standart_cells/cmos
    make lvx
    make view

A nice view of a chip should appear

## Information from Jean-Paul

There should be very soon a website at https://coriolis.lip6.fr (it is not yet
online). Where I intend to put all the documentation about Alliance/Coriolis.

In the meantime did you find the doc shipped with Coriolis ?

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/"...)

## More from JP

You must create a configuration for alliance-check-toolkit:

    alliance-check-toolkit/etc/mk/users.d/user-LOGIN.mk

    where you define where the various tools are installed
    (look in other ones to have an idea).

  You can try the ARM in alliance-check-toolkit:

    > cd alliance-check-toolkit/benchsARM/cmos/
    > make lvx

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

    > make cgt

    Then "File -> Open", "arm_chip_cts_r"

    To have a very rough approximation, you can say that one lambda
    equal 180nm.

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:
   Tools -> Controller -> Layers & Go

  You can quicly hide/show the Controller with CTRL+I.

  You may also toy with Controller -> Look, try the other ones.
  If you want a new one, to mimic something you're better
  familiar with, it's in configurations files all written
  in Python so easy to do, if a little tedious.

> i'd expect such a chip to be in the alliance-check-toolkit however we
> don't even know what we're looking at in order to know which bits we
> need, let alone know what to do or how to run them.
>
> we're *literally* completely in the dark, here, having never done this
> before - at all - so unless there's a specific tutorial which says, to
> make a chip layout do this: "step 1: install these tools.  step 2: get
> this project repo.  step 3: cd to this directory.  step 4: run make or
> ./compile-place-and-route.sh" we're absolutely lost.
>
> thx jean-paul, and apologies for not knowing where to begin, here.

  No problem. You're welcome.

  The doc is mostly for people who already have a background in ASICs,
  I will try to patch something from my lecture in VLSI to help people
  to orient themselves.

  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 everython else works.

   After installation, it is put in:

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

# Installing python3.7 into debian/buster chroot

as root, in the chroot:

    apt-get install python3.7 python3-setuptools \
               python3-jinja2 python3-pip

At this point it becomes possible to follow the main
instructions in [[HDL_workflow]] for installing nmigen,
ieee754fpu, soc and nmutil.

# 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.
To install from source, add the following to
/etc/apt/sources.list:

   deb-src http://ftp.uk.debian.org/debian buster main

then 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.

then, as the ordinary user, the following instructions can be followed
(<http://www.clifford.at/yosys/download.html>)

    cd ~
    git clone https://github.com/cliffordwolf/yosys.git
    cd yosys
    make config-clang
    make -j4

as root, run:

    make install

# Check out the libresoc "soclayout" repository

See [[HDL_workflow]] for git clone instructions

    $ git clone ssh://gitolite3@git.libre-riscv.org:922/libresoc.git

TODO further, here.

# 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