w11 - /man/cat5/vbom.0

VBOM(5)                      Retro Project Manual                      VBOM(5)


NAME
       vbom - vhdl manifest file format - 'vhdl bill of material'

DESCRIPTION
       vbom  files  describe  the  sources  needed to build a VHDL entity. The
       source files are either given directly in the case of libraries or  via
       other  vbom's in the case of instantiated components.  They are used by
       vbomconv(1) to build project descriptions for synthesis and  simulation
       tools.

       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.

       The format has five types of lines:

       Comments
           Each line starting with '#' is treated as a comment and ignored.

       File names
           Either  source files or nested vbom's. The file names must be given
           as relative path names from the directory the vbom file is  located
           in.   Absolute  path  names are not allowed, nor is an expansion of
           environment variables.

           Currently, the following file types are accepted:

           .vbom refers to a nested vbom. Usually used for instantiated compo-
                 nents.

           .vhd  refers  to a source file. Usually used for libraries referred
                 to in 'use' clauses, and as the last file, the source file of
                 the entity which is described by this vbom file.

           .v
           .sv   refers  to  a Verilog or System Verilog source file. Accepted
                 by the Vivado xsim simulator. Typically used for DPI wrappers
                 or simprim-based models in Vivado.

           .c    refers  to  the C sources which implement either a VHDL func-
                 tion or procedure via the VHPI mechanism or a System  Verilog
                 function via the DPI mechanism. Supported only in conjunction
                 with GHDL and Vivado simulator.

       File attributes
           File names can be followed by a list of attributes of the form
               -name[:value] ...
           Currently, the following attributes are recognized

           -UUT  Signals that the vbom describes a test bench and that file is
                 the 'unit under test'. This allows splitting the sources into
                 a simulation-only test bench part and a  synthesizable  'unit
                 under  test' part.  The file is typically a vbom in case of a
                 behavioral simulation or the file name of a  generated  model
                 for a functional or timing simulation.

           -SCOPE_REF[:entity]
                 Signals  that the xdc file should be 'scoped to reference' to
                 entity.  If entity is omitted the filename is  taken  as  the
                 entity  name.  In general used together with the @xdc: direc-
                 tive.

       Conditional file names
           File names can be preceded by a condition prefix of the form

              [tag]filename
              [tag,tag,...]filename

           The main purpose of this mechanism is to handle libraries and  com-
           ponents which are only referred in
               -- synthesis translate_off
               -- synthesis translate_on
           sections and are used only for simulation.

           Currently, supported tag names are
              ghdl  included in conjunction with GHDL simulation
              viv   included in conjunction with Vivado targets
              vsyn  included in conjunction with Vivado synthesis
              vsim  included in conjunction with Vivado simulation
              ise   included in conjunction with ISE targets
              xst   included in conjunction with ISE xst synthesis
              isim  included in conjunction with ISE ISim simulation
              sim   included in conjunction with simulation (ghdl,isim,vsim)

       Logical names
           A logical name can be defined with
               lname = filename
           The first definition of a logical name encountered in the traversal
           of the vbom's by vbomconv(1) is taken, and  all  later  definitions
           are ignored.

           A logical name can be used with
              ${lname}
              ${lname := default}
           In the first form, lname must have been defined before.  The second
           form allows specifying a default which is used  when  lname  hasn't
           been defined so far.

           Again,  the filenames must be given as relative path names from the
           directory the vbom file is located in.


       Directives
           Directives start with a '@', currently implemented are:

           @top:name
               Specifies the top-level design name. Mainly  used  when  it  is
               different from the stem of the vbom file name.

           @lib:name
               Specifies an additional system library. Allowed values for name
               are unisim, unimacro, and simprim.  Currently used to  generate
               the appropriate -L options for ghdl commands, e.g. generated by
               the vbomconv action --ghdl_m.

           @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 build-
               ing the Vivado project. The Tcl script generated by  the  vbom-
               conv  action  --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.

EXAMPLES
   Simple entity
       A simple VHDL entity named bp_2l4l which is defined in the source  file
       bp_2l4l.vhd,  which uses the library slvtypes and instantiates bp_2line
       and bp_4line, might have a bp_2l4l.vbom like

           # libs
           ../../vlib/slvtypes.vhd
           # components
           bp_2line.vbom
           bp_4line.vbom
           # design
           bp_2l4l.vhd

       Note that the VHDL source file bp_2l4l.vhd is always given in the  vbom
       file which describes this source file.  The comments are put in by con-
       vention to help the human reader and are not interpreted by vbomconv.

SEE ALSO
       vbomconv(1), ghdl(1), cpp(1)

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


Retro Project                     2018-11-09                           VBOM(5)