VBOMCONV(1)

NAME
vbomconv - generate files and actions from vbom manifest files

SYNOPSIS
vbomconv [--trace] --ghdl_i_cmd | --ghdl_i vbom
vbomconv [--trace] [--xlpath=path] --ghdl_a_cmd | --ghdl_a vbom
vbomconv [--trace] [--xlpath=path] --ghdl_m_cmd | --ghdl_m vbom
vbomconv [--trace] --ghdl_export=path vbom
vbomconv [--trace] --vsyn_prj | --vsim_prj vbom
vbomconv [--trace] --vsyn_export=path | --vsim_export=path vbom
vbomconv [--trace] --xst_prj | --isim_prj vbom
vbomconv [--trace] --xst_export=path | --isim_export=path vbom
vbomconv [--trace] --dep_ghdl vbom
vbomconv [--trace] --dep_xst | --dep_isim vbom
vbomconv [--trace] --dep_vsyn | --dep_vsim vbom
vbomconv [--trace] --get_top vbom
vbomconv [--trace] --flist vbom
vbomconv --help

DESCRIPTION

  Introduction
vbomconv is the central tool in a build system for VHDL projects. Each VHDL source file has an associated manifest file in vbom(5) format which contains a list of used libraries and instantiated components, and the name of the associated VHDL source file. The instantiated components are defined via their vbom file. All file names are relative to the current directory. A recursive traversal through all vbom's gives for each VHDL entity all the source files needed to compile it, with duplicates removed and in proper compilation order, thus libraries first and top-level design last. The vbomconv tool does this traversal of vbom files and generates, depending on command-line options, the files and/or commands needed to run a synthesis tool or to build a simulation model. Currently supported is synthesis with Xilinx ISE xst and Xilinx Vivado and simulation with ghdl(1), Xilinx ISE ISim, or Xilinx Vivado xsim. vbomconv therefore currently generates
- ghdl
    commands for analysis, inspection and make step
- vsyn
    project setups for Vivado synthesis
- vsim
    project setups for Vivado simulation
- xst
    project files for ISE synthesis
- ISim
    project files for ISE simulation
- make
    dependency files

The key advantage of this approach is that the individual vbom files are easy to maintain. They reflect the libraries and components used in the VHDL source they describe, a structural change in the VHDL source usually implies an update of the vbom. The project files are automatically generated from this 'local' information, which can be of great help in projects with many top-level designs with a large number of entities in different constellations. vbomconv is usually embedded in a GNU make(1)-based build system. The Makefile's in general just contain a few definitions and includes, the whole vbomconv magic is encapsulated in some pattern rules for simulation and synthesis. Some are given in the EXAMPLES section.

  Principle of Operation
vbomconv will start with processing the vbom file given as an argument. Each file name extracted from a vbom is prepended with the directory path of the vbom. This ensures that all file names are relative to the working directory under which vbomconv was started, even though each vbom file holds only file names that are relative to the vbom. vbomconv expects that the entries in the vbom's are ordered, libraries first, then the components in the order they are instantiated, and finally the name of the associated source file. Each .vhd file is added to a table of source files. Each .vbom file is added to a list of vbom's to be processed if it hasn't been processed yet. The sub-vbom's are processed in the order they were found which leads to breadth-first traversal of the vbom tree. After all vbom's are processed a ranking algorithm will generate an ordered list of source files in proper compilation order. This ensures that libraries are compiled before a source refers to them with a 'use' clause, and that entities are compiled before they are referred to by an explicit instatiation. The vbom file format supports conditional inclusion of files via a condition prefix. The main purpose of this mechanism is to handle libraries and components which are only referred in
        -- synthesis translate_off
        -- synthesis translate_on
sections and are used only for simulation. The vbom file format has a logical name mechanism to support the configuration mechanism of VHDL. A logical name can be defined with
        <lname> = <filename>
and it can be used with
       ${lname}
       ${lname := default}
The first definition seen in the vbom traversal is taken, all others are ignored. The filename in the usage clause is the default used in case the logical name wasn't defined. Last but not least are 5 directives defined in the vbom file format:

@top:name
    allows to specify the top-level design name in case it differs from the stem of the vbom file name.

@lib:name
    allows to specify additional system libraries. Currently used to indicate that the unisim, unimacro, or simprim libraries are needed by ghdl.

@xdc:file
    specifies that file is a constraint file for Vivado synthesis and should be included in the constraints fileset.

@tcl:file
    specifies that file is a Tcl script to be executed when building the Vivado project. The Tcl script generated by --vsyn_prj will contain statements with source file.

@ucf_cpp:file
    specifies that a file.ucf file is to be generated by cpp(1) from a file.ucf_cpp source file. This allows modularizing ISE ucf files.

The full description of the file format and examples are given in a separate man page vbom(5).

