HDL_workflow/coriolis2.mdwn

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