luke
/
iverilog
mirror of https://github.com/steveicarus/iverilog.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #679 from steveicarus/steveicarus/more-documentation 

Documentation: Transferring more content from the wiki
This commit is contained in:
Stephen Williams 2022-04-12 17:52:13 -07:00 committed by GitHub
parent 6b5d7a3695 2781aa05e1
commit 27b09f5d72
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 1435 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Documentation/targets/index.rst
View File

@ -13,4 +13,6 @@ Icarus Verilog. The code generator is selected by the "-t" command line flag.
vvp vvp
stub stub
null null
vhdl
verilog95
pcb

61
Documentation/targets/pcb.rst Normal file
View File

@ -0,0 +1,61 @@
Using the PCB code generator
============================
The PCB target code generator is designed to allow a user to enter a netlist
in Verilog format, then generate input files for the GNU PCB layout program.
Invocation
----------
The PCB target code generation is invoked with the -tpcb flag to the iverilog
command. The default output file, "a.out", contains the generated .PCB
file. Use the "-o" flag to set the output file name explicitly. The default
output file contains only the elements. To generate a "netlist" file, add the
flag "-pnetlist=<path>" command line flag.
Altogether, this example generates the foo.net and foo.pcb files from the
foo.v source file::
% iverilog -tpcb -ofoo.pcb -pnetlist=foo.net foo.v
Flags
-----
* -o <path>
Set the output (pcb) file path
* -pnetlist=path
Write a netlist file to the given path.
Attributes Summary
------------------
Attributes are attached to various constructs using the Verilog "(* *)"
attribute syntax.
* ivl_black_box
Attached to a module declaration or module instantiation, this indicates
that the module is a black box. The code generator will create an element
for black box instances.
Parameters Summary
------------------
Within modules, The PCB code generator uses certain parameters to control
details. Parameters may have defaults, and can be overridden using the usual
Verilog parameter override syntax. Parameters have preferred types.
* description (string, default="")
The "description" is a text string that describes the black box. This string
is written into the description field of the PCB Element.
* value (string, default="")
The "value" is a text tring that describes some value for the black
box. Like the description, the code generator does not interpret this value,
other then to write it to the appropriate field in the PCB Element."

101
Documentation/targets/verilog95.rst Normal file
View File

@ -0,0 +1,101 @@
Using The Verilog '95 Code Generator
====================================
Icarus Verilog contains a code generator to emit 1995 compliant Verilog from
the input Verilog netlist. This allows Icarus Verilog to function as a Verilog
> 1995 to Verilog 1995 translator. The main goal of the project was to convert
@*, ANSI style arguments and other constructs to something allowed in 1995
Verilog.
Invocation
----------
To translate a Verilog program to 1995 compliant Verilog, invoke "iverilog"
with the -tvlog95 flag::
% iverilog -tvlog95 -o my_design_95.v my_design.v
The generated Verilog will be placed in a single file (a.out by default), even
if the input Verilog is spread over multiple files.
Generator Flags
---------------
* -pspacing=N
Set the indent spacing (the default is 2).
* -pallowsigned=1
Allow emitting the various signed constructs as an extension to 1995 Verilog
(off by default).
* -pfileline=1
Emit the original file and line information as a comment for each generated
line (off by default).
Structures that cannot be converted to 1995 compatible Verilog
--------------------------------------------------------------
The following Verilog constructs are not translatable to 1995 compatible Verilog:
* Automatic tasks or functions.
* The power operator (**). Expressions of the form (2**N)**<variable> (where N
is a constant) can be converter to a shift.
* Some System Verilog constructs (e.g. final blocks, ++/-- operators,
etc.). 2-state variables are converted to 4-state variables.
Icarus extensions that cannot be translated:
* Integer constants greater than 32 bits.
* Real valued nets.
* Real modulus.
* Most Verilog-A constructs.
Known Issues and Limitations
----------------------------
Some things are just not finished and should generate an appropriate
warning. Here is a list of the major things that still need to be looked at.
* There are still a few module instantiation port issues (pr1723367 and
partselsynth).
* inout ports are not converted (tran-VP).
* Variable selects of a non-zero based vector in a continuous assignment are
not converted.
* There is no support for translating a zero repeat in a continuous
assignment. It is currently just dropped.
* A pull device connected to a signal select is not translated correctly (this
may be fixed).
* L-value indexed part selects with a constant undefined base in a continuous
assignment are not translated.
* Logic gates are not arrayed exactly the same as the input and the instance
name is not always the same.
* The signed support does not generate $signed() or $unsigned() function calls
in a continuous assignment expression.
* The special power operator cases are not converted in a continuous
assignment.
* Currently a signed constant that sets the MSB in an unsigned context will be
displayed as a negative value (e.g. bit = 1 translates to bit = -1).
* Can net arrays, etc. be unrolled?
* Can generate blocks be converted?

82
Documentation/targets/vhdl.rst Normal file
View File

@ -0,0 +1,82 @@
The VHDL Code Generator (-tvhdl)
================================
Icarus Verilog contains a code generator to emit VHDL from the Verilog
netlist. This allows Icarus Verilog to function as a Verilog to VHDL
translator.
Invocation
----------
To translate a Verilog program to VHDL, invoke "iverilog" with the -tvhdl
flag::
% iverilog -t vhdl -o my_design.vhd my_design.v
The generated VHDL will be placed in a single file (a.out by default), even if
the Verilog is spread over multiple files.
Flags
-----
* -pdebug=1
Print progress messages as the code generator visits each part of the
design.
* -pdepth=N
Only output VHDL entities for modules found at depth < N in the
hierarchy. N=0, the default, outputs all entities. For example, -pdepth=1
outputs only the top-level entity.
Supported Constructs
--------------------
TODO
Limitations
-----------
Signal Values and Resolution
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
There are several cases where the behaviour of the translated VHDL deviates
from the source Verilog:
* The result of division by zero is x in Verilog but raises an exception in
VHDL.
* Similarly, the result of reading past the end of an array in Verilog is x,
whereas VHDL raises an exception.
* Any signal that is driven by two or more processes will have the value
'U'. This is the result of the signal resolution function in the
std_logic_1164 package.
Constructs Not Supported
^^^^^^^^^^^^^^^^^^^^^^^^
The following Verilog constructs cannot be translated to VHDL:
* fork and join
* force and release
* disable
* real-valued variables
* switches
* hierarchical dereferencing
Other Limitations
^^^^^^^^^^^^^^^^^
* The test expressions in case statements must be constant.
* Translation of a parameter to a corresponding VHDL generic
declaration. Instead the default parameter value is used.