USAGE
The vbomconv command has the form

    vbomconv [options] [action] vbom

and must be called, except for the --help case, with exactly one vbom file.

OPTIONS

--trace
    Gives a detailed trace, written to stderr, of the vbom file traversal and processing, the process of source file ranking to determine the compilation order, and of the final internal file list and property table.

--xlpath=path
    Defines the location where the ghdl compiled Xilinx unisim, unimacro, or simprim libraries are located. This option is mandatory for --ghdl_a and --ghdl_m commands when the design contains a @lib directive. These compiled libs are typically created with the xviv_ghdl_unisim(1) command for Vivado and xise_ghdl_unisim(1) or xise_ghdl_simprim(1) commands for ISE environments.

ACTIONS

--help
    Prints a usage summary to stdout and quits. This action is the only one not requiring a vbom file.

--dep_ghdl
--dep_xst
--dep_isim
--dep_vsyn
--dep_vsim
    These four actions write to stdout dependency rules for inclusion in Makefiles. Together with an appropriate pattern rule, they allow to automatize the dependency handling, see the EXAMPLES section for practical usage. --dep_ghdl creates the dependencies for ghdl based simulation models and produces the following types of dependencies
           <stem> : <stem>.dep_ghdl
           <stem> : *.vhd
           <stem>.dep_ghdl : *.vbom
    --dep_xst creates the dependencies for xst synthesis make flows and produces the following types of dependencies
           <stem>.ngc : <stem>.dep_xst
           <stem>.ngc : *.vhd
           <stem>.dep_xst : *.vbom
    with * indicating that one rule will be generated for each file involved. If a @ucf_cpp directive was found also rules describing the ucf file handling are added
           <stem>.ncd : <stem>.ucf
           include sys_w11a_n2.dep_ucf_cpp
    If this mechanism is used the Makefile must contain, usually via another include, a pattern rule to create the .dep_ucf_cpp file, for example
            %.dep_ucf_cpp : %.ucf_cpp
                    cpp -I${RETROBASE}/rtl -MM $*.ucf_cpp |\
                        sed 's/.o:/.ucf:/' > $*.dep_ucf_cpp
    --dep_isim creates the dependencies for ISE ISim based simulation models and produces the following types of dependencies
           <stem>_ISim : <stem>.dep_isim
           <stem>_ISim : *.vhd
           <stem>.dep_isim : *.vbom
    --dep_vsyn creates the dependencies for Vivado synthesis make flows and produces the following types of dependencies
           <stem>.bit : <stem>.dep_vsyn
           <stem>.bit : *.vhd *.xdc
           <stem>_syn.dcp : *.vhd *.xdc
           <stem>_rou.dcp : *.vhd *.xdc
           <stem>.dep_vsyn : *.vbom
    --dep_vsim creates the dependencies for Vivado xim based simulation models and produces the following types of dependencies
           <stem>_XSim : <stem>.dep_vsim
           <stem>_XSim : *.vhd
           <stem>.dep_vsim : *.vbom

--ghdl_i_cmd
--ghdl_i
    The --ghdl_i_cmd action writes to stdout a "ghdl -i" command for the ghdl inspection step with all source file names in proper compilation order. The --ghdl_i action immediately executes this command via exec(3).

--ghdl_a_cmd
--ghdl_a
    The --ghdl_a_cmd action writes to stdout a list of "ghdl -a" commands for the ghdl analysis step. The commands are in proper compilation order. The --ghdl_a action immediately executes these commands via exec(3).

--ghdl_m_cmd
--ghdl_m
    The --ghdl_m_cmd action writes to stdout a "ghdl -m" command for the ghdl inspection make with all required library and external object file qualifiers. The --ghdl_m action immediately executes this command via exec(3).

--xst_prj
--isim_prj
    These two actions write to stdout a project file suitable for ISE xst or ISim, respectively. The VHDL source files are in proper compilation order. See the EXAMPLES section for practical usage in a make flow.

--vsyn_prj
    This action writes to stdout a Tcl script suitable as project definition for Vivado synthesis. This script is source'ed or eval'ed and defines the source fileset and the constraints fileset. The VHDL source files are in proper compilation order.

--vsim_prj
    This action writes to stdout a shell script which will generate the Vivado simulation snapshot and a short forwarder script for starting the simulation.

--ghdl_export=path
--vsyn_export=path
--vsim_export=path
--xst_export=path
--isim_export=path
    These actions create a flat copy of all source files needed for an xst synthesis or a ghdl or ISim simulation model in the directory path. The sub directory structure is lost, all files will be in directory path. This is for example helpful for setting up an ISE project.

--get_top
    Returns the top-level entity name to stdout. Is by default the stem of the vbom file name, or given by a @top directive picked up during vbom traversal.

