HDL_workflow/coriolis2.mdwn

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