Subversion Repositories w11

# $Id: README_buildsystem_ISE.txt 779 2016-06-26 15:37:16Z mueller $

Guide to the Build System (Xilinx ISE Version)

  Table of content:
  
  1.  Concept
  2.  Setup system environment
       a. Setup environment variables
       b. Compile UNISIM/UNIMACRO/SIMPRIM libraries for ghdl
  3.  Building test benches
       a. With ghdl
       b. With ISE ISim
  4.  Building systems
  5.  Configuring FPGAs (via make flow)
  6.  Configuring FPGAs (directly via config_wrapper)
  7.  Note on Artix-7 based designs

1. Concept ----------------------------------------------------------------

  This projects uses GNU make to
    - generate bit files     (synthesis with xst and place&route with par)
    - generate test benches  (with ghdl or Xilinx ISim)
    - configure the FPGA     (with Xilinx Impact or Linux jtag)

  The Makefile's in general contain only a few definitions, all the make logic
  is concentrated in a few master makefiles which are included.

  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 manifest files called
     'vbom' or "VHDL bill of material" 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  (synthesis)
    - ISE ISim project files (simulation)
    - 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 vbomconv magic

  A full w11a system is build from about 100 source files, test benches 
  from even more. Using the vbom's a large number of designs can be easily 
  maintained.

  For more details on vbomconv consult the man page.

2. Setup system environment -----------------------------------------------

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

  The build flows require the environment variables:

    - RETROBASE:  must refer to the installation root directory
    - XTWI_PATH:  install path of the ISE version, without /ISE_DS/ !
    - RETRO_FX2_VID and RETRO_FX2_PID: default USB VID/PID for Cypress FX2

  For general instructions on environment see INSTALL.txt .
  For details on RETRO_FX2_VID and RETRO_FX2_PID see INSTALL_fx2.txt.

  Notes:  
  - The build system uses a small wrapper script called xtwi to encapsulate
    the Xilinx environment. It uses XTWI_PATH to setup the ISE environment on 
    the fly. For details consult 'man xtwi'. 
  - don't run the ISE setup scripts ..../settings(32|64).sh in your working 
    shell. Setup only XTWI_PATH !
  
2b. Compile UNISIM/UNIMACRO/SIMPRIM libraries for ghdl ---------------

  A few entities use UNISIM or UNIMACRO primitives, and models derived after
  the par step require also SIMPRIM primitives. In these cases ghdl has to
  link against a compiled UNISIM, UNIMACRO or SIMPRIM libraries.

  To make handling of the parallel installation of several ISE versions
  easy the compiled libraries are stored in sub-directories under $XILINX:

     $XILINX/ghdl/unisim
     $XILINX/ghdl/unimacro
     $XILINX/ghdl/simprim

  Two helper scripts will create these libraries:

    cd $RETROBASE
    xise_ghdl_unisim            # does UNISIM and UNIMACRO
    xise_ghdl_simprim           # does SIMPRIM

  Run these scripts for each ISE version which is installed.

3. Building test benches --------------------------------------------------

  The build flows support two simulators
  - ghdl      -> open source, with VHPI support, doesn't accept sdf files
  - ISE ISim  -> limited to 50k lines in WebPack, no VHPI support

3a. With ghdl --------------------------------------------------------

  To compile a ghdl based test bench named <tbench> all is needed is

    make <tbench>

  The make file will use <tbench>.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 <tbench>_ssim                  # for post-xst  (using UNISIM)
    make <tbench>_fsim                  # for post-map  (using SIMPRIM)
    make <tbench>_tsim                  # for post-par  (using SIMPRIM)

  Individual working directories are used for the different models
    ghdl.bsim        for bahavioral model
    ghdl.ssim        for post-xst
    ghdl.fsim        for post-map
    ghdl.tsim        for post-par
  and can co-exist. The 'make ghdl_tmp_clean' can be used to flush the ghdl
  work areas, but in general this is not needed (since V0.73).

  Notes:
  - the post-xst simulation (_ssim targets) proved to be a valuable tool.
  - ghdl fails to read sdf files generated by Xilinx tools, and thus does
    not support a post-par simulation with full timing.
  - post-par simulations without timing annotation often fail, most likely
    due to clocking and delta cycle issues due to inserted clock buffers.