--flist
    Write an alphabetically sorted list of all source and vbom files to stdout. This information for example helps to build a project export tool. Note that in contrast to most other actions the files are not in compilation but in alphabetic order, and that also the vbom files are included in this list.

EXIT STATUS
Returns a non-zero exit status when the vbom file is not found or readable or none or multiple actions are given.

The --ghdl_a, --ghdl_i, or --ghdl_m actions use exec(3) to execute the ghdl command. In these cases, the caller will see the exit status of ghdl.

ENVIRONMENT

VBOMCONV_XSIM_LANG
    Controls the language for the generated models used by xsim. Can be set to Verilog or VHDL. If not defined Verilog is used. It affects --vsim_prj but also --dep_vsim. Use rm_dep(1) to force regeneration of dependency files when this environment variable is set, unset, or changed.

VBOMCONV_GHDL_OPTS
    Extra options for the ghdl compile stage. If not specified "-O2 -g" is taken to enable optimization (is not default for gcc backend!) and debug symbols (needed for assertion failure backtrace).

VBOMCONV_GHDL_GCOV
    If defined and set to '1' ghdl(1) models will be compiled with gcov(1) coverage support. This option is only available when ghdl was compiled with gcc backend, the llvm and mcode backend do not support coverage analysis. The generated ghdl options will be appended after the ones given by VBOMCONV_GHDL_OPTS. Note that no default options are assumed, so '-Ox' or '-g' options must be explicitly given via VBOMCONV_GHDL_OPTS. The additional ghdl options are
           -Wc,-ftest-coverage
           -Wc,-fprofile-arcs
           -Wl,-lgcov

BUGS

•   Duplicate file elimination fails when one source file is refered to by different vbom's with different paths, like for example the file aa/bb/cc/foo.vdh seen from aa/xx/yy via
            ../../bb/cc/foo.vhd
            ../../../aa/bb/cc/foo.vdh
    The synthesis and simulation tools will react with sometimes hard to trace error messages.
    To avoid this problem ensure that the building of the relative paths is always done with the minimal number of ../ to reach the file.

•   The handling of ucf files with the @ucf_cpp directive is a kludge and should be revised.

EXAMPLES

  Auto-Dependency Generation
The --dep_xst, --dep_ghdl, and --dep_isim actions allow to set up together with the auto-rebuild and restart semantics of the GNU make(1) include directive to fully automatize the proper generation of dependencies. Just add to the Makefile a pattern rule to create the dependency rule files from the vbom files and include them. In case they don't yet exist or are out of date make(1) will (re-)create them and restart. Example for using --dep_xst in a Makefile :

        VBOM_all = $(wildcard *.vbom)
        ...
        %.dep_xst: %.vbom
                vbomconv --dep_xst $< > $@
        ...
        include $(VBOM_all:.vbom=.dep_xst)

After renames and deletions of source files the dependency rule files can have dangling entries which cause 'No rule to make target' errors. In that case, just delete all '.dep_*' files. The script rm_dep(1) will do that recursively for a whole directory tree.

  Xst Synthesis
A simple make(1) flow for synthesis with xst using ISE xflow and the --xst_prj action and a pattern rule looks like

        %.ngc: %.vbom
                if [ ! -d ./ise ]; then mkdir ./ise; fi
                (cd ./ise; vbomconv --xst_prj ../$< > $*.prj)
                (cd ./ise; touch $*.xcf)
                xtwi xflow -wd ise -synth xst_vhdl.opt $*.prj
                (cd ./ise; chmod -x *.* )
                if [ -r ./ise/$*.ngc ]; then cp -p ./ise/$*.ngc .; fi
                if [ -r ./ise/$*_xst.log ]; then cp -p ./ise/$*_xst.log .; fi

It creates a working directory ./ise, the xst project file, runs xst via ISE xflow, and copies the ngc and log files back into the working directory. The ISE environment is started with xtwi(1) wrapper.

  Ghdl Simulation
A simple make(1) flow for building a ghdl simulation model from the sources described by a vbom file is given by the following pattern rule:

        % : %.vbom
                vbomconv --ghdl_i $<
                vbomconv --ghdl_m $<

  Collecting Statistics
A simple way to determine the number of sources involved in a synthesis or simulation model is to count with wc(1) the lines of a --xst_prj or --isim_prj output like in

    vbomconv --xst_prj     sys_w11a_n2.vbom | wc
    vbomconv --ghdl_a_cmd  tb_w11a_n2.vbom  | wc
    vbomconv --isim_prj    tb_w11a_n2.vbom  | wc

SEE ALSO
vbom(5), rm_dep(1), ghdl(1), xtwi(1), xtwv(1), cpp(1),
xviv_ghdl_unisim(1), xise_ghdl_simprim(1), xise_ghdl_unisim(1)

AUTHOR
Walter F.J. Mueller <W.F.J.Mueller@gsi.de>