198
Documentation/usage/command_files.rst Normal file
View File

@ -0,0 +1,198 @@
Command File Format
===================
The basic format of a command file is one source file or compiler argument per
line. Command files may also have comments of various form, and options for
controlling the compiler.
Comments
--------
Lines that start with a "#" character are comments. All text after the "#"
character, is ignored.
The "//" character sequence also starts a comment that continues to the end of
the line.
The "/\*" and "\*/" character sequences surround multi-line comments. All the
text between the comment start and comment end sequences is ignored, even when
that text spans multiple lines. This style of comment does not nest, so a "/\*"
sequence within a multi-line comment is probably an error.
Plus-args
---------
Outside of comments, lines that start with a "+" character are compiler
arguments. These are called plusargs but they are not the same as extended
arguments passed to the "vvp" command. The supported plusargs are definitively
listed in the iverilog manual page.
The plusargs lines are generally "+<name>+..." where the name is the name of
an switch, and the arguments are separated by "+" characters, as in::
+libext+.v+.V+.ver
With plusargs lines, the "+" character separates tokens, and not white space,
so arguments, which may include file paths, may include spaces. A plusarg line
is terminated by the line end.
The line in the command file may also be a "-y" argument. This works exactly
the same as the::
-y <path>
argument to the compiler; it declares a library directory. The "-y" syntax is
also a shorthand for the "+libdir" plusarg, which is a more general form::
+libdir+<path>...
File Names
----------
Any lines that are not comments, compiler arguments or plusargs are taken by
the compiler to be a source file. The path can contain any characters (other
then comment sequences) including blanks, although leading and trailing white
space characters are stripped. The restriction of one file name per line is in
support of operating systems that can name files any which way. It is not
appropriate to expect white spaces to separate file names.
Variable Substitution
---------------------
The syntax "$(name)" is a variable reference, and may be used anywhere within
filenames or directory names. The contents of the variable are read from the
environment and substituted in place of the variable reference. In Windows,
these environment variables are the very same variables that are set through
the Control Panel->System dialog box, and in UNIX these variables are
environment variables as exported by your shell.
Variables are useful for giving command files some installation
independence. For example, one can import a vendor library with the line::
-y $(VENDOR)/verilog/library
in the command file, and the next programmer will be able to use this command
file without editing it to point to the location of VENDOR on his
machine. Note the use of forward slashes as a directory separator. This works
even under Windows, so always use forward slashes in file paths and Windows
and UNIX users will be able to share command files.
An Example
----------
This sample::
# This is a comment in a command file.
# The -y statement declares a library
# search directory
-y $(PROJ_LIBRARY)/prims
#
# This plusarg tells the compiler that
# files in libraries may have .v or .vl
# extensions.
+libext+.v+.vl
#
main.v // This is a source file
#
# This is a file name with blanks.
C:/Project Directory/file name.vl
is a command file that demonstrates the major syntactic elements of command
files. It demonstrates the use of comments, variables, plusargs and file
names. It contains a lot of information about the hypothetical project, and
suggests that command files can be used to describe the project as a whole
fairly concisely.
The syntax of command files is rich enough that they can be used to document
and control the assembly and compilation of large Verilog programs. It is not
unusual to have command files that are hundreds of lines long, although
judicious use of libraries can lead to very short command files even for large
designs. It is also practical to have different command files that pull
together combinations of sources and compiler arguments to make different
designs from the same Verilog source files.
Summary
-------
Given the above description of the command file format, the following is a
list of the special records with their meaning.
* +libdir+*dir-path*
Specify directories to be searched for library modules. The *dir-path* can
have multiple directories, separated by "+" characters.
* +libdir-nocase+dir-path
This is the same as "+libdir+", but when searching "nocase" libraries for
module files, case will not be taken as significant. This is useful when the
library is on a case insensitive file system.
* +libext+*suffix-string*
Declare the suffix strings to use when searching library directories for
Verilog files. The compiler may test a list of suffix strings to support a
variety of naming conventions.
* -y dir-path
This is like "+libdir+" but each line takes only one path. Like "+libdir+"
there can be multiple "-y" records to declare multiple library
directories. This is similar to the "-y" flag on the iverilog command line.
* -v *file-name* or -l *file-name*
This declares a library file. A library file is just like any other Verilog
source file, except that modules declared within it are not implicitly
possible root modules.
NOTE: The "-l" alias is new as of 2 October 2016. It will become available
in releases and snapshots made after that date.
* +incdir+*include-dir-path*
Declare a directory or list of directories to search for files included by
the "include" compiler directive. The directories are searched in
order. This is similar to the "-I" flag on the iverilog command line.
* +define+*name=value*
Define the preprocessor symbol "name" to have the string value "value". If
the value (and the "=") are omitted, then it is assumed to be the string
"1". This is similar to the "-D" on the iverilog command line.
* +timescale+*units/precision*
Define the default timescale. This is the timescale that is used if there is
no other timescale directive in the Verilog source. The compiler default
default is "+timescale+1s/1s", which this command file setting can
change. The format of the units/precision is the same as that for the
timescale directive in the verilog source.
* +toupper-filename
This token causes file names after this in the command file to be translated
to uppercase. this helps with situations where a directory has passed
through a DOS machine (or a FAT file system) and in the process the file
names become munged. This is not meant to be used in general, but only in
emergencies.
* +tolower-filename
The is the lowercase version of "+toupper-filename".
* +parameter+*name=value*
This token causes the compiler to override a parameter value for a top-level
module. For example, if the module main has the parameter WIDTH, set the
width like this "+parameter+main.WIDTH=5". Note the use of the complete
hierarchical name. This currently only works for parameters defined in root
(top level) modules and a defparam may override the command file value.
* +vhdl-work+*path*
When compiling VHDL, this token allows control over the directory to use for
holding working package declarations. For example, "+vhdl-work+workdir" will
cause the directory "workdir" to be used as a directory for holding working
working copies of package headers.

