HDL_workflow/coriolis2.mdwn

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