mirror of
https://github.com/wfjm/w11.git
synced 2026-02-11 02:50:25 +00:00
209 lines
6.9 KiB
Groff
209 lines
6.9 KiB
Groff
.\" -*- nroff -*-
|
|
.\" $Id: vbom.5 1237 2022-05-15 07:51:47Z mueller $
|
|
.\" SPDX-License-Identifier: GPL-3.0-or-later
|
|
.\" Copyright 2010-2022 by Walter F.J. Mueller <W.F.J.Mueller@gsi.de>
|
|
.\"
|
|
.\" ------------------------------------------------------------------
|
|
.
|
|
.TH VBOM 5 2018-11-09 "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 the case of libraries
|
|
or via other \fBvbom\fP's in the 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, 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:
|
|
.
|
|
.\" ----------------------------------------------
|
|
.IP \fBComments\fP 4
|
|
Each line starting with '\fB#\fP' is treated as a comment and ignored.
|
|
.
|
|
.\" ----------------------------------------------
|
|
.IP "\fBFile names\fP"
|
|
Either source files or nested \fBvbom\fP's. The file names must be given
|
|
as relative path names from the directory the \fBvbom\fP file is located in.
|
|
Absolute path names are not allowed, nor is an 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 referred to in 'use'
|
|
clauses, and as the 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 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.
|
|
.
|
|
.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 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 \fIvbom\fP in case of a behavioral 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 the entity name.
|
|
In general used together with the \fB@xdc:\fP directive.
|
|
.
|
|
.RE
|
|
.
|
|
.\" ----------------------------------------------
|
|
.IP "\fBConditional file names\fP"
|
|
File names can be preceded 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 referred 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, and 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 specifying a \fIdefault\fP which is used when
|
|
\fIlname\fP hasn't been defined so far.
|
|
|
|
Again, the filenames must be given as relative path names 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@tcl\fP:\fIfile\fP"
|
|
specifies that \fIfile\fP is a Tcl script to be executed when building
|
|
the Vivado project. The Tcl script generated by the \fBvbomconv\fP action
|
|
\fB\-\-vsyn_prj\fP will contain statements with source \fIfile\fP.
|
|
.
|
|
.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 modularizing 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>
|