5
Documentation/usage/index.rst
View File

@ -8,7 +8,12 @@ Icarus Verilog.
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
installation
getting_started getting_started
simulation
command_line_flags command_line_flags
command_files
verilog_attributes verilog_attributes
vvp_flags vvp_flags
vpi
ivl_target

146
Documentation/usage/installation.rst Normal file
View File

@ -0,0 +1,146 @@
Installation Guide
==================
Icarus Verilog may be installed from source code, or from pre-packaged binary
distributions. If you don't have need for the very latest, and prepackaged
binaries are available, that would be the best place to start.
Installation From Source
------------------------
Icarus is developed for Unix-like environments but can also be compiled on
Windows systems using the Cygwin environment or MinGW compilers. The following
instructions are the common steps for obtaining the Icarus Verilog source,
compiling and installing. Note that there are precompiled and/or prepackaged
versions for a variety of systems, so if you find an appropriate packaged
version, then that is the easiest way to install.
The source code for Icarus is stored under the git source code control
system. You can use git to get the latest development head or the latest of a
specific branch. Stable releases are placed on branches, and in particular v11
stable releases are on the branch "v11-branch" To get the development version
of the code follow these steps::
% git config --global user.name "Your Name Goes Here"
% git config --global user.email you@yourpublicemail.example.com
% git clone https://github.com/steveicarus/iverilog.git
The first two lines are optional and are used to tell git who you are. This
information is important if/when you submit a patch. We suggest that you add
this information now so you don't forget to do it later. The clone will create
a directory, named iverilog, containing the source tree, and will populate
that directory with the most current source from the HEAD of the repository.
Change into this directory using::
% cd iverilog
Normally, this is enough as you are now pointing at the most current
development code, and you have implicitly created a branch "master" that
tracks the development head. However, If you want to actually be working on
the v11-branch (the branch where the latest v11 patches are) then you checkout
that branch with the command::
% git checkout --track -b v11-branch origin/v11-branch
This creates a local branch that tracks the v11-branch in the repository, and
switches you over to your new v11-branch. The tracking is important as it
causes pulls from the repository to re-merge your local branch with the remote
v11-branch. You always work on a local branch, then merge only when you
push/pull from the remote repository.
Now that you've cloned the repository and optionally selected the branch you
want to work on, your local source tree may later be synced up with the
development source by using the git command::
% git pull
The git system remembers the repository that it was cloned from, so you don't
need to re-enter it when you pull.
Finally, configuration files are built by the extra step::
% sh autoconf.sh
The source is then compiled as appropriate for your system. See the specific
build instructions below for your operation system for what to do next.
You will need autoconf and gperf installed in order for the script to work.
If you get errors such as::
Autoconf in root...
autoconf.sh: 10: autoconf: not found
Precompiling lexor_keyword.gperf
autoconf.sh: 13: gperf: not found.
You will need to install download and install the autoconf and gperf tools.
Icarus Specific Configuration Options
-------------------------------------
Icarus takes many of the standard configuration options and those will not be
described here. The following are specific to Icarus::
--enable-suffix[=suffix]
This option allows the user to build Icarus with a default suffix or when
provided a user defined suffix. Older stable releases have this flag on by
default e.g.(V0.8 by default will build with a "-0.8" suffix). All versions
have an appropriate default suffix ("-<base_version>").
All programs or directories are tagged with this suffix. e.g.(iverilog-0.8,
vvp-0.8, etc.). The output of iverilog will reference the correct run time
files and directories. The run time will check that it is running a file with
a compatible version e.g.(you can not run a V0.9 file with the V0.8 run
time). ::
--with-valgrind
This option adds extra memory cleanup code and pool management code to allow
better memory leak checking when valgrind is available. This option is not
need when checking for basic errors with valgrind.
Compiling on Linux/Unix
-----------------------
(Note: You will need to install bison, flex, g++ and gcc) This is probably the
easiest case. Given that you have the source tree from the above instructions,
the compile and install is generally as simple as::
% ./configure
% make
(su to root)
# make install
The "make install" typically needs to be done as root so that it can install
in directories such as "/usr/local/bin" etc. You can change where you want to
install by passing a prefix to the "configure" command::
% ./configure --prefix=/my/special/directory
This will configure the source for eventual installation in the directory that
you specify. Note that "rpm" packages of binaries for Linux are typically
configured with "--prefix=/usr" per the Linux File System Standard.
Make sure you have the latest version of flex otherwise you will get an error
when parsing lexor.lex.
Compiling on Macintosh OS X
---------------------------
Since Mac OS X is a BSD flavor of Unix, you can install Icarus Verilog from
source using the procedure described above. You need to install the Xcode
software, which includes the C and C++ compilers for Mac OS X. The package is
available for free download from Apple's developer site. Once Xcode is
installed, you can build Icarus Verilog in a terminal window just like any
other Unix install.
For versions newer than 10.3 the GNU Bison tool (packaged with Xcode) needs to
be updated to version 3. ::
brew install bison
echo 'export PATH="/usr/local/opt/bison/bin:$PATH"' >> ~/.bash_profile
Icarus Verilog is also available through the Homebrew package manager: "brew
install icarus-verilog".

