Subversion Repositories w11

# $Id: INSTALL.txt 408 2011-09-12 19:48:36Z mueller $

Guide to install and build w11a systems, test benches and support software

  Table of content:

  1.  Download

  2.  Setup environment variables

  3.  Compile UNISIM/SIMPRIM libraries for ghdl

  4.  Compile and install the support software

       a. Compile sharable libraries

       b. Setup Tcl packages

  5.  The build system

  6.  Building test benches

       a. General instructions

       b. Available test benches

  7.  Building systems

       a. General instructions

       b. Available systems

1. Download ---------------------------------------------------------------

  All instructions below assume that the project files reside in a

  working directory with the name represented as 

  To download latest tagged version (V0.5) of w11a

    cd 

    svn co http://opencores.org/ocsvn/w11/w11/tags/w11a_V0.5

  To download latest snapshot of trunk

    cd 

    svn co http://opencores.org/ocsvn/w11/w11/trunk

2. Setup environment variables --------------------------------------------

  The make flow for building test benches (ghdl and ISim based) and systems

  (Xilinx xst based) as well as the support software (mainly the rlink backend

  server) requires

    - the definition of the environment variables:

      - RETROBASE: must refer to the installation root directory

      - BOOSTINC:  pathname for includes of boost library

    - that the tools binary directory is in the path

    - that the tools library directory is in the library path

  For bash and alike use

    export RETROBASE=

    export PATH=$PATH:$RETROBASE/tools/bin

    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$RETROBASE/tools/lib

  In most cases the boost library version coming with the distribution will

  work, in those cases simply use

    export BOOSTINC=/usr/include

  After that building functional model based test benches will work. If you

  want to also build post-xst or post-par test benches read next section.

3. Compile UNISIM/SIMPRIM libraries for ghdl ------------------------------

  The build system for test benches also supports test benches run against

  the gate level models derived after the xst, map or par step. In this

  case ghdl has to link against a compiled UNISIM or SIMPRIM library.

  To make handling of the parallel installion of several WebPack versions

  easy the compiled libraries are stored in sub-directories under $XILINX:

     $XILINX/ghdl/unisim

     $XILINX/ghdl/simprim

  Two helper scripts will create these libraries:

    cd $RETROBASE

    xilinx_ghdl_unisim

    xilinx_ghdl_simprim

  If you have several WebPack versions installed, repeat for each version.

4. Compile and install the support software -------------------------------

4a. Compile sharable libraries ---------------------------------------

  Required tools and libraries:

    g++    >= 4.3    (decltype support assumed in usage of boost::bind)

    boost  >= 1.35   (boost::thread api changed, new one is used)

  Build was tested under:

    ubuntu lucid (10.04 LTS):  gcc 4.4.3  boost 1.40.0

    debian lenny (5.0.8):      gcc 4.3.2  boost 1.xx.x (t.b.c.)

  To build all sharable libraries

    cd $RETROBASE/tools/src

    make -j 4

  To cleanup, e.g. before a re-build

    cd $RETROBASE/tools/src

    rm_dep

    make realclean

4b. Setup Tcl environment --------------------------------------------

  The Tcl files are organized in several packages. To create the Tcl

  package files (pkgIndex.tcl)

    cd $RETROBASE/tools/tcl

    setup_packages

  To use these packages it is convenient to make them available via the

  'auto_path' mechanism. To do that add in your .tclshrc or .wishrc

    lappend auto_path [file join $env(RETROBASE) tools tcl]

    lappend auto_path [file join $env(RETROBASE) tools lib]

  The w11 distribution contains two ready to use .tclshrc or .wishrc

  files which

    - include the auto_path statements above

    - activate tclreadline (and thus in tclshrc an event loop)

  To use them simply copy them into your home directory (or soft link them)

    cd $HOME

    ln -s $RETROBASE/tools/tcl/.tclshrc .

    ln -s $RETROBASE/tools/tcl/.wishrc  .

5. The build system -------------------------------------------------------

  Simulation and synthesis tools usually need a list of the VHDL source

  files, often in proper compilation order (libraries before components).

  The different tools have different formats of these 'project files'.

  The build system employed in this project is based on

     "VHDL bill of material" or 'vbom' files

  which list for each vhdl source file the libraries and sources for

  the instantiated components, the later via their vbom, and last but

  not least the name of the vhdl source file. All file name are relative

  to the current directory. A recursive traversal through all vbom's gives

  for each vhld module all sources needed to compile it. The vbomconv script

  in tools/bin does this, and generates depending on options

   - make dependency files

   - ISE xst project files

   - ISE ISim project files

   - ghdl commands for analysis, inspection and make step

  The master make files contain pattern rules like

    %.ngc  : %.vbom           -- synthesize with xst

    %      : %.vbom           -- build functional model test bench

  which encapsulate all the vbomconf magic

  A full w11a is build from more than 80 source files, test benches from

  even more. Using the vbom's a large number of designs can be easily

  maintained.

6. Building test benches --------------------------------------------------

6a. General instructions ---------------------------------------------

  To compile a test bench named  all is needed is

    make 

  The make file will use .vbom, create all make dependency files,

  and generate the needed ghdl commands.

  In many cases the test benches can also be compiled against the gate

  level models derived after the xst, map or par step. To compile them

    make ghdl_tmp_clean

    make _ssim                  # for post-xst

    make _fsim                  # for post-map

    make _tsim                  # for post-par

  The 'make ghdl_tmp_clean' is needed to flush the ghdl work area from

  the compilation remains of earlier functional model compiles.

6b. Available test benches -------------------------------------------

  See file w11a_tb_guide.txt

7. Building systems -------------------------------------------------------

7a. General instructions ---------------------------------------------

  To generate a bit file for a system named  all is needed is

    make .bit

  The make file will use .vbom, create all make dependency files, build

  the ucf file with cpp, and run the synthesis flow (xst, ngdbuild, par, trce).

  The log files will be named

      _xst.log        # xst log file

      _tra.log        # translate (ngdbuild) log file (renamed %.bld)

      _map.log        # map log file                  (renamed %_map.mrp)

      _par.log        # par log file                  (renamed %.par)

      _pad.log        # pad file                      (renamed %_pad.txt)

      _twr.log        # trce log file                 (renamed %.twr)

  To load the bitfile with WebPack impact into the target board use

    make .iconfig

  If only the xst or par output is wanted just use

    make .ngc

    make .ncd

7b. Available systems ------------------------------------------------

  Note: Currently ready to build versions exist for

          Digilent S3BOARD (-1000 FPGA version)

          Digilent Nexys2 board (-1200 FPGA version)

  1. rlink tester

     a. for Digilent Nexys2 board

        cd $RETROBASE/rtl/sys_gen/tst_rlink/nexys2

        make sys_tst_rlink_n2.bit

  2. w11a systems

     a. for Digilent S3BOARD

        cd $RETROBASE/rtl/sys_gen/w11a/s3board

        make sys_w11a_s3.bit

     b. for Digilent Nexys2 board

        cd $RETROBASE/rtl/sys_gen/w11a/nexys2

        make sys_w11a_n2.bit