Subversion Repositories w11

.\"  -*- nroff -*-
.\"  $Id: vbom.5 779 2016-06-26 15:37:16Z mueller $
.\"
.\" Copyright 2010-2016 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
.\" 
.\" ------------------------------------------------------------------
.
.TH VBOM 2016-03-19 "Retro Project" "Retro Project Manual"
.\" ------------------------------------------------------------------
.SH NAME
vbom \- vhdl manifest file format - 'vhdl bill of material'
.
.\" ------------------------------------------------------------------
.SH DESCRIPTION
\fBvbom\fP files describe the sources needed to build a \fIvhdl\fP
entity. The source files are either given directly in case of libraries
or via other \fBvbom\fP's in case of instantiated components. 
They are used by \fBvbomconv\fP(1) to build project descriptions 
for synthesis and simulation tools.

\fBvbomconv\fP expects that the entries in the \fBvbom\fP's
are ordered, libraries first, than the components in the order they are
instantiated, finally the name of the associated source file.

The format has five types of lines:
.
.\" ----------------------------------------------
.IP \fBComments\fP 4
Each line starting with '\fB#\fP' is treated as comment and ignored.
.
.\" ----------------------------------------------
.IP "\fBFile names\fP"
Either source files or nested \fBvbom\fP's. The file names  must be given
as relative path name from the directory the \fBvbom\fP file is located in. 
Absolute path names are not allowed, nor is expansion of environment variables.

Currently the following file types are accepted:
.RS
.IP "\fB.vbom\fP" 6
refers to a nested \fBvbom\fP. Usually used for instantiated components.
.
.IP "\fB.vhd\fP"
refers to a source file. Usually used for libraries refered to in 'use'
clauses, and as last file, the source file of the entity which is
described by this \fBvbom\fP file.
.
.TP
.B "\fB.v\fP"
.TQ
.B "\fB.sv\fP"
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.
.
.IP "\fB.c\fP"
refers to the C source which implements a \fIvhdl\fP function or procedure
via the \fIvhpi\fP mechanism. Supported only in conjunction with \fBghdl\fP.
.
.RE
.
.\" ----------------------------------------------
.IP "\fBFile attributes\fP"
File names can be followed by a list of attributes of the form
.EX
    -\fIname\fP[:\fIvalue\fP] ...
.EE
Currently the following attributes are recognized
.RS
.IP "\fB-UUT\fP" 6
Signals that the \fIvbom\fP descibes a test bench and that file is
the 'unit under test'. This allows to split the sources into a simulation
only test bench part and a synthesizable 'unit under test' part. The file
is typically a \fIvbom\fP in case of a behavioural simulation or the file
name of a generated model for a functional or timing simulation.
.
.IP "\fB-SCOPE_REF[:\fIentity\fP]\fP" 6
Signals that the xdc file should be 'scoped to reference' to \fIentity\fP.
If \fIentity\fP is omitted the filename is taken as entity name.
In general used together with the \fB@xdc:\fP directive.
.
.RE
.
.\" ----------------------------------------------
.IP "\fBConditional file names\fP"
File names can be preceeded by a condition prefix of the form

.EX
   [\fItag\fP]filename
   [\fItag\fP,\fItag\fP,...]filename
.EE

The main purpose of this mechanism is to handle libraries and components 
which are only refered in 
.EX
    -- synthesis translate_off
    -- synthesis translate_on
.EE
sections and are used only for simulation.

Currently supported \fItag\fP names are
.RS
.RS 3
.PD 0
.IP "\fBghdl\fP" 6
included in conjunction with ghdl simulation
.IP "\fBviv\fP" 6
included in conjunction with Vivado targets
.IP "\fBvsyn\fP" 6
included in conjunction with Vivado synthesis
.IP "\fBvsim\fP" 6
included in conjunction with Vivado simulation
.IP "\fBise\fP" 6
included in conjunction with ISE targets
.IP "\fBxst\fP" 6
included in conjunction with ISE xst synthesis
.IP "\fBisim\fP" 6
included in conjunction with ISE ISim simulation
.IP "\fBsim\fP" 6
included in conjunction with simulation (ghdl,isim,vsim)
.PD
.RE
.RE
.
.\" ----------------------------------------------
.IP "\fBLogical names\fP"
A logical name can be defined with
.EX
    \fIlname\fP = \fIfilename\fP
.EE
The first definition of a logical name encountered in the traversal of the
\fBvbom\fP's by \fBvbomconv\fP(1) is taken, all later definitions are ignored.

A logical name can be used with
.EX
   ${\fIlname\fP}
   ${\fIlname\fP := \fIdefault\fP} 
.EE
In the first form \fIlname\fP must have been defined before.
The second form allows to specify a \fIdefault\fP which is used when
\fIlname\fP hasn't been defined so far.

Again, the filenames must be given as relative path name from the directory 
the \fBvbom\fP file is located in.

.\" ----------------------------------------------
.IP \fBDirectives\fP
Directives start with a '\fB@\fP', currently implemented are:
.RS
.IP "\fB@top\fP:\fIname\fP" 4
Specifies the top level design name. Mainly used when it is different 
from the stem of the \fBvbom\fP file name.
.
.IP "\fB@lib\fP:\fIname\fP"
Specifies an additional system library. Allowed values for \fIname\fP are
\fIunisim\fP, \fIunimacro\fP and \fIsimprim\fP. 
Currently used to generate the appropriate -L options for \fBghdl\fP commands, 
e.g. generated by the \fBvbomconv\fP action \fB\-\-ghdl_m\fP.
.
.IP "\fB@xdc\fP:\fIfile\fP"
Specifies that \fIfile\fP is a constraint file for Vivado synthesis and should
be included in the constraints fileset.
.
.IP "\fB@ucf_cpp\fP:\fIfile\fP"
Specifies that a \fIfile\fP.ucf file is to be generated by \fBcpp\fP(1)
from a \fIfile\fP.ucf_cpp source file. This allows to modularize ISE ucf files.
.RE
.
.\" ------------------------------------------------------------------
.SH EXAMPLES
.SS Simple entity
A simple vhdl entity named \fIbp_2l4l\fP which is defined in the source
file \fIbp_2l4l.vhd\fP, which uses the library \fIslvtypes\fP and
instantiates \fIbp_2line\fP and \fIbp_4line\fP, might have a 
\fIbp_2l4l.vbom\fP like
.PP
.EX
    # libs
    ../../vlib/slvtypes.vhd
    # components
    bp_2line.vbom
    bp_4line.vbom
    # design
    bp_2l4l.vhd
.EE
.PP
Note that the vhdl source file \fIbp_2l4l.vhd\fP is always given in the 
\fBvbom\fP file which describes this source file. 
The comments are put in by convention to help the human reader and 
are not interpreted by \fBvbomconv\fP.
.
.\" ------------------------------------------------------------------
.SH "SEE ALSO"
.BR vbomconv (1),
.BR ghdl (1),
.BR cpp (1)
.
.\" ------------------------------------------------------------------
.SH AUTHOR
Walter F.J. Mueller <W.F.J.Mueller@gsi.de>