106
Documentation/usage/ivl_target.rst Normal file
View File

@ -0,0 +1,106 @@
Loadable Target API (ivl_target.h)
==================================
In addition to the standard VPI API, Icarus Verilog supports a non-standard
loadable target module API. This API helps C programmers write modules that
Icarus Verilog can use to generate code. These modules are used at compile
time to write the elaborated design to the simulation or netlist files. For
example, the vvp code generator is a loadable target module that writes vvp
code into the specified file.
Loadable target modules gain access to the 'elaborated' design. That means,
the source files have been checked for syntax and correctness, any synthesis
and general optimization steps have been performed, and what is left is a
design that reflects but is not exactly the same as the input Verilog source
code. This relieves the modules of the burden of supporting all the odd
corners and complexities of the Verilog language.
The Target Module API
---------------------
The API is defined in the header file "ivl_target.h" which is installed with
Icarus Verilog. The header defines the functions that the module writer can
use to get at the elaborated design during the course of writing the output
format.
The target module API function "target_design" is special in that the API does
not provide this function: The target module itself provides it. When the
compiler loads the target module, it invokes the "target_design" function with
a handle to the design. This is the point where the target module takes over
to process the design.
Compiling Target Modules
------------------------
Compiling loadable target modules is similar to compiling VPI modules, in that
the module must be compiled with the "-fPIC" flag to gcc, and linked with the
"-shared" flag. The module that you compile is then installed in a place where
the "iverilog" command can find it, and configuration files are adjusted to
account for the new module.
This code::
# include <ivl_target.h>
int target_design(ivl_design_t des)
{
return 0;
}
is an example module that we can write into the file "empty.c"; and let us
compile it into the module file "empty.tgt" like so::
% gcc -o empty.tgt -fpic -shared empty.c
This makes the "empty.tgt" file an a dynamically loaded shared object.
Creating the Target Config File
-------------------------------
The target config file tells the Icarus Verilog core how to process your new
code generator. The ivl core expects two configuration files: the name.conf
and the name-s.config files. The "-s" version is what is used if the user
gives the "-S" (synthesis) flag on the command line.
The stub target, included in most distributions, demonstrates the config
files. The "stub.conf" file is::
functor:cprop
functor:nodangle
-t:dll
flag:DLL=stub.tgt
and the "stub-s.conf" file is::
functor:synth2
functor:synth
functor:syn-rules
functor:cprop
functor:nodangle
-t:dll
flag:DLL=stub.tgt
Note that the "stub-s.conf" file contains more lines to invoke internal
synthesis functions, whereas the "stub.conf" invokes only the basic
optimization steps.
In general, only the last line (The "flag:DLL=<name>.tgt" record) varies for
each target. For your target, replace the <name> with the name of your target
and you have a configuration file ready to install. Note that this is the name
of your target module. This is in fact how the config file tells the compiler
the name of your module.
The rest of the config file is best taken as boiler plate and installed as is,
with one difference. If your target is a synthesis target (for example a mosis
code generator or a pld code generator) that expects synthesis to happen, then
it makes the most sense to create both your config file like the "stub-s.conf"
config file. This causes the compiler to do synthesis for your target whether
the user gives the "-S" flag or not.
Installing the Target Module
----------------------------
Finally, the "empty.conf", the "empty-s.conf" and the "empty.tgt" files need
to be installed. Where they go depends on your system, but in Linux they are
normally installed in "/usr/lib/ivl".

487
Documentation/usage/simulation.rst Normal file
View File

