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 finally 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 components.

    .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 function 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: directive.

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 components 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 building the Vivado project. The Tcl script generated by the vbomconv 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 convention 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>