VBOMCONV(1) Retro Project Manual VBOMCONV(1) NNAAMMEE vbomconv - generate files and actions from vbom manifest files SSYYNNOOPPSSIISS vvbboommccoonnvv [----ttrraaccee] ----gghhddll__ii__ccmmdd | ----gghhddll__ii _v_b_o_m vvbboommccoonnvv [----ttrraaccee] [----xxllppaatthh==_p_a_t_h] ----gghhddll__aa__ccmmdd | ----gghhddll__aa _v_b_o_m vvbboommccoonnvv [----ttrraaccee] [----xxllppaatthh==_p_a_t_h] ----gghhddll__mm__ccmmdd | ----gghhddll__mm _v_b_o_m vvbboommccoonnvv [----ttrraaccee] ----gghhddll__eexxppoorrtt=_p_a_t_h _v_b_o_m vvbboommccoonnvv [----ttrraaccee] ----vvssyynn__pprrjj | ----vvssiimm__pprrjj _v_b_o_m vvbboommccoonnvv [----ttrraaccee] ----vvssyynn__eexxppoorrtt=_p_a_t_h | ----vvssiimm__eexxppoorrtt=_p_a_t_h _v_b_o_m vvbboommccoonnvv [----ttrraaccee] ----xxsstt__pprrjj | ----iissiimm__pprrjj _v_b_o_m vvbboommccoonnvv [----ttrraaccee] ----xxsstt__eexxppoorrtt=_p_a_t_h | ----iissiimm__eexxppoorrtt=_p_a_t_h _v_b_o_m vvbboommccoonnvv [----ttrraaccee] ----ddeepp__gghhddll _v_b_o_m vvbboommccoonnvv [----ttrraaccee] ----ddeepp__xxsstt | ----ddeepp__iissiimm _v_b_o_m vvbboommccoonnvv [----ttrraaccee] ----ddeepp__vvssyynn | ----ddeepp__vvssiimm _v_b_o_m vvbboommccoonnvv [----ttrraaccee] ----ggeett__ttoopp _v_b_o_m vvbboommccoonnvv [----ttrraaccee] ----fflliisstt _v_b_o_m vvbboommccoonnvv ----hheellpp DDEESSCCRRIIPPTTIIOONN IInnttrroodduuccttiioonn vvbboommccoonnvv is the central tool in a build system for _V_H_D_L projects. Each _V_H_D_L source file has an associated manifest file in vvbboomm(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 vvbboomm file. All file names are relative to the current directory. A recursive traversal through all vvbboomm'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 vvbboommccoonnvv tool does this traversal of vvbboomm 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 xxsstt and Xilinx Vivado and simula- tion with gghhddll(1), Xilinx ISE IISSiimm, or Xilinx Vivado xxssiimm. vvbboommccoonnvv therefore currently generates -- gghhddll commands for analysis, inspection and make step -- vvssyynn project setups for Vivado synthesis -- vvssiimm project setups for Vivado simulation -- xxsstt project files for ISE synthesis -- IISSiimm project files for ISE simulation -- mmaakkee dependency files The key advantage of this approach is that the individual vvbboomm 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. vvbboommccoonnvv is usually embedded in a GNU mmaakkee(1)-based build system. The _M_a_k_e_f_i_l_e's in general just contain a few definitions and includes, the whole vvbboommccoonnvv magic is encapsulated in some pattern rules for simula- tion and synthesis. Some are given in the EXAMPLES section. PPrriinncciippllee ooff OOppeerraattiioonn vvbboommccoonnvv will start with processing the _v_b_o_m file given as an argument. Each file name extracted from a vvbboomm is prepended with the directory path of the vvbboomm. This ensures that all file names are relative to the working directory under which vvbboommccoonnvv was started, even though each vvbboomm file holds only file names that are relative to the vvbboomm. vvbboommccoonnvv expects that the entries in the vvbboomm'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 _._v_h_d file is added to a table of source files. Each _._v_b_o_m file is added to a list of vvbboomm's to be processed if it hasn't been processed yet. The sub-vvbboomm's are processed in the order they were found which leads to breadth-first traversal of the vvbboomm tree. After all vvbboomm'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 '_u_s_e' clause, and that entities are compiled before they are referred to by an explicit instatiation. The vvbboomm 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 vvbboomm file format has a logical name mechanism to support the _c_o_n_- _f_i_g_u_r_a_t_i_o_n mechanism of VHDL. A logical name can be defined with = and it can be used with ${_l_n_a_m_e} ${_l_n_a_m_e := _d_e_f_a_u_l_t} The first definition seen in the _v_b_o_m 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 vvbboomm file format: @@ttoopp:_n_a_m_e allows to specify the top-level design name in case it differs from the stem of the _v_b_o_m file name. @@lliibb:_n_a_m_e allows to specify additional system libraries. Currently used to indicate that the _u_n_i_s_i_m, _u_n_i_m_a_c_r_o, or _s_i_m_p_r_i_m libraries are needed by gghhddll. @@xxddcc:_f_i_l_e specifies that _f_i_l_e is a constraint file for Vivado synthesis and should be included in the constraints fileset. @@ttccll:_f_i_l_e specifies that _f_i_l_e is a Tcl script to be executed when building the Vivado project. The Tcl script generated by ----vvssyynn__pprrjj will contain statements with source _f_i_l_e. @@uuccff__ccpppp:_f_i_l_e specifies that a _f_i_l_e.ucf file is to be generated by ccpppp(1) from a _f_i_l_e.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 vvbboomm(5). UUSSAAGGEE The vvbboommccoonnvv command has the form vvbboommccoonnvv [_o_p_t_i_o_n_s] [_a_c_t_i_o_n] _v_b_o_m and must be called, except for the ----hheellpp case, with exactly one _v_b_o_m file. OOPPTTIIOONNSS ----ttrraaccee Gives a detailed trace, written to _s_t_d_e_r_r, 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. ----xxllppaatthh=_p_a_t_h Defines the location where the gghhddll compiled Xilinx unisim, uni- macro, or simprim libraries are located. This option is manda- tory for ----gghhddll__aa and ----gghhddll__mm commands when the design contains a @@lliibb directive. These compiled libs are typically created with the xxvviivv__gghhddll__uunniissiimm(1) command for Vivado and xxiissee__gghhddll__uunniissiimm(1) or xxiissee__gghhddll__ssiimmpprriimm(1) commands for ISE en- vironments. AACCTTIIOONNSS ----hheellpp Prints a usage summary to _s_t_d_o_u_t and quits. This action is the only one not requiring a _v_b_o_m file. ----ddeepp__gghhddll ----ddeepp__xxsstt ----ddeepp__iissiimm ----ddeepp__vvssyynn ----ddeepp__vvssiimm These four actions write to _s_t_d_o_u_t dependency rules for inclu- sion in _M_a_k_e_f_i_l_es. Together with an appropriate pattern rule, they allow to automatize the dependency handling, see the EXAM- PLES section for practical usage. ----ddeepp__gghhddll creates the dependencies for gghhddll based simulation models and produces the following types of dependencies _<_s_t_e_m_> : _<_s_t_e_m_>.dep_ghdl _<_s_t_e_m_> : **.vhd _<_s_t_e_m_>.dep_ghdl : **.vbom ----ddeepp__xxsstt creates the dependencies for xxsstt synthesis make flows and produces the following types of dependencies _<_s_t_e_m_>.ngc : _<_s_t_e_m_>.dep_xst _<_s_t_e_m_>.ngc : **.vhd _<_s_t_e_m_>.dep_xst : **.vbom with ** indicating that one rule will be generated for each file involved. If a @@uuccff__ccpppp directive was found also rules describing the _u_c_f file handling are added .ncd : .ucf include sys_w11a_n2.dep_ucf_cpp If this mechanism is used the _M_a_k_e_f_i_l_e must contain, usually via another include, a pattern rule to create the _._d_e_p___u_c_f___c_p_p file, for example %.dep_ucf_cpp : %.ucf_cpp cpp -I${RETROBASE}/rtl -MM $*.ucf_cpp |\ sed 's/.o:/.ucf:/' > $*.dep_ucf_cpp ----ddeepp__iissiimm creates the dependencies for ISE IISSiimm based simula- tion models and produces the following types of dependencies _<_s_t_e_m_>_ISim : _<_s_t_e_m_>.dep_isim _<_s_t_e_m_>_ISim : **.vhd _<_s_t_e_m_>.dep_isim : **.vbom ----ddeepp__vvssyynn creates the dependencies for Vivado synthesis make flows and produces the following types of dependencies _<_s_t_e_m_>.bit : _<_s_t_e_m_>.dep_vsyn _<_s_t_e_m_>.bit : **.vhd **.xdc _<_s_t_e_m_>_syn.dcp : **.vhd **.xdc _<_s_t_e_m_>_rou.dcp : **.vhd **.xdc _<_s_t_e_m_>.dep_vsyn : **.vbom ----ddeepp__vvssiimm creates the dependencies for Vivado xxiimm based simula- tion models and produces the following types of dependencies _<_s_t_e_m_>_XSim : _<_s_t_e_m_>.dep_vsim _<_s_t_e_m_>_XSim : **.vhd _<_s_t_e_m_>.dep_vsim : **.vbom ----gghhddll__ii__ccmmdd ----gghhddll__ii The ----gghhddll__ii__ccmmdd action writes to _s_t_d_o_u_t a ""gghhddll --ii"" command for the gghhddll inspection step with all source file names in proper compilation order. The ----gghhddll__ii action immediately executes this command via eexxeecc(3). ----gghhddll__aa__ccmmdd ----gghhddll__aa The ----gghhddll__aa__ccmmdd action writes to _s_t_d_o_u_t a list of ""gghhddll --aa"" commands for the gghhddll analysis step. The commands are in proper compilation order. The ----gghhddll__aa action immediately executes these commands via eexxeecc(3). ----gghhddll__mm__ccmmdd ----gghhddll__mm The ----gghhddll__mm__ccmmdd action writes to _s_t_d_o_u_t a ""gghhddll --mm"" command for the gghhddll inspection make with all required library and external object file qualifiers. The ----gghhddll__mm action immediately exe- cutes this command via eexxeecc(3). ----xxsstt__pprrjj ----iissiimm__pprrjj These two actions write to _s_t_d_o_u_t a project file suitable for ISE xxsstt or IISSiimm, respectively. The VHDL source files are in proper compilation order. See the EXAMPLES section for practical usage in a make flow. ----vvssyynn__pprrjj This action writes to _s_t_d_o_u_t 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. ----vvssiimm__pprrjj This action writes to _s_t_d_o_u_t a shell script which will generate the Vivado simulation snapshot and a short forwarder script for starting the simulation. ----gghhddll__eexxppoorrtt=_p_a_t_h ----vvssyynn__eexxppoorrtt=_p_a_t_h ----vvssiimm__eexxppoorrtt=_p_a_t_h ----xxsstt__eexxppoorrtt=_p_a_t_h ----iissiimm__eexxppoorrtt=_p_a_t_h These actions create a flat copy of all source files needed for an xxsstt synthesis or a gghhddll or IISSiimm simulation model in the di- rectory _p_a_t_h. The sub directory structure is lost, all files will be in directory _p_a_t_h. This is for example helpful for set- ting up an ISE project. ----ggeett__ttoopp Returns the top-level entity name to _s_t_d_o_u_t. Is by default the stem of the _v_b_o_m file name, or given by a @@ttoopp directive picked up during vvbboomm traversal. ----fflliisstt Write an alphabetically sorted list of all source and vbom files to _s_t_d_o_u_t. 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 vvbboomm files are included in this list. EEXXIITT SSTTAATTUUSS Returns a non-zero exit status when the _v_b_o_m file is not found or read- able or none or multiple actions are given. The ----gghhddll__aa, ----gghhddll__ii, or ----gghhddll__mm actions use eexxeecc(3) to execute the gghhddll command. In these cases, the caller will see the exit status of gghhddll. EENNVVIIRROONNMMEENNTT VVBBOOMMCCOONNVV__XXSSIIMM__LLAANNGG Controls the language for the generated models used by xsim. Can be set to _V_e_r_i_l_o_g or _V_H_D_L. If not defined _V_e_r_i_l_o_g is used. It affects ----vvssiimm__pprrjj but also ----ddeepp__vvssiimm. Use rrmm__ddeepp(1) to force regenera- tion of dependency files when this environment variable is set, un- set, or changed. VVBBOOMMCCOONNVV__GGHHDDLL__OOPPTTSS Extra options for the ghdl compile stage. If not specified "--OO22 --gg" is taken to enable optimization (is not default for gcc backend!) and debug symbols (needed for assertion failure backtrace). VVBBOOMMCCOONNVV__GGHHDDLL__GGCCOOVV If defined and set to '1' gghhddll(1) models will be compiled with ggccoovv(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 VVBBOOMMCCOONNVV__GGHHDDLL__OOPPTTSS. Note that no de- fault options are assumed, so '-Ox' or '-g' options must be explic- itly given via VVBBOOMMCCOONNVV__GGHHDDLL__OOPPTTSS. The additional ghdl options are -Wc,-ftest-coverage -Wc,-fprofile-arcs -Wl,-lgcov BBUUGGSS +o Duplicate file elimination fails when one source file is refered to by different _v_b_o_m's with different paths, like for example the file _a_a_/_b_b_/_c_c_/_f_o_o_._v_d_h seen from _a_a_/_x_x_/_y_y 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 _u_c_f files with the @@uuccff__ccpppp directive is a kludge and should be revised. EEXXAAMMPPLLEESS AAuuttoo--DDeeppeennddeennccyy GGeenneerraattiioonn The ----ddeepp__xxsstt, ----ddeepp__gghhddll, and ----ddeepp__iissiimm actions allow to set up to- gether with the auto-rebuild and restart semantics of the GNU mmaakkee(1) _i_n_c_l_u_d_e directive to fully automatize the proper generation of depen- dencies. Just add to the _M_a_k_e_f_i_l_e a pattern rule to create the depen- dency rule files from the vvbboomm files and include them. In case they don't yet exist or are out of date mmaakkee(1) will (re-)create them and restart. Example for using ----ddeepp__xxsstt in a _M_a_k_e_f_i_l_e : 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 rrmm__ddeepp(1) will do that recursively for a whole directory tree. XXsstt SSyynntthheessiiss A simple mmaakkee(1) flow for synthesis with xxsstt using ISE xxffllooww and the ----xxsstt__pprrjj 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 _._/_i_s_e, the xst project file, runs xxsstt via ISE xxffllooww, and copies the _n_g_c and _l_o_g files back into the working directory. The ISE environment is started with xxttwwii(1) wrapper. GGhhddll SSiimmuullaattiioonn A simple mmaakkee(1) flow for building a gghhddll simulation model from the sources described by a vvbboomm file is given by the following pattern rule: % : %.vbom vbomconv --ghdl_i $< vbomconv --ghdl_m $< CCoolllleeccttiinngg SSttaattiissttiiccss A simple way to determine the number of sources involved in a synthesis or simulation model is to count with wwcc(1) the lines of a ----xxsstt__pprrjj or ----iissiimm__pprrjj 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 SSEEEE AALLSSOO vvbboomm(5), rrmm__ddeepp(1), gghhddll(1), xxttwwii(1), xxttwwvv(1), ccpppp(1), xxvviivv__gghhddll__uunniissiimm(1), xxiissee__gghhddll__ssiimmpprriimm(1), xxiissee__gghhddll__uunniissiimm(1) AAUUTTHHOORR Walter F.J. Mueller Retro Project 2018-11-09 VBOMCONV(1)