HDL_workflow/coriolis2.mdwn

   1 # Installing Coriolis2
   2
   3 Videos and links:
   4
   5 * <https://www.youtube.com/watch?v=TN9AQgoVwDw&list=PLj2N46Uqs4huGN-redGHVEILPz17OBu37&index=11>
   6 * <http://coriolis.lip6.fr/>
   7 * <https://gitlab.lip6.fr/vlsi-eda>
   8 * <https://www.youtube.com/watch?v=C0diiTc7_VI&list=PLBtNqZjUZB80uByfZVm0gGYEtmTG0mZzm&index=5>
   9 * <https://www.youtube.com/watch?v=e0ATrAlNzWk>
  10 * <https://fosdem.org/2022/schedule/event/coriolis2/>
  11 * <https://archive.fosdem.org/2021/schedule/event/alliance/>
  12 * <https://www.youtube.com/watch?v=TN9AQgoVwDw>
  13 * HiTas (tasyagle) page: [[tasyagle]]
  14
  15 ## Automated Installation - One-liner
  16
  17 The new automated method of installing/setting up Coriolis2 is as follows:
  18
  19 1. Clone the repo "dev-env-setup".
  20   <https://git.libre-soc.org/?p=dev-env-setup.git;a=summary>
  21   Tutorial assumes the directory is located under user's home.
  22 2. Run the script "coriolis2-chroot" to create a new chroot environment,
  23    and setup Coriolis2.
  24 3. Once cgt window appears, go to File, Open Cell, and type chip_r.
  25 4. You should now have a working Coriolis chroot!
  26
  27 In a terminal (of course you checked what this does before running
  28 it because it is "commands downloaded off the internet", and you
  29 of course take absolute and complete and full responsibility):
  30
  31     $ git clone https://git.libre-soc.org/git/dev-env-setup.git
  32     $ cd ~/dev-env-setup
  33     $ sudo bash
  34     # ./coriolis2-chroot
  35
  36 And now you wait... (about 30-45min, depends on your CPU).
  37 I suggest occasionallly checking the status messages,
  38 especially after apt finished updating the packages and the script moves on
  39 to compiling yosys, coriolis2, alliance, as well as when
  40 alliance-check-toolkit generates the floorplan for you.
  41
  42 This is what the chip floorplan should look like:
  43
  44 [[!img chip_r_floorplan.png ]]
  45
  46 ## Automated Installation - Separated Steps
  47 The steps performed by "coriolis2-chroot" can be done manually and are:
  48
  49 1. Run the script "mk-deb-chroot" to create a chroot environment.
  50 Tutorial assumes the name is "coriolis"
  51 1. Run the script "cp-scripts-to-chroot" to copy the dev-env-setup directory
  52 over to your new chroot environment.
  53 1. Login into the new scroot environment as a normal user
  54 (should be the same as your current user).
  55 1. Run the script "coriolis-install"
  56
  57 In a terminal:
  58
  59     $ cd ~/dev-env-setup
  60     $ sudo bash
  61     # ./mk-deb-chroot coriolis
  62     # ./cp-scripts-to-chroot coriolis
  63
  64 In a separate terminal as normal user:
  65
  66     $ scroot -c coriolis
  67     (coriolis)$ cd ~/dev-env-setup
  68     (coriolis)$ ./coriolis-install
  69
  70 # Further Details
  71
  72 ## Python3 Coriolis Support
  73
  74 A separate script will be written to use the latest development version of Coriolis2.
  75 For now however, a stable version is pulled in, which still uses Python2.
  76
  77 ## Chroot/Jail Environment
  78
  79 See [[devscripts]] for explanation of the "mk-deb-chroot" script.
  80
  81 ## Coriolis2 Setup
  82
  83 These are nominally taken from
  84 <https://www-soc.lip6.fr/equipe-cian/logiciels/coriolis/>
  85 however there are errors in the original at the moment.
  86 Do not try qt5, it will not work.
  87
  88 In ~/.bash\_profile add the following so that builds (rebuilds) if you need
  89 them will be quicker, and you can run the GUI from the chroot:
  90
  91     export PATH=/usr/lib/ccache:"$PATH"
  92     export DISPLAY=:0.0
  93
  94 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).
  95
  96 Then run the following commands, as root, *in* the chroot:
  97
  98     apt-get update
  99     apt-get install -y automake binutils-dev bison build-essential \
 100     ccache clang cmake doxygen dvipng flex gcc git graphviz \
 101     imagemagick libboost-all-dev libboost-python-dev libbz2-dev \
 102     libmpfr-dev libgmp-dev libmotif-dev libreadline-dev \
 103     libqwt-dev libtool libx11-dev libxaw7-dev libxml2-dev \
 104     libxpm-dev libxt-dev python3.7 python3-jinja2 python3-pip \
 105     python3-setuptools python-dev python-qt4 python-sphinx \
 106     qt4-dev-tools rapidjson-dev tcl tcl-dev tcl-tclreadline \
 107     texlive texlive-fonts-extra texlive-lang-french \
 108     texlive-latex-extra texlive-pictures xfig yosys zlib1g-dev
 109
 110 Then, as the ordinary (non-root) user in the schroot:
 111
 112     mkdir -p ~/coriolis-2.x/src
 113     cd ~/coriolis-2.x/src
 114     git clone https://gitlab.lip6.fr/vlsi-eda/coriolis.git
 115     cd coriolis
 116     git checkout LS180_RC7_FINAL
 117     ./bootstrap/ccb.py --project=coriolis --make="-j$(nproc) install"
 118
 119 Note: Instead of "devel", "LS180_RC7_FINAL" is used as it is more stable.
 120 Once Python3 support is added, can switch to using "devel".
 121
 122 To set up the coriolis2 environment, run this:
 123
 124     eval `~/coriolis-2.x/src/coriolis/bootstrap/coriolisEnv.py`
 125
 126 For convenience that may be placed in a file and "sourced", to avoid
 127 having to look this page up every time
 128
 129     /bin/bash << EOF
 130     /home/$USER/coriolis-2.x/src/coriolis/bootstrap/coriolisEnv.py > /home/$USER/coriolisenv
 131     EOF
 132     source ~/coriolisenv
 133
 134 For now a workaround must be used for coriolisEnv.py to correctly detect the shell (Bash in this case).
 135
 136 ## Testing coriolis2
 137
 138 To run the graphical editor go to the bin directory
 139
 140     cd ~/coriolis-2.x/Linux.MyARCH/Release.Shared/install/bin
 141     ./cgt
 142
 143 Then run the following commands from the menubar
 144
 145     Tutorials / Run Demo (Python Flavour)
 146
 147 If the following window appears you have an error.
 148
 149 [[!img chicken.png ]]
 150
 151 click on the chicken several times
 152
 153 If you have the following, congratulations:
 154
 155 [[!img demo_cell.png ]]
 156
 157 # Upgrading to latest yosys in the chroot
 158
 159 yosys in debian may not be enough to work with nmigen,
 160 therefore it's probably a good idea to upgrade.
 161
 162 As root, in the chroot, run the following:
 163
 164     apt-get update
 165     apt-get build-dep yosys
 166     apt-get install clang
 167     apt-get remove yosys
 168
 169 This will remove debian/buster yosys however getting the build dependencies is quick and easy enough.
 170
 171 As the ordinary user, the following instructions can be followed
 172 (<https://github.com/YosysHQ/yosys>)
 173
 174     cd ~
 175     git clone https://github.com/YosysHQ/yosys
 176     cd yosys
 177     git checkout 049e3abf9baf795e69b9ecb9c4f19de6131f8418
 178     make config-clang
 179     make -j$(nproc)
 180
 181 Note: For now a stable version of yosys is used!
 182
 183 As root, run:
 184
 185     make install
 186
 187 ## Alliance
 188
 189 Adapted from <https://www-soc.lip6.fr/en/team-cian/softwares/alliance/>
 190
 191 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:
 192
 193     export PATH=/usr/lib/ccache:"$PATH"
 194
 195 In the chroot, as the ordinary schroot user:
 196
 197     mkdir -p alliance/build alliance/install
 198     cd ~/alliance
 199     git clone https://gitlab.lip6.fr/vlsi-eda/alliance.git
 200     mv alliance/alliance/src alliance
 201     rm -rf alliance/alliance
 202     cd alliance/src
 203     ./autostuff
 204     cd ~/alliance/build
 205     export ALLIANCE_TOP=$HOME/alliance/install
 206     export LD_LIBRARY_PATH=${ALLIANCE_TOP}/lib:${LD_LIBRARY_PATH}
 207     export LD_LIBRARY_PATH=${ALLIANCE_TOP}/lib64:${LD_LIBRARY_PATH}
 208     ../alliance/src/configure --prefix=$ALLIANCE_TOP --enable-alc-shared
 209     make -j1 install
 210
 211 The three exports are best added to ~/.bash_profile for later convenience
 212
 213 # Tutorials and checks
 214
 215 Install alliance-check-toolkit in the chroot:
 216
 217 * <https://gitlab.lip6.fr/vlsi-eda/alliance-check-toolkit.git>
 218 * See coriolis-2.x/Linux.x86_64/Release.Shared/install/share/doc/coriolis2/en/html/main/PythonTutorial/index.html
 219
 220 Run the following (if not done already):
 221
 222     source ~/coriolisenv
 223
 224 Git clone alliance-check-toolkit:
 225
 226     git clone https://gitlab.lip6.fr/vlsi-eda/alliance-check-toolkit.git
 227
 228 You must create a configuration for your user in alliance-check-toolkit to define where the various tools are installed:
 229
 230     touch alliance-check-toolkit/etc/mk/users.d/user-$USERNAME.mk
 231     cat <<EOF >>alliance-check-toolkit/etc/mk/users.d/user-$USERNAME.mk
 232     export CORIOLIS_TOP=/home/$USERNAME/coriolis-2.x/Linux.x86_64/Release.Shared/install
 233     export ALLIANCE_TOP=/home/$USERNAME/alliance/install
 234     export CHECK_TOOLKIT=/home/$USERNAME/alliance-check-toolkit
 235     export YOSYS_TOP=/home/$USERNAME/yosys
 236     EOF
 237
 238 You can try the user adder benchmark in alliance-check-toolkit:
 239
 240     cd alliance-check-toolkit/benchs/adder/cmos
 241     make lvx
 242
 243 This should take about five minutes. It's symbolic, but should be a configuration compatible with 180nm. To actually see the results:
 244
 245     make cgt
 246
 247 Then:
 248
 249     Select File -> Open Cell or press CTRL + o
 250
 251 Enter as the cell name (without the single quotation marks):
 252
 253     'chip_r'
 254
 255 As a very rough approximation, you can say that one lambda equals 180nm.
 256
 257 It depends on the zoom level and of the fact that you ask to see the inside of the cells.
 258
 259 To actually see the transistors:
 260
 261     Tools -> Controller -> Filter Tab -> check "Process Terminal Cells"
 262
 263 You can also tweak the layer display by selecting:
 264
 265     Tools -> Controller -> Layers & Go
 266
 267   You can quicly hide/show the Controller with:
 268
 269     CTRL+I
 270
 271 The up-to-date documentation is supplied directly in the Coriolis repository:
 272
 273     coriolis/documentation/output/index.html
 274
 275 The links toward the doxygen doc will be invalid a this point, but everything else works.
 276
 277 After installation, it is put in:
 278
 279     coriolis-2.x/Linux.x86_64/Release.Shared/install/share/doc/coriolis2/en/html/index.html
 280
 281 ## More Information from Jean-Paul
 282
 283 There is a WIP documentation website for Alliance/Coriolis at <http://coriolis.lip6.fr/>.
 284
 285 There are also very cursory informations about installing Alliance here:
 286     https://www-soc.lip6.fr/en/team-cian/softwares/alliance/
 287
 288 You also have a third repository for various blocks/chip/examples here:
 289     https://gitlab.lip6.fr/jpc/alliance-check-toolkit
 290
 291 (with a basic doc under "doc/"...)
 292
 293 # Clone "soclayout" repository and place and route a layout experiment
 294
 295 In order to do the physical layout of the logical
 296 netlists generated by yosys we use coriolis and
 297 alliace installed above by doing the following
 298 (using experiment9 as an example):
 299
 300     $ source ~/coriolisenv  # if not done already
 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_RC8_FINAL>
 367 * run the ./build_full_4k_sram_recon.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 $ source ~/coriolisenv
 394 $ cd soclayout/experiments9
 395 $ git checkout LS180_RC8_FINAL
 396 $ ./build_full_4k_sram_recon.sh
 397 ```
 398 (now do something else for the next 90 minutes)
 399