3b. With ISE ISim ----------------------------------------------------

  To compile a ISE ISim based test bench named <tbench> all is needed is

    make <tbench>_ISim

  The make file will use <tbench>.vbom, create all make dependency files,
  and generate the needed ISE ISim project files and 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 ise_tmp_clean
    make <tbench>_ISim_ssim             # for post-xst
    make <tbench>_ISim_fsim             # for post-map
    make <tbench>_ISim_tsim             # for post-par

  Notes:
  - ISim in ISE WebPack is limited to about 50k lines source code. That is
    enough for many functional simulations, a w11a system has about 27k lines,
    the test bench adds another 3k lines. But the limit gets quickly exceeded 
    with post-xst and especially post-par models. If the limit is exceeded, the
    simulation engine throttles to snails speed.
  - ISim does not support VHPI (interfacing of external C routines to VHDL).
    Since VHPI is used in the rlink simulation all system test benches with
    an rlink interface, thus most, will only run with ghdl and not with ISim.
 
4. Building systems -------------------------------------------------------

  To generate a bit file for a system named <sys> all is needed is

    make <sys>.bit

  The make file will use <sys>.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 conveniently renamed

      <sys>_xst.log        # xst log file
      <sys>_tra.log        # translate (ngdbuild) log file (renamed %.bld)
      <sys>_map.log        # map log file                  (renamed %_map.mrp)
      <sys>_par.log        # par log file                  (renamed %.par)
      <sys>_pad.log        # pad file                      (renamed %_pad.txt)
      <sys>_twr.log        # trce log file                 (renamed %.twr)
      <sys>_tsi.log        # trce tsi file                 (renamed %.tsi)
      <sys>_bgn.log        # bitgen log file               (renamed %.bgn)
  
  If only the xst or par output is wanted just use

    make <sys>.ngc
    make <sys>.ncd

  Some tools require a .svf rather than a .bit file. It can be created with

    make <sys>.svf

  A simple 'message filter' system is also integrated into the make build flow.
  For many (though not all) systems a .mfset file has been provided which
  defines the xst,par and bitgen messages which are considered ok. To see
  only the remaining message extracted from the various .log files simply
  use the make target

    make <sys>.mfsum

  after a re-build.

5. Configuring FPGAs (via make flow) --------------------------------------

  The make flow supports also loading the bitstream into FPGAs, either
  via Xilinx Impact, or via the Cypress FX2 USB controller is available.

  For Xilinx Impact a Xilinx USB Cable II has to be properly setup, than
  simply use

    make <sys>.iconfig

  For using the Cypress FX2 USB controller on Digilent Nexys2, Nexys3 and
  Atlys boards just connect the USB cable and

    make <sys>.jconfig

  This will automatically check and optionally re-load the FX2 firmware
  to a version matching the FPGA design, generate a .svf file from the
  .bit file, and configure the FPGA. In case the bit file is out-of-date
  the whole design will be re-implemented before.

6. Configuring FPGAs (directly via config_wrapper) -------------------------

  The make flow described above uses two scripts
    config_wrapper              # must be used with xtwi !
    fx2load_wrapper
  which can be used directly for loading available bit or svf files into
  the FPGA. For detailed documentation see the respective man pages.

7. Note on Artix-7 based designs ------------------------------------------

  The development for Nexys4 started with ISE, but has now fully moved to
  Vivado. The make files for the ISE build flows have been kept for comparison
  are have the name Makefile.ise. So for some Nexys4 designs and associated
  one can still start with a 

    make -f Makefile.ise  <target>

  an ISE based build. To be used for tool comparisons, the ISE generated bit 
  files were never tested in an FPGA.