@ -0,0 +1,487 @@
Simulation Using Icarus Verilog
===============================
Simulation is the process of creating models that mimic the behavior of the
device you are designing (simulation models) and creating models to exercise
the device (test benches). The simulation model need not reflect any
understanding of the underlying technology, and the simulator need not know
that the design is intended for any specific technology.
The Verilog simulator, in fact, is usually a different program than the
synthesizer. It may even come from a different vendor. The simulator need not
know of or generate netlists for the target technology, so it is possible to
write one simulator that can be used to model designs intended for a wide
variety of technologies. A synthesizer, on the other hand, does need to know a
great deal about the target technology in order to generate efficient
netlists. Synthesizers are often technology specific and come from vendors
with specialized knowledge, whereas simulators are more general purpose.
Simulation models and test benches, therefore, can use the full range of
Verilog features to model the intended design as clearly as possible. This is
the time to test the algorithms of the design using language that is
relatively easy for humans to read. The simulator, along with the test bench,
can test that the clearly written model really does behave as intended, and
that the intended behavior really does meet expectations.
The test benches model the world outside the design, so they are rarely
destined for real hardware. They are written in Verilog simply as a matter of
convenience, and sometimes they are not written in Verilog at all. The test
benches are not throw-away code either, as they are used to retest the device
under test as it is transformed from a simulation model to a synthesizeable
description.
Compilation and Elaboration
---------------------------
Simulation of a design amounts to compiling and executing a program. The
Verilog source that represents the simulation model and the test bench is
compiled into an executable form and executed by a simulation
engine. Internally, Icarus Verilog divides the compilation of program source
to an executable form into several steps, and basic understanding of these
steps helps understand the nature of failures and errors. The first step is
macro preprocessing, then compilation, elaboration, optional optimizations and
finally code generation. The boundary between these steps is often blurred,
but this progression remains a useful model of the compilation process.
The macro preprocessing step performs textual substitutions of macros defined
with "\`define" statements, textual inclusion with "\`include" statements, and
conditional compilation by "\`ifdef" and "\`ifndef" statements. The
macropreprocessor for Icarus Verilog is internally a separate program that can
be accessed independently by using the "-E" flag to the "iverilog" command,
like so::
% iverilog -E -o out.v example.v
This command causes the input Verilog file "example.v" to be preprocessed, and
the output, a Verilog file without preprocessor statements, written into
"out.v". The "\`include" and "\`ifdef" directives in the input file are interpreted,
and defined macros substituted, so that the output, a single file, is the same
Verilog but with the preprocessor directives gone. All the explicitly
specified source files are also combined by the preprocessor, so that the
preprocessed result is a single Verilog stream.
Normally, however, the "-E" flag is not used and the preprocessed Verilog is
instead sent directly to the next step, the compiler. The compiler core takes
as input preprocessed Verilog and generates an internal parsed form. The
parsed form is an internal representation of the Verilog source, in a format
convenient for further processing, and is not accessible to the user.
The next step, elaboration, takes the parsed form, chooses the root modules,
and instantiates (makes *instances* of) those roots. The root instances may
contain instances of other modules, which may in turn contain instances of yet
other modules. The elaboration process creates a hierarchy of module instances
that ends with primitive gates and statements.
Note that there is a difference between a module and a module instance. A
module is a type. It is a description of the contents of module instances that
have its type. When a module is instantiated within another module, the module
name identifies the type of the instance, and the instance name identifies the
specific instance of the module. There can be many instances of any given
module.
Root modules are a special case, in that the programmer does not give them
instance names. Instead, the instance names of root modules are the same as
the name of the module. This is valid because, due to the nature of the
Verilog syntax, a module can be a root module only once, so the module name
itself is a safe instance name.
Elaboration creates a hierarchy of scopes. Each module instance creates a new
scope within its parent module, with each root module starting a
hierarchy. Every module instance in the elaborated program has a unique scope
path, a hierarchical name, that starts with its root scope and ends with its
own instance name. Every named object, including variables, parameters, nets
and gates, also has a hierarchical name that starts with a root scope and ends
with its own base name. The compiler uses hierarchical names in error messages
generated during or after elaboration, so that erroneous items can be
completely identified. These hierarchical names are also used by waveform
viewers that display waveform output from simulations.
The elaboration process creates from the parsed form the scope hierarchy
including the primitive objects within each scope. The elaborated design then
is optimized to reduce it to a more optimal, but equivalent design. The
optimization step takes the fully elaborated design and transforms it to an
equivalent design that is smaller or more efficient. These optimizations are,
for example, forms of constant propagation and dead code elimination. Useless
logic is eliminated, and constant expressions are pre-calculated. The
resulting design behaves as if the optimizations were not performed, but is
smaller and more efficient. The elimination (and spontaneous creation) of
gates and statements only affects the programmer when writing VPI modules,
which through the API have limited access to the structures of the design.
Finally, the optimized design, which is still in an internal form not
accessible to users, is passed to a code generator that writes the design into
an executable form. For simulation, the code generator is selected to generate
the vvp format--a text format that can be executed by the simulation
engine. Other code generators may be selected by the Icarus Verilog user, even
third party code generators, but the vvp code generator is the default for
simulation purposes.
Making and Using Libraries
--------------------------
Although simple programs may be written into a single source file, this gets
inconvenient as the designs get larger. Also, writing the entire program into
a single file makes it difficult for different programs to share common
code. It therefore makes sense to divide large programs into several source
files, and to put generally useful source code files somewhere accessible to
multiple designs.
Once the program is divided into many files, the compiler needs to be told how
to find the files of the program. The simplest way to do that is to list the
source files on the command line or in a command file. This is for example the
best way to divide up and integrate test bench code with the simulation model
of the device under test.
The Macro Preprocessor
^^^^^^^^^^^^^^^^^^^^^^
Another technique is to use the macro preprocessor to include library files
into a main file. The `include` directive takes the name of a source file to
include. The preprocessor inserts the entire contents of the included file in
place of the `include` directive. The preprocessor normally looks in the
current working directory (the current working directory of the running
compiler, and not the directory where the source file is located) for the
included file, but the "-I" switch to "iverilog" can add directories to the
search locations list. ::
% iverilog -I/directory/to/search example.v
It is common to create include directories shared by a set of programs. The
preprocessor `include` directive can be used by the individual programs to
include the source files that it needs.
The preprocessor method of placing source code into libraries is general
(arbitrary source code can be placed in the included files) but is static, in
the sense that the programmer must explicitly include the desired library
files. The automatic module library is a bit more constrained, but is
automatic.
Automatic Module Libraries
^^^^^^^^^^^^^^^^^^^^^^^^^^
A common use for libraries is to store module definitions that may be of use
to a variety of programs. If modules are divided into a single module per
file, and the files are named appropriately, and the compiler is told where to
look, then the compiler can automatically locate library files when it finds
that a module definition is missing.
For this to work properly, the library files must be Verilog source, they
should contain a single module definition, and the files must be named after
the module they contain. For example, if the module "AND2" is a module in the
library, then it belongs in a file called "AND2.v" and that file contains only
the "AND2" module. A library, then, is a directory that contains properly
named and formatted source files. ::
% iverilog -y/library/to/search example.v
The "-y" flag to "iverilog" tells the compiler to look in the specified
directory for library modules whenever the program instantiates a module that
is not otherwise defined. The programmer may include several "-y" flags on the
command line (or in a command file) and the compiler will search each
directory in order until an appropriate library file is found to resolve the
module.
Once a module is defined, either in the program or by reading a library
module, the loaded definition is used from then on within the program. If the
module is defined within a program file or within an included file, then the
included definition is used instead of any library definition. If a module is
defined in multiple libraries, then the first definition that the compiler
finds is used, and later definitions are never read.
Icarus Verilog accesses automatic libraries during elaboration, after it has
already preprocessed and parsed the non-library source files. Modules in
libraries are not candidates for root modules, and are not even parsed unless
they are instantiated in other source files. However, a library module may
reference other library modules, and reading in a library module causes it to
be parsed and elaborated, and further library references resolved, just like a
non-library module. The library lookup and resolution process iterates until
all referenced modules are resolved, or known to be missing from the
libraries.
The automatic module library technique is useful for including vendor or
technology libraries into a program. Many EDA vendors offer module libraries
that are formatted appropriately; and with this technique, Icarus Verilog can
use them for simulation.
Advanced Command Files
----------------------
Command files were mentioned in the "Getting Started" chapter, but only
briefly. In practice, Verilog programs quickly grow far beyond the usefulness
of simple command line options, and even the macro preprocessor lacks the
flexibility to combine source and library modules according to the advancing
development process.
The main contents of a command file is a list of Verilog source files. You can
name in a command file all the source files that make up your design. This is
a convenient way to collect together all the files that make up your
design. Compiling the design can then be reduced to a simple command line like
the following::
% iverilog -c example.cf
The command file describes a configuration. That is, it lists the specific
files that make up your design. It is reasonable, during the course of
development, to have a set of different but similar variations of your
design. These variations may have different source files but also many common
source files. A command file can be written for each variation, and each
command file lists the source file names used by each variation.
A configuration may also specify the use of libraries. For example, different
configurations may be implementations for different technologies so may use
different parts libraries. To make this work, command files may include "-y"
statements. These work in command files exactly how they work on "iverilog"
command line. Each "-y" flag is followed by a directory name, and the
directories are searched for library modules in the order that they are listed
in the command file.
The include search path can also be specified in configuration files with
"+incdir+" tokens. These tokens start with the "+incdir+" string, then
continue with directory paths, separated from each other with "+" characters
(not spaces) for the length of the line.
Other information can be included in the command file. See the section Command
File Format for complete details on what can go in a command file.
Input Data at Runtime
---------------------
Often, it is useful to compile a program into an executable simulation, then
run the simulation with various inputs. This requires some means to pass data
and arguments to the compiled program each time it is executed. For example,
if the design models a micro-controller, one would like to run the compiled
simulation against a variety of different ROM images.
There are a variety of ways for a Verilog program to get data from the outside
world into the program at run time. Arguments can be entered on the command
line, and larger amounts of data can be read from files. The simplest method
is to take arguments from the command line.
Consider this running example of a square root calculator::
module sqrt32(clk, rdy, reset, x, .y(acc));
input clk;
output rdy;
input reset;
input [31:0] x;
output [15:0] acc;
// acc holds the accumulated result, and acc2 is
// the accumulated square of the accumulated result.
reg [15:0] acc;
reg [31:0] acc2;
// Keep track of which bit I'm working on.
reg [4:0] bitl;
wire [15:0] bit = 1 << bitl;
wire [31:0] bit2 = 1 << (bitl << 1);
// The output is ready when the bitl counter underflows.
wire rdy = bitl[4];
// guess holds the potential next values for acc,
// and guess2 holds the square of that guess.
wire [15:0] guess = acc | bit;
wire [31:0] guess2 = acc2 + bit2 + ((acc << bitl) << 1);
task clear;
begin
acc = 0;
acc2 = 0;
bitl = 15;
end
endtask
initial clear;
always @(reset or posedge clk)
if (reset)
clear;
else begin
if (guess2 <= x) begin
acc <= guess;
acc2 <= guess2;
end
bitl <= bitl - 1;
end
endmodule
One could write the test bench as a program that passes a representative set
of input values into the device and checks the output result. However, we can
also write a program that takes on the command line an integer value to be
used as input to the device. We can write and compile this program, then pass
different input values on the run time command line without recompiling the
simulation.
This example demonstrates the use of the "$value$plusargs" to access command
line arguments of a simulation::
module main;
reg clk, reset;
reg [31:0] x;
wire [15:0] y;
wire rdy;
sqrt32 dut (clk, rdy, reset, x, y);
always #10 clk = ~clk;
initial begin
clk = 0;
reset = 1;
if (! $value$plusargs("x=%d", x)) begin
$display("ERROR: please specify +x=<value> to start.");
$finish;
end
#35 reset = 0;
wait (rdy) $display("y=%d", y);
$finish;
end // initial begin
endmodule // main
The "$value$plusargs" system function takes a string pattern that describes
the format of the command line argument, and a reference to a variable that
receives the value. The "sqrt_plusargs" program can be compiled and executed
like this::
% iverilog -osqrt_plusargs.vvp sqrt_plusargs.v sqrt.v
% vvp sqrt_plusargs.vvp +x=81
y= 9
Notice that the "x=%d" string of the "$value$plusargs" function describes the
format of the argument. The "%d" matches a decimal value, which in the sample
run is "81". This gets assigned to "x" by the "$value$plusargs" function,
which returns TRUE, and the simulation continues from there.
If two arguments have to be passed to the testbench then the main module would
be modified as follows::
module main;
reg clk, reset;
reg [31:0] x;
reg [31:0] z;
wire [15:0] y1,y2;
wire rdy1,rdy2;
sqrt32 dut1 (clk, rdy1, reset, x, y1);
sqrt32 dut2 (clk, rdy2, reset, z, y2);
always #10 clk = ~clk;
initial begin
clk = 0;
reset = 1;
if (! $value$plusargs("x=%d", x)) begin
$display("ERROR: please specify +x=<value> to start.");
$finish;
end
if (! $value$plusargs("z=%d", z)) begin
$display("ERROR: please specify +z=<value> to start.");
$finish;
end
#35 reset = 0;
wait (rdy1) $display("y1=%d", y1);
wait (rdy2) $display("y2=%d", y2);
$finish;
end // initial begin
endmodule // main
and the "sqrt_plusargs" program would be compiled and executed as follows::
% iverilog -osqrt_plusargs.vvp sqrt_plusargs.v sqrt.v
% vvp sqrt_plusargs.vvp +x=81 +z=64
y1= 9
y2= 8
In general, the "vvp" command that executes the compiled simulation takes a
few predefined argument flags, then the file name of the simulation. All the
arguments after the simulation file name are extended arguments to "vvp" and
are passed to the executed design. Extended arguments that start with a "+"
character are accessible through the "$test$plusargs" and "$value$plusargs"
system functions. Extended arguments that do not start with a "+" character
are only accessible to system tasks and functions written in C using the VPI.
In the previous example, the program pulls the argument from the command line,
assigns it to the variable "x", and runs the sqrt device under test with that
value. This program can take the integer square root of any single value. Of
course, if you wish to test with a large number of input values, executing the
program many times may become tedious.
Another technique would be to put a set of input values into a data file, and
write the test bench to read the file. We can then edit the file to add new
input values, then rerun the simulation without compiling it again. The
advantage of this technique is that we can accumulate a large set of test
input values, and run the lot as a batch.
This example::
module main;
reg clk, reset;
reg [31:0] data[4:0];
reg [31:0] x;
wire [15:0] y;
wire rdy;
sqrt32 dut (clk, rdy, reset, x, y);
always #10 clk = ~clk;
integer i;
initial begin
/* Load the data set from the hex file. */
$readmemh("sqrt.hex", data);
for (i = 0 ; i <= 4 ; i = i + 1) begin
clk = 0;
reset = 1;
x = data[i];
#35 reset = 0;
wait (rdy) $display("y=%d", y);
end
$finish;
end // initial begin
endmodule // main
demonstrates the use of "$readmemh" to read data samples from a file into a
Verilog array. Start by putting into the file "sqrt.hex" the numbers::
51
19
1a
18
1
Then run the simulation with the command sequence::
% iverilog -osqrt_readmem.vvp sqrt_readmem.vl sqrt.vl
% vvp sqrt_readmem.vvp
y= 9
y= 5
y= 5
y= 4
y= 1
It is easy enough to change this program to work with larger data sets, or to
change the "data.hex" file to contain different data. This technique is also
common for simulating algorithms that take in larger data sets. One can extend
this idea slightly by using a "$value$plusargs" statement to select the file
to read.

