149 lines
5.1 KiB
Plaintext
149 lines
5.1 KiB
Plaintext
|
|
Copyright (c) 1999 Stephen Williams (steve@icarus.com)
|
|
|
|
This source code is free software; you can redistribute it
|
|
and/or modify it in source code form under the terms of the GNU
|
|
General Public License as published by the Free Software
|
|
Foundation; either version 2 of the License, or (at your option)
|
|
any later version.
|
|
|
|
This program is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
GNU General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with this program; if not, write to the Free Software
|
|
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
|
|
|
|
|
|
THE IVL PREPROCESSOR
|
|
|
|
The ivlpp command is a Verilog preprocessor that handles file
|
|
inclusion and macro substitution. The program runs separate from the
|
|
actual compiler so as to ease the task of the compiler proper, and
|
|
provides a means of preprocessing files off-line.
|
|
|
|
|
|
USAGE:
|
|
|
|
ivlpp [options] <file>
|
|
|
|
The <file> parameter is the name of the file to be read and
|
|
preprocessed. The resulting output is sent to standard output. The
|
|
valid options include:
|
|
|
|
-Dname[=value]
|
|
Predefine the symbol ``name'' to have the specified
|
|
value. If the value is not specified, then ``1'' is
|
|
used. This is mostly of use for controlling conditional
|
|
compilation.
|
|
|
|
This option does *not* override existing `define
|
|
directives in the source file.
|
|
|
|
-F <path>
|
|
Read ivlpp options from a FLAGS FILE. This is not the same
|
|
as a file list. This file contains flags, not source
|
|
files. There may be multiple flags files.
|
|
|
|
-f <path>
|
|
Read ivlpp input files from a file list. There can be no
|
|
more than one file list.
|
|
|
|
-I <dir>
|
|
Add a directory to the include path. Normally, only "." is
|
|
in the search path. The -I flag causes other directories
|
|
to be searched for a named file. There may be as many -I
|
|
flags as needed.
|
|
|
|
-L
|
|
Generate `line directives. The ivl compiler understands
|
|
these directives and uses them to keep track of the
|
|
current line of the original source file. This makes error
|
|
messages more meaningful.
|
|
|
|
-o <file>
|
|
Send the output to the named file, instead of to standard
|
|
output.
|
|
|
|
-v
|
|
Print version and copyright information before processing
|
|
input files.
|
|
|
|
-V
|
|
Print version and copyright information, then exit WITHOUT
|
|
processing any input files.
|
|
|
|
FLAGS FILE
|
|
|
|
A flags file contains flags for use by ivlpp. This is a convenient way
|
|
for programs to pass complex sets of flags to the ivlpp program.
|
|
|
|
Blank lines and lines that start with "#" are ignored. The latter can
|
|
be used as comment lines. All other lines are flag lines. Leading and
|
|
trailing white space are removed before the lines are interpreted.
|
|
|
|
Other lines have the simple format:
|
|
|
|
<key>:<value>
|
|
|
|
The colon character separates a key from the value. The supported
|
|
keys, with their corresponding values, are:
|
|
|
|
D:name=<value>
|
|
This is exactly the same as the "-Dname=<value>" described above.
|
|
|
|
I:<dir>
|
|
This is exactly the same as "-I<dir>".
|
|
|
|
relative include:<flag>
|
|
The <flag> can be "true" or "false". This enables "relative
|
|
includes" nesting behavior.
|
|
|
|
vhdlpp:<path>
|
|
Give the path to the vhdlpp program. This program is used to
|
|
process VHDL input files.
|
|
|
|
LOCATING INCLUDED FILES
|
|
|
|
The ivlpp preprocessor implements the `include directives by
|
|
substituting the contents of the included file in place of the line
|
|
with the `include directive. The name that the programmer specifies is
|
|
a file name. Normally, the preprocessor looks in the current working
|
|
directory for the named file. However, the ``-I'' flags can be used to
|
|
specify a path of directories to search for named include files. The
|
|
current directory will be searched first, followed by all the include
|
|
directories in the order that the -I flag appears.
|
|
|
|
The exception to this process is include files that have a name that
|
|
starts with the '/' character. These file names are ``rooted names''
|
|
and must be in the rooted location specified.
|
|
|
|
|
|
GENERATED LINE DIRECTIVES
|
|
|
|
Compilers generally try to print along with their error messages the
|
|
file and line number where the error occurred. Icarus Verilog is no
|
|
exception. However, if a separate preprocessor is actually selecting
|
|
and opening files, then the line numbers counted by the compiler
|
|
proper will not reflect the actual line numbers in the source file.
|
|
|
|
To handle this situation, the preprocessor can generate line
|
|
directives. These directives are lines of the form:
|
|
|
|
`line <num> <name> <level>
|
|
|
|
where <name> is the file name in double-quotes and <num> is the line
|
|
number in the file. The parser changes the filename and line number
|
|
counters in such a way that the next line is line number <num> in
|
|
the file named <name>. For example:
|
|
|
|
`line 6 "foo.vl" 0
|
|
// I am on line 6 in file foo.vl.
|
|
|
|
The preprocessor generates a `line directive every time it switches
|
|
files. That includes starting an included file (`line 1 "foo.vlh" 1) or
|
|
returning to the including file.
|
|
|