diff --git a/documentation/Stratus/Developper.rst b/documentation/Stratus/Developper.rst index 19292e02..f764241a 100644 --- a/documentation/Stratus/Developper.rst +++ b/documentation/Stratus/Developper.rst @@ -3,9 +3,6 @@ Stratus Developper's Guide ========================== Sophie Belloeil -.. toctree:: - :maxdepth: 2 - Class Model =========== diff --git a/documentation/Stratus/DpGen.rst b/documentation/Stratus/DpGen.rst index 3fbc30be..cd8c1cac 100644 --- a/documentation/Stratus/DpGen.rst +++ b/documentation/Stratus/DpGen.rst @@ -3,9 +3,6 @@ DpGen generators manual ======================= Sophie Belloeil -.. toctree:: - :maxdepth: 2 - DpgenInv ======== diff --git a/documentation/Stratus/Language.rst b/documentation/Stratus/Language.rst index d23854d0..793afe6a 100644 --- a/documentation/Stratus/Language.rst +++ b/documentation/Stratus/Language.rst @@ -4,9 +4,6 @@ Stratus User's Guide Sophie Belloeil -.. toctree:: - :maxdepth: 2 - Introduction ============ diff --git a/documentation/Stratus/Patterns.rst b/documentation/Stratus/Patterns.rst index c5c1d4a1..32438686 100644 --- a/documentation/Stratus/Patterns.rst +++ b/documentation/Stratus/Patterns.rst @@ -3,9 +3,6 @@ Patterns module User's Guide ============================ Roselyne Chotin-Avot -.. toctree:: - :maxdepth: 2 - Description =========== diff --git a/documentation/UsersGuide/Configuration.rst b/documentation/UsersGuide/Configuration.rst index c40562d3..5adcfef8 100644 --- a/documentation/UsersGuide/Configuration.rst +++ b/documentation/UsersGuide/Configuration.rst @@ -12,8 +12,6 @@ :align: middle :width: 60% -|newpage| - Coriolis Configuration & Initialisation ======================================= @@ -52,8 +50,6 @@ Configuration is done in two stages: #. Loading the complete configuration for the given technology and the user's settings. -|newpage| - First Stage: Technology Selection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -135,8 +131,6 @@ simple assembly of tuples. The helpers are installed under the directory: :: Where :cb:`/` is the root of the installation. -|newpage| - .. _Alliance Helper: @@ -188,6 +182,8 @@ variable, and if not found, default to ``/soc/alliance``. , ( 'PAD' , '.*_px$') ) +|newpage| + |noindent| The example above shows the system configuration file, with all the available settings. Some important remarks about thoses settings: @@ -265,6 +261,9 @@ configuration files are defined: * :cb:`kite.conf`: for the |Kite| tool. * :cb:`stratus1.conf`: for the |stratus1| tool. +|newpage| + + Here is the contents of :cb:`etesian.conf`: :: # Etesian parameters. @@ -301,8 +300,6 @@ Here is the contents of :cb:`etesian.conf`: :: , (TypeRule ,) ) -|newpage| - Taxonomy of the file: diff --git a/documentation/UsersGuide/DesignFlow.rst b/documentation/UsersGuide/DesignFlow.rst new file mode 100644 index 00000000..90a4c0bf --- /dev/null +++ b/documentation/UsersGuide/DesignFlow.rst @@ -0,0 +1,25 @@ +.. -*- Mode: rst -*- + +.. include:: ../etc/definitions.rst + +|newpage| + + +Complete Design Flow & Examples +=============================== + +While |Coriolis| can be used stand-alone, it is in fact part of a more complete +design flow build upon |Yosys| and |Alliance|. In addition, a set of demos and +examples are supplied in the repository |alliance-check-toolkit|. + +* |Yosys| : http://www.clifford.at/yosys/ + + An |rpm| packaged version is available here: + + https://ftp.lip6.fr/pub/linux/distributions/slsoc/soc/7/addons/x86_64/repoview/yosys.html + +* Alliance : https://www-soc.lip6.fr/equipe-cian/logiciels/alliance/ + +* |alliance-check-toolkit| |git| repository: + + https://www-soc.lip6.fr/git/alliance-check-toolkit.git/ diff --git a/documentation/UsersGuide/Installation.rst b/documentation/UsersGuide/Installation.rst index cb264d3c..3f38c7ac 100644 --- a/documentation/UsersGuide/Installation.rst +++ b/documentation/UsersGuide/Installation.rst @@ -2,23 +2,28 @@ .. include:: ../etc/definitions.rst -|newpage| - Installation ============ .. note:: As the sources are being released, the binary packaging is dropped. - You still may find older version here: http://asim.lip6.fr/pub/coriolis/2.0 . + You may still find (very) old versions here: http://asim.lip6.fr/pub/coriolis/2.0 . In a nutshell, building source consist in pulling the |git| repository then running the |ccb| installer. +.. note:: + The documentation is already generated and commited in the |git| tree. + You may not install the additional prerequisites for the documentation. + By default the documentation is not generated, just installed by |ccb|. + If you really want to re-generate it, add the ``--doc`` flag to |ccb|. + Main building prerequisites: * cmake * C++11-capable compiler +* BFD library (provided through ``binutils``). * RapidJSON_ * python2.7 * boost @@ -26,12 +31,12 @@ Main building prerequisites: * bzip2 * yacc & lex * Qt 4 or Qt 5 +* Qwt Building documentation prerequisites: * doxygen * latex -* latex2html * python-docutils (for reStructuredText) The following libraries gets directly bundled with |Coriolis|: @@ -41,8 +46,6 @@ The following libraries gets directly bundled with |Coriolis|: For other distributions, refer to their own packaging system. -|newpage| - Fixed Directory Tree ~~~~~~~~~~~~~~~~~~~~ @@ -94,79 +97,172 @@ automatically created either by |ccb| or the build system. ``Static`` do not work because I don't know yet to mix statically linked binaries and Python modules (which must be dynamic). -|newpage| - Building Coriolis ~~~~~~~~~~~~~~~~~ -First step is to install the prerequisites. Currently, only RapidJSON_. -As RapidJSON is evolving fast, if you encounter compatibility problems, -the exact version we compiled against is given below. :: +The actively developed branch +----------------------------- - dummy@lepka:~> mkdir -p ~/coriolis-2.x/src/support - dummy@lepka:~> cd ~/coriolis-2.x/src/support - dummy@lepka:~> git clone http://github.com/miloyip/rapidjson - dummy@lepka:~> git checkout ec322005072076ef53984462fb4a1075c27c7dfd +For an intermediary period, the branch under active development you must use is +**devel_anabatic** :: -The second step is to create the source directory and pull the |git| repository: :: + dummy@lepka:coriolis> git checkout devel_anabatic - dummy@lepka:~> mkdir -p ~/coriolis-2.x/src - dummy@lepka:~> cd ~/coriolis-2.x/src - dummy@lepka:~> git clone https://www-soc.lip6.fr/git/coriolis.git -Third and final step, build & install: :: +Installing on |RedHat| or compatible distributions +-------------------------------------------------- - dummy@lepka:src> ./bootstrap/ccb.py --project=support \ - --project=coriolis \ - --make="-j4 install" - dummy@lepka:src> ./bootstrap/ccb.py --project=support \ - --project=coriolis \ - --doc --make="-j1 install" +1. Install or check that the required prerequisites are installeds : :: + + dummy@lepka:~> yum install -y git cmake bison flex gcc-c++ libstdc++-devel \ + binutils-devel \ + boost-devel boost-python boost-filesystem \ + boost-regex boost-wave \ + python-devel libxml2-devel bzip2-devel \ + qt5-qtbase-devel qt5-qtsvg-devel # Qt 5. + + The package ``qwt-qt5-devel`` and it's dependency ``qwt-qt5`` are not provided + by any standard repository (like |EPEL|). You may download them from the + `LIP6 Addons Repository `_ + Then run: :: + + dummy@lepka:~> yum localinstall -y qwt-qt5-6.1.2-4.fc23.x86_64.rpm \ + qwt-qt5-6.1.2-4.fc23.x86_64.rpm # Qwt for Qt 5. + -We need to separate to perform a separate installation of the documentation because it -do not support to be generated with a parallel build. So we compile & install in a first -stage in ``-j4`` (or whatever) then we generate the documentation in ``-j1`` +2. Install the unpackaged prerequisites. Currently, only RapidJSON_. :: + + dummy@lepka:~> mkdir -p ~/coriolis-2.x/src/support + dummy@lepka:support> cd ~/coriolis-2.x/src/support + dummy@lepka:support> git clone http://github.com/miloyip/rapidjson + + +3. Create the source directory and pull the |git| repository: :: + + dummy@lepka:~> mkdir -p ~/coriolis-2.x/src + dummy@lepka:src> cd ~/coriolis-2.x/src + dummy@lepka:src> git clone https://www-soc.lip6.fr/git/coriolis.git + +4. Build & install: :: + + dummy@lepka:src> cd coriolis + dummy@lepka:coriolis> git checkout devel_anabatic + dummy@lepka:coriolis> ./bootstrap/ccb.py --project=support \ + --project=coriolis \ + --qt5 \ + --make="-j4 install" + +.. note:: + Pre-generated documentation will get installed by the previous command. + Only if you did made modifications to it you need to regenerate it with: :: + + dummy@lepka:coriolis> ./bootstrap/ccb.py --project=support \ + --project=coriolis \ + --doc --make="-j1 install" + + We need to perform a separate installation of the documentation because it + do not support to be generated with a parallel build. So we compile & install in a first + stage in ``-j4`` (or whatever) then we generate the documentation in ``-j1`` Under |RHEL6| or clones, you must build using the |devtoolset|, the version is to be given as argument: :: - dummy@lepka:src> ./bootstrap/ccb.py --project=coriolis \ - --devtoolset=8 --make="-j4 install" + dummy@lepka:coriolis> ./bootstrap/ccb.py --project=coriolis \ + --devtoolset=8 --make="-j4 install" -If you want to uses Qt 5 instead of Qt 4, you may add the ``--qt5`` argument. +If you want to uses Qt 4 instead of Qt 5 modify the previous steps as follow: + +* At **step 1**, do not install the |QT| 5 related development packages (``qt5-qtbase-devel`` + and ``qt5-qtsvg-devel``), but instead: :: + + dummy@lepka:~> yum install -y git qt-devel qwt-devel # Qt 4 + + Note, that the ``Qwt`` packages are directly availables from the standart distribution + when using |Qt| 4. + +* At **step 4**, remove the ``--qt5`` arguments to the ``ccb.py`` command line. + +Be aware that, under |RHEL| 7 or clones, there is a bug in |Qt| 4 that makes diagonal +lines appears whenever a filled rectangle is not fully included in the displayed area. +This may be misleading when visualising a layout... The complete list of |ccb| functionalities can be accessed with the ``--help`` argument. It also may be run in graphical mode (``--gui``). -Building the Devel Branch -------------------------- +Building a Debug Enabled Version +-------------------------------- -In the |Coriolis| |git| repository, two branches are present: +The ``Release.Shared`` default version of the |Coriolis| is build stripped of symbols +and optimized so that it makes analysing a core dump after a crash difficult. In the +(unlikely) case of a crash, you may want to build, alongside the optimized version, +a debug one which allow forensic examination by |gdb| (or |valgrind| or whatever). -* The :cb:`master` branch, which contains the latest stable version. This is the - one used by default if you follow the above instructions. +Run again ``ccb.py``, adding the ``--debug`` argument: :: -* The :cb:`devel` branch, which obviously contains the latest commits from the - development team. To use it instead of the :cb:`master` one, do the following - command just after the first step: :: + dummy@lepka:coriolis> ./bootstrap/ccb.py --project=support \ + --project=coriolis \ + --qt5 \ + --make="-j4 install" --debug - dummy@lepka:~> git checkout devel - dummy@lepka:src> ./bootstrap/ccb.py --project=coriolis \ - --make="-j4 install" --debug - Be aware that it may requires newer versions of the dependencies and may introduce - incompatibilites with the stable version. +As |cgt| is a |Python| script, the right command to run |gdb| is: :: - In the (unlikely) event of a crash of |cgt|, as it is a |Python| script, the right - command to run |gdb| on it is: :: + dummy@lepka:work> gdb python core.XXXX - dummy@lepka:work> gdb python core.XXXX + +.. Building the Devel Branch +.. ------------------------- +.. +.. In the |Coriolis| |git| repository, two branches are present: +.. +.. * The :cb:`master` branch, which contains the latest stable version. This is the +.. one used by default if you follow the above instructions. +.. +.. * The :cb:`devel` branch, which obviously contains the latest commits from the +.. development team. To use it instead of the :cb:`master` one, do the following +.. command just after the first step: :: +.. +.. dummy@lepka:coriolis> git checkout devel +.. dummy@lepka:coriolis> ./bootstrap/ccb.py --project=coriolis \ +.. --make="-j4 install" --debug +.. +.. Be aware that it may requires newer versions of the dependencies and may introduce +.. incompatibilites with the stable version. |newpage| +Installing on |Debian| 9, |Ubuntu| 18 or compatible distributions +----------------------------------------------------------------- + +First, install or check that the required prerequisites are installeds : :: + + dummy@lepka:~> sudo apt install -y build-essential binutils-dev \ + git cmake bison flex gcc python-dev \ + libboost-all-dev libboost-python-dev \ + libbz2-dev libxml2-dev rapidjson-dev libbz2-dev \ + qt4-dev-tools libqwt5-qt4-dev \ # Qt 4 + qtbase5-dev libqt5svg5-dev libqwt-qt5-dev \ # Qt 5 + doxygen dvipng graphviz python-sphinx \ + texlive-fonts-extra texlive-lang-french + +Second step is to create the source directory and pull the |git| repository: :: + + dummy@lepka:~> mkdir -p ~/coriolis-2.x/src + dummy@lepka:src> cd ~/coriolis-2.x/src + dummy@lepka:src> git clone https://www-soc.lip6.fr/git/coriolis.git + +Third and final step, build & install: :: + + dummy@lepka:src> cd coriolis + dummy@lepka:coriolis> git checkout devel_anabatic + dummy@lepka:coriolis> ./bootstrap/ccb.py --project=coriolis \ + --qt5 \ + --make="-j4 install" + + Additionnal Requirement under |MacOS| ------------------------------------- @@ -223,7 +319,7 @@ Use it like this: :: dummy@lepka:~> eval `~/coriolis-2.x/src/coriolis/bootstrap/coriolisEnv.py` .. note:: **Do not call that script in your environement initialisation.** - When used under |RHEL6| or clones, it needs to be run in the |devtoolset2| + When used under |RHEL6| or clones, it needs to be run in the |devtoolset| environement. The script then launch a new shell, which may cause an infinite loop if it's called again in, say :cb:`~/.bashrc`. diff --git a/documentation/UsersGuide/LicenseCredits.rst b/documentation/UsersGuide/LicenseCredits.rst index a815e214..babf710c 100644 --- a/documentation/UsersGuide/LicenseCredits.rst +++ b/documentation/UsersGuide/LicenseCredits.rst @@ -42,14 +42,14 @@ Credits & License |medskip| -The |Hurricane| data-base is copyright© |Bull| 2000-2018 and is +The |Hurricane| data-base is copyright© |Bull| 2000-2019 and is released under the terms of the |LGPL| license. All other tools are -copyright© |UPMC| 2008-2018 and released under the |GPL| -license. +copyright© |UPMC| 2008-2018, |SorbonneUniversite| 2018-2019 +and released under the |GPL| license. Others important contributors to |Coriolis| are Christophe |Alexandre|, Hugo |Clement|, Marek |Sroka| and Wu |Yifei|. -The |Knik| router makes use of the |Flute| software, which is +The |Katana| router makes use of the |Flute| software, which is copyright© Chris C. N. |Chu| from the Iowa State University (http://home.eng.iastate.edu/~cnchu/). diff --git a/documentation/UsersGuide/index.rst b/documentation/UsersGuide/index.rst index 7121510a..0f50174a 100644 --- a/documentation/UsersGuide/index.rst +++ b/documentation/UsersGuide/index.rst @@ -15,6 +15,7 @@ Printable version of this document `UsersGuide.pdf <../../../pdf/main/UsersGuide LicenseCredits.rst Releases.rst + DesignFlow.rst Installation.rst Configuration.rst ViewerTools.rst diff --git a/documentation/etc/definitions.rst b/documentation/etc/definitions.rst index 7329285c..8ccf8ebc 100644 --- a/documentation/etc/definitions.rst +++ b/documentation/etc/definitions.rst @@ -29,6 +29,8 @@ .. |LGPL| replace:: :sc:`lgpl` .. |GPL| replace:: :sc:`gpl` .. |UPMC| replace:: :sc:`upmc` +.. |SorbonneUniversite| replace:: :sc:`Sorbonne Université` +.. |SU| replace:: :sc:`su` .. |Bull| replace:: :sc:`Bull` .. |Cadence| replace:: :sc:`Cadence` .. |Si2| replace:: :sc:`Si2` @@ -38,6 +40,7 @@ .. |Flute| replace:: :sc:`Flute` .. |MacOS| replace:: :sc:`MacOS` .. |Darwin| replace:: :sc:`Darwin` +.. |RHEL| replace:: :sc:`rhel` .. |RHEL6| replace:: :sc:`rhel6` .. |RHEL7| replace:: :sc:`rhel7` .. |SL6| replace:: :sc:`Scientific Linux 6` @@ -46,6 +49,7 @@ .. |RedHat| replace:: :sc:`RedHat` .. |Fedora| replace:: :sc:`Fedora` .. |FC13| replace:: :sc:`fc13` +.. |EPEL| replace:: :sc:`epel` .. |Debian| replace:: :sc:`Debian` .. |Ubuntu| replace:: :sc:`Ubuntu` .. |MOSIS| replace:: :sc:`mosis` @@ -78,6 +82,7 @@ .. |Coriolis| replace:: :sc:`Coriolis` .. |Coriolis1| replace:: :sc:`Coriolis 1` .. |Coriolis2| replace:: :sc:`Coriolis 2` +.. |alliance-check-toolkit| replace:: ``alliance-check-toolkit`` .. |VLSISAPD| replace:: :sc:`vlsisapd` .. |CRLcore| replace:: :sc:`CRLcore` .. |Cyclop| replace:: :sc:`Cyclop` @@ -113,6 +118,7 @@ .. |git| replace:: :cb:`git` .. |rpm| replace:: :cb:`rpm` .. |gdb| replace:: :cb:`gdb` +.. |valgrind| replace:: :cb:`valgrind` .. |cmake| replace:: :cb:`cmake` .. |struct| replace:: :cb:`struct`