1 |
8 |
wfjm |
.\" -*- nroff -*-
|
2 |
23 |
wfjm |
.\" $Id: vbom.5 558 2014-06-01 22:20:51Z mueller $
|
3 |
8 |
wfjm |
.\"
|
4 |
23 |
wfjm |
.\" Copyright 2010-2013 by Walter F.J. Mueller
|
5 |
8 |
wfjm |
.\"
|
6 |
|
|
.\" ------------------------------------------------------------------
|
7 |
|
|
.
|
8 |
23 |
wfjm |
.TH VBOM 2013-10-20 "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 |
|
|
Currently three file types are accepted:
|
38 |
|
|
.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 |
|
|
.IP "\fB.c\fP"
|
48 |
|
|
refers to the C source which implements a \fIvhdl\fP function or procedure
|
49 |
|
|
via the \fIvhpi\fP mechanism. Supported only in conjunction with \fBghdl\fP.
|
50 |
|
|
.
|
51 |
|
|
.RE
|
52 |
|
|
.
|
53 |
|
|
.
|
54 |
8 |
wfjm |
.\" ----------------------------------------------
|
55 |
23 |
wfjm |
.IP "\fBConditional file names\fP"
|
56 |
|
|
File names can be preceeded by a condition prefix of the form
|
57 |
|
|
|
58 |
|
|
.EX
|
59 |
|
|
[\fItag\fP]filename
|
60 |
|
|
[\fItag\fP,\fItag\fP,...]filename
|
61 |
|
|
.EE
|
62 |
|
|
|
63 |
|
|
The main purpose of this mechanism is to handle libraries and components
|
64 |
|
|
which are only refered in
|
65 |
|
|
.EX
|
66 |
|
|
-- synthesis translate_off
|
67 |
|
|
-- synthesis translate_on
|
68 |
|
|
.EE
|
69 |
|
|
sections and are used only for simulation.
|
70 |
|
|
|
71 |
|
|
Currently supported \fItag\fP names are
|
72 |
|
|
.RS
|
73 |
|
|
.RS 3
|
74 |
|
|
.PD 0
|
75 |
|
|
.IP "\fBxst\fP" 6
|
76 |
|
|
included in conjunction with xst synthesis
|
77 |
|
|
.IP "\fBghdl\fP"
|
78 |
|
|
included in conjunction with ghdl simulation
|
79 |
|
|
.IP "\fBisim\fP"
|
80 |
|
|
included in conjunction with isim simulation
|
81 |
|
|
.IP "\fBsim\fP"
|
82 |
|
|
included in conjunction with simulation (ghdl or isim)
|
83 |
|
|
.PD
|
84 |
|
|
.RE
|
85 |
|
|
.RE
|
86 |
|
|
.
|
87 |
|
|
.\" ----------------------------------------------
|
88 |
|
|
.IP "\fBLogical names\fP"
|
89 |
8 |
wfjm |
A logical name can be defined with
|
90 |
|
|
.EX
|
91 |
|
|
=
|
92 |
|
|
.EE
|
93 |
|
|
The first definition of a logical name encountered in the traversal of the
|
94 |
23 |
wfjm |
\fBvbom\fP's by \fBvbomconv\fP(1) is taken, all later definitions are ignored.
|
95 |
8 |
wfjm |
|
96 |
|
|
A logical name can be used with
|
97 |
|
|
.EX
|
98 |
|
|
:
|
99 |
|
|
.EE
|
100 |
23 |
wfjm |
The filename in the usage clause is the default used in case the
|
101 |
|
|
logical name wasn't defined before it is used.
|
102 |
8 |
wfjm |
|
103 |
22 |
wfjm |
Again, the filenames, either of type \fI.vhd\fP or \fI.vbom\fP ,
|
104 |
23 |
wfjm |
must be given as relative path name from the directory the \fBvbom\fP
|
105 |
8 |
wfjm |
file is located in.
|
106 |
|
|
|
107 |
|
|
.\" ----------------------------------------------
|
108 |
23 |
wfjm |
.IP \fBDirectives\fP
|
109 |
|
|
Directives start with a '\fB@\fP', currently implemented are:
|
110 |
|
|
.RS
|
111 |
|
|
.IP "\fB@top\fP:\fIname\fP" 4
|
112 |
|
|
Specifies the top level design name. Mainly used when it is different
|
113 |
|
|
from the stem of the \fBvbom\fP file name.
|
114 |
8 |
wfjm |
.
|
115 |
23 |
wfjm |
.IP "\fB@lib\fP:\fIname\fP"
|
116 |
|
|
Specifies an additional system library. Allowed values for \fIname\fP are
|
117 |
|
|
\fIunisim\fP and \fIsimprim\fP. Currently used to generate the appropriate
|
118 |
|
|
-L options for \fBghdl\fP commands, e.g. generated by the
|
119 |
|
|
\fBvbomconv\fP action \fB\-\-ghdl_m\fP.
|
120 |
|
|
.
|
121 |
|
|
.IP "\fB@ucf_cpp\fP:\fIfile\fP"
|
122 |
|
|
Specifies that a \fIfile\fP.ucf file is to be generated by \fBcpp\fP(1)
|
123 |
|
|
from a \fIfile\fP.ucf_cpp source file. This allows to modularize ISE ucf files.
|
124 |
|
|
.RE
|
125 |
|
|
.
|
126 |
8 |
wfjm |
.\" ------------------------------------------------------------------
|
127 |
|
|
.SH EXAMPLES
|
128 |
23 |
wfjm |
.SS Simple entity
|
129 |
|
|
A simple vhdl entity named \fIbp_2l4l\fP which is defined in the source
|
130 |
|
|
file \fIbp_2l4l.vhd\fP, which uses the library \fIslvtypes\fP and
|
131 |
|
|
instantiates \fIbp_2line\fP and \fIbp_4line\fP, might have a
|
132 |
|
|
\fIbp_2l4l.vbom\fP like
|
133 |
|
|
.PP
|
134 |
|
|
.EX
|
135 |
|
|
# libs
|
136 |
|
|
../../vlib/slvtypes.vhd
|
137 |
|
|
# components
|
138 |
|
|
bp_2line.vbom
|
139 |
|
|
bp_4line.vbom
|
140 |
|
|
# design
|
141 |
|
|
bp_2l4l.vhd
|
142 |
|
|
.EE
|
143 |
|
|
.PP
|
144 |
|
|
Note that the vhdl source file \fIbp_2l4l.vhd\fP is always given in the
|
145 |
|
|
\fBvbom\fP file which describes this source file.
|
146 |
|
|
The comments are put in by convention to help the human reader and
|
147 |
|
|
are not interpreted by \fBvbomconv\fP.
|
148 |
8 |
wfjm |
.
|
149 |
|
|
.\" ------------------------------------------------------------------
|
150 |
|
|
.SH "SEE ALSO"
|
151 |
23 |
wfjm |
.BR vbomconv (1),
|
152 |
|
|
.BR ghdl (1),
|
153 |
|
|
.BR cpp (1)
|
154 |
8 |
wfjm |
.
|
155 |
|
|
.\" ------------------------------------------------------------------
|
156 |
|
|
.SH AUTHOR
|
157 |
|
|
Walter F.J. Mueller
|