HDL_workflow/coriolis2.mdwn

   1 # Installing Coriolis2
   2
   3 TODO: include tasyagle <https://www-soc.lip6.fr/en/team-cian/softwares/tasyagle/>
   4
   5 ## debootstrap
   6
   7 First set up an schroot debootstrap jail with debian 10.
   8 These instructions are based on information taken from here:
   9 <https://www.debian.org/releases/stretch/amd64/apds03.html.en>
  10
  11 In advance, on the host system, edit /etc/fstab and add mount points:
  12
  13 (edit: personally I prefer using mount --bind points.  however if doing
  14 that then after a reboot the chroot will lose the bind mountpoints
  15 and the commands need to be re-run, without which the chroot is
  16 unusable)
  17
  18     /dev    /home/chroot/coriolis/dev   none    bind    0   0
  19     /dev/pts /home/chroot/coriolis/dev/pts  none    bind    0   0
  20     /proc   /home/chroot/coriolis/proc  none    bind    0   0
  21     /sys    /home/chroot/coriolis/sys   none    bind    0   0
  22     /tmp    /home/chroot/coriolis/tmp   none    bind    0   0
  23
  24 Then run these commands:
  25
  26     sudo bash
  27     apt-get install debootstrap schroot
  28     mkdir /opt/chroot/coriolis
  29     /usr/sbin/debootstrap buster !$ http://ftp.us.debian.org/debian
  30     mount /home/chroot/coriolis/dev
  31     mount /home/chroot/coriolis/dev/pts
  32     mount   /home/chroot/coriolis/proc
  33     mount   /home/chroot/coriolis/sys
  34     mount   /home/chroot/coriolis/tmp
  35     echo "coriolis2" > /home/chroot/coriolis/etc/debian_chroot
  36
  37 To do some preparation (users):
  38
  39     chroot /home/chroot/coriolis2 /bin/bash
  40     adduser {yourpreferredusername}
  41
  42 It is best to make the username the same as the first user that
  43 was added during the *main* (non-chroot) debian install, so that
  44 uid 1000 matches between both main and chroot.  You can check
  45 this by looking at /etc/passwd as root, or by typing "id".
  46
  47     lkcl@fizzy:~$ id
  48     uid=1000(lkcl) gid=1000(lkcl) groups=1000(lkcl),5(tty),....
  49
  50 Alternatively, /etc/passwd and /etc/group may
  51 be mount-bound as well as /home however if you later forget you did
  52 this and decide to delete the chroot, you will delete the entire /home
  53 of your main system, as well as /etc/passwd.
  54
  55 You may wish to follow some of the other things such as configuring apt,
  56 locales and keyboard, from the above-linked debian-admin HOWTO.
  57
  58 bootloader, kernel, ssh access, are unnecessary. Do run "apt clean" to clear out /var/cache/apt/archives in the chroot.
  59
  60 ## schroot
  61
  62 Create an schroot file section for the coriolis chroot by
  63 editing /etc/schroot/schroot.conf:
  64
  65     [coriolis]
  66     description=Debian Buster for Coriolis
  67     directory=/home/chroot/coriolis
  68     groups=sbuild-security,lkcl,users
  69
  70 Now as an *ordinary* user - not as root - you may type:
  71
  72     lkcl@fizzy:~$ schroot -c coriolis
  73
  74 and, due to the contents of /etc/debian\_chroot, and that you were in
  75 fact logged in as uid 1000 and did in fact add a user to the chroot
  76 as uid 1000, the prompt should become:
  77
  78     (coriolis2)lkcl@fizzy:~$
  79
  80 If however you need to run as root, then from outside the chroot,
  81 as *root*, you run this:
  82
  83     lkcl@fizzy:~# schroot -c coriolis
  84
  85 and you will see this as a result:
  86
  87     (coriolis2)lkcl@fizzy:~#
  88
  89 ## coriolis2
  90
  91 These are nominally taken from
  92 <https://www-soc.lip6.fr/equipe-cian/logiciels/coriolis/>
  93 however there are errors in the original at the moment.
  94 Do not try qt5, it will not work.
  95
  96 In ~/.bash\_profile add the following so that builds (rebuilds) if you need
  97 them will be quicker, and you can run the GUI from the chroot:
  98
  99     export PATH=/usr/lib/ccache:"$PATH"
 100     export DISPLAY=:0.0
 101
 102 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).
 103
 104 Then run the following commands, as root, *in* the chroot:
 105
 106     apt-get update
 107     apt-get install -y automake binutils-dev bison build-essential \
 108     ccache clang cmake doxygen dvipng flex gcc git graphviz \
 109     imagemagick libboost-all-dev libboost-python-dev libbz2-dev \
 110     libmpfr-dev libgmp-dev libmotif-dev libreadline-dev \
 111     libqwt-dev libtool libx11-dev libxaw7-dev libxml2-dev \
 112     libxpm-dev libxt-dev python3.7 python3-jinja2 python3-pip \
 113     python3-setuptools python-dev python-qt4 python-sphinx \
 114     qt4-dev-tools rapidjson-dev tcl tcl-dev tcl-tclreadline \
 115     texlive texlive-fonts-extra texlive-lang-french \
 116     texlive-latex-extra texlive-pictures xfig yosys zlib1g-dev
 117
 118 Then, as the ordinary (non-root) user in the schroot:
 119
 120     mkdir -p ~/coriolis-2.x/src
 121     cd ~/coriolis-2.x/src
 122     git clone https://gitlab.lip6.fr/vlsi-eda/coriolis.git
 123     cd coriolis
 124     git checkout devel
 125     ./bootstrap/ccb.py --project=coriolis --make="-j$(nproc) install"
 126
 127 To set up the coriolis2 environment, run this:
 128
 129     eval `~/coriolis-2.x/src/coriolis/bootstrap/coriolisEnv.py`
 130
 131 For convenience that may be placed in a file and "sourced", to avoid
 132 having to look this page up every time
 133
 134     echo "`~/coriolis-2.x/src/coriolis/bootstrap/coriolisEnv.py`" > \
 135             ~/coriolisenv
 136     source ~/coriolisenv
 137
 138 ## Testing coriolis2
 139
 140 To run the graphical editor go to the bin directory
 141
 142     cd ~/coriolis-2.x/Linux.MyARCH/Release.Shared/install/bin
 143     ./cgt
 144
 145 Then run the following commands from the menubar
 146
 147     Tutorials / Run Demo (Python Flavour)
 148
 149 If the following window appears you have an error.
 150
 151 [[!img chicken.png ]]
 152
 153 click on the chicken several times
 154
 155 If you have the following, congratulations:
 156
 157 [[!img demo_cell.png ]]
 158
 159 # Upgrading to latest yosys in the chroot
 160
 161 yosys in debian may not be enough to work with nmigen,
 162 therefore it's probably a good idea to upgrade.
 163
 164 As root, in the chroot, run the following:
 165
 166     apt-get update
 167     apt-get build-dep yosys
 168     apt-get install clang
 169     apt-get remove yosys
 170
 171 This will remove debian/buster yosys however getting the build dependencies is quick and easy enough.
 172
 173 As the ordinary user, the following instructions can be followed
 174 (<http://www.clifford.at/yosys/download.html>)
 175
 176     cd ~
 177     git clone https://github.com/cliffordwolf/yosys.git
 178     cd yosys
 179     make config-clang
 180     make -j$(nproc)
 181
 182 As root, run:
 183
 184     make install
 185
 186 ## Check out alliance
 187
 188 Adapted from <https://www-soc.lip6.fr/en/team-cian/softwares/alliance/>
 189
 190 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:
 191
 192     export PATH=/usr/lib/ccache:"$PATH"
 193
 194 In the chroot, as the ordinary schroot user:
 195
 196     mkdir -p alliance/build alliance/install
 197     cd ~/alliance
 198     git clone https://gitlab.lip6.fr/vlsi-eda/alliance.git
 199     mv alliance/alliance/src alliance
 200     rm -rf alliance/alliance
 201     cd alliance/src
 202     ./autostuff
 203     cd ~/alliance/build
 204     export ALLIANCE_TOP=$HOME/alliance/install
 205     export LD_LIBRARY_PATH=${ALLIANCE_TOP}/lib:${LD_LIBRARY_PATH}
 206     export LD_LIBRARY_PATH=${ALLIANCE_TOP}/lib64:${LD_LIBRARY_PATH}
 207     ../alliance/src/configure --prefix=$ALLIANCE_TOP --enable-alc-shared
 208     make -j1 install
 209
 210 The three exports are best added to ~/.bash_profile for later convenience
 211
 212 # Tutorials and checks
 213
 214 Install alliance-check-toolkit in the chroot:
 215
 216 * <https://gitlab.lip6.fr/vlsi-eda/alliance-check-toolkit.git>
 217 * See coriolis-2.x/Linux.x86_64/Release.Shared/install/share/doc/coriolis2/en/html/main/PythonTutorial/index.html
 218
 219 Run the following (if not done already):
 220
 221     source ~/coriolisenv
 222
 223 Git clone alliance-check-toolkit:
 224
 225     git clone https://gitlab.lip6.fr/vlsi-eda/alliance-check-toolkit.git
 226
 227 You must create a configuration for your user in alliance-check-toolkit to define where the various tools are installed:
 228
 229     touch alliance-check-toolkit/etc/mk/users.d/user-$USERNAME.mk
 230     cat <<EOF >>alliance-check-toolkit/etc/mk/users.d/user-$USERNAME.mk
 231     export CORIOLIS_TOP=/home/$USERNAME/coriolis-2.x/Linux.x86_64/Release.Shared/install
 232     export ALLIANCE_TOP=/home/$USERNAME/alliance/install
 233     export CHECK_TOOLKIT=/home/$USERNAME/alliance-check-toolkit
 234     export YOSYS_TOP=/home/$USERNAME/yosys
 235     EOF
 236
 237 You can try the ARM in alliance-check-toolkit:
 238
 239     cd alliance-check-toolkit/benchs/ARM/cmos/
 240     make lvx
 241
 242 This should take about five minutes. It's symbolic, but should be a configuration compatible with 180nm. To actually see the results:
 243
 244     make cgt
 245
 246 Then:
 247
 248     Select File -> Open Cell or press CTRL + o
 249
 250 Enter as the cell name (without the single quotation marks):
 251
 252     'arm_chip_cts_r'
 253
 254 As a very rough approximation, you can say that one lambda equals 180nm.
 255
 256 It depends on the zoom level and of the fact that you ask to see the inside of the cells.
 257
 258 To actually see the transistors:
 259
 260     Tools -> Controller -> Filter Tab -> check "Process Terminal Cells"
 261
 262 You can also tweak the layer display by selecting:
 263
 264     Tools -> Controller -> Layers & Go
 265
 266   You can quicly hide/show the Controller with:
 267
 268     CTRL+I
 269
 270 The up-to-date documentation is supplied directly in the Coriolis repository:
 271
 272     coriolis/documentation/output/index.html
 273
 274 The links toward the doxygen doc will be invalid a this point, but everything else works.
 275
 276 After installation, it is put in:
 277
 278     coriolis-2.x/Linux.x86_64/Release.Shared/install/share/doc/coriolis2/en/html/index.html
 279
 280 ## More Information from Jean-Paul
 281
 282 There is a WIP documentation website for Alliance/Coriolis at <http://coriolis.lip6.fr/>.
 283
 284 There are also very cursory informations about installing Alliance here:
 285     https://www-soc.lip6.fr/en/team-cian/softwares/alliance/
 286
 287 You also have a third repository for various blocks/chip/examples here:
 288     https://gitlab.lip6.fr/jpc/alliance-check-toolkit
 289
 290 (with a basic doc under "doc/"...)
 291
 292 # Clone "soclayout" repository and place and route a layout experiment
 293
 294 In order to do the physical layout of the logical
 295 netlists generated by yosys we use coriolis and
 296 alliace installed above by doing the following
 297 (using experiment9 as an example):
 298
 299     $ cd ~/src
 300     $ git clone https://git.libre-soc.org/git/soclayout.git
 301     $ cd soclayout/
 302     $ git submodule update --init --recursive
 303     $ find . -type f -exec sed -i 's/'lkcl'/'"$USER"'/g' {} \;
 304     $ ./mksym.sh
 305     $ cd experiments9
 306     $ ./mksym.sh
 307     $ yosys
 308     yosys> read_ilang test_issuer.il
 309     yosys> heirarchy -check -top test_issuer
 310     yosys> synth -top test_issuer
 311     yosys> dfflibmap -liberty /home/USERNAME/alliance/install/cells/sxlib/sxlib.lib
 312     yosys> abc -liberty /home/USERNAME/alliance/install/cells/sxlib/sxlib.lib
 313     yosys> clean
 314     yosys> write_blif test_issuer.blif
 315     yosys> exit
 316     $ make pinmux
 317     $ make layout (will take between 20min and 2 hours depending on your hardware)
 318     $ make view
 319
 320 A window should open with with contents that look like this (pretty isn't it?)
 321
 322 [[!img 180nm_Oct2020/2020-07-03_11-04.png size="825x" ]]
 323
 324 # Issues running from (e.g.) archlinux as host and debian as a chroot
 325
 326 You may run into difficulties firing up GUI applications from the chroot.
 327 Try installing Xnest <https://box.matto.nl/xnest.html> which you should
 328 do in the *host* system.  Also remember to install a "basic" window manager
 329 (twm, fvwm2)
 330
 331 On the *host*, run Xnest and a window manager:
 332
 333     Xnest :1 -ac &
 334     twm -display :1 &
 335
 336 Then, in the chroot, change DISPLAY environment variable (permanently
 337 in ~/.bash_profile if desired)
 338
 339     export DISPLAY=:1.0
 340
 341 Then, in the chroot, follow the cgt instructions above, or use "make view"
 342 in any of the soclayout experiments or alliance-check-toolkit bench tests
 343
 344 # Libre-SOC 180nm ASIC reproducible build <a name="ls180_repro_build"> </a>
 345
 346 Prerequisites:
 347
 348 * machine with debian/10 (or if you absolutely must, ubuntu)
 349 * minimum 32 GB RAM
 350 * minimum XEON processor or Intel i9 or IBM POWER9
 351 * enough time to complete the build in full
 352 * around 50 GB free space (this is more than enough)
 353
 354 **WARNING! DO NOT TRY RUNNING CORIOLIS2 IN QEMU OR OTHER VM!**
 355 VLSI builds are far too CPU and memory intensive.
 356
 357 Follow these instructions to build the ls180 GDS-II files
 358
 359 * clone the dev-env-setup repository
 360 * run the coriolis2-chroot script as root
 361 * drop into the schroot
 362 * navigate to the soclayout/experiments9 directory
 363 * run the ./build_full_4k_sram.sh script
 364 * run "make view" to see the results.
 365
 366 The FreePDK45 Chips4Makers FlexLib variant is slightly
 367 different, in that it builds GDS-II rather than Alliance Symbolic
 368 and so requires klayout to view the GDS-II. We do not yet
 369  have a build script for klayout, it will be in dev-env-setup
 370 when it is.  In the meantime you can follow instructions
 371 on the website <https://klayout.de/>
 372
 373 Please check these scripts before running them.
 374 **This is your responsibility**.  Also as explained in
 375 the [[HDL_workflow]] the standard OS for reproducible
 376 builds is debian/10.  It is just about possible to use
 377 ubuntu to run the debootstrap chroot setup but it is
 378 not recommended.
 379
 380 Commands to run:
 381
 382 ```
 383 $ git clone https://git.libre-soc.org/git/dev-env-setup.git
 384 $ cd dev-env-setup
 385 $ sudo bash
 386 # ./coriolis2-chroot
 387 # exit
 388 $ schroot -c cotiolis
 389 $ cd soclayout/experiments9
 390 $ ./build_full_4k_sram.sh
 391 ```
 392 (now do something else for the next 90 minutes)
 393