HDL_workflow/coriolis2.mdwn

   1 TODO, repos moved
   2 git remote set-url origin https://gitlab.lip6.fr/vlsi-eda/alliance-check-toolkit.git
   3   git remote set-url origin https://gitlab.lip6.fr/vlsi-eda/alliance.git
   4   git remote set-url origin https://gitlab.lip6.fr/vlsi-eda/coriolis.git
   5
   6 # Installing Coriolis2
   7
   8 ## debootstrap
   9
  10 First set up an schroot debootstrap jail with debian 9.0.
  11 These instructions are based on information taken from here:
  12 <https://www.debian.org/releases/stretch/amd64/apds03.html.en>
  13
  14 In advance, on the host system, edit /etc/fstab and add mount points:
  15
  16 (edit: personally I prefer using mount --bind points.  however if doing
  17 that then after a reboot the chroot will lose the bind mountpoints
  18 and the commands need to be re-run, without which the chroot is
  19 unusable)
  20
  21     /dev    /home/chroot/coriolis/dev   none    bind    0   0
  22     /dev/pts /home/chroot/coriolis/dev/pts  none    bind    0   0
  23     /proc   /home/chroot/coriolis/proc  none    bind    0   0
  24     /sys    /home/chroot/coriolis/sys   none    bind    0   0
  25     /tmp    /home/chroot/coriolis/tmp   none    bind    0   0
  26
  27 Then run these commands:
  28
  29     sudo bash
  30     apt-get install debootstrap schroot
  31     mkdir /opt/chroot/coriolis
  32     /usr/sbin/debootstrap stretch !$ http://ftp.us.debian.org/debian
  33     mount /home/chroot/coriolis/dev
  34     mount /home/chroot/coriolis/dev/pts
  35     mount   /home/chroot/coriolis/proc
  36     mount   /home/chroot/coriolis/sys
  37     mount   /home/chroot/coriolis/tmp
  38     echo "coriolis2" > /home/chroot/coriolis/etc/debian_chroot
  39
  40 To do some preparation (users):
  41
  42     chroot /home/chroot/coriolis2 /bin/bash
  43     adduser {yourpreferredusername}
  44
  45 It is best to make the username the same as the first user that
  46 was added during the *main* (non-chroot) debian install, so that
  47 uid 1000 matches between both main and chroot.  You can check
  48 this by looking at /etc/passwd as root, or by typing "id".
  49
  50     lkcl@fizzy:~$ id
  51     uid=1000(lkcl) gid=1000(lkcl) groups=1000(lkcl),5(tty),....
  52
  53 Alternatively, /etc/passwd and /etc/group may
  54 be mount-bound as well as /home however if you later forget you did
  55 this and decide to delete the chroot, you will delete the entire /home
  56 of your main system, as well as /etc/passwd.
  57
  58 You may wish to follow some of the other things such as configuring apt,
  59 locales and keyboard, from the above-linked debian-admin HOWTO.
  60 bootloader, kernel, ssh access, all these are
  61 unnecessary.  do run "apt clean" to clear out /var/cache/apt/archives
  62 in the chroot.
  63
  64 ## schroot
  65
  66 Create an schroot file section:
  67
  68     [coriolis]
  69     description=Debian Stable for Coriolis
  70     directory=/home/chroot/coriolis
  71     groups=sbuild-security,lkcl,users
  72
  73 Now as an *ordinary* user - not as root - you may type:
  74
  75     lkcl@fizzy:~$ schroot -c coriolis
  76
  77 and, due to the contents of /etc/debian\_chroot, and that you were in
  78 fact logged in as uid 1000 and did in fact add a user to the chroot
  79 as uid 1000, the prompt should become:
  80
  81     (coriolis2)lkcl@fizzy:~$
  82
  83 If however you need to run as root, then from outside the chroot,
  84 as *root*, you run this:
  85
  86     lkcl@fizzy:~# schroot -c coriolis
  87
  88 and you will see this as a result:
  89
  90     (coriolis2)lkcl@fizzy:~#
  91
  92 ## check out alliance and alliance-check-toolkit
  93
  94 Adapted from <https://www-soc.lip6.fr/en/team-cian/softwares/alliance/>
  95
  96 in the schroot:
  97
  98     git clone https://gitlab.lip6.fr/jpc/alliance-check-toolkit.git
  99
 100 TODO: document how to build alliance, basically this:
 101
 102 In the chroot, as root:
 103
 104     apt-get update
 105     apt-get install ccache git build-essential libtool automake \
 106              flex bison xfig imagemagick \
 107              texlive texlive-pictures texlive-latex-extra \
 108              libx11-dev libxt-dev libxaw7-dev libxpm-dev libmotif-dev
 109
 110 In the chroot, as the ordinary schroot user, in ~/.bash\_profile add
 111 the following so that builds (rebuilds) if you need them will be quicker:
 112
 113     export PATH=/usr/lib/ccache:"$PATH"
 114
 115 In the chroot, as the ordinary schroot user:
 116
 117     mkdir -p alliance/build alliance/install
 118     cd ~/alliance
 119     git clone https://www-soc.lip6.fr/git/alliance.git
 120     cd alliance/src
 121     ./autostuff
 122     cd ~/alliance/build
 123     export ALLIANCE_TOP=$HOME/alliance/install
 124     export LD_LIBRARY_PATH=${ALLIANCE_TOP}/lib:${LD_LIBRARY_PATH}
 125     export LD_LIBRARY_PATH=${ALLIANCE_TOP}/lib64:${LD_LIBRARY_PATH}
 126     ../alliance/src/configure --prefix=$ALLIANCE_TOP --enable-alc-shared
 127     make -j1 install
 128
 129 the two exports are best added to ~/.bash_profile for later convenience
 130
 131 ## coriolis2
 132
 133 These are nominally taken from
 134 <https://www-soc.lip6.fr/equipe-cian/logiciels/coriolis/>
 135 however there are errors in the original at the moment.
 136 Do not try qt5, it will not work.
 137
 138 In ~/.bash\_profile add the following so that builds (rebuilds) if you need
 139 them will be quicker, and you can run the GUI from the chroot:
 140
 141     export PATH=/usr/lib/ccache:"$PATH"
 142     export DISPLAY=:0.0
 143
 144 Second (or at a new terminal / xterm), log in as root on the host (not
 145 the chroot) then do schroot -c coriolis to get to be root in the chroot
 146 (or, you can install sudo in the chroot and then do "sudo bash" in the
 147 chroot).
 148
 149 Then run the following commands, as root, *in* the chroot:
 150
 151     apt-get update
 152     apt-get install -y ccache build-essential binutils-dev          \
 153                   git cmake bison flex gcc python-dev               \
 154                   libboost-all-dev libboost-python-dev               \
 155                   zlib1g-dev                                         \
 156                   libbz2-dev libxml2-dev rapidjson-dev libbz2-dev     \
 157                   doxygen dvipng graphviz python-sphinx               \
 158                   texlive-fonts-extra texlive-lang-french            \
 159                   libqwt-dev qt4-dev-tools python-qt4               \
 160                    libxt-dev libxpm-dev libmotif-dev                \
 161                    yosys
 162
 163 Then, as the ordinary (non-root) user in the schroot:
 164
 165     mkdir -p ~/coriolis-2.x/src
 166     cd ~/coriolis-2.x/src
 167     git clone https://www-soc.lip6.fr/git/coriolis.git
 168
 169     cd coriolis
 170     git checkout devel
 171     ./bootstrap/ccb.py --project=coriolis --make="-j4 install"
 172
 173 To set up the alliance environment, run this:
 174
 175     eval `~/coriolis-2.x/src/coriolis/bootstrap/coriolisEnv.py`
 176
 177 For convenience that may be placed in a file and "sourced", to avoid
 178 having to look this page up every time
 179
 180     echo "eval `~/coriolis-2.x/src/coriolis/bootstrap/coriolisEnv.py`" > \
 181             ~/coriolisenv
 182     source ~/coriolisenv
 183
 184 To run the graphical editor go to the bin directory
 185
 186      cd ~/coriolis-2.x/Linux.MyARCH/Release.Shared/install/bin
 187     ./cgt
 188
 189 Then run the following commands from the menubar
 190
 191     Tutorials / Run Demo (Python Flavour)
 192
 193 The following window will appear
 194
 195 [[!img chicken.png ]]
 196
 197 click on the chicken several times
 198
 199 # Tutorials and checks
 200
 201 * <https://gitlab.com/Chips4Makers/alliance-check-toolkit>
 202 * See coriolis-2.x/Linux.x86_64/Release.Shared/install/share/doc/coriolis2/en/html/main/PythonTutorial/index.html
 203
 204 ## Information from Jean-Paul
 205
 206 There should be very soon a website at https://coriolis.lip6.fr (it is not yet
 207 online). Where I intend to put all the documentation about Alliance/Coriolis.
 208
 209 In the meantime did you find the doc shipped with Coriolis ?
 210
 211 There are also very cursory informations about installing Alliance here:
 212     https://www-soc.lip6.fr/en/team-cian/softwares/alliance/
 213
 214 You also have a third repository for various blocks/chip/examples here:
 215     https://gitlab.lip6.fr/jpc/alliance-check-toolkit
 216
 217 (with a basic doc under "doc/"...)
 218
 219 ## More from JP
 220
 221 You must create a configuration for alliance-check-toolkit:
 222
 223     alliance-check-toolkit/etc/mk/users.d/user-LOGIN.mk
 224
 225     where you define where the various tools are installed
 226     (look in other ones to have an idea).
 227
 228   You can try the ARM in alliance-check-toolkit:
 229
 230     > cd alliance-check-toolkit/benchsARM/cmos/
 231     > make lvx
 232
 233     Should take about five minutes. It's symbolic, but should be
 234     a configuration compatible with 180nm. To actually see the
 235     results:
 236
 237     > make cgt
 238
 239     Then "File -> Open", "arm_chip_cts_r"
 240
 241     To have a very rough approximation, you can say that one lambda
 242     equal 180nm.
 243
 244 Depends on the zoom level and of the fact that you ask to see
 245 the inside of the cells.
 246
 247 To actually see the transistors:
 248    Tools -> Controller -> Filter Tab -> check "Process Terminal Cells"
 249
 250 You can also tweak the layer display:
 251    Tools -> Controller -> Layers & Go
 252
 253   You can quicly hide/show the Controller with CTRL+I.
 254
 255   You may also toy with Controller -> Look, try the other ones.
 256   If you want a new one, to mimic something you're better
 257   familiar with, it's in configurations files all written
 258   in Python so easy to do, if a little tedious.
 259
 260 > i'd expect such a chip to be in the alliance-check-toolkit however we
 261 > don't even know what we're looking at in order to know which bits we
 262 > need, let alone know what to do or how to run them.
 263 >
 264 > we're *literally* completely in the dark, here, having never done this
 265 > before - at all - so unless there's a specific tutorial which says, to
 266 > make a chip layout do this: "step 1: install these tools.  step 2: get
 267 > this project repo.  step 3: cd to this directory.  step 4: run make or
 268 > ./compile-place-and-route.sh" we're absolutely lost.
 269 >
 270 > thx jean-paul, and apologies for not knowing where to begin, here.
 271
 272   No problem. You're welcome.
 273
 274   The doc is mostly for people who already have a background in ASICs,
 275   I will try to patch something from my lecture in VLSI to help people
 276   to orient themselves.
 277
 278   The up-to-date documentation is supplied directly in the Coriolis
 279   repository:
 280
 281      coriolis/documentation/output/index.html
 282
 283      The links toward the doxygen doc will be invalid a this point,
 284      but everython else works.
 285
 286    After installation, it is put in:
 287
 288      coriolis-2.x/Linux.x86_64/Release.Shared/install/share/doc/coriolis2/en/html/index.html
 289
 290 # Installing python3.7 into debian/stretch chroot
 291
 292 python 3.6 is a prerequisite for nmigen however something
 293 weird is going on, and it can't be installed.  instead,
 294 python 3.7 has to be installed instead.  we do this by
 295 adding debian/testing but setting the default release
 296 as "stretch".
 297
 298 as root, in the
 299 chroot, add the following to /etc/apt/sources.list
 300
 301     deb http://ftp.de.debian.org/debian testing main
 302
 303 then, also as root:
 304
 305     echo 'APT::Default-Release "stretch";' | tee -a /etc/apt/apt.conf.d/00local
 306     sudo apt-get update
 307     apt-get -t testing install python3.7 python3-setuptools \
 308                python3-jinja2 python3-pip
 309
 310 At this point it becomes possible to follow the main
 311 instructions in [[HDL_workflow]] for installing nmigen,
 312 ieee754fpu, soc and nmutil.
 313
 314 # Upgrading to latest yosys and nmigen in the chroot
 315
 316 yosys in debian/stretch may not be enough to work with nmigen,
 317 therefore it's probably a good idea to upgrade.   if this was
 318 not a debian/stretch chroot (i.e. was a debian 10), it would be
 319 a simple matter of "apt-get install yosys" however it's probably best,
 320 here to install from source.
 321
 322 **however**.. there is another way: once the instructions
 323 for installing python3.7 have been carried out.  As root,
 324 in the chroot:
 325
 326    apt-get -t testing install yosys
 327
 328 That's all.
 329
 330 To install instead from source, add the following to
 331 /etc/apt/sources.list:
 332
 333    deb-src http://ftp.uk.debian.org/debian stretch main
 334
 335 then as root, in the chroot, run the following:
 336
 337     apt-get update
 338     apt-get build-dep yosys
 339     apt-get install clang
 340     apt-get remove yosys
 341
 342 this will remove debian/stretch yosys however getting the build
 343 dependencies is quick and easy enough.
 344
 345 then, as the ordinary user, the following instructions can be followed
 346 (<http://www.clifford.at/yosys/download.html>)
 347
 348     cd ~
 349     git clone https://github.com/cliffordwolf/yosys.git
 350     cd yosys
 351     make config-clang
 352     make -j4
 353
 354 as root, run:
 355
 356     make install
 357
 358 # Check out the libresoc "soclayout" repository
 359
 360 See [[HDL_workflow]] for git clone instructions
 361
 362     $ git clone ssh://gitolite3@git.libre-riscv.org:922/libresoc.git
 363
 364 TODO further, here.