|
Generated: 2023-02-09 |
Generated by man2html V0.26
page hit count: 553 |
|
VBOMCONV(1) Retro Project Manual 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 com- ponents 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, de- pending on command-line options, the files and/or commands needed to run a synthesis tool or to build a simulation model. Currently sup- ported is synthesis with Xilinx ISE xst and Xilinx Vivado and simula- tion 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 automati- cally generated from this 'local' information, which can be of great help in projects with many top-level designs with a large number of en- tities 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 simula- tion 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 fi- nally 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 or- dered 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 con- dition prefix. The main purpose of this mechanism is to handle li- braries 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 con- figuration 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 tra- versal and processing, the process of source file ranking to de- termine the compilation order, and of the final internal file list and property table. --xlpath=path Defines the location where the ghdl compiled Xilinx unisim, uni- macro, or simprim libraries are located. This option is manda- tory 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 en- vironments. 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 inclu- sion in Makefiles. Together with an appropriate pattern rule, they allow to automatize the dependency handling, see the EXAM- PLES 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 simula- tion 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 simula- tion 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 exe- cutes 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 file- set. 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 di- rectory path. The sub directory structure is lost, all files will be in directory path. This is for example helpful for set- ting 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 ac- tions 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 read- able 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 regenera- tion of dependency files when this environment variable is set, un- set, 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 ap- pended after the ones given by VBOMCONV_GHDL_OPTS. Note that no de- fault options are assumed, so '-Ox' or '-g' options must be explic- itly given via VBOMCONV_GHDL_OPTS. The additional ghdl options are -Wc,-ftest-coverage -Wc,-fprofile-arcs -Wl,-lgcov BUGS +o 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. +o 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 to- gether with the auto-rebuild and restart semantics of the GNU make(1) include directive to fully automatize the proper generation of depen- dencies. Just add to the Makefile a pattern rule to create the depen- dency 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> Retro Project 2018-11-09 VBOMCONV(1)
|
Generated: 2023-02-09 |
Generated by man2html V0.26
page hit count: 553 |
|