246
Documentation/usage/vpi.rst Normal file
View File

@ -0,0 +1,246 @@
Using VPI
=========
Icarus Verilog implements a portion of the PLI 2.0 API to Verilog. This allows
programmers to write C code that interfaces with Verilog simulations to
perform tasks otherwise impractical with straight Verilog. Many Verilog
designers, especially those who only use Verilog as a synthesis tool, can
safely ignore the entire matter of the PLI (and this chapter) but the designer
who wishes to interface a simulation with the outside world cannot escape VPI.
The rest of this article assumes some knowledge of C programming, Verilog PLI,
and of the compiler on your system. In most cases, Icarus Verilog assumes the
GNU Compilation System is the compiler you are using, so tips and instructions
that follow reflect that. If you are not a C programmer, or are not planning
any VPI modules, you can skip this entire article. There are references at the
bottom for information about more general topics.
How It Works
------------
The VPI modules are compiled loadable object code that the runtime loads at
the user's request. The user commands vvp to locate and load modules with the
"-m" switch. For example, to load the "sample.vpi" module::
% vvp -msample foo.vvp
The vvp run-time loads the modules first, before executing any of the
simulation, or even before compiling the vvp code. Part of the loading
includes invoking initialization routines. These routines register with the
run-time all the system tasks and functions that the module implements. Once
this is done, the run time loader can match names of the called system tasks
of the design with the implementations in the VPI modules.
(There is a special module, the system.vpi module, that is always loaded to
provide the core system tasks.)
The simulator run time (The "vvp" program) gets a handle on a freshly loaded
module by looking for the symbol "vlog_startup_routines" in the loaded
module. This table, provided by the module author and compiled into the
module, is a null terminated table of function pointers. The simulator calls
each of the functions in the table in order. The following simple C definition
defines a sample table::
void (*vlog_startup_routines[])() = {
hello_register,
0
};
Note that the "vlog_startup_routines" table is an array of function pointers,
with the last pointer a 0 to mark the end. The programmer can organize the
module to include many startup functions in this table, if desired.
The job of the startup functions that are collected in the startup table is to
declare the system tasks and functions that the module provides. A module may
implement as many tasks/functions as desired, so a module can legitimately be
called a library of system tasks and functions.
Compiling VPI Modules
---------------------
To compile and link a VPI module for use with Icarus Verilog, you must compile
all the source files of a module as if you were compiling for a DLL or shared
object. With gcc under Linux, this means compiling with the "-fpic" flag. The
module is then linked together with the vpi library like so::
% gcc -c -fpic hello.c
% gcc -shared -o hello.vpi hello.o -lvpi
This assumes that the "vpi_user.h header file and the libvpi.a library file
are installed on your system so that gcc may find them. This is normally the
case under Linux and UNIX systems. An easier, the preferred method that works
on all supported systems is to use the single command::
% iverilog-vpi hello.c
The "iverilog-vpi" command takes as command arguments the source files for
your VPI module, compiles them with proper compiler flags, and links them into
a vpi module with any system specific libraries and linker flags that are
required. This simple command makes the "hello.vpi" module with minimum fuss.
A Worked Example
----------------
Let us try a complete, working example. Place the C code that follows into the
file hello.c::
# include <vpi_user.h>
static int hello_compiletf(char*user_data)
{
return 0;
}
static int hello_calltf(char*user_data)
{
vpi_printf("Hello, World!\n");
return 0;
}
void hello_register()
{
s_vpi_systf_data tf_data;
tf_data.type = vpiSysTask;
tf_data.tfname = "$hello";
tf_data.calltf = hello_calltf;
tf_data.compiletf = hello_compiletf;
tf_data.sizetf = 0;
tf_data.user_data = 0;
vpi_register_systf(&tf_data);
}
void (*vlog_startup_routines[])() = {
hello_register,
0
};
and place the Verilog code that follows into hello.v::
module main;
initial $hello;
endmodule
Next, compile and execute the code with these steps::
% iverilog-vpi hello.c
% iverilog -ohello.vvp hello.v
% vvp -M. -mhello hello.vvp
Hello, World!
The compile and link in this example are conveniently combined into the
"iverilog-vpi" command. The "iverilog" command then compiles the "hello.v"
Verilog source file to the "hello.vvp" program. Next, the "vvp" command
demonstrates the use of the "-M" and "-m" flags to specify a vpi module search
directory and vpi module name. Specifically, they tell the "vvp" command where
to find the module we just compiled.
The "vvp" command, when executed as above, loads the "hello.vpi" module that
it finds in the current working directory. When the module is loaded, the
vlog_startup_routines table is scanned, and the "hello_register" function is
executed. The "hello_register" function in turn tells "vvp" about the system
tasks that are included in this module.
After the modules are all loaded, the "hello.vvp" design file is loaded and
its call to the "$hello" system task is matched up to the version declared by
the module. While "vvp" compiles the "hello.vvp" source, any calls to "$hello"
are referred to the "compiletf" function. This function is called at compile
time and can be used to check parameters to system tasks or function. It can
be left empty like this, or left out completely. The "compiletf" function can
help performance by collecting parameter checks in compile time, so they do
not need to be done each time the system task is run, thus potentially saving
execution time overall.
When the run-time executes the call to the hello system task, the
"hello_calltf" function is invoked in the loaded module, and thus the output
is generated. The "calltf" function is called at run time when the Verilog
code actually executes the system task. This is where the active code of the
task belongs.
System Function Return Types
----------------------------
Icarus Verilog supports system functions as well as system tasks, but there is
a complication. Notice how the module that you compile is only loaded by the
"vvp" program. This is mostly not an issue, but elaboration of expressions
needs to keep track of types, so the main compiler needs to know the return
type of functions.
Starting with Icarus Verilog v11, the solution is quite simple. The names and
locations of the user's VPI modules can be passed to the compiler via the
"iverilog" -m and -L flags and the IVERILOG_VPI_MODULE_PATH environment
variable. The compiler will load and analyse the specified modules to
automatically determine any function return types. The compiler will also
automatically pass the names and locations of the specified modules to the
"vvp" program, so that they don't need to be specified again on the "vvp"
command line.
For Icarus Verilog versions prior to v11, the solution requires that the
developer of a module include the table in a form that the compiler can
read. The System Function Table file carries this information. A simple
example looks like this::
# Example sft declarations of some common functions
$random vpiSysFuncInt
$bitstoreal vpiSysFuncReal
$realtobits vpiSysFuncSized 64 unsigned
This demonstrates the format of the file and support types. Each line contains
a comment (starts with "#") or a type declaration for a single function. The
declaration starts with the name of the system function (including the leading
"$") and ends with the type. The supported types are:
* vpiSysFuncInt
* vpiSysFuncReal
* vpiSysFuncSized <wid> <signed|unsigned>
Any functions that do not have an explicit type declaration in an SFT file are
implicitly taken to be "vpiSysFuncSized 32 unsigned".
The module author provides, along with the ".vpi" file that is the module, a
".sft" that declares all the function return types. For example, if the file
is named "example.sft", pass it to the "iverilog" command line or in the
command file exactly as if it were an ordinary source file.
Cadence PLI Modules
-------------------
With the cadpli module, Icarus Verilog is able to load PLI1 applications that
were compiled and linked to be dynamic loaded by Verilog-XL or
NC-Verilog. This allows Icarus Verilog users to run third-party modules that
were compiled to interface with XL or NC. Obviously, this only works on the
operating system that the PLI application was compiled to run on. For example,
a Linux module can only be loaded and run under Linux. In addition, a 64-bit
version of vvp can only load 64-bit PLI1 applications, etc.
Icarus Verilog uses an interface module, the "cadpli" module, to connect the
worlds. This module is installed with Icarus Verilog, and is invoked by the
usual -m flag to iverilog or vvp. This module in turn scans the extended
arguments, looking for -cadpli= arguments. The latter specify the share object
and bootstrap function for running the module. For example, to run the module
product.so, that has the bootstrap function "my_boot"::
% vvp -mcadpli a.out -cadpli=./product.so:my_boot
The "-mcadpli" argument causes vvp to load the cadpli.vpl library module. This
activates the -cadpli= argument interpreter. The -cadpli=<module>:<boot_func>
argument, then, causes vvp, through the cadpli module, to load the loadable
PLI application, invoke the my_boot function to get a veriusertfs table, and
scan that table to register the system tasks and functions exported by that
object. The format of the -cadpli= extended argument is essentially the same
as the +loadpli1= argument to Verilog-XL.
The integration from this point is seamless. The PLI application hardly knows
that it is being invoked by Icarus Verilog instead of Verilog-XL, so operates
as it would otherwise.
Other References
----------------
Since the above only explains how to get PLI/VPI working with Icarus Verilog,
here are some references to material to help with the common aspects of
PLI/VPI.
* Principles of Verilog PLI by Swapnajit Mittra. ISBN 0-7923-8477-6
* The Verilog PLI Handbook by Stuart Sutherland. ISBN 0-7923-8489-X