1 |
8 |
wfjm |
.\" -*- nroff -*-
|
2 |
36 |
wfjm |
.\" $Id: vbom.5 779 2016-06-26 15:37:16Z mueller $
|
3 |
8 |
wfjm |
.\"
|
4 |
35 |
wfjm |
.\" Copyright 2010-2016 by Walter F.J. Mueller
|
5 |
8 |
wfjm |
.\"
|
6 |
|
|
.\" ------------------------------------------------------------------
|
7 |
|
|
.
|
8 |
35 |
wfjm |
.TH VBOM 2016-03-19 "Retro Project" "Retro Project Manual"
|
9 |
8 |
wfjm |
.\" ------------------------------------------------------------------
|
10 |
|
|
.SH NAME
|
11 |
23 |
wfjm |
vbom \- vhdl manifest file format - 'vhdl bill of material'
|
12 |
8 |
wfjm |
.
|
13 |
|
|
.\" ------------------------------------------------------------------
|
14 |
|
|
.SH DESCRIPTION
|
15 |
23 |
wfjm |
\fBvbom\fP files describe the sources needed to build a \fIvhdl\fP
|
16 |
|
|
entity. The source files are either given directly in case of libraries
|
17 |
|
|
or via other \fBvbom\fP's in case of instantiated components.
|
18 |
22 |
wfjm |
They are used by \fBvbomconv\fP(1) to build project descriptions
|
19 |
|
|
for synthesis and simulation tools.
|
20 |
8 |
wfjm |
|
21 |
23 |
wfjm |
\fBvbomconv\fP expects that the entries in the \fBvbom\fP's
|
22 |
|
|
are ordered, libraries first, than the components in the order they are
|
23 |
|
|
instantiated, finally the name of the associated source file.
|
24 |
|
|
|
25 |
|
|
The format has five types of lines:
|
26 |
8 |
wfjm |
.
|
27 |
|
|
.\" ----------------------------------------------
|
28 |
23 |
wfjm |
.IP \fBComments\fP 4
|
29 |
|
|
Each line starting with '\fB#\fP' is treated as comment and ignored.
|
30 |
8 |
wfjm |
.
|
31 |
|
|
.\" ----------------------------------------------
|
32 |
23 |
wfjm |
.IP "\fBFile names\fP"
|
33 |
|
|
Either source files or nested \fBvbom\fP's. The file names must be given
|
34 |
|
|
as relative path name from the directory the \fBvbom\fP file is located in.
|
35 |
|
|
Absolute path names are not allowed, nor is expansion of environment variables.
|
36 |
|
|
|
37 |
36 |
wfjm |
Currently the following file types are accepted:
|
38 |
23 |
wfjm |
.RS
|
39 |
|
|
.IP "\fB.vbom\fP" 6
|
40 |
|
|
refers to a nested \fBvbom\fP. Usually used for instantiated components.
|
41 |
8 |
wfjm |
.
|
42 |
23 |
wfjm |
.IP "\fB.vhd\fP"
|
43 |
|
|
refers to a source file. Usually used for libraries refered to in 'use'
|
44 |
|
|
clauses, and as last file, the source file of the entity which is
|
45 |
|
|
described by this \fBvbom\fP file.
|
46 |
|
|
.
|
47 |
35 |
wfjm |
.TP
|
48 |
|
|
.B "\fB.v\fP"
|
49 |
|
|
.TQ
|
50 |
|
|
.B "\fB.sv\fP"
|
51 |
|
|
refers to a verilog or system-verilog source file. Accepted by the vivado
|
52 |
|
|
xsim simulator. Typically used for DPI wrappers or simprim based models
|
53 |
|
|
in vivado.
|
54 |
|
|
.
|
55 |
23 |
wfjm |
.IP "\fB.c\fP"
|
56 |
|
|
refers to the C source which implements a \fIvhdl\fP function or procedure
|
57 |
|
|
via the \fIvhpi\fP mechanism. Supported only in conjunction with \fBghdl\fP.
|
58 |
|
|
.
|
59 |
|
|
.RE
|
60 |
|
|
.
|
61 |
36 |
wfjm |
.\" ----------------------------------------------
|
62 |
|
|
.IP "\fBFile attributes\fP"
|
63 |
|
|
File names can be followed by a list of attributes of the form
|
64 |
|
|
.EX
|
65 |
|
|
-\fIname\fP[:\fIvalue\fP] ...
|
66 |
|
|
.EE
|
67 |
|
|
Currently the following attributes are recognized
|
68 |
|
|
.RS
|
69 |
|
|
.IP "\fB-UUT\fP" 6
|
70 |
|
|
Signals that the \fIvbom\fP descibes a test bench and that file is
|
71 |
|
|
the 'unit under test'. This allows to split the sources into a simulation
|
72 |
|
|
only test bench part and a synthesizable 'unit under test' part. The file
|
73 |
|
|
is typically a \fIvbom\fP in case of a behavioural simulation or the file
|
74 |
|
|
name of a generated model for a functional or timing simulation.
|
75 |
23 |
wfjm |
.
|
76 |
36 |
wfjm |
.IP "\fB-SCOPE_REF[:\fIentity\fP]\fP" 6
|
77 |
|
|
Signals that the xdc file should be 'scoped to reference' to \fIentity\fP.
|
78 |
|
|
If \fIentity\fP is omitted the filename is taken as entity name.
|
79 |
|
|
In general used together with the \fB@xdc:\fP directive.
|
80 |
|
|
.
|
81 |
|
|
.RE
|
82 |
|
|
.
|
83 |
8 |
wfjm |
.\" ----------------------------------------------
|
84 |
23 |
wfjm |
.IP "\fBConditional file names\fP"
|
85 |
|
|
File names can be preceeded by a condition prefix of the form
|
86 |
|
|
|
87 |
|
|
.EX
|
88 |
|
|
[\fItag\fP]filename
|
89 |
|
|
[\fItag\fP,\fItag\fP,...]filename
|
90 |
|
|
.EE
|
91 |
|
|
|
92 |
|
|
The main purpose of this mechanism is to handle libraries and components
|
93 |
|
|
which are only refered in
|
94 |
|
|
.EX
|
95 |
|
|
-- synthesis translate_off
|
96 |
|
|
-- synthesis translate_on
|
97 |
|
|
.EE
|
98 |
|
|
sections and are used only for simulation.
|
99 |
|
|
|
100 |
|
|
Currently supported \fItag\fP names are
|
101 |
|
|
.RS
|
102 |
|
|
.RS 3
|
103 |
|
|
.PD 0
|
104 |
29 |
wfjm |
.IP "\fBghdl\fP" 6
|
105 |
|
|
included in conjunction with ghdl simulation
|
106 |
35 |
wfjm |
.IP "\fBviv\fP" 6
|
107 |
|
|
included in conjunction with Vivado targets
|
108 |
|
|
.IP "\fBvsyn\fP" 6
|
109 |
|
|
included in conjunction with Vivado synthesis
|
110 |
|
|
.IP "\fBvsim\fP" 6
|
111 |
|
|
included in conjunction with Vivado simulation
|
112 |
|
|
.IP "\fBise\fP" 6
|
113 |
|
|
included in conjunction with ISE targets
|
114 |
23 |
wfjm |
.IP "\fBxst\fP" 6
|
115 |
29 |
wfjm |
included in conjunction with ISE xst synthesis
|
116 |
|
|
.IP "\fBisim\fP" 6
|
117 |
|
|
included in conjunction with ISE ISim simulation
|
118 |
|
|
.IP "\fBsim\fP" 6
|
119 |
|
|
included in conjunction with simulation (ghdl,isim,vsim)
|
120 |
23 |
wfjm |
.PD
|
121 |
|
|
.RE
|
122 |
|
|
.RE
|
123 |
|
|
.
|
124 |
|
|
.\" ----------------------------------------------
|
125 |
|
|
.IP "\fBLogical names\fP"
|
126 |
8 |
wfjm |
A logical name can be defined with
|
127 |
|
|
.EX
|
128 |
36 |
wfjm |
\fIlname\fP = \fIfilename\fP
|
129 |
8 |
wfjm |
.EE
|
130 |
|
|
The first definition of a logical name encountered in the traversal of the
|
131 |
23 |
wfjm |
\fBvbom\fP's by \fBvbomconv\fP(1) is taken, all later definitions are ignored.
|
132 |
8 |
wfjm |
|
133 |
|
|
A logical name can be used with
|
134 |
|
|
.EX
|
135 |
36 |
wfjm |
${\fIlname\fP}
|
136 |
|
|
${\fIlname\fP := \fIdefault\fP}
|
137 |
8 |
wfjm |
.EE
|
138 |
36 |
wfjm |
In the first form \fIlname\fP must have been defined before.
|
139 |
|
|
The second form allows to specify a \fIdefault\fP which is used when
|
140 |
|
|
\fIlname\fP hasn't been defined so far.
|
141 |
8 |
wfjm |
|
142 |
36 |
wfjm |
Again, the filenames must be given as relative path name from the directory
|
143 |
|
|
the \fBvbom\fP file is located in.
|
144 |
8 |
wfjm |
|
145 |
|
|
.\" ----------------------------------------------
|
146 |
23 |
wfjm |
.IP \fBDirectives\fP
|
147 |
|
|
Directives start with a '\fB@\fP', currently implemented are:
|
148 |
|
|
.RS
|
149 |
|
|
.IP "\fB@top\fP:\fIname\fP" 4
|
150 |
|
|
Specifies the top level design name. Mainly used when it is different
|
151 |
|
|
from the stem of the \fBvbom\fP file name.
|
152 |
8 |
wfjm |
.
|
153 |
23 |
wfjm |
.IP "\fB@lib\fP:\fIname\fP"
|
154 |
|
|
Specifies an additional system library. Allowed values for \fIname\fP are
|
155 |
29 |
wfjm |
\fIunisim\fP, \fIunimacro\fP and \fIsimprim\fP.
|
156 |
|
|
Currently used to generate the appropriate -L options for \fBghdl\fP commands,
|
157 |
|
|
e.g. generated by the \fBvbomconv\fP action \fB\-\-ghdl_m\fP.
|
158 |
23 |
wfjm |
.
|
159 |
29 |
wfjm |
.IP "\fB@xdc\fP:\fIfile\fP"
|
160 |
|
|
Specifies that \fIfile\fP is a constraint file for Vivado synthesis and should
|
161 |
|
|
be included in the constraints fileset.
|
162 |
35 |
wfjm |
.
|
163 |
|
|
.IP "\fB@ucf_cpp\fP:\fIfile\fP"
|
164 |
|
|
Specifies that a \fIfile\fP.ucf file is to be generated by \fBcpp\fP(1)
|
165 |
|
|
from a \fIfile\fP.ucf_cpp source file. This allows to modularize ISE ucf files.
|
166 |
23 |
wfjm |
.RE
|
167 |
|
|
.
|
168 |
8 |
wfjm |
.\" ------------------------------------------------------------------
|
169 |
|
|
.SH EXAMPLES
|
170 |
23 |
wfjm |
.SS Simple entity
|
171 |
|
|
A simple vhdl entity named \fIbp_2l4l\fP which is defined in the source
|
172 |
|
|
file \fIbp_2l4l.vhd\fP, which uses the library \fIslvtypes\fP and
|
173 |
|
|
instantiates \fIbp_2line\fP and \fIbp_4line\fP, might have a
|
174 |
|
|
\fIbp_2l4l.vbom\fP like
|
175 |
|
|
.PP
|
176 |
|
|
.EX
|
177 |
|
|
# libs
|
178 |
|
|
../../vlib/slvtypes.vhd
|
179 |
|
|
# components
|
180 |
|
|
bp_2line.vbom
|
181 |
|
|
bp_4line.vbom
|
182 |
|
|
# design
|
183 |
|
|
bp_2l4l.vhd
|
184 |
|
|
.EE
|
185 |
|
|
.PP
|
186 |
|
|
Note that the vhdl source file \fIbp_2l4l.vhd\fP is always given in the
|
187 |
|
|
\fBvbom\fP file which describes this source file.
|
188 |
|
|
The comments are put in by convention to help the human reader and
|
189 |
|
|
are not interpreted by \fBvbomconv\fP.
|
190 |
8 |
wfjm |
.
|
191 |
|
|
.\" ------------------------------------------------------------------
|
192 |
|
|
.SH "SEE ALSO"
|
193 |
23 |
wfjm |
.BR vbomconv (1),
|
194 |
|
|
.BR ghdl (1),
|
195 |
|
|
.BR cpp (1)
|
196 |
8 |
wfjm |
.
|
197 |
|
|
.\" ------------------------------------------------------------------
|
198 |
|
|
.SH AUTHOR
|
199 |
|
|
Walter F.J. Mueller
|