Subversion Repositories w11

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

Guide to the Build System (Xilinx Vivado Version)

  Table of content:

  1.  Concept

  2.  Setup system environment

       a. Setup environment variables

       b. Compile UNISIM/UNIMACRO libraries for ghdl

  3.  Building test benches

       a. With ghdl

       b. With Vivado xsim

  4.  Building systems

  5.  Building vivado projects, creating gate level models

  6.  Configuring FPGAs (via make flow)

  7.  Note on ISE

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

  This projects uses GNU make to

    - generate bit files     (with Vivado synthesis)

    - generate test benches  (with ghdl or Vivado XSim)

    - configure the FPGA     (with Vivado hardware server)

  The Makefile's in general contain only a few definitions. By far most of

  the build flow logic in Vivado is in tcl scripts, only a thin interface

  layer is needed at the make level, which is concentrated in a few master

  makefiles which are included.

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

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

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

  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

    - Vivado synthesis setup files

    - Vivado simulation setup files

    - ghdl commands for analysis, inspection and make step

  The master make files contain pattern rules like

    %.bit  : %.vbom           -- create bit file

    %      : %.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

    - XTWV_PATH:  install path of the Vivado version

  For general instructions on environment see INSTALL.txt .

  Notes:

  - The build system uses a small wrapper script called xtwv to encapsulate

    the Xilinx environment. It uses XTWV_PATH to setup the Vivado environment

    on the fly. For details consult 'man xtwv'.

  - don't run the Vivado setup scripts ..../settings(32|64).sh in your working

    shell. Setup only XTWV_PATH !

2b. Compile UNISIM/UNIMACRO libraries for ghdl -----------------------

  A few entities use UNISIM or UNIMACRO primitives, and post synthesis models

  require also UNISIM primitives. In these cases ghdl has to link against a

  compiled UNISIM or UNIMACRO libraries.

  To make handling of the parallel installation of several Vivado versions

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

     $XTWV_PATH/ghdl/unisim

     $XTWV_PATH/ghdl/unimacro

  A helper scripts will create these libraries:

    cd $RETROBASE

    xviv_ghdl_unisim            # does UNISIM and UNIMACRO

  Run these scripts for each Vivado version which is installed.

  Notes:

  - Vivado supports SIMPRIM libraries only in Verilog form, there is no vhdl

    version anymore.

  - ghdl can therefore not be used to do timing simulations with Vivado.

    However: under ISE SIMPRIM was available in vhdl, but ghdl did never accept

    the sdf files, making ghdl timing simulations impossible under ISE too.

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

  The build flows currently supports ghdl and the vivado simulator xsim.

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

  To compile a ghdl based 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 some cases the test benches can also be compiled against the gate

  level models derived after the synthesis or optimize step.

  Vivado only generated functional (UNISIM based) models in vhdl. Timing

  (SIMPRIM based) models are only available on verilog. The combination

  vivado + ghdl is therefore limited to functional model simulation.

  To compile them

    make ghdl_tmp_clean

    make _ssim                  # for post synthesis functional

    make _osim                  # for post optimize  functional

    make _rsim                  # for post routing   functional

  Individual working directories are used for the different models

    ghdl.bsim        for bahavioral model

    ghdl.ssim        for post synthesis

    ghdl.osim        for post optimize

    ghdl.rsim        for post routing

  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:

  - Many post-synthesis functional currently fail due to startup and

    initialization problems (see issue V0.73-2).

3b. With Vivado xsim -------------------------------------------------

  To compile a Vivado xsim based test bench named  all is needed is

    make _XSim

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

  and generate the needed Vivado xsim project files and commands.

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

  level models derived after the synthesis, optimize or routing step.

  Vivado supports functional (UNISIM based) models in vhdl and in verilog,

  and timing (SIMPRIM based) models only in verilog. Since practice showed

  that verilog models compile and execute faster, verilog is used for both

  functional and timing models.

    make _XSim_ssim             # for post-synthesis functional

    make _XSim_osim             # for post-optimize  functional

    make _XSim_rsim             # for post-routing   functional

    make _XSim_esim             # for post-synthesis timing

    make _XSim_psim             # for post-optimize  timing

    make _XSim_tsim             # for post-routing   timing

  Notes:

  - as of vivado 2016.2 xelab shows sometimes extremely long build times,

    especially for generated post-synthesis vhdl models (see issue V0.73-1).

  - Many post-synthesis functional and especially post-routing timing

    simulations currently fail due to startup and initialization problems

    (see issue V0.73-2).

4. Building systems -------------------------------------------------------

  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 and

  starts Vivado in batch mode with the proper scripts which will handle the

  build steps. The log files and reports are conveniently renamed

      _syn.log            # synthesis log                 (from runme.log)

      _imp.log            # implementation log            (from runme.log)

      _bit.log            # write_bitstream log           (from runme.log)

      _syn_util.rpt       # (from _utilization_synth.rpt)

      _opt_drc.rpt        # (from _opt_drc.rpt)

      _pla_io.rpt         # (from _io_placed.rpt)

      _pla_clk.rpt        # (from _clock_utilization_placed.rpt)

      _pla_util.rpt       # (from _utilization_placed.rpt)

      _pla_cset.rpt       # (from _control_sets_placed.rpt)

      _rou_sta.rpt        # (from _route_status.rpt)

      _rou_drc.rpt        # (from _drc_routed.rpt)

      _rou_tim.rpt        # (from _timing_summary_routed.rpt)

      _rou_pwr.rpt        # (from _power_routed.rpt)

      _rou_util.rpt       # (extra report_utilization)

      _rou_util_h.rpt     # (extra report_utilization -hierarchical)

      _ds.rpt             # (extra report_datasheet)

  The design check points are also kept

      _syn.dcp            # (from .dcp)

      _opt.dcp            # (from _opt.dcp)

      _pla.dcp            # (from _placed.dcp)

      _rou.dcp            # (from _routed.dcp)

  If only the post synthesis, optimize or route design checkpoints are wanted

    make _syn.dcp

    make _opt.dcp

    make _rou.dcp

5. Building vivado projects, creating gate level models -------------------

  Vivado is used in 'project mode', whenever one of the targets mentioned

  above is build a vivado project is freshly created in the directory

    project_mflow

  with the project file

    project_mflow/project_mflow.xpr

  There are many make targets which

    - just create the project

    - start vivado in gui mode to inspect the most recent project

    - create gate level models

  Specifically

    make .vivado          # create vivado project from .vbom

    make vivado                # open project in project_mflow

    make _ssim.vhd        # post-synthesis functional model (vhdl)

    make _osim.vhd        # post-optimize  functional model (vhdl)

    make _rsim.vhd        # post-routing   functional model (vhdl)

    make _ssim.v          # post-synthesis functional model (verilog)

    make _osim.v          # post-optimize  functional model (verilog)

    make _rsim.v          # post-routing   functional model (verilog)

    make _esim.v          # post-synthesis timing model (verilog)

    make _psim.v          # post-optimize  timing model (verilog)

    make _tsim.v          # post-routing   timing model (verilog)

  For timing model verilog file an associated sdf file is also generated.

6. Configuring FPGAs ------------------------------------------------------

  The make flow supports also loading the bitstream into FPGAs via the

  Vivado hardware server. Simply use

    make .vconfig

  Note: works with Arty, Basys3, and Nexys4, only one board must connected.

7. Note on ISE ------------------------------------------------------------

  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  

  or

    makeise 

  an ISE based build. To be used for tool comparisons, the ISE generated bit

  files were never tested in an FPGA.