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

Deploy to GitHub pages

This commit is contained in:
github-actions[bot] 2025-12-17 03:55:50 +00:00 committed by GitHub
commit 6dea3b9b8f
135 changed files with 26856 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.buildinfo Normal file
View File

@ -0,0 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 51382038c6d73d97b563089aa41ed80d
tags: 645f666f9bcd5a90fca523b33c5a78b7

0
.nojekyll Normal file
View File

BIN
_images/GTKWave_Example2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 40 KiB

240
_sources/developer/getting_started.rst.txt Normal file
View File

@ -0,0 +1,240 @@
Getting Started as a Contributor
================================
Icarus Verilog development is centered around the github repository at
`github.com/steveicarus/iverilog <http://github.com/steveicarus/iverilog>`_.
Contributing to Icarus Verilog requires a basic knowledge of git and github,
so see the github documentation for more information. The sections below will
step you through the basics of getting the source code from github, making a
branch, and submitting a pull request for review.
Getting Icarus Verilog
----------------------
To start, you will need to clone the code. It is preferred that you use the
"ssh" method, and the ssh based clone with the command:
.. code-block:: console
% git clone git@github.com:steveicarus/iverilog.git
This assumes that you have a github account (accounts are free) and you have
set up your ssh authentication keys. See the
`Authentication Guides here <https://docs.github.com/en/authentication>`_.
The "git clone" command will get you all the source:
.. code-block:: console
% git clone git@github.com:steveicarus/iverilog.git
Cloning into 'iverilog'...
remote: Enumerating objects: 66234, done.
remote: Counting objects: 100% (6472/6472), done.
remote: Compressing objects: 100% (4123/4123), done.
remote: Total 66234 (delta 2412), reused 6039 (delta 2190), pack-reused 59762
Receiving objects: 100% (66234/66234), 27.98 MiB | 2.53 MiB/s, done.
Resolving deltas: 100% (50234/50234), done.
% 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 a
specific version, say for example version 11, the v11-branch, you checkout
that branch with the command:
.. code-block:: console
% 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:
.. code-block:: console
% git pull
Already up to date.
Finally, configuration files are built by the extra step:
.. code-block:: console
% sh autoconf.sh
Autoconf in root...
Precompiling lexor_keyword.gperf
Precompiling vhdlpp/lexor_keyword.gperf
You will need autoconf and gperf installed in order for the script to work.
If you get errors such as:
.. code-block:: console
% sh autoconf.sh
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.
Now you are ready to configure and compile the source.
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 Verilog:
.. code-block:: none
--enable-suffix[=suffix]
This option allows the user to build Icarus with a default suffix or when
provided a user defined suffix. 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).
.. code-block:: none
--enable-libvvp
The vvp progam is built as a small stub linked to a shared library,
libvvp.so, that may be linked with other programs so that they can host
a vvp simulation.
.. code-block:: none
--enable-libveriuser
PLI version 1 (the ACC and TF routines) were deprecated in IEEE 1364-2005.
These are supported in Icarus Verilog by the libveriuser library and cadpli
module. Starting with v13, these will only be built if this option is used.
A debug options is:
.. code-block:: none
--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
needed when checking for basic errors with valgrind.
Compiling on Linux
------------------
(Note: You will need to install bison, flex, g++ and gcc) This is probably the
easiest step. Given that you have the source tree from the above instructions,
the compile and install is generally as simple as:
.. code-block:: console
% ./configure
configure: loading site script /usr/share/site/x86_64-unknown-linux-gnu
checking build system type... x86_64-unknown-linux-gnu
checking host system type... x86_64-unknown-linux-gnu
checking for gcc... gcc
checking whether the C compiler works... yes
checking for C compiler default output file name... a.out
checking for suffix of executables...
[...and so on...]
% make
mkdir dep
Using git-describe for VERSION_TAG
g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c main.cc -o main.o
mv main.d dep/main.d
g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c async.cc -o async.o
mv async.d dep/async.d
g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c design_dump.cc -o design_dump.o
mv design_dump.d dep/design_dump.d
g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c discipline.cc -o discipline.o
[...and so on...]
The end result is a complete build of Icarus Verilog. You can install your
compiled version with a command like this:
.. code-block:: console
% sudo make install
Regression Tests
----------------
Icarus Verilog comes with a fairly extensive regression test suite. As of
2022, that test suite is included with the source in the "ivtest"
directory. Contained in that directory are a couple driver scripts that run
all the regression tests on the installed version of Icarus Verilog. So for
example:
.. code-block:: console
% cd ivtest
% ./vvp_reg.pl --strict
will run all the regression tests for the simulation engine. (This is what
most people will want to do.) You should rerun this test before submitting
patches to the developers. Also, if you are adding a new feature, you should
add test programs to the regression test suite to validate your new feature
(or bug fix.)
Note that pull requests will be required to pass these regression tests before
being merged.
Forks, Branches and Pull Requests
---------------------------------
Currently, the preferred way to submit patches to Icarus Verilog is via pull
requests.
`Pull requests <https://docs.github.com/en/github-ae@latest/pull-requests>`_
can be created from the main repository if you have write access (very few
people have write access) or more commonly from a fork, so the first step is
to create a fork that you can work with. It is easy enough to create a fork,
just go to the
`github.com/steveicarus/iverilog <http://github.com/steveicarus/iverilog>`_
page and use the "fork" button in the upper right corner. This will create
a new repository that you can clone instead of the steveicarus/iverilog
repository. You then use your local repository to create feature branches,
then submit them for inclusion in the main repository as pull
requests. Remember to `synchronize your fork
<https://docs.github.com/en/github-ae@latest/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork>`_
periodically with the main repository. This will make sure your work is based
on the latest upstream and avoid merge conflicts.
Create your patch by first creating a branch that contains your commits:
.. code-block:: console
% git checkout -b my-github-id/branch-name
We are encouraging using this scheme for naming your branches that are
destined for pull requests. Use your github id in the branch name. So for
example:
.. code-block:: console
% git checkout -b steveicarus/foo-feature
Do your work in this branch, then when you are ready to create a pull request,
first push the branch up to github:
.. code-block:: console
% git push -u origin my-github-id/branch-name
Then go to github.com to create your pull request. `Create your pull request
against the "master" branch of the upstream repository
<https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork>`_,
or the version branch that you are working on. Your pull request will be run
through continuous integration, and reviewed by one of the main
authors. Feedback may be offered to your PR, and once accepted, an approved
individual will merge it for you. Then you are done.

48
_sources/developer/glossary.rst.txt Normal file
View File

@ -0,0 +1,48 @@
Glossary
========
Throughout Icarus Verilog descriptions and source code, I use a
variety of terms and acronyms that might be specific to Icarus
Verilog, have an Icarus Verilog specific meaning, or just aren't
widely known. So here I define these terms.
LRM - Language Reference Manual
This is a generic acronym, but in the Verilog world we sometimes
mean *the* language reference manual, the IEEE1364 standard.
PLI - Programming Language Interface
This is a C API into Verilog simulators that is defined by the
IEEE1364. There are two major interfaces, sometimes called PLI 1
and PLI 2. PLI 2 is also often called VPI.
UDP - User Defined Primitive
These are objects that Verilog programmers define with the
"primitive" keyword. They are truth-table based devices. The
syntax for defining them is described in the LRM.
VPI - Verilog Procedural Interface
This is the C API that is defined by the Verilog standard, and
that Icarus Verilog partially implements. See also PLI.
VVM - Verilog Virtual Machine
This is the Icarus Verilog runtime that works with the code
generator that generates C++.
VVP - Verilog Virtual Processor
This is the Icarus Verilog runtime that reads in custom code in a
form that I call "VVP Assembly".
LPM - Library of Parameterized Modules
LPM (Library of Parameterized Modules) is EIS-IS standard 103-A. It is
a standard library of abstract devices that are designed to be close
enough to the target hardware to be easily translated, yet abstract
enough to support a variety of target technologies without excessive
constraints. Icarus Verilog uses LPM internally to represent idealized
hardware, especially when doing target neutral synthesis.

34
_sources/developer/guide/cadpli/cadpli.rst.txt Normal file
View File

@ -0,0 +1,34 @@
Cadence PLI1 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.
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.

169
_sources/developer/guide/index.rst.txt Normal file
View File

@ -0,0 +1,169 @@
Developer Guide
===============
The developer guide is intended to give you a gross structure of the
Icarus Verilog compiler source. This will help orient you to the
source code itself, so that you can find the global parts where you
can look for even better detail.
The documentation for getting, building and installing Icarus Verilog
is kept and maintained at :doc:`Getting Started as a Contributer <../getting_started>`
See the Installation Guide for getting the current source from the git
repository (and how to use the git repository) and see the Developer Guide
for instructions on participating in the Icarus Verilog development process.
That information will not be repeated here.
Scroll down to a listing with further readings.
Compiler Components
-------------------
- The compiler driver (driver/)
This is the binary that is installed as "iverilog". This program takes
the command line arguments and assembles invocations of all the other
subcommands to perform the steps of compilation.
- The preprocessor (ivlpp/)
This implements the Verilog pre-processor. In Icarus Verilog, the
compiler directives \`define, \`include, \`ifdef and etc. are implemented
in an external program. The ivlpp/ directory contains the source for
this program.
- The core compiler (root directory)
The "ivl" program is the core that does all the Verilog compiler
processing that is not handled elsewhere. This is the main core of the
Icarus Verilog compiler, not the runtime. See below for more details
on the core itself.
- The loadable code generators (tgt-\*/)
This core compiler, after it is finished with parsing and semantic
analysis, uses loadable code generators to emit code for supported
targets. The tgt-\*/ directories contains the source for the target
code generators that are bundled with Icarus Verilog. The tgt-vvp/
directory in particular contains the code generator for the vvp
runtime.
Runtime Components
------------------
- The vvp runtime (vvp/)
This program implements the runtime environment for Icarus
Verilog. It implements the "vvp" command described in the user
documentation. See the vvp/ subdirectory for further developer
documentation.
- The system tasks implementations (vpi/)
The standard Verilog system tasks are implemented using VPI (PLI-2)
and the source is in this subdirectory.
- The PLI-1 compatibility library (libveriuser/)
The Icarus Verilog support for the deprecated PLI-1 is in this
subdirectory. The vvp runtime does not directly support the
PLI-1. Instead, the libveriuser library emulates it using the builtin
PLI-2 support.
- The Cadence PLI module compatibility module (cadpli/)
It is possible in some specialized situations to load and execute
PLI-1 code written for Verilog-XL. This directory contains the source
for the module that provides the Cadence PLI interface.
The Core Compiler
-----------------
The "ivl" binary is the core compiler that does the heavy lifting of
compiling the Verilog source (including libraries) and generating the
output. This is the most complex component of the Icarus Verilog
compilation system.
The process in the abstract starts with the Verilog lexical analysis
and parsing to generate an internal "pform". The pform is then
translated by elaboration into the "netlist" form. The netlist is
processed by some functors (which include some optimizations and
optional synthesis) then is translated into the ivl_target internal
form. And finally, the ivl_target form is passed via the ivl_target.h
API to the code generators.
- Lexical Analysis
Lexical analysis and parsing use the tools "flex", "gperf", and
"bison". The "flex" input file "lexor.lex" recognizes the tokens in
the input stream. This is called "lexical analysis". The lexical
analyzer also does some processing of compiler directives that are not
otherwise taken care of by the external preprocessor. The lexical
analyzer uses a table of keywords that is generated using the "gperf"
program and the input file "lexor_keywords.gperf". This table allows
the lexical analyzer to efficiently check input words with the rather
large set of potential keywords.
- Parsing
The parser input file "parse.y" is passed to the "bison" program to
generate the parser. The parser uses the functions in parse*.h,
parse*.cc, pform.h, and pform*.cc to generate the pform from the
stream of input tokens. The pform is what compiler writers call a
"decorated parse tree".
The pform itself is described by the classes in the header files
"PScope.h", "Module.h", "PGenerate.h", "Statement.h", and
"PExpr.h". The implementations of the classes in those header files
are in the similarly named C++ files.
- Elaboration
Elaboration transforms the pform to the netlist form. Elaboration is
conceptually divided into several major steps: Scope elaboration,
parameter overrides and defparam propagation, signal elaboration, and
statement and expression elaboration.
The elaboration of scopes and parameter overrides and defparam
propagation are conceptually separate, but are in practice
intermingled. The elaboration of scopes scans the pform to find and
instantiate all the scopes of the design. New scopes are created by
instantiation of modules (starting with the root instances) by user
defined tasks and functions, named blocks, and generate schemes. The
elaborate_scope methods implement scope elaboration, and the
elab_scope.cc source file has the implementations of those
methods.
The elaborate.cc source file contains the initial calls to the
elaborate_scope for the root scopes to get the process started. In
particular, see the "elaborate" function near the bottom of the
elaborate.cc source file. The calls to Design::make_root_scope create
the initial root scopes, and the creation and enqueue of the
elaborate_root_scope_t work items primes the scope elaboration work
list.
Intermingled in the work list are defparms work items that call the
Design::run_defparams and Design::evaluate_parameters methods that
override and evaluate parameters. The override and evaluation of
parameters must be intermingled with the elaboration of scopes because
the exact values of parameters may impact the scopes created (imagine
generate schemes and instance arrays) and the created scopes in turn
create new parameters that need override and evaluation.
Further Reading
---------------
For further information on the individual parts of Icarus Verilog, see this listing:
.. toctree::
:maxdepth: 2
ivl/index
vvp/index
tgt-vvp/tgt-vvp
vpi/index
cadpli/cadpli
misc/index

91
_sources/developer/guide/ivl/attributes.rst.txt Normal file
View File

@ -0,0 +1,91 @@
Icarus Verilog Attributes
=========================
Attribute Naming Conventions
----------------------------
Attributes that are specific to Icarus Verilog, and are intended to be
of use to programmers, start with the prefix "ivl\_".
Attributes with the "_ivl_" prefix are set aside for internal
use. They may be generated internally by the compiler. They need not
be documented here.
Attributes To Control Synthesis
-------------------------------
The following is a summary of Verilog attributes that Icarus Verilog
understands within Verilog source files to control synthesis
behavior. This section documents generic synthesis attributes. For
target specific attributes, see target specific documentation.
These attributes only effect the behavior of the synthesizer. For
example, the ivl_combinational will not generate an error message
if the Verilog is being compiled for simulation. (It may generate a
warning.)
* Attributes for "always" and "initial" statements
(\* ivl_combinational \*)
This attribute tells the compiler that the statement models
combinational logic. If the compiler finds that it cannot make
combinational logic out of a marked always statement, it will
report an error.
This attribute can be used to prevent accidentally inferring
latches or flip-flops where the user intended combinational
logic.
(\* ivl_synthesis_on \*)
This attribute tells the compiler that the marked always statement
is synthesizable. The compiler will attempt to synthesize the
code in the marked "always" statement. If it cannot in any way
synthesize it, then it will report an error.
(\* ivl_synthesis_off \*)
If this value is attached to an "always" statement, then the
compiler will *not* synthesize the "always" statement. This can be
used, for example, to mark embedded test bench code.
* Attributes for modules
(\* ivl_synthesis_cell \*)
If this value is attached to a module during synthesis, that
module will be considered a target architecture primitive, and
its interior will not be synthesized further. The module can
therefore hold a model for simulation purposes.
* Attributes for signals (wire/reg/integer/tri/etc.)
(\* PAD = "<pad assignment list>" \*)
If this attribute is attached to a signal that happens to be a
root module port, then targets that support it will use the string
value as a list of pin assignments for the port/signal. The format
is a comma separated list of location tokens, with the format of
the token itself defined by the back-end tools in use.
* Other Attributes
[ none defined yet ]
Misc
----
(\* _ivl_schedule_push \*)
If this attribute is attached to a thread object (always or
initial statement) then the vvp code generator will generate code
that causes the scheduler to push this thread at compile time. The
compiler may internally add this attribute to always statements if
it detects that it is combinational. This helps resolve time-0
races.

12
_sources/developer/guide/ivl/index.rst.txt Normal file
View File

@ -0,0 +1,12 @@
IVL - The Core Compiler
=======================
.. toctree::
:maxdepth: 1
netlist
attributes
ivl_target
lpm
t-dll

131
_sources/developer/guide/ivl/ivl_target.rst.txt Normal file
View File

@ -0,0 +1,131 @@
Loadable Target API (ivl_target)
================================
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".
LPM Devices
-----------
All LPM devices support a small set of common LPM functions, as
described in the ivl_target header file. The ivl_lpm_t object has a
type enumerated by ivl_lpm_type_t, and that type is accessible via the
ivl_lpm_type function.
The following are type specific aspects of LPM devices.
* IVL_LPM_UFUNC
This LPM represents a user defined function. It is a way to connect
behavioral code into a structural network. The UFUNC device has a
vector output and a set of inputs. The ivl_lpm_define function returns
the definition as an ivl_scope_t object.
The output vector is accessible through the ivl_lpm_q, and the output
has the width defined by ivl_lpm_width. This similar to most every
other LPM device with outputs.
There are ivl_lpm_size() input ports, each with the width
ivl_lpm_data2_width(). The actual nexus is indexed by ivl_lpm_data2().

28
_sources/developer/guide/ivl/lpm.rst.txt Normal file
View File

@ -0,0 +1,28 @@
What Is LPM
===========
LPM (Library of Parameterized Modules) is EIS-IS standard 103-A. It is
a standard library of abstract devices that are designed to be close
enough to the target hardware to be easily translated, yet abstract
enough to support a variety of target technologies without excessive
constraints. Icarus Verilog uses LPM internally to represent idealized
hardware, especially when doing target neutral synthesis.
In general, the user does not even see the LPM that Icarus Verilog
generates, because the LPM devices are translated into technology
specific devices by the final code generator or target specific
optimizers.
Internal Uses Of LPM
--------------------
Internally, Icarus Verilog uses LPM devices to represent the design in
abstract, especially when synthesizing such functions as addition,
flip-flops, etc. The `synth` functor generates LPM modules when
interpreting procedural constructs. The functor generates the LPM
objects needed to replace a behavioral description, and uses
attributes to tag the devices with LPM properties.
Code generators need to understand the supported LPM devices so that
they can translate the devices into technology specific devices.

285
_sources/developer/guide/ivl/netlist.rst.txt Normal file
View File

@ -0,0 +1,285 @@
Netlist Format
==============
The output from the parse and elaboration steps is a "netlist" rooted
in a Design object. Parsing translates the design described in the
initial source file into a temporary symbolic "pform". Elaboration
then expands the design, resolving references and expanding
hierarchies, to produce a flattened netlist. This is the form that
optimizers and code generators use.
The design optimization processes all manipulate the netlist,
translating it to a (hopefully) better netlist after each step. The
complete netlist is then passed to the code generator, the emit
function, where the final code (in the target format) is produced.
Structural Items: NetNode and NetNet
------------------------------------
Components and wires, memories and registers all at their base are
either NetNode objects or NetNet objects. Even these classes are
derived from the NetObj class.
All NetNode and NetNet objects have a name and some number of
pins. The name usually comes from the Verilog source that represents
that object, although objects that are artifacts of elaboration will
have a generated (and probably unreadable) name. The pins are the
ports into the device. NetNode objects have a pin for each pin of the
component it represents, and NetNet objects have a pin for each signal
in the vector.
Node and net pins can be connected together via the connect
function. Connections are transitive (A==B and B==c means A==C) so
connections accumulate on a link as items are connected to it. The
destructors for nets and nodes automatically arrange for pins to be
disconnected when the item is deleted, so that the netlist can be
changed during processing.
Structural Links
----------------
The NetNode and NetNet classes contain arrays of Link objects, one
object per pin. Each pin is a single bit. The Link objects link to all
the NetNode and NetNet objects' links that are connected together in
the design, and to a Nexus object. This way, code that examines a node
of the design can discover what is connected to each pin.
The connected set of links also has common properties that are stored
or access from the Nexus object. All the Links that are connected
together are also connected to a single Nexus object. This object is
useful for accessing the properties and values that come from the
connected set of links. The Nexus object is also handy for iterating
over the connected set of Links.
See the Link class definition in netlist.h for a description of the link
methods, and the Nexus class for nexus global methods.
Currently, a link has 3 possible direction properties:
PASSIVE -- These pins are sampled by the object that holds the
pin based on some external event. These are used,
for example, by NetESignal objects that read a
point for a procedural expression.
INPUT -- These pins potentially react to the setting of its
input.
OUTPUT -- These pins potentially drive the node. (They may be
three-state.)
Behavioral Items: NetProcTop, NetProc and derived classes
---------------------------------------------------------
Behavioral items are not in general linked to the netlist. Instead,
they represent elaborated behavioral statements. The type of the object
implies what the behavior of the statement does. For example, a
NetCondit object represents an `if` statement, and carries a
condition expression and up to two alternative sub-statements.
At the root of a process is a NetProcTop object. This class carries a
type flag (initial or always) and a single NetProc object. The
contained statement may, depending on the derived class, refer to
other statements, compound statements, so on. But at the root of the
tree is the NetProcTop object. The Design class keeps a list of the
elaborated NetProcTop objects. That list represents the list of
processes in the design.
Interaction Of Behavioral And Structural: NetAssign\_
-----------------------------------------------------
The behavioral statements in a Verilog design effect the structural
aspects through assignments to registers. Registers are structural
items represented by the NetNet class, linked to the assignment
statement through pins. This implies that the l-value of an assignment
is structural. It also implies that the statement itself is
structural, and indeed it is derived from NetNode.
The NetAssign\_ class is also derived from the NetProc class because
what it does is brought on by executing the process. By multiple
inheritance we have therefore that the assignment is both a NetNode
and a NetProc. The NetAssign\_ node has pins that represent the l-value
of the statement, and carries behavioral expressions that represent
the r-value of the assignment.
Memories
--------
The netlist form includes the NetMemory type to hold the content of a
memory. Instances of this type represent the declaration of a memory,
and occur once for each memory. References to the memory are managed
by the NetEMemory and NetAssignMem\_ classes.
An instance of the NetEMemory class is created whenever a procedural
expression references a memory element. The operand is the index to
use to address (and read) the memory.
An instance of the NetAssignMem\_ class is created when there is a
procedural assignment to the memory. The NetAssignMem\_ object
represents the l-value reference (a write) to the memory. As with the
NetEMemory class, this is a procedural reference only.
When a memory reference appears in structural context (i.e. continuous
assignments) elaboration creates a NetRamDq. This is a LPM_RAM_DQ
device. Elaboration leaves the write control and data input pins
unconnected for now, because memories cannot appear is l-values of
continuous assignments. However, the synthesis functor may connect
signals to the write control lines to get a fully operational RAM.
By the time elaboration completes, there may be many NetAssignMem\_,
NetEMemory and NetRamDq objects referencing the same NetMemory
object. Each represents a port into the memory. It is up to the
synthesis steps (and the target code) to figure out what to do with
these ports.
Expressions
-----------
Expressions are represented as a tree of NetExpr nodes. The NetExpr
base class contains the core methods that represent an expression
node, including virtual methods to help with dealing with nested
complexities of expressions.
Expressions (as expressed in the source and p-form) may also be
elaborated structurally, where it makes sense. For example, assignment
l-value expressions are represented as connections to pins. Also,
continuous assignment module items are elaborated as gates instead of
as a procedural expression. Event expressions are also elaborated
structurally as events are like devices that trigger behavioral
statements.
However, typical expressions the behavioral description are
represented as a tree of NetExpr nodes. The derived class of the node
encodes what kind of operator the node represents.
Expression Bit Width
--------------------
The expression (represented by the NetExpr class) has a bit width that
it either explicitly specified, or implied by context or contents.
When each node of the expression is first constructed during
elaboration, it is given, by type and parameters, an idea what its
width should be. It certain cases, this is definitive, for example
with signals. In others, it is ambiguous, as with unsized constants.
As the expression is built up by elaboration, operators that combine
expressions impose bit widths of the environment or expose the bit
widths of the sub expressions. For example, the bitwise AND (&)
operator has a bit size implied by its operands, whereas the
comparison (==) operator has a bit size of 1. The building up of the
elaborated expression checks and adjusts the bit widths as the
expression is built up, until finally the context of the expression
takes the final bit width and makes any final adjustments.
The NetExpr::expr_width() method returns the calculated (or guessed)
expression width. This method will return 0 until the width is set by
calculation or context. If this method returns false, then it is up to
the context that wants the width to set one. The elaboration phase
will call the NetExpr::set_width method on an expression as soon as it
gets to a point where it believes that it knows what the width should
be.
The NetExpr::set_width(unsigned) virtual method is used by the context
of an expression node to note to the expression that the width is
determined and please adapt. If the expression cannot reasonably
adapt, it will return false. Otherwise, it will adjust bit widths and
return true.
::
I do not yet properly deal with cases where elaboration knows for
certain that the bit width does not matter. In this case, I
really should tell the expression node about it so that it can
pick a practical (and optimal) width.
Interaction Of Expressions And Structure: NetESignal
----------------------------------------------------
The NetAssign\_ class described above is the means for processes to
manipulate the net, but values are read from the net by NetESignal
objects. These objects are class NetExpr because they can appear in
expressions (and have width). They are not NetNode object, but hold
pointers to a NetNet object, which is used to retrieve values with the
expression is evaluated.
Hierarchy In Netlists
---------------------
The obvious hierarchical structure of Verilog is the module. The
Verilog program may contain any number of instantiations of modules in
order to form an hierarchical design. However, the elaboration of the
design into a netlist erases module boundaries. Modules are expanded
each place they are used, with the hierarchical instance name used to
name the components of the module instance. However, the fact that a
wire or register is a module port is lost.
The advantage of this behavior is first the simplification of the
netlist structure itself. Backends that process netlists only need to
cope with a list of nets, a list of nodes and a list of
processes. This eases the task of the backend code generators.
Another advantage of this flattening of the netlist is that optimizers
can operate globally, with optimizations freely crossing module
boundaries. This makes coding of netlist transform functions such as
constant propagation more effective and easier to write.
Scope Representation In Netlists
--------------------------------
In spite of the literal flattening of the design, scope information is
preserved in the netlist, with the NetScope class. The Design class
keeps a single pointer to the root scope of the design. This is the
scope of the root module. Scopes that are then created within that
(or any nested) module are placed as children of the root scope, and
those children can have further children, and so on.
Each scope in the tree carries its own name, and its relationship to
its parent and children. This makes it possible to walk the tree of
scopes. In practice, the walking of the scopes is handled by recursive
methods.
Each scope also carries the parameters that are applicable to the
scope itself. The parameter expression (possibly evaluated) can be
located by name, given the scope object itself. The scan of the pform
to generate scopes also places the parameters that are declared in the
scope. Overrides are managed during the scan, and once the scan is
complete, defparam overrides are applied.
Tasks In Netlists
-----------------
The flattening of the design does not include tasks and named
begin-end blocks. Tasks are behavioral hierarchy (whereas modules are
structural) so do not easily succumb to the flattening process. In
particular, it is logically impossible to flatten tasks that
recurse. (The elaboration process does reserve the right to flatten
some task calls. C++ programmers recognize this as inlining a task.)
Time Scale In Netlists
----------------------
The Design class and the NetScope classes carry time scale and
resolution information of the elaborated design. There is a global
resolution, and there are scope specific units and resolutions. Units
and resolutions are specified as signed integers, and interpreted as
the power of 10 of the value. For example, a resolution "-9" means
that "1" is 1ns (1e-9). The notation supports units from -128 to +127.
It is up to the back-ends to interpret "-4" as "100us".
Delays are expressed in the netlist by integers. The units of these
delays are always given in the units of the design precision. This
allows everything to work with integers, and generally places the
burden of scaling delays into elaboration. This is, after all, a
common task. The Design::get_precision() method gets the global design
precision.
Each NetScope also carries its local time_units and time_precision
values. These are filled in during scope elaboration and are used in
subsequent elaboration phases to arrange for scaling of delays. This
information can also be used by the code generator to scale times back
to the units of the scope, if that is desired.

61
_sources/developer/guide/ivl/t-dll.rst.txt Normal file
View File

@ -0,0 +1,61 @@
Loadable Targets
================
Icarus Verilog supports dynamically loading code generator modules to
perform the back-end processing of the completed design. The user
specifies on the command line the module to load. The compiler loads
the module (once the design is compiled and elaborated) and calls it
to finally handle the design.
Loadable target modules implement a set of functions that the core
compiler calls to pass the design to it, and the module in turn uses a
collection of functions in the core (the API) to access details of the
design.
Loading Target Modules
----------------------
The target module loader is invoked with the ivl flag "-tdll". That
is, the DLL loader is a linked in target type. The name of the target
module to load is then specified with the DLL flag, i.e. "-fDLL=<path>".
Compiling Target Modules
------------------------
<write me>
Loadable Target Module Api
--------------------------
The target module API is defined in the ivl_target.h header file. This
declares all the type and functions that a loadable module needs to
access the design.
About Specific Expression Types
-------------------------------
In this section find notes about the various kinds of expression
nodes. The notes here are in addition to the more general
documentation in the ivl_target.h header file.
* IVL_EX_CONCAT
The concatenation operator forms an expression node that holds the
repeat count and all the parameter expressions. The repeat count is
an integer that is calculated by the core compiler so it fully
evaluated, and *not* an expression.
The parameter expressions are retrieved by the ivl_expr_parm method,
with the index increasing as parameters go from left to right, from
most significant to least significant. (Note that this is different
from the order of bits within an expression node.)
* IVL_EX_NUMBER
This is a constant number. The width is fully known, and the bit
values are all represented by the ASCII characters 0, 1, x or z. The
ivl_expr_bits method returns a pointer to the least significant bit,
and the remaining bits are ordered from least significant to most
significant. For example, 5'b1zzx0 is the 5 character string "0xzz1".

501
_sources/developer/guide/misc/ieee1364-notes.rst.txt Normal file
View File

@ -0,0 +1,501 @@
IEEE1364 Notes
==============
The IEEE1364 standard is the bible that defines the correctness of the
Icarus Verilog implementation and behavior of the compiled
program. The IEEE1364.1 is also referenced for matters of
synthesis. So the ultimate definition of right and wrong comes from
those documents.
That does not mean that a Verilog implementation is fully
constrained. The standard document allows for implementation specific
behavior that, when properly accounted for, does not effect the
intended semantics of the specified language. It is therefore possible
and common to write programs that produce different results when run
by different Verilog implementations.
Standardization Issues
----------------------
These are some issues where the IEEE1364 left unclear, unspecified or
simply wrong. I'll try to be precise as I can, and reference the
standard as needed. I've made implementation decisions for Icarus
Verilog, and I will make clear what those decisions are and how they
affect the language.
* OBJECTS CAN BE DECLARED ANYWHERE IN THE MODULE
Consider this module::
module sample1;
initial foo = 1;
reg foo;
wire tmp = bar;
initial #1 $display("foo = %b, bar = %b", foo, tmp);
endmodule
Notice that the `reg foo;` declaration is placed after the first
initial statement. It turns out that this is a perfectly legal module
according to the -1995 and -2000 versions of the standard. The
statement `reg foo;` is a module_item_declaration which is in turn a
module_item. The BNF in the appendix of IEEE1364-1995 treats all
module_item statements equally, so no order is imposed.
Furthermore, there is no text (that I can find) elsewhere in the
standard that imposes any ordering restriction. The sorts of
restrictions I would look for are "module_item_declarations must
appear before all other module_items" or "variables must be declared
textually before they are referenced." Such statements simply do not
exist. (Personally, I think it is fine that they don't.)
The closest is the rules for implicit declarations of variables that
are otherwise undeclared. In the above example, `bar` is implicitly
declared and is therefore a wire. However, although `initial foo = 1;`
is written before foo is declared, foo *is* declared within the
module, and declared legally by the BNF of the standard.
Here is another example::
module sample2;
initial x.foo = 1;
test x;
initial #1 $display("foo = %b", x.foo);
endmodule
module test;
reg foo;
endmodule;
From this example one can clearly see that foo is once again declared
after its use in behavioral code. One also sees a forward reference of
an entire module. Once again, the standard places no restriction on
the order of module declarations in a source file, so this program is,
according to the standard, perfectly well formed.
Icarus Verilog interprets both of these examples according to "The
Standard As I Understand It." However, commercial tools in general
break down with these programs. In particular, the first example
may generate different errors depending on the tool. The most common
error is to claim that `foo` is declared twice, once (implicitly) as
a wire and once as a reg.
So the question now becomes, "Is the standard broken, or are the tools
limited?" Coverage of the standard seems to vary widely from tool to
tool so it is not clear that the standard really is at fault. It is
clear, however, that somebody goofed somewhere.
My personal opinion is that there is no logical need to require that
all module_item_declarations precede any other module items. I
personally would oppose such a restriction. It may make sense to
require that declarations of variables within a module be preceded by
their use, although even that is not necessary for the implementation
of efficient compilers.
However, the existence hierarchical naming syntax as demonstrated in
sample2 can have implications that affect any declaration order
rules. When reaching into a module with a hierarchical name, the
module being referenced is already completely declared (or not
declared at all, as in sample2) so module_item order is completely
irrelevant. But a "declare before use" rule would infect module
ordering, by requiring that modules that are used be first defined.
* TASK AND FUNCTION PARAMETERS CANNOT HAVE EXPLICIT TYPES
Consider a function negate that wants to take a signed integer value
and return its negative::
function integer negate;
input [15:0] val;
negate = -val;
endfunction
This is not quite right, because the input is implicitly a reg type,
which is unsigned. The result, then, will always be a negative value,
even if a negative val is passed in.
It is possible to fix up this specific example to work properly with
the bit pattern of a 16bit number, but that is not the point. What's
needed is clarification on whether an input can be declared in the
port declaration as well as in the contained block declaration.
As I understand the situation, this should be allowed::
function integer negate;
input [15:0] val;
reg signed [15:0] val;
negate = -val;
endfunction
In the -1995 standard, the variable is already implicitly a reg if
declared within a function or task. However, in the -2000 standard
there is now (as in this example) a reason why one might want to
actually declare the type explicitly.
I think that a port *cannot* be declared as an integer or time type
(though the result can) because the range of the port declaration must
match the range of the integer/time declaration, but the range of
integers is unspecified. This, by the way, also applies to module
ports.
With the above in mind, I have decided to *allow* function and task
ports to be declared with types, as long as the types are variable
types, such as reg or integer. Without this, there would be no
portable way to pass integers into functions/tasks. The standard does
not say it is allowed, but it doesn't *disallow* it, and other
commercial tools seem to work similarly.
* ROUNDING OF TIME
When the \`timescale directive is present, the compiler is supposed to
round fractional times (after scaling) to the nearest integer. The
confusing bit here is that it is apparently conventional that if the
\`timescale directive is *not* present, times are rounded towards zero
always.
* VALUE OF X IN PRIMITIVE OUTPUTS
The IEEE1364-1995 standard clearly states in Table 8-1 that the x
symbols is allowed in input columns, but is not allowed in
outputs. Furthermore, none of the examples have an x in the output of
a primitive. Table 8-1 in the IEEE1364-2000 also says the same thing.
However, the BNF clearly states that 0, 1, x and X are valid
output_symbol characters. The standard is self contradictory. So I
take it that x is allowed, as that is what Verilog-XL does.
* REPEAT LOOPS vs. REPEAT EVENT CONTROL
There seems to be ambiguity in how code like this should be parsed::
repeat (5) @(posedge clk) <statement>;
There are two valid interpretations of this code, from the
IEEE1364-1995 standard. One looks like this::
procedural_timing_control_statement ::=
delay_or_event_control statement_or_null
delay_or_event_control ::=
event_control
| repeat ( expression ) event_control
If this interpretation is used, then the statement <statement> should
be executed after the 5th posedge of clk. However, there is also this
interpretation::
loop_statement ::=
repeat ( expression ) statement
If *this* interpretation is used, then <statement> should be executed
5 times on the posedge of clk. The way the -1995 standard is written,
these are both equally valid interpretations of the example, yet they
produce very different results. The standard offers no guidance on how
to resolve this conflict, and the IEEE1364-2000 DRAFT does not improve
the situation.
Practice suggests that a repeat followed by an event control should be
interpreted as a loop head, and this is what Icarus Verilog does, as
well as all the other major Verilog tools, but the standard does not
say this.
* UNSIZED NUMERIC CONSTANTS ARE NOT LIMITED TO 32 BITS
The Verilog standard allows Verilog implementations to limit the size
of unsized constants to a bit width of at least 32. That means that a
constant 17179869183 (36'h3_ffff_ffff) may overflow some compilers. In
fact, it is common to limit these values to 32bits. However, a
compiler may just as easily choose another width limit, for example
64bits. That value is equally good.
However, it is not *required* that an implementation truncate at 32
bits, and in fact Icarus Verilog does not truncate at all. It will
make the unsized constant as big as it needs to be to hold the value
accurately. This is especially useful in situations like this::
reg [width-1:0] foo = 17179869183;
The programmer wants the constant to take on the width of the reg,
which in this example is parameterized. Since constant sizes cannot be
parameterized, the programmer ideally gives an unsized constant, which
the compiler then expands/contracts to match the l-value.
Also, by choosing to not ever truncate, Icarus Verilog can handle code
written for a 64bit compiler as easily as for a 32bit compiler. In
particular, any constants that the user does not expect to be
arbitrarily truncated by his compiler will also not be truncated by
Icarus Verilog, no matter what that other compiler chooses as a
truncation point.
* UNSIZED EXPRESSIONS AS PARAMETERS TO CONCATENATION {}
The Verilog standard clearly states in 4.1.14::
"Unsized constant numbers shall not be allowed in
concatenations. This is because the size of each
operand in the concatenation is needed to calculate
the complete size of the concatenation."
So for example the expression {1'b0, 16} is clearly illegal. It
also stands to reason that {1'b0, 15+1} is illegal, for exactly the
same justification. What is the size of the expression (15+1)?
Furthermore, it is reasonable to expect that (16) and (15+1) are
exactly the same so far as the compiler is concerned.
Unfortunately, Cadence seems to feel otherwise. In particular, it has
been reported that although {1'b0, 16} causes an error, {1'b0, 15+1}
is accepted. Further testing shows that any expression other than a
simple unsized constant is accepted there, even if all the operands of
all the operators that make up the expression are unsized integers.
This is a semantic problem. Icarus Verilog doesn't limit the size of
integer constants. This is valid as stated in 2.5.1 Note 3::
"The number of bits that make up an unsized number
(which is a simple decimal number or a number without
the size specification) shall be *at*least* 32."
[emphasis added]
Icarus Verilog will hold any integer constant, so the size will be as
large as it needs to be, whether that is 64bits, 128bits, or
more. With this in mind, what is the value of these expressions?
::
{'h1_00_00_00_00}
{'h1 << 32}
{'h0_00_00_00_01 << 32}
{'h5_00_00_00_00 + 1}
These examples show that the standard is justified in requiring that
the operands of concatenation have size. The dispute is what it takes
to cause an expression to have a size, and what that size is.
Verilog-XL claims that (16) does not have a size, but (15+1) does. The
size of the expression (15+1) is the size of the adder that is
created, but how wide is the adder when adding unsized constants?
One might note that the quote from section 4.1.14 says "Unsized
*constant*numbers* shall not be allowed." It does not say "Unsized
expressions...", so arguably accepting (15+1) or even (16+0) as an
operand to a concatenation is not a violation of the letter of the
law. However, the very next sentence of the quote expresses the
intent, and accepting (15+1) as having a more defined size than (16)
seems to be a violation of that intent.
Whatever a compiler decides the size is, the user has no way to
predict it, and the compiler should not have the right to treat (15+1)
any differently than (16). Therefore, Icarus Verilog takes the
position that such expressions are *unsized* and are not allowed as
operands to concatenations. Icarus Verilog will in general assume that
operations on unsized numbers produce unsized results. There are
exceptions when the operator itself does define a size, such as the
comparison operators or the reduction operators. Icarus Verilog will
generate appropriate error messages.
* MODULE INSTANCE WITH WRONG SIZE PORT LIST
A module declaration like this declares a module that takes three ports::
module three (a, b, c);
input a, b, c;
reg x;
endmodule
This is fine and obvious. It is also clear from the standard that
these are legal instantiations of this module::
three u1 (x,y,z);
three u2 ( ,y, );
three u3 ( , , );
three u4 (.b(y));
In some of the above examples, there are unconnected ports. In the
case of u4, the pass by name connects only port b, and leaves a and c
unconnected. u2 and u4 are the same thing, in fact, but using
positional or by-name syntax. The next example is a little less
obvious::
three u4 ();
The trick here is that strictly speaking, the parser cannot tell
whether this is a list of no pass by name ports (that is, all
unconnected) or an empty positional list. If this were an empty
positional list, then the wrong number of ports is given, but if it is
an empty by-name list, it is an obviously valid instantiation. So it
is fine to accept this case as valid.
These are more doubtful::
three u5(x,y);
three u6(,);
These are definitely positional port lists, and they are definitely
the wrong length. In this case, the standard is not explicit about
what to do about positional port lists in module instantiations,
except that the first is connected to the first, second to second,
etc. It does not say that the list must be the right length, but every
example of unconnected ports used by-name syntax, and every example of
ordered list has the right size list.
Icarus Verilog takes the (very weak) hint that ordered lists should be
the right length, and will therefore flag instances u5 and u6 as
errors. The IEEE1364 standard should be more specific one way or the
other.
* UNKNOWN VALUES IN L-VALUE BIT SELECTS
Consider this example::
reg [7:0] vec;
wire [4:0] idx = <expr>;
[...]
vec[idx] = 1;
So long as the value of idx is a valid bit select address, the
behavior of this assignment is obvious. However, there is no explicit
word in the standard as to what happens if the value is out of
range. The standard clearly states the value of an expression when the
bit-select or part select is out of range (the value is x) but does
not address the behavior when the expression is an l-value.
Icarus Verilog will take the position that bit select expressions in
the l-value will select oblivion if it is out of range. That is, if
idx has a value that is not a valid bit select of vec, then the
assignment will have no effect.
* SCHEDULING VALUES IN LOGIC
The interaction between blocking assignments in procedural code and
logic gates in gate-level code and expressions is poorly defined in
Verilog. Consider this example::
reg a;
reg b;
wire q = a & b;
initial begin
a = 1;
b = 0;
#1 b = 1;
if (q !== 0) begin
$display("FAILED -- q changed too soon? %b", q);
$finish;
end
end
This is a confusing situation. It is clear from the Verilog standard
that an assignment to a variable using a blocking assign causes the
l-value to receive the value before the assignment completes. This
means that a subsequent read of the assigned variable *must* read back
what was blocking-assigned.
However, in the example above, the "wire q = a & b" expresses some
gate logic between a/b and q. The standard does not say whether a read
out of logic should read the value computed from previous assigns to
the input from the same thread. Specifically, when "a" and "b" are
assigned by blocking assignments, will a read of "q" get the computed
value or the existing value?
In fact, existing commercial tools do it both ways. Some tools print
the FAILED message in the above example, and some do not. Icarus
Verilog does not print the FAILED message in the above example,
because the gate value change is *scheduled* when inputs are assigned,
but not propagated until the thread gives up the processor.
Icarus Verilog chooses this behavior in order to filter out zero-width
pulses as early as possible. The implication of this is that a read of
the output of combinational logic will most likely *not* reflect the
changes in inputs until the thread that changed the inputs yields
execution.
* BIT AND PART SELECTS OF PARAMETERS
Bit and part selects are supposed to only be supported on vector nets
and variables (wires, regs, etc.) However, it is common for Verilog
compilers to also support bit and part select on parameters. Icarus
Verilog also chooses to support bit and part selects on parameter
names, but we need to define what that means.
A bit or a part select on a parameter expression returns an unsigned
value with a defined size. The parameter value is considered be a
constant vector of bits foo[X:0]. That is, zero based. The bit and
part selects operate from that assumption.
Verilog 2001 adds syntax to allow the user to explicitly declare the
parameter range (i.e. parameter [5:0] foo = 9;) so Icarus Verilog will
(or should) use the explicitly declared vector dimensions to interpret
bit and part selects.
* EDGES OF VECTORS
Consider this example::
reg [ 5:0] clock;
always @(posedge clock) [do stuff]
The IEEE1364 standard clearly states that the @(posedge clock) looks
only at the bit clock[0] (the least significant bit) to search for
edges. It has been pointed out by some that Verilog XL instead
implements it as `@(posedge |clock)`: it looks for a rise in the
reduction or of the vector. Cadence Design Systems technical support
has been rumored to claim that the IEEE1364 specification is wrong,
but NC-Verilog behaves according to the specification, and thus
different from XL.
Icarus Verilog, therefore, takes the position that the specification
is clear and correct, and it behaves as does NC-Verilog in this
matter.
* REAL VARIABLES IN $dumpoff DEAD-ZONES
The IEEE1364 standard clearly states that in VCD files, the $dumpoff
section checkpoints all the dumped variables as X values. For reg and
wire bits/vectors, this obviously means 'bx values. Icarus Verilog
does this, for example::
$dumpoff
x!
x"
$end
Real variables can also be included in VCD dumps, but it is not at
all obvious what is supposed to be dumped into the $dumpoff-$end
section of the VCD file. Verilog-XL dumps "r0 !" to set the real
variables to the dead-zone value of 0.0, whereas other tools, such as
ModelTech, ignore real variables in this section.
For example (from XL)::
$dumpoff
r0 !
r0 "
$end
Icarus Verilog dumps NaN values for real variables in the
$dumpoff-$end section of the VCD file. The NaN value is the IEEE754
equivalent of an unknown value, and so better reflects the unknown
(during the dead zone) status of the variable, like this::
$dumpoff
rNaN !
rNaN "
$end
It turns out that NaN is conventionally accepted by scanf functions,
and viewers that support real variables support NaN values. So while
the IEEE1364 doesn't require this behavior, and given the variety that
already seems to exist amongst VCD viewers in the wild, this behavior
seems to be acceptable according to the standard, is a better mirror
of 4-value behavior in the dead zone, and appears more user friendly
when viewed by reasonable viewers.

10
_sources/developer/guide/misc/index.rst.txt Normal file
View File

@ -0,0 +1,10 @@
Miscellaneous
=============
.. toctree::
:maxdepth: 1
ieee1364-notes
swift
xilinx-hint

68
_sources/developer/guide/misc/swift.rst.txt Normal file
View File

@ -0,0 +1,68 @@
Swift Model Support (Preliminary)
=================================
Copyright 2003-2024 Stephen Williams
NOTE: SWIFT support does not work yet, these are provisional
instructions, intended to show what's supposed to happen when I get
it working.
Icarus Verilog support for SWIFT models is based on the LMTV interface
module from Synopsys. This module is normally distributed along with
the SWIFT models proper. This module can be linked with Icarus Verilog
via the cadpli compatibility object. (See cadpli.txt.)
* Preliminaries
First, you need the LMC_HOME environment variable set to point to the
installed directory for your SWIFT software. This setup is documented
in your SWIFT model documentation.
* Compilation
When compiling your Verilog design to include a SWIFT model, you need
to include wrappers for the model you intend to use. You may choose to
use ncverilog or verilogxl compatible wrappers, they work the
same. Locate your smartmodel directory, and include it in your command
file like so::
+libdir+.../smartmodel/sol/wrappers/verilogxl
The wrappers directory includes Verilog modules that wrap your SWIFT
module, and with this +libdir+ statement in your command file, the
Icarus Verilog compiler will be able to locate these wrappers. The
wrappers in turn invoke the $lm_model system tasks that are the LMTV
support for your model.
NOTE: This example uses the solaris directory of VerilogXL support
files as a source of wrappers. The files of interest, however, are
written in Verilog and are identical for all supported platforms, so
long as you choose the verilogxl or ncverilog files.
* Execution
After your simulation is compiled, run the simulation with the vvp
command, like this::
% vvp -mcadpli a.out -cadpli=$LMC_HOME/lib/x86_linux.lib/swiftpli.so:swift_boot
What this command line means is::
-mcadpli
Include the cadpli compatibility module
a.out
This is your compiled vvp file
-cadpli=$LMC_HOME/lib/x86_linux.lib/swiftpli.so:swift_boot
This tells the cadpli module to load the swiftpli.so
shared object, and boot it. This is code that comes with
your SWIFT modules, and provides the generic SWIFT
capabilities (lm_* system tasks) needed by the module
itself.
Once you start the vvp command, the SWIFT infrastructure will be
initialized as part of the simulation setup, and all should work
normally from here.

113
_sources/developer/guide/misc/xilinx-hint.rst.txt Normal file
View File

@ -0,0 +1,113 @@
Xilinx Hint
===========
For those of you who wish to use Icarus Verilog, in combination with
the Xilinx back end (Foundation or Alliance), it can be done. I have
run some admittedly simple (2300 equivalent gates) designs through this
setup, targeting a Spartan XCS10.
Verilog:
--------
Older versions of Icarus Verilog (like 19990814) couldn't synthesize
logic buried in procedural (flip-flop) assignment. Newer versions
(like 20000120) don't have this limitation.
Procedural assignments have to be given one at a time, to be
"found" by xnfsyn. Say
::
always @ (posedge Clk) Y = newY;
always @ (posedge Clk) Z = newZ;
rather than
::
always @ (posedge Clk) begin
Y = newY;
Z = newZ;
end
Steve's xnf.txt covers most buffer and pin constructs, but I had reason
to use a global clock net not connected to an input pin. The standard
Verilog for a buffer, combined with a declaration to turn that into a
BUFG, is::
buf BUFG( your_output_here, your_input_here );
$attribute(BUFG,"XNF-LCA","BUFG:O,I")
I use post-processing on my .xnf files to add "FAST" attributes to
output pins.
Running ivl:
------------
The -F switches are important. The following order seems to robustly
generate valid XNF files, and is used by "verilog -X"::
-Fsynth -Fnodangle -Fxnfio
Generating .pcf files:
----------------------
The ngdbuild step seems to lose pin placement information that ivl
puts in the XNF file. Use xnf2pcf to extract this information to
a .pcf file, which the Xilinx place-and-route software _will_ pay
attention to. Steve says he now makes that information available
in an NCF file, with -fncf=<path>, but I haven't tested that.
Running the Xilinx back end:
You can presumably use the GUI, but that doesn't fit in Makefiles :-).
Here is the command sequence in pseudo-shell-script::
ngdbuild -p $part $1.xnf $1.ngd
map -p $part -o map.ncd $1.ngd
xnf2pcf <$1.xnf >$1.pcf # see above
par -w -ol 2 -d 0 map.ncd $1.ncd $1.pcf
bitgen_flags = -g ConfigRate:SLOW -g TdoPin:PULLNONE -g DonePin:PULLUP \
-g CRC:enable -g StartUpClk:CCLK -g SyncToDone:no \
-g DoneActive:C1 -g OutputsActive:C3 -g GSRInactive:C4 \
-g ReadClk:CCLK -g ReadCapture:enable -g ReadAbort:disable
bitgen $1.ncd -l -w $bitgen_flags
The Xilinx software has diarrhea of the temp files (14, not including
.xnf, .pcf, .ngd, .ncd, and .bit), so this sequence is best done in a
dedicated directory. Note in particular that map.ncd is a generic name.
I had reason to run this remotely (and transparently within a Makefile)
via ssh. I use the gmake rule::
%.bit : %.xnf
ssh -x -a -o 'BatchMode yes' ${ALLIANCE_HOST} \
remote_alliance ${REMOTE_DIR} $(basename $@) 2>&1 < $<
scp ${ALLIANCE_HOST}:${REMOTE_DIR}/$@ .
and the remote_alliance script (on ${ALLIANCE_HOST})::
/bin/csh
cd $1
cat >! $2.xnf
xnf2pcf <$2.xnf >! $2.pcf
./backend $2
There is now a "Xilinx on Linux HOWTO" at http://www.polybus.com/xilinx_on_linux.html
I haven't tried this yet, it looks interesting.
Downloading:
------------
I use the XESS (http://www.xess.com/) XSP-10 development board, which
uses the PC parallel (printer) port for downloading and interaction
with the host. They made an old version of their download program
public domain, posted it at http://www.xess.com/FPGA/xstools.zip ,
and now there is a Linux port at ftp://ftp.microux.com/pub/pilotscope/xstools.tar.gz .
The above hints are based on my experience with Foundation 1.5 on NT
(gack) and Alliance 2.1i on Solaris. Your mileage may vary. Good luck!
- Larry Doolittle <LRDoolittle@lbl.gov> August 19, 1999
updated February 1, 2000

36
_sources/developer/guide/tgt-vvp/tgt-vvp.rst.txt Normal file
View File

@ -0,0 +1,36 @@
The VVP Target
==============
Symbol Name Conventions
-----------------------
There are some naming conventions that the vvp target uses for
generating symbol names.
* wires and regs
Nets and variables are named V_<full-name> where <full-name> is the
full hierarchical name of the signal.
* Logic devices
Logic devices (and, or, buf, bufz, etc.) are named L_<full_name>. In
this case the symbol is attached to a functor that is the output of
the logic device.
General Functor Web Structure
-----------------------------
The net of gates, signals and resolvers is formed from the input
design. The basic structure is wrapped around the nexus, which is
represented by the ivl_nexus_t.
Each nexus represents a resolved value. The input of the nexus is fed
by a single driver. If the nexus in the design has multiple drivers,
the drivers are first fed into a resolver (or a tree of resolvers) to
form a single output that is the nexus.
The nexus, then, feeds its output to the inputs of other gates, or to
the .net objects in the design.

9
_sources/developer/guide/vpi/index.rst.txt Normal file
View File

@ -0,0 +1,9 @@
VPI in Icarus Verilog
=====================
.. toctree::
:maxdepth: 1
vpi
va_math

100
_sources/developer/guide/vpi/va_math.rst.txt Normal file
View File

@ -0,0 +1,100 @@
Verilog-A math library
======================
License.
--------
Verilog-A math library built for Icarus Verilog
https://github.com/steveicarus/iverilog/
Copyright (C) 2007-2024 Cary R. (cygcary@yahoo.com)
This program is free software; you can redistribute it and/or modify
it 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.
Standard Verilog-A Mathematical Functions.
------------------------------------------
The va_math VPI module implements all the standard math functions provided
by Verilog-A as Verilog-D system functions. The names are the same except
like all Verilog-D system functions the name must be prefixed with a '$'.
For reference the functions are::
$ln(x) -- Natural logarithm
$log10(x) -- Decimal logarithm
$exp(x) -- Exponential
$sqrt(x) -- Square root
$min(x,y) -- Minimum
$max(x,y) -- Maximum
$abs(x) -- Absolute value
$floor(x) -- Floor
$ceil(x) -- Ceiling
$pow(x,y) -- Power (x**y)
$sin(x) -- Sine
$cos(x) -- Cosine
$tan(x) -- Tangent
$asin(x) -- Arc-sine
$acos(x) -- Arc-cosine
$atan(x) -- Arc-tangent
$atan2(y,x) -- Arc-tangent of y/x
$hypot(x,y) -- Hypotenuse (sqrt(x**2 + y**2))
$sinh(x) -- Hyperbolic sine
$cosh(x) -- Hyperbolic cosine
$tanh(x) -- Hyperbolic tangent
$asinh(x) -- Arc-hyperbolic sine
$acosh(x) -- Arc-hyperbolic cosine
$atanh(x) -- Arc-hyperbolic tangent
The only limit placed on the x and y arguments by the library is that they
must be numbers (not constant strings). The underlying C library controls
any other limits placed on the arguments. Most libraries return +-Inf or
NaN for results that cannot be represented with real numbers. All functions
return a real result.
Standard Verilog-A Mathematical Constants.
------------------------------------------
The Verilog-A mathematical constants can be accessed by including the
"constants.vams" header file. It is located in the standard include
directory. Recent version of Icarus Verilog (0.9.devel) automatically
add this directory to the end of the list used to find include files.
For reference the mathematical constants are::
`M_PI -- Pi
`M_TWO_PI -- 2*Pi
`M_PI_2 -- Pi/2
`M_PI_4 -- Pi/4
`M_1_PI -- 1/Pi
`M_2_PI -- 2/Pi
`M_2_SQRTPI -- 2/sqrt(Pi)
`M_E -- e
`M_LOG2E -- log base 2 of e
`M_LOG10E -- log base 10 of e
`M_LN2 -- log base e of 2
`M_LN10 -- log base e of 10
`M_SQRT2 -- sqrt(2)
`M_SQRT1_2 -- 1/sqrt(2)
Using the Library.
------------------
Just add "-m va_math" to your iverilog command line/command file and
\`include the "constants.vams" file as needed.
Thanks
------
I would like to thank Larry Doolittle for his suggestions and
Stephen Williams for developing Icarus Verilog.

50
_sources/developer/guide/vpi/vpi.rst.txt Normal file
View File

@ -0,0 +1,50 @@
VPI Modules in Icarus Verilog
================================
The VPI interface for Icarus Verilog works by creating from a
collection of PLI applications a single vpi module. The vpi module
includes compiled code for the applications linked together (with any
other libraries that the applications need) into a module with two
exported symbols, the vpip_set_callback function and the
vlog_startup_routines array.
The product that wishes to invoke the module (normally at run time) loads
the module, locates and calls the vpip_set_callback function to pass the
the module a jump table that allows the module to access the VPI routines
implemented by the product, then locates the vlog_startup_routines table
and calls all the startup routines contained in that table. It is possible
for a product to link with many modules. In that case, all the modules are
linked in and startup routines are called in order.
The product that uses vpi modules uses the environment variable
VPI_MODULE_PATH as a ':' separated list of directories. This is the
module search path. When a module is specified by name (using whatever
means the product supports) the module search path is scanned until
the module is located.
The special module names "system.vpi", "v2005_math.vpi", "v2009.vpi",
and "va_math.vpi" are part of the core Icarus Verilog distribution and
include implementations of the standard system tasks/functions. The
additional special module names "vhdl_sys.vpi" and "vhdl_textio.vpi"
include implementations of private functions used to support VHDL.
Compiling A VPI Module
----------------------
See the documentation under: :doc:`Using VPI <../../../usage/vpi>`
Tracing VPI Use
---------------
The vvp command includes the ability to trace VPI calls. This is
useful if you are trying to debug a problem with your code. To
activate tracing simply set the VPI_TRACE environment variable, with
the path to a file where trace text gets written. For example::
setenv VPI_TRACE /tmp/foo.txt
This tracing is pretty verbose, so you don't want to run like this
normally. Also, the format of the tracing messages will change
according to my needs (and whim) so don't expect to be able to parse
it in software.

19
_sources/developer/guide/vvp/debug.rst.txt Normal file
View File

@ -0,0 +1,19 @@
Debug Aids For VVP
==================
Debugging vvp can be fiendishly difficult, so there are some built in
debugging aids. These are enabled by setting the environment variable
VVP_DEBUG to the path to an output file. Then, various detailed debug
tools can be enabled as described below.
* .resolv
The .resolv can print debug information along with a label by
specifying the debug output label on the .resolv line::
.resolv tri$<label>
In this case, the "$" character directly after the "tri" enables debug
dumps for this node, and the <label> is the label to prepend to log
messages from this node.

13
_sources/developer/guide/vvp/index.rst.txt Normal file
View File

@ -0,0 +1,13 @@
VVP - Verilog Virtual Processor
===============================
.. toctree::
:maxdepth: 1
vvp
opcodes
vpi
vthread
debug

1357
_sources/developer/guide/vvp/opcodes.rst.txt Normal file
View File

File diff suppressed because it is too large Load Diff

169
_sources/developer/guide/vvp/vpi.rst.txt Normal file
View File

@ -0,0 +1,169 @@
VPI Within VVP
==============
System tasks and functions in Verilog are implemented in Icarus
Verilog by C routines written with VPI. This implies that the vvp
engine must provide at least a subset of the Verilog VPI
interface. The minimalist concepts of vvp, however, make the method
less than obvious.
Within a Verilog design, there is a more or less fixed web of
vpiHandles that is the design database as is available to VPI
functions. The Verilog standard defines quite a lot of types, but the
vvp only implements the ones it needs. The VPI web is added into the
design using special pseudo-ops that create the needed objects.
Loading VPI Modules
-------------------
The vvp runtime loads VPI modules at runtime before the parser reads
in the source files. This gives the modules a chance to register tasks
and functions before the source is compiled. This allows the compiler
to resolve references to system tasks and system functions to a
vpiHandle at compile time. References to missing tasks/function can
thus be caught before the simulation is run.
NOTE: This also, miraculously, allows for some minimal support of
the compiletf call. From the perspective of VPI code, compilation
of the VVP source is not unlike compilation of the original
Verilog.
The handle that the vvp threads have to the VPI are the vpiHandles of
the system tasks and functions. The %vpi_call instruction, once compiled,
carries the vpiHandle of the system task.
System Task Calls
-----------------
A system task call invokes a VPI routine, and makes available to that
routine the arguments to the system task. The called routine gets
access to the system task call by calling back the VPI requesting the
handle. It uses the handle, in turn, to get hold of the operands for
the task.
All that vvp needs to know about a system task call is the handle of
the system task definitions (created by the vpi_register_systf
function) and the arguments of the actual call. The arguments are
tricky because the list has no bound, even though each particular call
in the Verilog source has a specific set of parameters.
Since each call takes a fixed number of parameters, the input source
can include in the statement the list of arguments. The argument list
will not fit in a single generated instruction, but a vpiHandle that
refers to a vpiSysTfCall does. Therefore, the compiler can take the
long argument list and form a vpiSysTaskCall object. The generated
instruction then only needs to be a %vpi_call with the single parameter
that is the vpiHandle for the call.
System Function Calls
---------------------
System function calls are similar to system tasks. The only
differences are that all the arguments are input only, and there is a
single magic output that is the return value. The same %vpi_call can
even be used to call a function.
System functions, like system tasks, can only be called from thread
code. However, they can appear in expressions, even when that
expression is entirely structural. The desired effect is achieved by
writing a wrapper thread that calls the function when inputs change,
and that writes the output into the containing expression.
System Task/Function Arguments
------------------------------
The arguments to each system task or call are not stored in the
instruction op-code, but in the vpiSysTfCall object that the compiler
creates and that the %vpi_call instruction ultimately refers to. All
the arguments must be some sort of object that can be represented by a
vpiHandle at compile time.
Arguments are handled at compile time by the parser, which uses the
argument_list rule to build a list of vpiHandle objects. Each argument
in the argument_list invokes whatever function is appropriate for the
token in order to make a vpiHandle object for the argument_list. When
all this is done, an array of vpiHandles is passed to code to create a
vpiSysTfCall object that has all that is needed to make the call.
Scopes
------
VPI can access scopes as objects of type vpiScope. Scopes have names
and can also contain other sub-scopes, all of which the VPI function
can access by the vpiInternalScope reference. Therefore, the run-time
needs to form a tree of scopes into which other scoped VPI objects are
placed.
A scope is created with a .scope directive, like so::
<label> .scope "name" [, <parent>];
.timescale <units>;
The scope takes a string name as the first parameter. If there is an
additional parameter, it is a label of the directive for the parent
scope. Scopes that have no parent are root scopes. It is an error to
declare a scope with the same name more than once in a parent scope.
The name string given when creating the scope is the basename for the
scope. The vvp automatically constructs full names from the scope
hierarchy, and runtime VPI code can access that full name with the
vpiFullName reference.
The .timescale directive changes the scope units from the simulation
precision to the specified precision. The .timescale directive affects
the current scope.
Objects that place themselves in a scope place themselves in the
current scope. The current scope is the one that was last mentioned by
a .scope directive. If the wrong scope is current, the label on a
scope directive can be used to resume a scope. The syntax works like
this::
.scope <symbol>;
In this case, the <symbol> is the label of a previous scope directive,
and is used to identify the scope to be resumed. A scope resume
directive cannot have a label.
Variables
---------
Reg vectors (scalars are vectors of length 1) are created by .var
statements in the source. The .var statement includes the declared
name of the variable, and the indices of the MSB and LSB of the
vector. The vpiHandle is then created with this information, and the
vpi_ipoint_t pointer to the LSB functor of the variable. VPI programs
access the vector through the vpiHandle and related functions. The VPI
code gets access to the declared indices.
The VPI interface to variable (vpiReg objects) uses the MSB and LSB
values that the user defined to describe the dimensions of the
object.
::
/*
* Copyright (c) 2001-2024 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.
*/

64
_sources/developer/guide/vvp/vthread.rst.txt Normal file
View File

@ -0,0 +1,64 @@
Thread Details
==============
Thread objects in vvp are created by `.thread` statements in the
input source file.
A thread object includes a program counter and private bit
registers. The program counter is used to step the processor through
the code space as it executes instructions. The bit registers each
hold Verilog-style 4-value bits and are for use by the arithmetic
operators as they operate.
The program counter normally increments by one instruction after the
instruction is fetched. If the instruction is a branching instruction,
then the execution of the instruction sets a new value for the pc.
Instructions that use the bit registers have as an operand a <bit>
value. There is usually space in the instruction for 2 <bit>
operands. Instructions that work on vectors pull the vector values
from the bit registers starting with the LSB and up.
The bit addresses 0, 1, 2 and 3 are special constant bits 0, 1, x and
z, and are used as read-only immediate values. If the instruction
takes a single bit operand, then the appropriate value is simply read
out. If the instruction expects a vector, then a vector of the
expected width is created by replicating the constant value.
Bits 4, 5, 6 and 7 are read/write bits but are reserved by many
instructions for special purposes. Comparison operators, for example,
use these as comparison flag bits.
The remaining 64K-8 possible <bit> values are read-write bit registers
that can be accessed singly or as vectors. This obviously implies that
a bit address is 16 bits.
Threads also contain 16 numeric registers. These registers can hold a
real value or a 64bit integer, and can be used in certain cases where
numeric values are needed. The thread instruction set includes
%ix/* instructions to manipulate these registers. The instructions
that use these registers document which register is used, and what the
numeric value is used for. Registers 0-3 are often given fixed
meanings to instructions that need an integer value.
::
/*
* Copyright (c) 2001-2024 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.
*/

1246
_sources/developer/guide/vvp/vvp.rst.txt Normal file
View File

File diff suppressed because it is too large Load Diff

15
_sources/developer/index.rst.txt Normal file
View File

@ -0,0 +1,15 @@
Icarus Verilog Developer Support
================================
This section contains documents to help support developers who contribute to
Icarus Verilog.
.. toctree::
:maxdepth: 1
getting_started
regression_tests
version_stamps
guide/index
glossary

125
_sources/developer/regression_tests.rst.txt Normal file
View File

@ -0,0 +1,125 @@
The Regression Test Suite
=========================
Icarus Verilog development includes a regression test suite that is included
along with the source. The "ivtest" directory contains the regression test
suite, and this suite is used by the github actions as continuous integration
to make sure the code is always going forward.
NOTE: There are scripts written in perl to run the regression tests, but they
are being gradually replaced with a newer set of scripts. It is the newer
method that is described here.
Test Descriptions
-----------------
Regression tests are listed in the regress-vvp.list file. Each line lists the
name of the test and the path to the dest description. The list file is
therefore pretty simple, and all the description of the test is in the
description file:
.. code-block:: console
macro_str_esc vvp_tests/macro_str_esc.json
The "name" is a simple name, and the test-description-file is the path (relative
the ivtest directory) to the description file. A simple test description file
is a JSON file, like this:
.. code-block:: java
{
"type" : "normal",
"source" : "macro_str_esc.v",
"gold" : "macro_str_esc"
}
This description file contains all the information that the vvp_reg.py script
needs to run the regression test. The sections below describe the keys and
values in the description file dictionary.
source (required)
^^^^^^^^^^^^^^^^^
This specifies the name of the source file. The file is actually to be found
in the ivltests/ directory.
type (required)
^^^^^^^^^^^^^^^
This describes the kind of test to run. The valid values are:
* **normal** - Compile the source using the iverilog compiler vvp target, and if
that succeeds execute it using the vvp command. If there is no gold file
specified, then look for an output line with the "PASSED" string.
* **normal-vlog95** - This is similar to the normal case, but uses
the -tvlog95 target in a first pass to generate simplified verilog, then a
regular iverilog command with the -tvvp target to generate the actual
executable. This tests the -tvlog95 target.
* **NI** - Mark the test as not implemented. The test will be skipped without
running or reporting an error.
* **CE** - Compile, but expect the compiler to fail. This means the compiler
command process must return an error exit.
* **EF** - Compile and run, but expect the run time to fail. This means the
run time program must return an error exit.
gold (optional)
^^^^^^^^^^^^^^^
If this is specified, it replaces the "Passed" condition with a comparison of
the output with a gold file. The argument is the name of the gold file set,
which will be found in the "gold/" directory. The name here is actually the
basename of the gold files, with separate actual gold files for the iverilog
and vvp stderr and stdout. For example, if a "normal" test includes a gold
file, then the program is compiled and run, and the outputs are compared with
the gold file to make sure it ran properly.
The way the regression suite works, there are 4 log files created for each
test:
* foo-iverilog-stdout.log
* foo-iverilog-stderr.log
* foo-vvp-stdout.log
* foo-vvp-stderr.log
The "gold" value is the name of the gold file set. If the gold value is "foo",
Then the actual gold files are called:
* gold/foo-iverilog-stdout.gold
* gold/foo-iverilog-stderr.gold
* gold/foo-vvp-stdout.gold
* gold/foo/vvp-stderr.gold
If any of those files is empty, then the gold file doesn't need to be
present at all. The log files and the gold files are compared byte for
byte, so if the output you are getting is correct, then copy the log to
the corresponding gold, and you're done.
If the run type is "CE" or "RE", then the gold files still work, and can
be used to check that the error message is correct. If the gold file setting
is present, the error return is required, and also the gold files must match.
iverilog-args (optional)
^^^^^^^^^^^^^^^^^^^^^^^^
If this is specified, it is a list of strings that are passed as arguments to
the iverilog command line.
vvp-args (optional)
^^^^^^^^^^^^^^^^^^^^
If this is specified, it is a list of strings that are passed as arguments to
the vvp command. These arguments go before the vvp input file that is to be
run.
vvp-args-extended (optional)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If this is specified, it is a lost of strings that are passed as arguments to
the vvp command. These are extended arguments, and are placed after the vvp
input file that is being run. This is where you place things like plusargs.

37
_sources/developer/version_stamps.rst.txt Normal file
View File

@ -0,0 +1,37 @@
Files With Version Information
==============================
These are the only files that have version information in them:
* version_base.h -- This should be the 1 source for version info.
* version_tag.h -- Generated automatically with git tag information.
* verilog.spec -- Used to stamp RPM packages
When versions are changed, the above files need to be edited to account for
the new version information. The following used to have version information in
them, but now their version information is generated:
The version_tag.h file is generated from git tag information using
the "make version" target, or automatically if the version_tag.h
file doesn't exist at all. This implies that a "make version" is
something worth doing when you do a "git pull" or create commits.
The files below are now edited by the makefile and the version.exe program:
* iverilog-vpi.man -- The .TH tag has a version string
* driver/iverilog.man -- The .TH tag has a version string
* driver-vpi/res.rc -- Used to build Windows version stamp
* vvp/vvp.man -- The .TH tag has a version string
This now includes version_base.h to get the version:
* vpi/vams_simparam.c -- Hard coded result to simulatorVersion query
This is actually a test file list that is specific to a major version.
The regression test scripts query the version of the compiler to infer
that it must include this list of tests. For example, for version 12.x
of the compiler, the needs to be an ivltest/regress-v12.list file that
lists the tests that are specific to that version.
* ivltests/regress-XXX.list -- Version specific regression tests

25
_sources/index.rst.txt Normal file
View File

@ -0,0 +1,25 @@
.. Icarus Verilog documentation master file, created by
sphinx-quickstart on Sun Apr 10 16:28:38 2022.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Icarus Verilog
==============
Welcome to the documentation for Icarus Verilog.
.. toctree::
:maxdepth: 2
:caption: Contents:
usage/index
targets/index
developer/index
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

23
_sources/targets/index.rst.txt Normal file
View File

@ -0,0 +1,23 @@
The Icarus Verilog Targets
==========================
Icarus Verilog elaborates the design, then sends to the design to code
generates (targets) for processing. New code generators can be added by
external packages, but these are the code generators that are bundled with
Icarus Verilog. The code generator is selected by the "-t" command line flag.
.. toctree::
:maxdepth: 1
tgt-vvp
tgt-stub
tgt-null
tgt-vhdl
tgt-vlog95
tgt-pcb
tgt-fpga
tgt-pal
tgt-sizer
tgt-verilog
tgt-blif

44
_sources/targets/tgt-blif.rst.txt Normal file
View File

@ -0,0 +1,44 @@
The BLIF Code Generator (-tblif)
================================
The BLIF code generator supports emitting the design to a blif format
file as accepted by:
ABC: A System for Sequential Synthesis and Verification
<http://www.eecs.berkeley.edu/~alanmi/abc/>
This package contains tools sometimes used by ASIC designers. This
blif target emits .blif file that the ABC system can read int via
the "read_blif" command.
USAGE
-----
This code generator is intended to process structural Verilog source
code. To convert a design to blif, use this command::
% iverilog -tblif -o<path>.blif <source files>...
The source files can be Verilog, SystemVerilog, VHDL, whatever Icarus
Verilog supports, so long as it elaborates down to the limited subset
that the code generator supports. In other words, the files must be
structural.
The root module of the elaborated design becomes the model is
generated. That module may instantiate sub-modules and so on down the
design, completing the design. The output model is flattened, so it
doesn't invoke any subcircuits. Bit vectors are exploded out at the
model ports and internally. This is necessary since blif in particular
and ABC in general processes bits, not vectors.
LIMITATIONS
-----------
Currently, only explicit logic gates and continuous assignments are
supported.
The design must contain only one root module. The name of that root
module becomes the name of the blif model in the ".model" record.

201
_sources/targets/tgt-fpga.rst.txt Normal file
View File

@ -0,0 +1,201 @@
The FPGA Code Generator (-tfpga)
================================
.. warning::
This code generator is currently not included in Icarus Verilog.
The FPGA code generator supports a variety of FPGA devices, writing
XNF or EDIF depending on the target. You can select the architecture
of the device, and the detailed part name. The architecture is used to
select library primitives, and the detailed part name is written into
the generated file for the use of downstream tools.
INVOKING THE FPGA TARGET
------------------------
The code generator is invoked with the -tfpga flag to iverilog. It
understands the part= and the arch= parameters, which can be set with
the -p flag of iverilog:
iverilog -parch=virtex -ppart=v50-pq240-6 -tfpga foo.vl
This example selects the Virtex architecture, and give the detailed
part number as v50-pq240-6. The output is written into a.out unless a
different output file is specified with the -o flag.
The following is a list of architecture types that this code generator
supports.
* arch=lpm
This is a device independent format, where the gates are device types
as defined by the LPM 2 1 0 specification. Some backend tools may take
this format, or users may write interface libraries to connect these
netlists to the device in question.
* arch=generic-edif (obsolete)
This is generic EDIF code. It doesn't necessarily work because the
external library is not available to the code generator. But, what it
does is generate generic style gates that a portability library can
map to target gates if desired.
* arch=generic-xnf (obsolete)
If this is selected, then the output is formatted as an XNF file,
suitable for most any type of device. The devices that it emits
are generic devices from the unified library. Some devices are macros,
you may need to further resolve the generated XNF to get working
code for your part.
* arch=virtex
If this is selected, then the output is formatted as an EDIF 200 file,
suitable for Virtex class devices. This is supposed to know that you
are targeting a Virtex part, so can generate primitives instead of
using external macros. It includes the VIRTEX internal library, and
should work properly for any Virtex part.
* arch=virtex2
If this is selected, then the output is EDIF 2 0 0 suitable for
Virtex-II and Virtex-II Pro devices. It uses the VIRTEX2 library, but
is very similar to the Virtex target.
XNF ROOT PORTS
--------------
NOTE: As parts are moved over to EDIF format, XNF support will be
phased out. Current Xilinx implementation tools will accept EDIF
format files even for the older parts, and non-Xilinx implementation
tools accept nothing else.
When the output format is XNF, the code generator will generate "SIG"
records for the signals that are ports of the root module. The name is
declared as an external pin that this macro makes available.
The name given to the macro pin is generated from the base name of the
signal. If the signal is one bit wide, then the pin name is exactly
the module port name. If the port is a vector, then the pin number is
given as a vector. For example, the module:
.. code-block::
module main(out, in);
output out;
input [2:0] in;
[...]
endmodule
leads to these SIG, records:
.. code-block::
SIG, main/out, PIN=out
SIG, main/in<2>, PIN=in2
SIG, main/in<1>, PIN=in1
SIG, main/in<0>, PIN=in0
EDIF ROOT PORTS
---------------
The EDIF format is more explicit about the interface into an EDIF
file. The code generator uses that control to generate an explicit
interface definition into the design. (This is *not* the same as the
PADS of a part.) The generated EDIF interface section contains port
definitions, including the proper direction marks.
With the (rename ...) s-exp in EDIF, it is possible to assign
arbitrary text to port names. The EDIF code generator therefore does
not resort to the mangling that is needed for the XNF target. The base
name of the signal that is an input or output is used as the name of
the port, complete with the proper case.
However, since the ports are single bit ports, the name of vectors
includes the string "[0]" where the number is the bit number. For
example, the module:
.. code-block::
module main(out, in);
output out;
input [2:0] in;
[...]
endmodule
creates these ports:
.. code-block::
out OUTPUT
in[0] INPUT
in[1] INPUT
in[2] INPUT
Target tools, including Xilinx Foundation tools, understand the []
characters in the name and recollect the signals into a proper bus
when presenting the vector to the user.
PADS AND PIN ASSIGNMENT
-----------------------
The ports of a root module may be assigned to specific pins, or to a
generic pad. If a signal (that is a port) has a PAD attribute, then
the value of that attribute is a list of locations, one for each bit
of the signal, that specifies the pin for each bit of the signal. For
example:
.. code-block::
module main( (* PAD = "P10" *) output out,
(* PAD = "P20,P21,P22" *) input [2:0] in);
[...]
endmodule
In this example, port `out` is assigned to pin 10, and port `in`
is assigned to pins 20-22. If the architecture supports it, a pin
number of 0 means let the back end tools choose a pin. The format of
the pin number depends on the architecture family being targeted, so
for example Xilinx family devices take the name that is associated
with the "LOC" attribute.
NOTE: If a module port is assigned to a pin (and therefore attached to
a PAD) then it is *not* connected to a port of the EDIF file. This is
because the PAD (and possibly IBUF or OBUF) would become an extra
driver to the port. An error.
SPECIAL DEVICES
---------------
The code generator supports the "cellref" attribute attached to logic
devices to cause specific device types be generated, instead of the
usual device that the code generator might generate. For example, to
get a clock buffer out of a Verilog buf:
buf my_gbuf(out, in);
$attribute(my_buf, "cellref", "GBUF:O,I");
The "cellref" attribute tells the code generator to use the given
cell. The syntax of the value is:
<cell type>:<pin name>,...
The cell type is the name of the library part to use. The pin names
are the names of the type in the library, in the order that the logic
device pins are connected.
COMPILING WITH XILINX FOUNDATION
--------------------------------
Compile a single-file design with command line tools like so::
% iverilog -parch=virtex -o foo.edf foo.vl
% edif2ngd foo.edf foo.ngo
% ngdbuild -p v50-pq240 foo.ngo foo.ngd
% map -o map.ncd foo.ngd
% par -w map.ncd foo.ncd

7
_sources/targets/tgt-null.rst.txt Normal file
View File

@ -0,0 +1,7 @@
The null Code Generator (-tnull)
================================
The null target generates no code. Invoking this code generator causes no code
generation to happen.

8
_sources/targets/tgt-pal.rst.txt Normal file
View File

@ -0,0 +1,8 @@
The PAL Code Generator (-tpal)
==============================
.. warning::
This code generator is currently not included in Icarus Verilog.
The PAL target generates JEDEC output for a Programmable Array Logic.

61
_sources/targets/tgt-pcb.rst.txt Normal file
View File

@ -0,0 +1,61 @@
The PCB Code Generator (-tpcb)
==============================
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."

49
_sources/targets/tgt-sizer.rst.txt Normal file
View File

@ -0,0 +1,49 @@
The sizer Code Analyzer (-tvvp)
===============================
The sizer target does not generate any code. Instead it will print statistics about the Verilog code.
It is important to synthesize the Verilog code before invoking the sizer. This can be done with the `-S` flag passed to iverilog. Note, that behavioral code can not be synthesized and will generate a warning when passed to the sizer.
Example command::
% iverilog -o sizer.txt -tsizer -S -s top input.v
With this example code:
.. code-block:: verilog
module top (
input clock,
input reset,
output blink
);
reg out;
always @(posedge clock) begin
if (reset) begin
out = 1'b0;
end else begin
out <= !out;
end
end
assign blink = out;
endmodule
The resulting `sizer.txt` will contain::
**** module/scope: top
Flip-Flops : 1
Logic Gates : 3
MUX[2]: 1 slices
LOG[13]: 1 unaccounted
LOG[14]: 1 unaccounted
**** TOTALS
Flip-Flops : 1
Logic Gates : 3
MUX[2]: 1 slices
LOG[13]: 1 unaccounted
LOG[14]: 1 unaccounted

30
_sources/targets/tgt-stub.rst.txt Normal file
View File

@ -0,0 +1,30 @@
The stub Code Generator (-tstub)
================================
The stub code generator is a debugging aid for the Icarus Verilog compiler
itself. It outputs a text dump of the elaborated design as it is passed to
code generators.
Example command::
% iverilog -o stub.txt -tstub -s top input.v
With this example code:
.. code-block:: verilog
module top;
initial $display("Hello World!");
endmodule
The resulting `stub.txt` will contain::
root module = top
scope: top (0 parameters, 0 signals, 0 logic) module top time units = 1e0
time precision = 1e0
end scope top
# There are 0 constants detected
initial
Call $display(1 parameters); /* hello_world.v:2 */
<string="Hello World!", width=96, type=bool>

6
_sources/targets/tgt-verilog.rst.txt Normal file
View File

@ -0,0 +1,6 @@
The Verilog Code Generator (-tverilog)
======================================
.. warning::
This code generator is currently not included in Icarus Verilog.

82
_sources/targets/tgt-vhdl.rst.txt 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.

101
_sources/targets/tgt-vlog95.rst.txt Normal file
View File

@ -0,0 +1,101 @@
The Verilog '95 Code Generator (-tvlog95)
=========================================
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?

63
_sources/targets/tgt-vvp.rst.txt Normal file
View File

@ -0,0 +1,63 @@
The vvp Code Generator (-tvvp)
==============================
The vvp target generates code for the "vvp" run time. This is the most
commonly used target for Icarus Verilog, as it is the main simulation engine.
Example command::
% iverilog -o top.vvp -s top hello_world.v
Equivalent command::
% iverilog -o top.vvp -tvvp -s top hello_world.v
With this example code in `hello_world.v`:
.. code-block:: verilog
module top;
initial $display("Hello World!");
endmodule
The resulting `top.vvp` will contain something similar to::
#! /usr/local/bin/vvp
:ivl_version "13.0 (devel)" "(s20221226-119-g8cb2e1a05-dirty)";
:ivl_delay_selection "TYPICAL";
:vpi_time_precision + 0;
:vpi_module "/usr/local/lib/ivl/system.vpi";
:vpi_module "/usr/local/lib/ivl/vhdl_sys.vpi";
:vpi_module "/usr/local/lib/ivl/vhdl_textio.vpi";
:vpi_module "/usr/local/lib/ivl/v2005_math.vpi";
:vpi_module "/usr/local/lib/ivl/va_math.vpi";
S_0x563c3c5d1540 .scope module, "top" "top" 2 1;
.timescale 0 0;
.scope S_0x563c3c5d1540;
T_0 ;
%vpi_call 2 2 "$display", "Hello World!" {0 0 0};
%end;
.thread T_0;
# The file index is used to find the file name in the following table.
:file_names 3;
"N/A";
"<interactive>";
"hello_world.v";
The first line contains the shebang. If this file is executed, the shebang tells the shell to use vvp for the execution of this file.
To run the simulation, execute::
% ./top.vvp
Or you can call vvp directly::
% vvp top.vvp
Next are some directives. The first one, `:ivl_version` specifies which version of iverilog this file was created with. Next is the delay selection with "min:typical:max" values and the time precision, which we did not set specifically, so the default value is used. The next lines tell vvp which VPI modules to load and in which order. The next lines tell vvp which VPI modules to load and in what order. Next, a new scope is created with the `.scope` directive and the timescale is set with `.timescale`. A thread `T_0` is created that contains two instructions: `%vpi_call` executes the VPI function `$display` with the specified arguments, and `%end` terminates the simulation.
Opcodes
-------
The various available opcodes can be seen in :doc:`Opcodes <../developer/guide/vvp/opcodes>`

198
_sources/usage/command_files.rst.txt 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.

444
_sources/usage/command_line_flags.rst.txt Normal file
View File

@ -0,0 +1,444 @@
iverilog Command Line Flags
===========================
The iverilog command is the compiler/driver that takes the Verilog input and
generates the output format, whether the simulation file or synthesis
results. This information is at least summarized in the iverilog man page
distributed in typical installations, but here we try to include more detail.
General
-------
These flags affect the general behavior of the compiler.
* -c <cmdfile>
This flag selects the command file to use. The command file is an
alternative to writing a long command line with a lot of file names and
compiler flags. See the Command File Format page for more information.
* -d <flag>
Enable compiler debug output. These are aids for debugging Icarus Verilog,
and this flag is not commonly used.
The flag is one of these debug classes:
* scope
* eval_tree
* elaborate
* synth2
* -g <generation flag>
the generation is the compiler language, and specifies the language and
extensions to use during the compile. The language level can be selected
by a major level selector, and by controlling various features. Various
"-g" flags can be compined. For example, to get Verilog 2001 without
specify supoprt, use "-g2001 -gno-specify".
The supported flags are:
* 1995
This flag enables the IEEE1364-1995 standard.
* 2001
This flag enables the IEEE1364-2001 standard.
* 2001-noconfig
This flag enables the IEEE1364-2001 standard with config file support
disabled. This eliminates the config file keywords from the language and
so helps some programs written to older 2001 support compile.
* 2005
This flag enables the IEEE1364-2005 standard. This is default enabled
after v0.9.
* 2009
This flag enables the IEEE1800-2009 standard, which includes
SystemVerilog. The SystemVerilog support is not present in v0.9 and
earlier. It is new to git master as of November 2009. Actual SystemVerilog
support is ongoing.
* 2012
This flag enables the IEEE1800-2012 standard, which includes
SystemVerilog.
* verilog-ams
This flag enables Verilog-AMS features that are supported by Icarus
Verilog. (This is new as of 5 May 2008.)
* assertions/supported-assertions/no-assertions
Enable or disable SystemVerilog assertions. When enabled, assertion
statements are elaborated. When disabled, assertion statements are parsed
but ignored. The supported-assertions option only enables assertions that
are currently supported by the compiler.
* specify/no-specify
Enable or disable support for specify block timing controls. When
disabled, specify blocks are parsed but ignored. When enabled, specify
blocks cause timing path and timing checks to be active.
* std-include/no-std-include
Enable or disable the search of a standard installation include directory
after all other explicit include directories. This standard include
directory is a convenient place to install standard header files that a
Verilog program may include.
* relative-include/no-relative-include
Enable or disable adding the local files directory to the beginning of the
include file search path. This allows files to be included relative to the
current file.
* xtypes/no-xtypes
Enable or disable support for extended types. Enabling types allows for
new types and type syntax that are Icarus Verilog extensions.
* io-range-error/no-io-range-error
When enabled the range for a port and any associated net declaration must
match exactly. When disabled a scalar port is allowed to have a net
declaration with a range (obsolete usage). A warning message will be
printed for this combination. All other permutations are still considered
an error.
* strict-ca-eval/no-strict-ca-eval
The standard requires that if any input to a continuous assignment
expression changes value, the entire expression is re-evaluated. By
default, parts of the expression that do not depend on the changed input
value(s) are not re-evaluated. If an expression contains a call to a
function that doesn't depend solely on its input values or that has side
effects, the resulting behavior will differ from that required by the
standard. Enabling strict-ca-eval will force standard compliant behavior
(with some loss in performance).
* strict-expr-width/no-strict-expr-width
Enable or disable strict compliance with the standard rules for
determining expression bit lengths. When disabled, the RHS of a parameter
assignment is evaluated as a lossless expression, as is any expression
containing an unsized constant number, and unsized constant numbers are
not truncated to integer width.
* shared-loop-index/no-shared-loop-index
Enable or disable the exclusion of for-loop control variables from
implicit event_expression lists. When enabled, if a for-loop control
variable (loop index) is only used inside the for-loop statement, the
compiler will not include it in an implicit event_expression list it
calculates for that statement or any enclosing statement. This allows the
same control variable to be used in multiple processes without risk of
entering an infinite loop caused by each process triggering all other
processes that use the same variable. For strict compliance with the
standards, this behaviour should be disabled.
* -i
Ignore missing modules. Normally it is an error if a module instantiation
refers to an undefined module. This option causes the compiler to skip over
that instantiation. It will also stop the compiler returning an error if
there are no top level modules. This allows the compiler to be used to check
incomplete designs for errors.
NOTE: The "-i" flag was added in v11.0.
* -L <path>
Add the specified directory to the path list used to locate VPI modules. The
default path includes only the install directory for the system.vpi module,
but this flag can add other directories. Multiple paths are allowed, and the
paths will be searched in order.
NOTE: The "-L" flag was added in v11.0.
* -l <path>
Add the specified file to the list of source files to be compiled, but mark
it as a library file. All modules contained within that file will be treated
as library modules, and only elaborated if they are instantiated by other
modules in the design.
NOTE: The "-l" flag is new as of 2 October 2016. It will become available in
releases and snapshots made after that date.
* -M<mode>=<path>
Write into the file specified by path a list of files that contribute to the
compilation of the design.
If _mode_ is *all* or *prefix*, this includes files that are included by
include directives and files that are automatically loaded by library
support as well as the files explicitly specified by the user.
If _mode_ is *include*, only files that are included by include directives
are listed.
If _mode_ is *module*, only files that are specified by the user or that are
automatically loaded by library support are listed. The output is one file
name per line, with no leading or trailing space.
If _mode_ is *prefix*, files that are included by include directives are
prefixed by "I " and other files are prefixed by "M ".
* -m<module>
Add this module to the list of VPI modules to be loaded by the
simulation. Many modules can be specified, and all will be loaded, in the
order specified. The system module is implicit and always included (and
loaded last).
If the specified name includes at least one directory character, it is
assumed to be prefixed by the path to the module, otherwise the module is
searched for in the paths specified by preceding -L options, and if not
found there, in the iverilog base directory.
NOTE: The "-m" flag was added in v11.0.
* -o <path>
Specify the output file. The <path> is the name of the file to hold the
output. The default is "a.out".
* -S
Activate synthesis. This flag tells the compiler to do what synthesis it can
do before calling the code generator. This flag is rarely used explicitly,
and certain code generators will implicitly enable this flag.
* -u
Treat each source file as a separate compilation unit (as defined in
SystemVerilog). If compiling for an IEEE1364 generation, this will just
reset all compiler directives (including macro definitions) before each new
file is processed.
NOTE: The "-u" flag was added in v11.0.
* -v
Be verbose. Print copyright information, progress messages, and some timing
information about various compilation phases.
(New in snapshots after 2014-12-16) If the selected target is vvp, the -v
switch is appended to the shebang line in the compiler output file, so
directly executing the compiler output file will turn on verbose messages in
vvp. This extra verbosity can be avoided by using the vvp command to
indirectly execute the compiler output file.
* -V
Print the version information. This skips all compilation. Just print the
version information, including version details for the various components of
the compiler.
* -R
Print the runtime paths of the compiler. This can be useful to find, e.g.,
the include path of vpi_user.h.
* -W<warning class>
Enable/disable warnings. All the warning types (other then "all") can be
prefixed with no- to disable that warning.
* all
This enables almost all of the available warnings. More specifically, it
enables these warnings::
-Wanachronisms
-Wimplicit
-Wimplicit-dimensions
-Wmacro-replacement
-Wportbind
-Wselect-range
-Wtimescale
-Wsensitivity-entire-array
* anachronisms
This enables warnings for use of features that have been deprecated or
removed in the selected generation of the Verilog language.
* implicit
This enables warnings for creation of implicit declarations. For example,
if a scalar wire X is used but not declared in the Verilog source, this
will print a warning at its first use.
* implicit-dimensions
This enables warnings for the case where a port declaration or a var/net
declaration for the same name is missing dimensions. Normally, Verilog
allows you to do this (the undecorated declaration gets its dimensions
form the decorated declaration) but this is no longer common, and some
other tools (notable Xilix synthesizers) do not handle this correctly.
This flag is supported in release 10.1 or master branch snapshots after
2016-02-06.
* macro-redefinition
This enables warnings when a macro is redefined, even if the macro text
remains the same.
NOTE: The "macro-redefinition" flag was added in v11.0.
* macro-replacement
This enables warnings when a macro is redefined and the macro text
changes. Use no-macro-redefinition to disable this,
NOTE: The "macro-replacement" flag was added in v11.0.
* portbind
This enables warnings for ports of module instantiations that are not
connected properly, but probably should be. Dangling input ports, for
example, will generate a warning.
* select-range
This enables warnings for constant out-of-bound selects. This includes
partial or fully out-of-bound select as well as a select containing a 'bx
or 'bz in the index.
* timescale
This enables warnings for inconsistent use of the timescale directive. It
detects if some modules have no timescale, or if modules inherit timescale
from another file. Both probably mean that timescales are inconsistent,
and simulation timing can be confusing and dependent on compilation order.
* infloop
This enables warnings for always statements that may have runtime infinite
loops (i.e. has paths with zero or no delay). This class of warnings is
not included in -Wall and hence does not have a no- variant. A fatal error
message will always be printed when the compiler can determine that there
will definitely be an infinite loop (all paths have no or zero delay).
When you suspect an always statement is producing a runtine infinite loop,
use this flag to find the always statements that need to have their logic
verified. it is expected that many of the warnings will be false
positives, since the code treats the value of all variables and signals as
indeterninite.
* sensitivity-entire-vector
This enables warnings for when a part select with an "always @*" statement
results in the entire vector being added to the implicit sensitivity
list. Although this behavior is prescribed by the IEEE standard, it is not
what might be expected and can have performance implications if the vector
is large.
* sensitivity-entire-array
This enables warnings for when a word select with an "always @*" statement
results in the entire array being added to the implicit sensitivity
list. Although this behavior is prescribed by the IEEE standard, it is not
what might be expected and can have performance implications if the array
is large.
* floating-nets
This enables warnings for nets that are present but have no drivers.
This flag was added in version 11.0 or later (and is in the master branch
as of 2015-10-01).
* -y<libdir>
Append the directory to the library module search path. When the compiler
finds an undefined module, it looks in these directories for files with the
right name.
* -Y<suf>
Appends suf to the list of file extensions that are used to resolve an
undefined module to a file name. Should be specified before any -y flag. For
example, this command::
% iverilog -Y .sv -y sources src.v
will try to resolve any undefined module m by looking into the directory
sources and checking if there exist files named m.v or m.sv.
Preprocessor Flags
------------------
These flags control the behavior of the preprocessor. They are similar to
flags for the typical "C" compiler, so C programmers will find them familiar.
* -E
This flag is special in that it tells the compiler to only run the
preprocessor. This is useful for example as a way to resolve preprocessing
for other tools. For example, this command::
% iverilog -E -ofoo.v -DKEY=10 src1.v src2.v
runs the preprocessor on the source files src1.v and src2.v and produces the
single output file foo.v that has all the preprocessing (including header
includes and ifdefs) processed.
* -D<macro>
Assign a value to the macro name. The format of this flag is one of::
-Dkey=value
-Dkey
The key is defined to have the given value. If no value is given, then it is
assumed to be "1". The above examples are the same as these defines in
Verilog source::
`define key value
`define key
* -I<path>
Append directory <path> to list of directories searched for Verilog include
files. The -I switch may be used many times to specify several directories
to search, the directories are searched in the order they appear on the
command line.
Elaboration Flags
-----------------
These are flags that pass information to the elaboration steps.
* -P<symbol>=<value>
Define a parameter using the defparam behavior to override a parameter
values. This can only be used for parameters of root module instances.
* -s <topmodule>
Specify the top level module to elaborate. Icarus Verilog will by default
choose modules that are not instantiated in any other modules, but sometimes
that is not sufficient, or instantiates too many modules. If the user
specifies one or more root modules with "-s" flags, then they will be used
as root modules instead.
* -Tmin, -Ttyp, -Tmax
Select the timings to use. The Verilog language allows many timings to be
specified as three numbers, min:typical:max, but for simulation you need to
choose which set to use. The "-Tmin" flag tells the compiler to at
elaboration time choose "min" times. The default is "-Ttyp".
Target Flags
------------

167
_sources/usage/getting_started.rst.txt Normal file
View File

@ -0,0 +1,167 @@
Getting Started With Icarus Verilog
===================================
Before getting started with actual examples, here are a few notes on
conventions. First, command lines and sequences take the same arguments on all
supported operating environments, including Linux, Windows and the various
Unix systems. When an example command is shown in a figure, the generic prompt
character "% " takes the place of whatever prompt string is appropriate for
your system. Under Windows, the commands are invoked in a command window.
Second, when creating a file to hold Verilog code, it is common to use the
".v" or the ".vl" suffix. This is not a requirement imposed by Icarus Verilog,
but a useful convention. Some people also use the suffixes ".ver" or even
".vlg". Examples in this book will use the ".v" suffix.
So let us start. Given that you are going to use Icarus Verilog as part of
your design process, the first thing to do as a designer is learn how to
compile and execute even the most trivial design. For the purposes of
simulation, we use as our example the most trivial simulation, a simple Hello,
World program.
.. code-block:: verilog
module hello;
initial
begin
$display("Hello, World");
$finish ;
end
endmodule
Use a text editor to place the program in a text file, hello.v, then compile
this program with the command::
% iverilog -o hello hello.v
The results of this compile are placed into the file "hello", because the "-o"
flag tells the compiler where to place the compiled result. Next, execute the
compiled program like so::
% vvp hello
Hello, World
And there it is, the program has been executed. So what happened? The first
step, the "iverilog" command, read and interpreted the source file, then
generated a compiled result. The compiled form may be selected by command line
switches, but the default is the "vvp" format, which is actually run later, as
needed. The "vvp" command of the second step interpreted the "hello" file from
the first step, causing the program to execute.
The "iverilog" and "vvp" commands are the most important commands available to
users of Icarus Verilog. The "iverilog" command is the compiler, and the "vvp"
command is the simulation runtime engine. What sort of output the compiler
actually creates is controlled by command line switches, but normally it
produces output in the default vvp format, which is in turn executed by the
vvp program.
As designs get larger and more complex, they gain hierarchy in the form of
modules that are instantiated within others, and it becomes convenient to
organize them into multiple files. A common convention is to write one
moderate sized module per file (or group related tiny modules into a single
file) then combine the files of the design together during compilation. For
example, the counter model in counter.v
.. code-block:: verilog
module counter(out, clk, reset);
parameter WIDTH = 8;
output [WIDTH-1 : 0] out;
input clk, reset;
reg [WIDTH-1 : 0] out;
wire clk, reset;
always @(posedge clk or posedge reset)
if (reset)
out <= 0;
else
out <= out + 1;
endmodule // counter
and the test bench in counter_tb.v
.. code-block:: verilog
module test;
/* Make a reset that pulses once. */
reg reset = 0;
initial begin
# 17 reset = 1;
# 11 reset = 0;
# 29 reset = 1;
# 11 reset = 0;
# 100 $stop;
end
/* Make a regular pulsing clock. */
reg clk = 0;
always #5 clk = !clk;
wire [7:0] value;
counter c1 (value, clk, reset);
initial
$monitor("At time %t, value = %h (%0d)",
$time, value, value);
endmodule // test
are written into different files.
The "iverilog" command supports multi-file designs by two methods. The
simplest is to list the files on the command line::
% iverilog -o my_design counter_tb.v counter.v
% vvp my_design
This command compiles the design, which is spread across two input files, and
generates the compiled result into the "my_design" file. This works for small
to medium sized designs, but gets cumbersome when there are lots of files.
Another technique is to use a commandfile, which lists the input files in a
text file. For example, create a text file called "file_list.txt" with the
files listed one per line::
counter.v
counter_tb.v
Then compile and execute the design with a command like so::
% iverilog -o my_design -c file_list.txt
% vvp my_design
The command file technique clearly supports much larger designs simply by
saving you the trouble of listing all the source files on the command
line. Name the files that are part of the design in the command file and use
the "-c" flag to tell iverilog to read the command file as a list of Verilog
input files.
As designs get more complicated, they almost certainly contain many Verilog
modules that represent the hierarchy of your design. Typically, there is one
module that instantiates other modules but is not instantiated by any other
modules. This is called a root module. Icarus Verilog chooses as roots (There
can be more than one root) all the modules that are not instantiated by other
modules. If there are no such modules, the compiler will not be able to choose
any root, and the designer must use the "-sroot" switch to identify the root
module, like this::
% iverilog -s main -o hello hello.v
If there are multiple candidate roots, all of them will be elaborated. The
compiler will do this even if there are many root modules that you do not
intend to simulate, or that have no effect on the simulation. This can happen,
for example, if you include a source file that has multiple modules, but are
only really interested in some of them. The "-s" flag identifies a specific
root module and also turns off the automatic search for other root
modules. You can use this feature to prevent instantiation of unwanted roots.
As designs get even larger, they become spread across many dozens or even
hundreds of files. When designs are that complex, more advanced source code
management techniques become necessary. These are described in later chapters,
along with other advanced design management techniques supported by Icarus
Verilog.

118
_sources/usage/gtkwave.rst.txt Normal file
View File

@ -0,0 +1,118 @@
Waveforms With GTKWave
======================
GTKWave is a VCD waveform viewer based on the GTK library. This viewer support
VCD and LXT formats for signal dumps. GTKWAVE is available on github
`here <https://github.com/gtkwave/gtkwave>`_. Most Linux distributions already
include gtkwave prepackaged.
.. image:: GTKWave_Example2.png
Generating VCD/FST files for GTKWAVE ------------------------------------
Waveform dumps are written by the Icarus Verilog runtime program vvp. The user
uses $dumpfile and $dumpvars system tasks to enable waveform dumping, then the
vvp runtime takes care of the rest. The output is written into the file
specified by the $dumpfile system task. If the $dumpfile call is absent, the
compiler will choose the file name dump.vcd or dump.lxt or dump.fst, depending
on runtime flags. The example below dumps everything in and below the test
module:
.. code-block:: verilog
// Do this in your test bench
initial
begin
$dumpfile("test.vcd");
$dumpvars(0,test);
end
By default, the vvp runtime will generate VCD dump output. This is the default
because it is the most portable. However, when using gtkwave, the FST output
format is faster and most compact. Use the "-fst" extended argument to
activate LXT output. For example, if your compiled output is written into the
file "foo.vvp", the command:
.. code-block:: console
% vvp foo.vvp -fst <other-plusargs>
will cause the dumpfile output to be written in FST format. Absent any
specific $dumpfile command, this file will be called dump.fst, which can be
viewed with the command:
.. code-block:: console
% gtkwave dump.fst
A Working Example
-----------------
First, the design itself:
.. code-block:: verilog
module counter(out, clk, reset);
parameter WIDTH = 8;
output [WIDTH-1 : 0] out;
input clk, reset;
reg [WIDTH-1 : 0] out;
wire clk, reset;
always @(posedge clk)
out <= out + 1;
always @reset
if (reset)
assign out = 0;
else
deassign out;
endmodule // counter
Then the simulation file:
.. code-block:: verilog
module test;
/* Make a reset that pulses once. */
reg reset = 0;
initial begin
$dumpfile("test.vcd");
$dumpvars(0,test);
# 17 reset = 1;
# 11 reset = 0;
# 29 reset = 1;
# 5 reset =0;
# 513 $finish;
end
/* Make a regular pulsing clock. */
reg clk = 0;
always #1 clk = !clk;
wire [7:0] value;
counter c1 (value, clk, reset);
initial
$monitor("At time %t, value = %h (%0d)",
$time, value, value);
endmodule // test
Compile, run, and view waveforms with these commands:
.. code-block:: console
% iverilog -o dsn counter_tb.v counter.v
% vvp dsn
% gtkwave test.vcd &
Click on the 'test', then 'c1' in the top left box on GTKWAVE, then drag the
signals to the Signals box. You will be able to add signals to display,
scanning by scope.

173
_sources/usage/icarus_verilog_extensions.rst.txt Normal file
View File

@ -0,0 +1,173 @@
Icarus Verilog Extensions
=========================
Icarus Verilog supports certain extensions to the baseline IEEE 1364
standard. Some of these are picked from extended variants of the
language, such as SystemVerilog, and some are expressions of internal
behavior of Icarus Verilog, made available as a tool debugging aid.
Don't use any of these extensions if you want to keep your code portable
across other Verilog compilers.
System Functions
----------------
``$is_signed(<expr>)``
^^^^^^^^^^^^^^^^^^^^^^
This function returns 1 if the expression contained is signed, or 0 otherwise.
This is mostly of use for compiler regression tests.
``$bits(<expr>)``, ``$sizeof(<expr>)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The ``$bits`` system function returns the size in bits of the expression that
is its argument. The result of this function is undefined if the argument
doesn't have a self-determined size.
The ``$sizeof`` system function is deprecated in favour of ``$bits``, which is
the same thing, but included in the SystemVerilog definition.
``$simtime()``
^^^^^^^^^^^^^^
This returns as a 64bit value the simulation time, unscaled by the time units
of the local scope. This is different from the ``$time`` and ``$stime``
functions which return the scaled times. This function is added for regression
testing of the compiler and run time, but can be used by applications who
really want the simulation time.
Note that the simulation time can be confusing if there are lots of different
```timescales`` within a design. It is not in general possible to predict
what the simulation precision will turn out to be.
``$mti_random()``, ``$mti_dist_uniform``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
These functions are similar to the IEEE 1364 standard ``$random`` functions,
but they use the Mersenne Twister (MT19937) algorithm. This is considered an
excellent random number generator, but does not generate the same sequence as
the standardized ``$random``.
System Tasks
------------
``$readmempath``
^^^^^^^^^^^^^^^^
The ``$readmemb`` and ``$readmemh`` system tasks read text files that contain
data values to populate memories. Normally, those files are found in a current
working directory. The ``$readmempath()`` system task can be used to create a
search path for those files. For example:
.. code-block:: verilog
reg [7:0] mem [0:7];
initial begin
$readmemh("datafile.txt", mem);
end
This assumes that "datafile.txt" is in the current working directory where
the ``vvp`` command is running. But with the ``$readmempath``, one can specify
a search path:
.. code-block:: verilog
reg [7:0] mem [0:7];
initial begin
$readmempath(".:alternative:/global/defaults");
$readmemh("datafile.txt", mem);
end
In this example, "datafile.txt" is searched for in each of the directories
in the above list (separated by ":" characters). The first located instance
is the one that is used. So for example, if "./datafile.txt" exists, then it
is read instead of "/global/defaults/datafile.txt" even if the latter exists.
``$finish_and_return(code)``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
This task operates the same as the ``$finish`` system task, but adds the
feature of specifying an exit code for the interpreter. This can be useful in
automated test environments to indicate whether the simulation finished with
or without errors.
Extended Verilog Data Types
---------------------------
This feature is turned on by the generation flag "-gxtypes" and turned
off by the generation flag "-gno-xtypes". It is turned on by default.
Icarus Verilog adds support for extended data types. This extended
type syntax is based on a proposal by Cadence Design Systems,
originally as an update to the IEEE 1364 standard. Icarus Verilog
currently only takes the new primitive types from the proposal.
SystemVerilog provides the same functionality using somewhat different
syntax. This extension is maintained for backwards compatibility.
- Types
Extended data types separates the concept of net/variable from the
data type. Both nets and variables can declared with any data
type. The primitive types available are::
logic - The familiar 0, 1, x and z, optionally with strength.
bool - Limited to only 0 and 1
real - 64-bit real values
Nets with logic type may have multiple drivers with strength, and the
value is resolved the usual way. Only logic values may be driven to
logic nets, so bool values driven onto logic nets are implicitly
converted to logic.
Nets with any other type may not have multiple drivers. The compiler
should detect the multiple drivers and report an error.
- Declarations
The declaration of a net is extended to include the type of the wire,
with the syntax::
wire <type> <wire-assignment-list>... ;
The <type>, if omitted, is taken to be logic. The "wire" can be any of
the net keywords. Wires can be logic, bool, real, or vectors of logic
or bool. Some valid examples::
wire real foo = 1.0;
tri logic bus[31:0];
wire bool addr[23:0];
... and so on.
The declarations of variables is similar. The "reg" keyword is used to
specify that this is a variable. Variables can have the same data
types as nets.
- Ports
Module and task ports in standard Verilog are restricted to logic
types. This extension removes that restriction, allowing any of
the above types to pass through the port consistent with the
continuous assignment connectivity that is implied by the type.
- Expressions
Expressions in the face of real values is covered by the baseline
Verilog standard.
The bool type supports the same operators as the logic type, with the
obvious differences imposed by the limited domain.
Comparison operators (not case compare) return logic if either of
their operands is logic. If both are bool or real (including mix of
bool and real) then the result is bool. This is because comparison of
bools and reals always return exactly true or false.
Case comparison returns bool. This differs from baseline Verilog,
which strictly speaking returns a logic, but only 0 or 1 values.
Arithmetic operators return real if either of their operands is real,
otherwise they return logic if either of their operands is logic. If
both operands are bool, they return bool.

438
_sources/usage/icarus_verilog_quirks.rst.txt Normal file
View File

@ -0,0 +1,438 @@
Icarus Verilog Quirks
=====================
This is a list of known quirks that are presented by Icarus Verilog. The idea
of this chapter is to call out ways that Icarus Verilog differs from the
standard, or from other implementations.
This is NOT AN EXHAUSTIVE LIST. If something is missing from this list, let us
know and we can add documentation.
Unsized Numeric Constants are Not Limited to 32 Bits
----------------------------------------------------
The Verilog standard allows Verilog implementations to limit the size of
unsized constants to a bit width of at least 32. That means that a constant
17179869183 (``36'h3_ffff_ffff``) may overflow some compilers. In fact, it
is common to limit these values to 32 bits. However, a compiler may just as
easily choose another width limit, for example 64 bits. That value is
equally good.
However, it is not required that an implementation truncate at 32 bits, and
in fact Icarus Verilog does not truncate at all. It will make the unsized
constant as big as it needs to be to hold the value accurately. This is
especially useful in situations like this;
.. code-block:: verilog
reg [width-1:0] foo = 17179869183;
The programmer wants the constant to take on the width of the reg, which in
this example is parameterized. Since constant sizes cannot be parameterized,
the programmer ideally gives an unsized constant, which the compiler then
expands/contracts to match the l-value.
Also, by choosing to not ever truncate, Icarus Verilog can handle code written
for a 64 bit compiler as easily as for a 32 bit compiler. In particular, any
constants that the user does not expect to be arbitrarily truncated by their
compiler will also not be truncated by Icarus Verilog, no matter what that
other compiler chooses as a truncation point.
Unsized Expressions
-------------------
Icarus Verilog classes any expression containing an unsized numeric constant
or unsized parameter value that is not part of a self-determined operand as
an unsized expression. When calculating the bit width of an unsized expression,
it extends the width of the expression to avoid arithmetic overflow or
underflow; in other words, the expression width will be made large enough to
represent any possible arithmetic result of the expression. If the expression
contains operations that do not follow the normal rules of arithmetic (e.g. an
explicit or implicit cast between signed and unsigned values), the expression
width will be extended to at least the width of an integer.
An exception to the above is made if the expression contains a shift or power
operator with a right hand operand that is a non-constant unsized expression.
In this case any expansion of the expression width due to that operation is
limited to the width of an integer, to avoid excessive expression widths
(without this, an expression such as ``2**(i-1)``, where ``i`` is an integer,
would be expanded to 2\**33 bits).
The above behaviour is a deviation from the Verilog standard, which states
that when calculating an expression width, the width of an unsized constant
number is the same as the width of an integer. If you need strict standard
compliance (for compatibility with other EDA tools), then the compiler has
a command line option, ``-gstrict-expr-width``, which disables the special
treatment of unsized expressions. With this option, the compiler will output
a warning message if an unsized numeric constant is encountered that cannot
be represented in integer-width bits and will truncate the value.
If you are simulating synthesisable code, it is recommended that the
``-gstrict-expr-width`` option is used, as this eliminates a potential
source of synthesis vs. simulation mismatches.
Unsized Parameters
------------------
Icarus Verilog classes any parameter declaration that has no explicit or
implicit range specification as an unsized parameter declaration. When
calculating the bit width of the final value expression for the parameter,
it follows the same rules as it does for unsized expressions, regardless of
whether or not the expression contains any unsized numeric constants.
If the final value expression for an unsized parameter is an unsized
expression (i.e. does contain unsized numeric constants), any subsequent use
of that parameter will be treated as if it was an unsized numeric constant.
If not, it will be treated as if it was a numeric constant of the appropriate
size. For example, with the declarations:
.. code-block:: verilog
localparam Value1 = 'd3 + 'd2;
localparam Value2 = 2'd3 + 2'd2;
any subsequent use of ``Value1`` will be treated as if the programmer had
written ``'d5`` and any subsequent use of ``Value2`` will be treated as if
the programmer had written ``3'd5``. In particular, note that ``Value2`` can
be used as a concatenation operand, but ``Value1`` cannot.
The above behaviour is a deviation from the Verilog standard. As for
unsized expressions, if you need strict standard compliance. use the
``-gstrict-expr-width`` compiler option.
Unsized Expressions as Arguments to Concatenation
-------------------------------------------------
The Verilog standard clearly states in 4.1.14:
"Unsized constant numbers shall not be allowed in concatenations. This
is because the size of each operand in the concatenation is needed to
calculate the complete size of the concatenation."
So for example the expression ``{1'b0, 16}`` is clearly illegal. It also stands
to reason that ``{1'b0, 15+1}`` is illegal, for exactly the same justification.
What is the size of the expression (15+1)? Furthermore, it is reasonable to
expect that (16) and (15+1) are exactly the same so far as the compiler is
concerned.
Unfortunately, Cadence seems to feel otherwise. In particular, it has been
reported that although ``{1'b0, 16}`` causes an error, ``{1'b0, 15+1}`` is
accepted. Further testing shows that any expression other than a simple
unsized constant is accepted there, even if all the operands of all the
operators that make up the expression are unsized integers.
This is a semantic problem. Icarus Verilog doesn't limit the size of integer
constants. This is valid as stated in 2.5.1 Note 3:
"The number of bits that make up an unsized number (which is a simple
decimal number or a number without the size specification) shall be
**at least** 32." [emphasis added]
Icarus Verilog will hold any integer constant, so the size will be as large as
it needs to be, whether that is 64 bits, 128 bits, or more. With this in mind,
what is the value of these expressions?
.. code-block:: verilog
{'h1_00_00_00_00}
{'h1 << 32}
{'h0_00_00_00_01 << 32}
{'h5_00_00_00_00 + 1}
These examples show that the standard is justified in requiring that the
operands of concatenation have size. The dispute is what it takes to cause
an expression to have a size, and what that size is. Verilog-XL claims that
(16) does not have a size, but (15+1) does. The size of the expression (15+1)
is the size of the adder that is created, but how wide is the adder when
adding unsized constants?
One might note that the quote from section 4.1.14 says "Unsized constant
numbers shall not be allowed." It does not say "Unsized expressions...", so
arguably accepting (15+1) or even (16+0) as an operand to a concatenation is
not a violation of the letter of the law. However, the very next sentence of
the quote expresses the intent, and accepting (15+1) as having a more defined
size then (16) seems to be a violation of that intent.
Whatever a compiler decides the size is, the user has no way to predict it,
and the compiler should not have the right to treat (15+1) any differently
then (16). Therefore, Icarus Verilog takes the position that such expressions
are unsized and are not allowed as operands to concatenations. Icarus Verilog
will in general assume that operations on unsized numbers produce unsized
results. There are exceptions when the operator itself does define a size,
such as the comparison operators or the reduction operators. Icarus Verilog
will generate appropriate error messages.
Scope of Macro Defines Doesn't Extend into Libraries
----------------------------------------------------
Icarus Verilog does preprocess modules that are loaded from libraries via the
``-y`` mechanism to substitute macros and load includes. However, the only
macros defined during compilation of an automatically loaded library module
file are those that it defines itself (or includes) or that are defined on the
command line or in the command file. Specifically, macros defined in the non-
library source files are not remembered when the library module is loaded, and
macros defined in a library module do not escape into the rest of the design.
This is intentional. If it were otherwise, then compilation results might vary
depending on the order that libraries are loaded, and that is unacceptable.
For example, given sample library module ``a.v``:
.. code-block:: verilog
`define MACRO_A 1
module a(input x);
always @(x) $display("x=",x);
endmodule
and sample library module ``b.v``:
.. code-block:: verilog
module b(input y);
`ifdef MACRO_A
always @(y) $display("MACRO_A is defined",,y);
`else
always @(y) $display("MACRO_A is NOT defined",,y);
`endif
endmodule
If a program instantiates both of these modules, there is no way to know
which will be loaded first by the compiler, so if the definition of
``MACRO_A`` in ``a.v`` were to escape, then there is no way to predict or
control whether ``MACRO_A`` is defined when ``b.v`` is processed. So the
preprocessor processes automatic library module files as if they are in
their own compilation unit, and you can know that ``MACRO_A`` will not be
defined in ``b.v`` unless it is defined on the command line (a ``-D`` flag)
or in the command file (a ``+define+`` record.)
Of course if ``a.v`` and ``b.v`` were listed in the command file or on the
command line, then the situation is different; the order is clear. The files
are processed as if they were concatenated in the order that they are listed
on the command line. The non-library modules are all together in a main
compilation unit, and they are all processed before any library modules are
loaded.
It is said that some commercial compilers do allow macro definitions to span
library modules. That's just plain weird. However, there is a special case
that Icarus Verilog does handle. Preprocessor definitions that are made in
files explicitly listed on the command line or in the command file, do pass
into implicitly loaded library files. For example, given the source file
``x.v``:
.. code-block:: verilog
module main;
reg foo;
b dut(foo);
endmodule
`define MACRO_A
and the library module file ``b.v`` described above, the situation is well
defined, assuming the ``x.v`` file is listed on the command line or in the
command file. The library module will receive the ``MACRO_A`` definition
from the last explicitly loaded source file. The position of the define of
``MACRO_A`` in the explicitly loaded source files does not matter, as all
explicitly loaded source files are preprocessed before any library files
are loaded.
Continuous Assign L-Values Can Implicit-Define Wires
----------------------------------------------------
The IEEE 1364-2001 standard, Section 3.5, lists the cases where nets may be
implicitly created. These include:
- identifier is a module port
- identifier is passed as a port to a primitive or module
This does not seem to include continuous assignment l-values (or r-values)
so the standard does not justify allowing implicit declarations of nets by
continuous assignment.
However, it has been reported that many Verilog compilers, including the big
name tools, do allow this. So, Icarus Verilog will allow it as well, as an
extension. If ``-gxtypes`` (the default) is used, this extension is enabled.
To turn off this behavior, use the ``-gno-xtypes`` flag.
Dumping Array Words (``$dumpvars``)
-----------------------------------
Icarus has the ability to dump individual array words. They are only dumped
when explicitly passed to $dumpvars. They are not dumped by default. For
example given the following:
.. code-block:: verilog
module top;
reg [7:0] array [2:0];
initial begin
$dumpvars(0, array[0], array[1]);
...
end
endmodule
``array[0]`` and ``array[1]`` will be dumped whenever they change value. They
will be displayed as an escaped identifier and GTKWave fully supports this.
Note that this is an implicitly created escaped identifier that could conflict
with an explicitly created escaped identifier. You can automate adding the
array word by adding an index definition
.. code-block:: verilog
integer idx;
and replacing the previous $dumpvars statement with
.. code-block:: verilog
for (idx = 0; idx < 2; idx = idx + 1) $dumpvars(0, array[idx]);
This will produce the same results as the previous example, but it is much
easier to specify/change which elements are to be dumped. One important note
regarding this syntax. Most system tasks/functions keep the variable selection
(for this case it is a variable array word selection) context. If ``$dumpvars``
did this then all callback created would point to this element and would use
the same index which for the example above would have the value 2. This is
certainly not what is desired and for this special case when ``$dumpvars``
executes it uses the current index value to create a constant array selection
and that is monitored instead of the original variable selection.
Referencing Declarations Within an Unnamed Generate Block
---------------------------------------------------------
The IEEE 1364-2005 standard permits generate blocks to be unnamed, but states:
"If the generate block selected for instantiation is not named, it still
creates a scope; but the declarations within it cannot be referenced using
hierarchical names other than from within the hierarchy instantiated by the
generate block itself."
The standard later defines a scheme for automatically naming the unnamed
scopes for use with external interfaces.
Icarus Verilog implements the defined automatic naming scheme, but does not
prevent the automatically generated names being used in a hierarchical
reference. This behaviour is harmless - the automatically generated names are
guaranteed to be unique within the enclosing scope, so there is no possibility
of confusion with explicit scope names. However, to maintain code portability,
it is recommended that this behavior is not exploited.
``%g/%G`` Format Specifiers
---------------------------
In the IEEE 1364-2001 standard there is a general statement that the real
number format specifiers will use the full formatting capabilities of C.
This is then followed by an example that describes ``%10.3g``. The example
description would be correct for the ``%e`` format specifier which should
always have three fractional digits, but the ``%g`` format specifier does
not work that way. For it the ``.3`` specifies that there will be three
significant digits. What this means is that ``%g`` will always produce one
less significant digit than ``%e`` and will only match the output from ``%f``
for certain values. For example:
.. code-block:: verilog
module top_level;
real rval;
initial begin
rval = 1234567890;
$display("This is g and e: %10.3g, %10.3e.", rval, rval);
rval = 0.1234567890;
$display("This is g and f: %10.3g, %10.3f.", rval, rval);
rval = 1.234567890;
$display("This is more g and f: %10.3g, %10.3f.", rval, rval);
end
endmodule // top_level
will produce the following output:
.. code-block:: verilog
This is g and e: 1.23e+09, 1.235e+09.
This is g and f: 0.123, 0.123.
This is more g and f: 1.23, 1.235.
``%t`` Time Format Specifier Can Specify Width
----------------------------------------------
Standard Verilog does not allow width fields in the ``%t`` formats of display
strings. For example, this is illegal:
.. code-block:: verilog
$display("Time is %0t", $time);
Standard Verilog instead relies on the ``$timeformat`` to completely specify
the format.
Icarus Verilog allows the programmer to specify the field width. The ``%t``
format in Icarus Verilog works exactly as it does in standard Verilog.
However, if the programmer chooses to specify a minimum width (i.e., ``%5t``),
then for that display Icarus Verilog will override the ``$timeformat`` minimum
width and use the explicit minimum width.
``%v`` Format Specifier Can Display Vectors
-------------------------------------------
The IEEE 1364-2005 standard limits the ``%v`` specifier in display strings to
work only with a single bit. Icarus Verilog extends that to support displaying
the strength of vectors. The output is a strength specifier for each bit of the
vector, with underscore characters separating each bit, e.g. ``St0_St1_Pu1_HiZ``.
Most other tools will just print the strength of the least significant bit of
a vector, so this may give different output results for code that otherwise
works fine.
Assign/Deassign and Force/Release of Bit/Part Selects
-----------------------------------------------------
Icarus Verilog allows as an extension the assign/deassign and force/release
of variable bit and part selects in certain cases. This allows the Verilog
test bench writer to assign/deassign for example single bits of a variable
(register, etc.). Other tools will report this as an error.
``repeat`` Statement is Sign Aware
----------------------------------
The standard does not specify what to do for this case, but it does say what
a repeat event control should do. In Icarus Verilog the ``repeat`` statement
is consistent with the repeat event control definition. If the argument is
signed and is a negative value this will be treated the same as an argument
value of 0.
Built-in System Functions May Be Evaluated at Compile Time
----------------------------------------------------------
Certain of the system functions have well-defined meanings, so can
theoretically be evaluated at compile-time, instead of using runtime VPI
code. Doing so means that VPI cannot override the definitions of functions
handled in this manner. On the other hand, this makes them synthesizable,
and also allows for more aggressive constant propagation. The functions
handled in this manner are:
- ``$bits``
- ``$signed``
- ``$sizeof``
- ``$unsigned``
Implementations of these system functions in VPI modules will be ignored.
``vpiScope`` Iterator on ``vpiScope`` Objects
---------------------------------------------
In the VPI, the normal way to iterate over ``vpiScope`` objects contained
within a ``vpiScope`` object, is the ``vpiInternalScope`` iterator. Icarus
Verilog adds support for the ``vpiScope`` iterator of a ``vpiScope`` object,
that iterates over *everything* that is contained in the current scope. This
is useful in cases where one wants to iterate over all the objects in a scope
without iterating over all the contained types explicitly.
Time 0 Race Resolution
----------------------
Combinational logic is routinely modelled using always blocks. However, this
can lead to race conditions if the inputs to the combinational block are
initialized in initial statements. Icarus Verilog slightly modifies time 0
scheduling by arranging for always statements with ANYEDGE sensitivity lists
to be scheduled before any other threads. This causes combinational always
blocks to be triggered when the values in the sensitivity list are initialized
by initial threads.

25
_sources/usage/index.rst.txt Normal file
View File

@ -0,0 +1,25 @@
Icarus Verilog Usage
====================
This section contains documents to help support Icarus Verilog users.
.. toctree::
:maxdepth: 1
installation
getting_started
simulation
command_line_flags
command_files
verilog_attributes
ivlpp_flags
vvp_flags
vvp_debug
vvp_library
vhdlpp_flags
gtkwave
vpi
icarus_verilog_extensions
icarus_verilog_quirks
reporting_issues

193
_sources/usage/installation.rst.txt Normal file
View File

@ -0,0 +1,193 @@
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
needed when checking for basic errors with valgrind. ::
--enable-libvvp
The vvp progam is built as a small stub linked to a shared library,
libvvp.so, that may be linked with other programs so that they can host
a vvp simulation. ::
--enable-libveriuser
PLI version 1 (the ACC and TF routines) were deprecated in IEEE 1364-2005.
These are supported in Icarus Verilog by the libveriuser library and cadpli
module. Starting with v13, these will only be built if this option is used.
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".
Cross-Compiling for Windows
---------------------------
These are instructions for building Icarus Verilog binaries for
Windows using mingw cross compiler tools on Linux.
To start with, you need the mingw64-cross-* packages for your linux
distribution, which gives you the x86_64-w64-mingw32-* commands
installed on your system. Installing the cross environment is outside
the scope of this writeup.
First, configure with this command::
$ ./configure --host=x86_64-w64-mingw32
This generates the Makefiles needed to cross compile everything with
the mingw32 compiler. The configure script will generate the command
name paths, so long as commands line x86_64-w64-mingw32-gcc
et. al. are in your path.
Next, compile with the command::
$ make
The configure generated the cross compiler flags, but there are a few
bits that need to be compiled with the native compiler. (version.exe
for example is used by the build process but is not installed.) The
configure script should have gotten all that right.
Compiling for Windows using MSYS2
---------------------------------
There is a MSYS2 build recipe which you can find under `msys2/` in the
repository. The accompanying README file provides further details.

146
_sources/usage/ivlpp_flags.rst.txt Normal file
View File

@ -0,0 +1,146 @@
IVLPP - 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.

76
_sources/usage/reporting_issues.rst.txt Normal file
View File

@ -0,0 +1,76 @@
Reporting Issues
================
The developers of and contributers to Icarus Verilog use github to track
issues and to create patches for the product. If you believe you have found a
problem, use the Issues tracker at the
`Icarus Verilog github page <https://github.com/steveicarus/iverilog>`_.
You may browse the bugs database for existing
bugs that may be related to yours. You might find that your bug has
already been fixed in a later release or snapshot. If that's the case,
then you are set.
On the main page, you will find a row of selections near the top. Click the
`Issues <https://github.com/steveicarus/iverilog/issues>`_ link to get to the
list of issues, open and closed. You will find a friendly green button where
you can create a new issue. You will be asked to create a title for your
issue, and to write a detailed description of your issue. Please include
enough information that anyone who sees your issue can understand and
reproduce it.
Good Issue Reporting
--------------------
Before an error can be fixed, one needs to understand what the problem
is. Try to explain what is wrong and why you think it is wrong. Please
try to include sample code that demonstrates the problem.
One key characteristic of a well reported issue is a small sample program that
demonstrates the issue. The smaller the better. No developer wants to wade
through hundreds of lines of working Verilog to find the few lines that cause
trouble, so if you can get it down to a 10 line sample program, then your
issue will be far more likely to be addressed.
Also, include the command line you use to invoke the compiler. For
example::
iverilog -o foo.out -tvvp foo.v
iverilog foo.vl -s starthere
Be prepared to have a conversation about your issue. More often then you would
expect, the issue turns out to be a bug in your program, and the person
looking into your issue may point out a bug in your code. You learn something,
and we all win. We are not always correct, though, so if we are incorrect,
help us see our error, if that's appropriate. If we don't understand what your
issue is, we will label your issue with a "Need info" label, and if we never
hear from you again, your issue may be closed summarily.
If you can submit a complete, working program that we can use in the
regression test suite, then that is the best. Check out the existing tests in
the regression test suite to see how they are structured. If you have a
complete test that can go into the test suite, then that saves everyone a lot
of grief, and again you increase the odds that your issue will be addressed.
How To Create A Pull Request
----------------------------
Bug reports with patches/PRs are very welcome. Please also add a new test case in the regression test suite to prevent the bug from reappearing.
If you are editing the source, you should be using the latest
version from git. Please see the developer documentation for more
detailed instructions -- :doc:`Getting Started as a Contributer <getting_started>` .
COPYRIGHT ISSUES
Icarus Verilog is Copyright (c) 1998-2024 Stephen Williams except
where otherwise noted. Minor patches are covered as derivative works
(or editorial comment or whatever the appropriate legal term is) and
folded into the rest of ivl. However, if a submission can reasonably
be considered independently copyrightable, it's yours and I encourage
you to claim it with appropriate copyright notices. This submission
then falls under the "otherwise noted" category.
I must insist that any copyright material submitted for inclusion
include the GPL license notice as shown in the rest of the source.

495
_sources/usage/simulation.rst.txt Normal file
View File

@ -0,0 +1,495 @@
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
.. code-block:: verilog
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
.. code-block:: verilog
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
.. code-block:: verilog
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
.. code-block:: verilog
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.

35
_sources/usage/verilog_attributes.rst.txt Normal file
View File

@ -0,0 +1,35 @@
Verilog Attributes
==================
This is a description of the various attributes that the Icarus Verilog tools
understand. The attributes are attached to objects using the "(\* ... \*)"
syntax, which is described by the Verilog LRM.
Attributes that start with "ivl\_" are Icarus Verilog specific are are probably
ignored by other tools.
Optimizations
-------------
* ivl_do_not_elide (snapshot 20140619 or later)
This applies to signals (i.e. reg, wire, etc.) and tells the optimizer to
not elide the signal, even if it is not referenced anywhere in the
design. This is useful if the signal is for some reason only accessed by
VPI/PLI code.
Synthesis
---------
* ivl_synthesis_cell
Applied to a module definition, this tells the synthesizer that the module
is a cell. The synthesizer does not descend into synthesis cells, as they
are assumed to be primitives in the target technology.
* ivl_synthesis_off
Attached to an "always" statement, this tells the synthesizer that the
statement is not to be synthesized. This may be useful, for example, to tell
the compiler that a stretch of code is test-bench code.

59
_sources/usage/vhdlpp_flags.rst.txt Normal file
View File

@ -0,0 +1,59 @@
vhdlpp Command Line Flags
=========================
* -D <token>
Debug flags. The token can be:
* yydebug | no-yydebug
* entities=<path>
* -L <path>
Library path. Add the directory name to the front of the library
search path. The library search path is initially empty.
* -V
Display version on stdout
* -v
Verbose: Display version on stderr, and enable verbose messages to
stderr.
* -w <path>
Work path. This is the directory where the working directory is.
Library Format
--------------
The vhdlpp program stores libraries as directory that contain
packages. The name of the directory (in lower case) is the name of the
library as used on the "import" statement. Within that library, there
are packages in files named <foo>.pkg. For example::
<directory>/...
sample/...
test1.pkg
test2.pkg
bar/...
test3.pkg
Use the "+vhdl-libdir+<directory>" record in a config file to tell
Icarus Verilog that <directory> is a place to look for libraries. Then
in your VHDL code, access packages like this::
library sample;
library bar;
use sample.test1.all;
use bar.test3.all;
The \*.pkg files are just VHDL code containing only the package with
the same name. When Icarus Verilog encounters the "use <lib>.<name>.*;"
statement, it looks for the <name>.pkg file in the <lib> library and
parses that file to get the package header declared therein.

248
_sources/usage/vpi.rst.txt Normal file
View File

@ -0,0 +1,248 @@
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[])(void) = {
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)
{
(void)user_data; // Avoid a warning since user_data is not used.
return 0;
}
static int hello_calltf(char*user_data)
{
(void)user_data; // Avoid a warning since user_data is not used.
vpi_printf("Hello, World!\n");
return 0;
}
void hello_register(void)
{
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[])(void) = {
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

148
_sources/usage/vvp_debug.rst.txt Normal file
View File

@ -0,0 +1,148 @@
VVP Interactive Mode
====================
The vvp command has an interactive debug mode, where you can stop the
simulation and browse the current state of the simulation. There are
a couple ways to enter the debug mode, but once in interactive debug
mode, the usage is the same. Consider the example below:
.. code-block:: verilog
module clock(output reg clock);
initial clock = 1'b1;
always #100 clock = !clock;
endmodule // clock
module main;
reg [2:0] foo;
wire clk;
clock foo_clock(clk);
always @(posedge clk)
foo <= foo + 1;
initial begin
foo = 3'b000;
#250 $stop;
end
endmodule
In examples that follow, we will use the above sample program.
Enter Interactive Mode
----------------------
The first and most common method is to put "$stop" system task
calls in the simulation at the times where you want to simulation
to break and enter interactive mode. The example above has a $stop,
so the output looks like this::
../foo.vl:25: $stop called at 250 (1s)
** VVP Stop(0) **
** Flushing output streams.
** Current simulation time is 250 ticks.
>
You can get some interactive help by using the "help" command::
> help
Commands can be from the following table of base commands,
or can be invocations of system tasks/functions.
cd - Synonym for push.
cont - Resume (continue) the simulation
finish - Finish the simulation.
help - Get help.
list - List items in the current scope.
load - Load a VPI module, a la vvp -m.
ls - Shorthand for "list".
pop - Pop one scope from the scope stack.
push - Descend into the named scope.
step - Single-step the scheduler for 1 event.
time - Print the current simulation time.
trace - Control statement tracing (on/off) when the code is instrumented.
where - Show current scope, and scope hierarchy stack.
If the command name starts with a '$' character, it
is taken to be the name of a system task, and a call is
built up and executed. For example, "$display foo" will
call the function as $display(foo).
You can also enter interactive mode at the terminal by interrupting the
execution with a "^C" (Control-C) character. The vvp engine catches the
terminal interrupt and drops you into the interactive prompt::
^C** VVP Stop(0) **
** Flushing output streams.
** Current simulation time is 533928600 ticks.
>
This could be useful if you suspect that your simulation is stuck in
an infinite loop and you want to rummage around and see what's going on.
And finally, you can pass the "-s" command line flag to vvp to tell it
to execute "$stop" at the beginning of the simulation, before any other
events are executed. This may be useful as a way to manually set up some
details about the simulation.
Browsing the Design
-------------------
Now that you are in the interactive prompt, you can browse
around the design::
> ls
2 items in this scope:
package : $unit
module : main
> cd main
> ls
3 items in this scope:
reg : foo[2:0]
module : foo_clock
net : clk
> where
module main
> $display foo
1
> cd foo_clock
> where
module foo_clock
module main
> ls
2 items in this scope:
port : clock -- output
reg : clock
In the above example, the 'cd' and 'pop' commands descend into a scope
or pop back up a scope level. The 'where' command shows the scope stack,
and the 'ls' command lists the items present in the scope. With these
commands, one can browse freely throughout the design scope hierarchy.
It is also possible to call system tasks within the debug mode. The call
to the "$display" function is an example of this. In general, any system
task can be invoked, in the current context, with the objects that are
included on the command line passed as arguments. The arguments can be
variables or nets, and various kinds of literals::
> ls
2 items in this scope:
port : clock -- output
reg : clock
> $display "Hello, World! " 10 " " clock
Hello, World! 10 1
This is a great way to call custom system tasks as well. And system task
that vvp knows about can be invoked this way.
Leave Interactive Mode
----------------------
After you are done probing around in the interactive mode, you can
resume the simulation, or termimate execution. Resume the simulation
with the "cont" command, and terminate the simulation with the
"finish" command. The latter is the same as executing the
"$finish" system task.

145
_sources/usage/vvp_flags.rst.txt Normal file
View File

@ -0,0 +1,145 @@
VVP Command Line Flags
======================
The vvp command is the simulation run-time engine. The command line for vvp
execution is first the options and flags, then the vvp input file, and finally
extended arguments. Typical usage looks like this::
% vvp <flags> foo.vvp <extended arguments>
Options/Flags
-------------
These options/flags go before the path to the vvp-executable program. They
effect behavior of the vvp runtime engine, including preparation for
simulation.
* -i
This flag causes all output to <stdout> to be unbuffered.
* -l<logfile>
This flag specifies a logfile where all MCI <stdlog> output goes. Specify
logfile as '-' to send log output to <stderr>. $display and friends send
their output both to <stdout> and <stdlog>.
* -M<path>
Add the directory path to the (VPI) module search path. Multiple "-M" flags
are allowed, and the directories are added in the order that they are given
on the command line.
The string "-M-" is special, in that it doesn't add a directory to the
path. It instead *removes* the compiled directory. This is generally used
only for development of the vvp engine.
* -m<module>
Name a VPI module that should be loaded. The vvp engine looks for the named
module in the module search path, which includes the compiled in default
directory and directories given by "-M" flags.
NOTE: Starting with v11.0, the VPI modules to be loaded can be specified
when you compile your design. This allows the compiler to automatically
determine the return types of user-defined system functions. If specified at
compile-time, there is no need to specify them again here.
* -n
This flag makes $stop or a <Control\-C> a synonym for $finish. It can be
used to give the program a more meaningful interface when running in a
non-interactive environment.
* -N
This flag does the same thing as "-n", but results in an exit code of 1
if the stimulation calls $stop. It can be used to indicate a simulation
failure when running a testbench.
* -q
Enable quiet mode. This suppresses all output to <stdout> sent via MCD
bit 0 (e.g. all output from $display and friends). It does not affect
output to the log file, nor does it affect output to <stdout> sent via
the STDOUT file descriptor.
* -s
$stop right away, in the beginning of the simulation. This kicks the
vvp program into interactive debug mode.
* -v
Show verbose progress while setting up or cleaning up the runtime
engine. This also displays some performance information.
* -V
Print the version of the runtime, and exit.
Extended Arguments
------------------
The extended arguments are available to the simulation runtime, especially
system tasks, system functions and any VPI/PLI code. Extended arguments that
start with a "+" character are left for use by the user via the $plus$flag and
$plus$value functions.
NOTE: The extended arguments must appear *after* the input file name on the
command line.
VCD/FST/LXT Arguments
^^^^^^^^^^^^^^^^^^^^^
If not otherwise specified, the vvp engine will by default use VCD formats to
support the $dumpvars system task. The flags described here can alter that
behavior.
* -none/-vcd-none/-vcd-off/-fst-none
Disable trace output. The trace output will be stubbed so that no trace file
is created and the cost of dumping is avoided. All off these options are
synonyms for turning of dumping.
* -fst
Generate FST format outputs instead of VCD format waveform dumps. This is
the preferred output format if using GTKWave for viewing waveforms.
* -lxt/-lxt2
Generate LXT or LXT2format instead of VCD format waveform dumps. The LXT2
format is more advanced.
* -dumpfile=<name>
Set the default dumpfile. If unspecified, the default is "dump". This
command line flag allows you do change it. If no suffix is specified,
then the suffix will be chosen based on the dump type. In any case, the
$dumpfile system task overrides this flag.
SDF Support
^^^^^^^^^^^
The Icarus Verilog support for SDF back-annotation can take some extended
arguments to control aspects of SDF support.
* -sdf-warn
Print warnings during load of/annotation from an SDF file.
* -sdf-info
Print interesting information about an SDF file while parsing it.
* -sdf-verbose
Print warnings and info messages.
Environment Variables
---------------------
The vvp program pays attention to certain environment variables.
* IVERILOG_DUMPER

29
_sources/usage/vvp_library.rst.txt Normal file
View File

@ -0,0 +1,29 @@
VVP as a library
================
If configured with ::
--enable-libvvp
the vvp program will be built as a small stub that
depends on a shared library, libvvp.so.
The library may also be used to include a vvp simulation
in a larger program. Typically, the simulation communicates
with its host program using VPI, but since
almost all the functions of vvp are included in the library
it may be possible to use text output and interactive mode.
The accessible functions of the library are defined and documented
in the header file, vvp/libvvp.h. Although vvp is a C++ program, the
header file presents a C interface.
Note that the vvp software was not designed to be used this way
and the library is a straightforward recompilation of the program code.
That imposes some restrictions, mostly arising from the use
of static variables: only a single run of a single simulation instance
can be expected to work without special actions.
To mitigate these restrictions, the library may by loaded dynamically
and unloaded at the end of each simulation run.
Parallel simulation should be possible by making multiple copies
of the library with different names.

701
_static/alabaster.css Normal file
View File

@ -0,0 +1,701 @@
@import url("basic.css");
/* -- page layout ----------------------------------------------------------- */
body {
font-family: Georgia, serif;
font-size: 17px;
background-color: #fff;
color: #000;
margin: 0;
padding: 0;
}
div.document {
width: 940px;
margin: 30px auto 0 auto;
}
div.documentwrapper {
float: left;
width: 100%;
}
div.bodywrapper {
margin: 0 0 0 220px;
}
div.sphinxsidebar {
width: 220px;
font-size: 14px;
line-height: 1.5;
}
hr {
border: 1px solid #B1B4B6;
}
div.body {
background-color: #fff;
color: #3E4349;
padding: 0 30px 0 30px;
}
div.body > .section {
text-align: left;
}
div.footer {
width: 940px;
margin: 20px auto 30px auto;
font-size: 14px;
color: #888;
text-align: right;
}
div.footer a {
color: #888;
}
p.caption {
font-family: inherit;
font-size: inherit;
}
div.relations {
display: none;
}
div.sphinxsidebar a {
color: #444;
text-decoration: none;
border-bottom: 1px dotted #999;
}
div.sphinxsidebar a:hover {
border-bottom: 1px solid #999;
}
div.sphinxsidebarwrapper {
padding: 18px 10px;
}
div.sphinxsidebarwrapper p.logo {
padding: 0;
margin: -10px 0 0 0px;
text-align: center;
}
div.sphinxsidebarwrapper h1.logo {
margin-top: -10px;
text-align: center;
margin-bottom: 5px;
text-align: left;
}
div.sphinxsidebarwrapper h1.logo-name {
margin-top: 0px;
}
div.sphinxsidebarwrapper p.blurb {
margin-top: 0;
font-style: normal;
}
div.sphinxsidebar h3,
div.sphinxsidebar h4 {
font-family: Georgia, serif;
color: #444;
font-size: 24px;
font-weight: normal;
margin: 0 0 5px 0;
padding: 0;
}
div.sphinxsidebar h4 {
font-size: 20px;
}
div.sphinxsidebar h3 a {
color: #444;
}
div.sphinxsidebar p.logo a,
div.sphinxsidebar h3 a,
div.sphinxsidebar p.logo a:hover,
div.sphinxsidebar h3 a:hover {
border: none;
}
div.sphinxsidebar p {
color: #555;
margin: 10px 0;
}
div.sphinxsidebar ul {
margin: 10px 0;
padding: 0;
color: #000;
}
div.sphinxsidebar ul li.toctree-l1 > a {
font-size: 120%;
}
div.sphinxsidebar ul li.toctree-l2 > a {
font-size: 110%;
}
div.sphinxsidebar input {
border: 1px solid #CCC;
font-family: Georgia, serif;
font-size: 1em;
}
div.sphinxsidebar hr {
border: none;
height: 1px;
color: #AAA;
background: #AAA;
text-align: left;
margin-left: 0;
width: 50%;
}
div.sphinxsidebar .badge {
border-bottom: none;
}
div.sphinxsidebar .badge:hover {
border-bottom: none;
}
/* To address an issue with donation coming after search */
div.sphinxsidebar h3.donation {
margin-top: 10px;
}
/* -- body styles ----------------------------------------------------------- */
a {
color: #004B6B;
text-decoration: underline;
}
a:hover {
color: #6D4100;
text-decoration: underline;
}
div.body h1,
div.body h2,
div.body h3,
div.body h4,
div.body h5,
div.body h6 {
font-family: Georgia, serif;
font-weight: normal;
margin: 30px 0px 10px 0px;
padding: 0;
}
div.body h1 { margin-top: 0; padding-top: 0; font-size: 240%; }
div.body h2 { font-size: 180%; }
div.body h3 { font-size: 150%; }
div.body h4 { font-size: 130%; }
div.body h5 { font-size: 100%; }
div.body h6 { font-size: 100%; }
a.headerlink {
color: #DDD;
padding: 0 4px;
text-decoration: none;
}
a.headerlink:hover {
color: #444;
background: #EAEAEA;
}
div.body p, div.body dd, div.body li {
line-height: 1.4em;
}
div.admonition {
margin: 20px 0px;
padding: 10px 30px;
background-color: #EEE;
border: 1px solid #CCC;
}
div.admonition tt.xref, div.admonition code.xref, div.admonition a tt {
background-color: #FBFBFB;
border-bottom: 1px solid #fafafa;
}
div.admonition p.admonition-title {
font-family: Georgia, serif;
font-weight: normal;
font-size: 24px;
margin: 0 0 10px 0;
padding: 0;
line-height: 1;
}
div.admonition p.last {
margin-bottom: 0;
}
div.highlight {
background-color: #fff;
}
dt:target, .highlight {
background: #FAF3E8;
}
div.warning {
background-color: #FCC;
border: 1px solid #FAA;
}
div.danger {
background-color: #FCC;
border: 1px solid #FAA;
-moz-box-shadow: 2px 2px 4px #D52C2C;
-webkit-box-shadow: 2px 2px 4px #D52C2C;
box-shadow: 2px 2px 4px #D52C2C;
}
div.error {
background-color: #FCC;
border: 1px solid #FAA;
-moz-box-shadow: 2px 2px 4px #D52C2C;
-webkit-box-shadow: 2px 2px 4px #D52C2C;
box-shadow: 2px 2px 4px #D52C2C;
}
div.caution {
background-color: #FCC;
border: 1px solid #FAA;
}
div.attention {
background-color: #FCC;
border: 1px solid #FAA;
}
div.important {
background-color: #EEE;
border: 1px solid #CCC;
}
div.note {
background-color: #EEE;
border: 1px solid #CCC;
}
div.tip {
background-color: #EEE;
border: 1px solid #CCC;
}
div.hint {
background-color: #EEE;
border: 1px solid #CCC;
}
div.seealso {
background-color: #EEE;
border: 1px solid #CCC;
}
div.topic {
background-color: #EEE;
}
p.admonition-title {
display: inline;
}
p.admonition-title:after {
content: ":";
}
pre, tt, code {
font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
font-size: 0.9em;
}
.hll {
background-color: #FFC;
margin: 0 -12px;
padding: 0 12px;
display: block;
}
img.screenshot {
}
tt.descname, tt.descclassname, code.descname, code.descclassname {
font-size: 0.95em;
}
tt.descname, code.descname {
padding-right: 0.08em;
}
img.screenshot {
-moz-box-shadow: 2px 2px 4px #EEE;
-webkit-box-shadow: 2px 2px 4px #EEE;
box-shadow: 2px 2px 4px #EEE;
}
table.docutils {
border: 1px solid #888;
-moz-box-shadow: 2px 2px 4px #EEE;
-webkit-box-shadow: 2px 2px 4px #EEE;
box-shadow: 2px 2px 4px #EEE;
}
table.docutils td, table.docutils th {
border: 1px solid #888;
padding: 0.25em 0.7em;
}
table.field-list, table.footnote {
border: none;
-moz-box-shadow: none;
-webkit-box-shadow: none;
box-shadow: none;
}
table.footnote {
margin: 15px 0;
width: 100%;
border: 1px solid #EEE;
background: #FDFDFD;
font-size: 0.9em;
}
table.footnote + table.footnote {
margin-top: -15px;
border-top: none;
}
table.field-list th {
padding: 0 0.8em 0 0;
}
table.field-list td {
padding: 0;
}
table.field-list p {
margin-bottom: 0.8em;
}
/* Cloned from
* https://github.com/sphinx-doc/sphinx/commit/ef60dbfce09286b20b7385333d63a60321784e68
*/
.field-name {
-moz-hyphens: manual;
-ms-hyphens: manual;
-webkit-hyphens: manual;
hyphens: manual;
}
table.footnote td.label {
width: .1px;
padding: 0.3em 0 0.3em 0.5em;
}
table.footnote td {
padding: 0.3em 0.5em;
}
dl {
margin: 0;
padding: 0;
}
dl dd {
margin-left: 30px;
}
blockquote {
margin: 0 0 0 30px;
padding: 0;
}
ul, ol {
/* Matches the 30px from the narrow-screen "li > ul" selector below */
margin: 10px 0 10px 30px;
padding: 0;
}
pre {
background: #EEE;
padding: 7px 30px;
margin: 15px 0px;
line-height: 1.3em;
}
div.viewcode-block:target {
background: #ffd;
}
dl pre, blockquote pre, li pre {
margin-left: 0;
padding-left: 30px;
}
tt, code {
background-color: #ecf0f3;
color: #222;
/* padding: 1px 2px; */
}
tt.xref, code.xref, a tt {
background-color: #FBFBFB;
border-bottom: 1px solid #fff;
}
a.reference {
text-decoration: none;
border-bottom: 1px dotted #004B6B;
}
/* Don't put an underline on images */
a.image-reference, a.image-reference:hover {
border-bottom: none;
}
a.reference:hover {
border-bottom: 1px solid #6D4100;
}
a.footnote-reference {
text-decoration: none;
font-size: 0.7em;
vertical-align: top;
border-bottom: 1px dotted #004B6B;
}
a.footnote-reference:hover {
border-bottom: 1px solid #6D4100;
}
a:hover tt, a:hover code {
background: #EEE;
}
@media screen and (max-width: 870px) {
div.sphinxsidebar {
display: none;
}
div.document {
width: 100%;
}
div.documentwrapper {
margin-left: 0;
margin-top: 0;
margin-right: 0;
margin-bottom: 0;
}
div.bodywrapper {
margin-top: 0;
margin-right: 0;
margin-bottom: 0;
margin-left: 0;
}
ul {
margin-left: 0;
}
li > ul {
/* Matches the 30px from the "ul, ol" selector above */
margin-left: 30px;
}
.document {
width: auto;
}
.footer {
width: auto;
}
.bodywrapper {
margin: 0;
}
.footer {
width: auto;
}
.github {
display: none;
}
}
@media screen and (max-width: 875px) {
body {
margin: 0;
padding: 20px 30px;
}
div.documentwrapper {
float: none;
background: #fff;
}
div.sphinxsidebar {
display: block;
float: none;
width: 102.5%;
margin: 50px -30px -20px -30px;
padding: 10px 20px;
background: #333;
color: #FFF;
}
div.sphinxsidebar h3, div.sphinxsidebar h4, div.sphinxsidebar p,
div.sphinxsidebar h3 a {
color: #fff;
}
div.sphinxsidebar a {
color: #AAA;
}
div.sphinxsidebar p.logo {
display: none;
}
div.document {
width: 100%;
margin: 0;
}
div.footer {
display: none;
}
div.bodywrapper {
margin: 0;
}
div.body {
min-height: 0;
padding: 0;
}
.rtd_doc_footer {
display: none;
}
.document {
width: auto;
}
.footer {
width: auto;
}
.footer {
width: auto;
}
.github {
display: none;
}
}
/* misc. */
.revsys-inline {
display: none!important;
}
/* Make nested-list/multi-paragraph items look better in Releases changelog
* pages. Without this, docutils' magical list fuckery causes inconsistent
* formatting between different release sub-lists.
*/
div#changelog > div.section > ul > li > p:only-child {
margin-bottom: 0;
}
/* Hide fugly table cell borders in ..bibliography:: directive output */
table.docutils.citation, table.docutils.citation td, table.docutils.citation th {
border: none;
/* Below needed in some edge cases; if not applied, bottom shadows appear */
-moz-box-shadow: none;
-webkit-box-shadow: none;
box-shadow: none;
}
/* relbar */
.related {
line-height: 30px;
width: 100%;
font-size: 0.9rem;
}
.related.top {
border-bottom: 1px solid #EEE;
margin-bottom: 20px;
}
.related.bottom {
border-top: 1px solid #EEE;
}
.related ul {
padding: 0;
margin: 0;
list-style: none;
}
.related li {
display: inline;
}
nav#rellinks {
float: right;
}
nav#rellinks li+li:before {
content: "|";
}
nav#breadcrumbs li+li:before {
content: "\00BB";
}
/* Hide certain items when printing */
@media print {
div.related {
display: none;
}
}

925
_static/basic.css Normal file
View File

@ -0,0 +1,925 @@
/*
* basic.css
* ~~~~~~~~~
*
* Sphinx stylesheet -- basic theme.
*
* :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
/* -- main layout ----------------------------------------------------------- */
div.clearer {
clear: both;
}
div.section::after {
display: block;
content: '';
clear: left;
}
/* -- relbar ---------------------------------------------------------------- */
div.related {
width: 100%;
font-size: 90%;
}
div.related h3 {
display: none;
}
div.related ul {
margin: 0;
padding: 0 0 0 10px;
list-style: none;
}
div.related li {
display: inline;
}
div.related li.right {
float: right;
margin-right: 5px;
}
/* -- sidebar --------------------------------------------------------------- */
div.sphinxsidebarwrapper {
padding: 10px 5px 0 10px;
}
div.sphinxsidebar {
float: left;
width: 230px;
margin-left: -100%;
font-size: 90%;
word-wrap: break-word;
overflow-wrap : break-word;
}
div.sphinxsidebar ul {
list-style: none;
}
div.sphinxsidebar ul ul,
div.sphinxsidebar ul.want-points {
margin-left: 20px;
list-style: square;
}
div.sphinxsidebar ul ul {
margin-top: 0;
margin-bottom: 0;
}
div.sphinxsidebar form {
margin-top: 10px;
}
div.sphinxsidebar input {
border: 1px solid #98dbcc;
font-family: sans-serif;
font-size: 1em;
}
div.sphinxsidebar #searchbox form.search {
overflow: hidden;
}
div.sphinxsidebar #searchbox input[type="text"] {
float: left;
width: 80%;
padding: 0.25em;
box-sizing: border-box;
}
div.sphinxsidebar #searchbox input[type="submit"] {
float: left;
width: 20%;
border-left: none;
padding: 0.25em;
box-sizing: border-box;
}
img {
border: 0;
max-width: 100%;
}
/* -- search page ----------------------------------------------------------- */
ul.search {
margin: 10px 0 0 20px;
padding: 0;
}
ul.search li {
padding: 5px 0 5px 20px;
background-image: url(file.png);
background-repeat: no-repeat;
background-position: 0 7px;
}
ul.search li a {
font-weight: bold;
}
ul.search li p.context {
color: #888;
margin: 2px 0 0 30px;
text-align: left;
}
ul.keywordmatches li.goodmatch a {
font-weight: bold;
}
/* -- index page ------------------------------------------------------------ */
table.contentstable {
width: 90%;
margin-left: auto;
margin-right: auto;
}
table.contentstable p.biglink {
line-height: 150%;
}
a.biglink {
font-size: 1.3em;
}
span.linkdescr {
font-style: italic;
padding-top: 5px;
font-size: 90%;
}
/* -- general index --------------------------------------------------------- */
table.indextable {
width: 100%;
}
table.indextable td {
text-align: left;
vertical-align: top;
}
table.indextable ul {
margin-top: 0;
margin-bottom: 0;
list-style-type: none;
}
table.indextable > tbody > tr > td > ul {
padding-left: 0em;
}
table.indextable tr.pcap {
height: 10px;
}
table.indextable tr.cap {
margin-top: 10px;
background-color: #f2f2f2;
}
img.toggler {
margin-right: 3px;
margin-top: 3px;
cursor: pointer;
}
div.modindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
div.genindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
/* -- domain module index --------------------------------------------------- */
table.modindextable td {
padding: 2px;
border-collapse: collapse;
}
/* -- general body styles --------------------------------------------------- */
div.body {
min-width: 360px;
max-width: 800px;
}
div.body p, div.body dd, div.body li, div.body blockquote {
-moz-hyphens: auto;
-ms-hyphens: auto;
-webkit-hyphens: auto;
hyphens: auto;
}
a.headerlink {
visibility: hidden;
}
a:visited {
color: #551A8B;
}
h1:hover > a.headerlink,
h2:hover > a.headerlink,
h3:hover > a.headerlink,
h4:hover > a.headerlink,
h5:hover > a.headerlink,
h6:hover > a.headerlink,
dt:hover > a.headerlink,
caption:hover > a.headerlink,
p.caption:hover > a.headerlink,
div.code-block-caption:hover > a.headerlink {
visibility: visible;
}
div.body p.caption {
text-align: inherit;
}
div.body td {
text-align: left;
}
.first {
margin-top: 0 !important;
}
p.rubric {
margin-top: 30px;
font-weight: bold;
}
img.align-left, figure.align-left, .figure.align-left, object.align-left {
clear: left;
float: left;
margin-right: 1em;
}
img.align-right, figure.align-right, .figure.align-right, object.align-right {
clear: right;
float: right;
margin-left: 1em;
}
img.align-center, figure.align-center, .figure.align-center, object.align-center {
display: block;
margin-left: auto;
margin-right: auto;
}
img.align-default, figure.align-default, .figure.align-default {
display: block;
margin-left: auto;
margin-right: auto;
}
.align-left {
text-align: left;
}
.align-center {
text-align: center;
}
.align-default {
text-align: center;
}
.align-right {
text-align: right;
}
/* -- sidebars -------------------------------------------------------------- */
div.sidebar,
aside.sidebar {
margin: 0 0 0.5em 1em;
border: 1px solid #ddb;
padding: 7px;
background-color: #ffe;
width: 40%;
float: right;
clear: right;
overflow-x: auto;
}
p.sidebar-title {
font-weight: bold;
}
nav.contents,
aside.topic,
div.admonition, div.topic, blockquote {
clear: left;
}
/* -- topics ---------------------------------------------------------------- */
nav.contents,
aside.topic,
div.topic {
border: 1px solid #ccc;
padding: 7px;
margin: 10px 0 10px 0;
}
p.topic-title {
font-size: 1.1em;
font-weight: bold;
margin-top: 10px;
}
/* -- admonitions ----------------------------------------------------------- */
div.admonition {
margin-top: 10px;
margin-bottom: 10px;
padding: 7px;
}
div.admonition dt {
font-weight: bold;
}
p.admonition-title {
margin: 0px 10px 5px 0px;
font-weight: bold;
}
div.body p.centered {
text-align: center;
margin-top: 25px;
}
/* -- content of sidebars/topics/admonitions -------------------------------- */
div.sidebar > :last-child,
aside.sidebar > :last-child,
nav.contents > :last-child,
aside.topic > :last-child,
div.topic > :last-child,
div.admonition > :last-child {
margin-bottom: 0;
}
div.sidebar::after,
aside.sidebar::after,
nav.contents::after,
aside.topic::after,
div.topic::after,
div.admonition::after,
blockquote::after {
display: block;
content: '';
clear: both;
}
/* -- tables ---------------------------------------------------------------- */
table.docutils {
margin-top: 10px;
margin-bottom: 10px;
border: 0;
border-collapse: collapse;
}
table.align-center {
margin-left: auto;
margin-right: auto;
}
table.align-default {
margin-left: auto;
margin-right: auto;
}
table caption span.caption-number {
font-style: italic;
}
table caption span.caption-text {
}
table.docutils td, table.docutils th {
padding: 1px 8px 1px 5px;
border-top: 0;
border-left: 0;
border-right: 0;
border-bottom: 1px solid #aaa;
}
th {
text-align: left;
padding-right: 5px;
}
table.citation {
border-left: solid 1px gray;
margin-left: 1px;
}
table.citation td {
border-bottom: none;
}
th > :first-child,
td > :first-child {
margin-top: 0px;
}
th > :last-child,
td > :last-child {
margin-bottom: 0px;
}
/* -- figures --------------------------------------------------------------- */
div.figure, figure {
margin: 0.5em;
padding: 0.5em;
}
div.figure p.caption, figcaption {
padding: 0.3em;
}
div.figure p.caption span.caption-number,
figcaption span.caption-number {
font-style: italic;
}
div.figure p.caption span.caption-text,
figcaption span.caption-text {
}
/* -- field list styles ----------------------------------------------------- */
table.field-list td, table.field-list th {
border: 0 !important;
}
.field-list ul {
margin: 0;
padding-left: 1em;
}
.field-list p {
margin: 0;
}
.field-name {
-moz-hyphens: manual;
-ms-hyphens: manual;
-webkit-hyphens: manual;
hyphens: manual;
}
/* -- hlist styles ---------------------------------------------------------- */
table.hlist {
margin: 1em 0;
}
table.hlist td {
vertical-align: top;
}
/* -- object description styles --------------------------------------------- */
.sig {
font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
}
.sig-name, code.descname {
background-color: transparent;
font-weight: bold;
}
.sig-name {
font-size: 1.1em;
}
code.descname {
font-size: 1.2em;
}
.sig-prename, code.descclassname {
background-color: transparent;
}
.optional {
font-size: 1.3em;
}
.sig-paren {
font-size: larger;
}
.sig-param.n {
font-style: italic;
}
/* C++ specific styling */
.sig-inline.c-texpr,
.sig-inline.cpp-texpr {
font-family: unset;
}
.sig.c .k, .sig.c .kt,
.sig.cpp .k, .sig.cpp .kt {
color: #0033B3;
}
.sig.c .m,
.sig.cpp .m {
color: #1750EB;
}
.sig.c .s, .sig.c .sc,
.sig.cpp .s, .sig.cpp .sc {
color: #067D17;
}
/* -- other body styles ----------------------------------------------------- */
ol.arabic {
list-style: decimal;
}
ol.loweralpha {
list-style: lower-alpha;
}
ol.upperalpha {
list-style: upper-alpha;
}
ol.lowerroman {
list-style: lower-roman;
}
ol.upperroman {
list-style: upper-roman;
}
:not(li) > ol > li:first-child > :first-child,
:not(li) > ul > li:first-child > :first-child {
margin-top: 0px;
}
:not(li) > ol > li:last-child > :last-child,
:not(li) > ul > li:last-child > :last-child {
margin-bottom: 0px;
}
ol.simple ol p,
ol.simple ul p,
ul.simple ol p,
ul.simple ul p {
margin-top: 0;
}
ol.simple > li:not(:first-child) > p,
ul.simple > li:not(:first-child) > p {
margin-top: 0;
}
ol.simple p,
ul.simple p {
margin-bottom: 0;
}
aside.footnote > span,
div.citation > span {
float: left;
}
aside.footnote > span:last-of-type,
div.citation > span:last-of-type {
padding-right: 0.5em;
}
aside.footnote > p {
margin-left: 2em;
}
div.citation > p {
margin-left: 4em;
}
aside.footnote > p:last-of-type,
div.citation > p:last-of-type {
margin-bottom: 0em;
}
aside.footnote > p:last-of-type:after,
div.citation > p:last-of-type:after {
content: "";
clear: both;
}
dl.field-list {
display: grid;
grid-template-columns: fit-content(30%) auto;
}
dl.field-list > dt {
font-weight: bold;
word-break: break-word;
padding-left: 0.5em;
padding-right: 5px;
}
dl.field-list > dd {
padding-left: 0.5em;
margin-top: 0em;
margin-left: 0em;
margin-bottom: 0em;
}
dl {
margin-bottom: 15px;
}
dd > :first-child {
margin-top: 0px;
}
dd ul, dd table {
margin-bottom: 10px;
}
dd {
margin-top: 3px;
margin-bottom: 10px;
margin-left: 30px;
}
.sig dd {
margin-top: 0px;
margin-bottom: 0px;
}
.sig dl {
margin-top: 0px;
margin-bottom: 0px;
}
dl > dd:last-child,
dl > dd:last-child > :last-child {
margin-bottom: 0;
}
dt:target, span.highlighted {
background-color: #fbe54e;
}
rect.highlighted {
fill: #fbe54e;
}
dl.glossary dt {
font-weight: bold;
font-size: 1.1em;
}
.versionmodified {
font-style: italic;
}
.system-message {
background-color: #fda;
padding: 5px;
border: 3px solid red;
}
.footnote:target {
background-color: #ffa;
}
.line-block {
display: block;
margin-top: 1em;
margin-bottom: 1em;
}
.line-block .line-block {
margin-top: 0;
margin-bottom: 0;
margin-left: 1.5em;
}
.guilabel, .menuselection {
font-family: sans-serif;
}
.accelerator {
text-decoration: underline;
}
.classifier {
font-style: oblique;
}
.classifier:before {
font-style: normal;
margin: 0 0.5em;
content: ":";
display: inline-block;
}
abbr, acronym {
border-bottom: dotted 1px;
cursor: help;
}
.translated {
background-color: rgba(207, 255, 207, 0.2)
}
.untranslated {
background-color: rgba(255, 207, 207, 0.2)
}
/* -- code displays --------------------------------------------------------- */
pre {
overflow: auto;
overflow-y: hidden; /* fixes display issues on Chrome browsers */
}
pre, div[class*="highlight-"] {
clear: both;
}
span.pre {
-moz-hyphens: none;
-ms-hyphens: none;
-webkit-hyphens: none;
hyphens: none;
white-space: nowrap;
}
div[class*="highlight-"] {
margin: 1em 0;
}
td.linenos pre {
border: 0;
background-color: transparent;
color: #aaa;
}
table.highlighttable {
display: block;
}
table.highlighttable tbody {
display: block;
}
table.highlighttable tr {
display: flex;
}
table.highlighttable td {
margin: 0;
padding: 0;
}
table.highlighttable td.linenos {
padding-right: 0.5em;
}
table.highlighttable td.code {
flex: 1;
overflow: hidden;
}
.highlight .hll {
display: block;
}
div.highlight pre,
table.highlighttable pre {
margin: 0;
}
div.code-block-caption + div {
margin-top: 0;
}
div.code-block-caption {
margin-top: 1em;
padding: 2px 5px;
font-size: small;
}
div.code-block-caption code {
background-color: transparent;
}
table.highlighttable td.linenos,
span.linenos,
div.highlight span.gp { /* gp: Generic.Prompt */
user-select: none;
-webkit-user-select: text; /* Safari fallback only */
-webkit-user-select: none; /* Chrome/Safari */
-moz-user-select: none; /* Firefox */
-ms-user-select: none; /* IE10+ */
}
div.code-block-caption span.caption-number {
padding: 0.1em 0.3em;
font-style: italic;
}
div.code-block-caption span.caption-text {
}
div.literal-block-wrapper {
margin: 1em 0;
}
code.xref, a code {
background-color: transparent;
font-weight: bold;
}
h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
background-color: transparent;
}
.viewcode-link {
float: right;
}
.viewcode-back {
float: right;
font-family: sans-serif;
}
div.viewcode-block:target {
margin: -1px -10px;
padding: 0 10px;
}
/* -- math display ---------------------------------------------------------- */
img.math {
vertical-align: middle;
}
div.body div.math p {
text-align: center;
}
span.eqno {
float: right;
}
span.eqno a.headerlink {
position: absolute;
z-index: 1;
}
div.math:hover a.headerlink {
visibility: visible;
}
/* -- printout stylesheet --------------------------------------------------- */
@media print {
div.document,
div.documentwrapper,
div.bodywrapper {
margin: 0 !important;
width: 100%;
}
div.sphinxsidebar,
div.related,
div.footer,
#top-link {
display: none;
}
}

1
_static/custom.css Normal file
View File

@ -0,0 +1 @@
/* This file intentionally left blank. */

156
_static/doctools.js Normal file
View File

@ -0,0 +1,156 @@
/*
* doctools.js
* ~~~~~~~~~~~
*
* Base JavaScript utilities for all Sphinx HTML documentation.
*
* :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
"use strict";
const BLACKLISTED_KEY_CONTROL_ELEMENTS = new Set([
"TEXTAREA",
"INPUT",
"SELECT",
"BUTTON",
]);
const _ready = (callback) => {
if (document.readyState !== "loading") {
callback();
} else {
document.addEventListener("DOMContentLoaded", callback);
}
};
/**
* Small JavaScript module for the documentation.
*/
const Documentation = {
init: () => {
Documentation.initDomainIndexTable();
Documentation.initOnKeyListeners();
},
/**
* i18n support
*/
TRANSLATIONS: {},
PLURAL_EXPR: (n) => (n === 1 ? 0 : 1),
LOCALE: "unknown",
// gettext and ngettext don't access this so that the functions
// can safely bound to a different name (_ = Documentation.gettext)
gettext: (string) => {
const translated = Documentation.TRANSLATIONS[string];
switch (typeof translated) {
case "undefined":
return string; // no translation
case "string":
return translated; // translation exists
default:
return translated[0]; // (singular, plural) translation tuple exists
}
},
ngettext: (singular, plural, n) => {
const translated = Documentation.TRANSLATIONS[singular];
if (typeof translated !== "undefined")
return translated[Documentation.PLURAL_EXPR(n)];
return n === 1 ? singular : plural;
},
addTranslations: (catalog) => {
Object.assign(Documentation.TRANSLATIONS, catalog.messages);
Documentation.PLURAL_EXPR = new Function(
"n",
`return (${catalog.plural_expr})`
);
Documentation.LOCALE = catalog.locale;
},
/**
* helper function to focus on search bar
*/
focusSearchBar: () => {
document.querySelectorAll("input[name=q]")[0]?.focus();
},
/**
* Initialise the domain index toggle buttons
*/
initDomainIndexTable: () => {
const toggler = (el) => {
const idNumber = el.id.substr(7);
const toggledRows = document.querySelectorAll(`tr.cg-${idNumber}`);
if (el.src.substr(-9) === "minus.png") {
el.src = `${el.src.substr(0, el.src.length - 9)}plus.png`;
toggledRows.forEach((el) => (el.style.display = "none"));
} else {
el.src = `${el.src.substr(0, el.src.length - 8)}minus.png`;
toggledRows.forEach((el) => (el.style.display = ""));
}
};
const togglerElements = document.querySelectorAll("img.toggler");
togglerElements.forEach((el) =>
el.addEventListener("click", (event) => toggler(event.currentTarget))
);
togglerElements.forEach((el) => (el.style.display = ""));
if (DOCUMENTATION_OPTIONS.COLLAPSE_INDEX) togglerElements.forEach(toggler);
},
initOnKeyListeners: () => {
// only install a listener if it is really needed
if (
!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS &&
!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS
)
return;
document.addEventListener("keydown", (event) => {
// bail for input elements
if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
// bail with special keys
if (event.altKey || event.ctrlKey || event.metaKey) return;
if (!event.shiftKey) {
switch (event.key) {
case "ArrowLeft":
if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
const prevLink = document.querySelector('link[rel="prev"]');
if (prevLink && prevLink.href) {
window.location.href = prevLink.href;
event.preventDefault();
}
break;
case "ArrowRight":
if (!DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) break;
const nextLink = document.querySelector('link[rel="next"]');
if (nextLink && nextLink.href) {
window.location.href = nextLink.href;
event.preventDefault();
}
break;
}
}
// some keyboard layouts may need Shift to get /
switch (event.key) {
case "/":
if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) break;
Documentation.focusSearchBar();
event.preventDefault();
}
});
},
};
// quick alias for translations
const _ = Documentation.gettext;
_ready(Documentation.init);

13
_static/documentation_options.js Normal file
View File

@ -0,0 +1,13 @@
const DOCUMENTATION_OPTIONS = {
VERSION: '',
LANGUAGE: 'en',
COLLAPSE_INDEX: false,
BUILDER: 'html',
FILE_SUFFIX: '.html',
LINK_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt',
NAVIGATION_WITH_KEYS: false,
SHOW_SEARCH_SUMMARY: true,
ENABLE_SEARCH_SHORTCUTS: true,
};

BIN
_static/favicon.ico Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 1.1 KiB

BIN
_static/file.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 286 B

BIN
_static/forkme_right_darkblue_121621.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 4.7 KiB

199
_static/language_data.js Normal file
View File

@ -0,0 +1,199 @@
/*
* language_data.js
* ~~~~~~~~~~~~~~~~
*
* This script contains the language-specific data used by searchtools.js,
* namely the list of stopwords, stemmer, scorer and splitter.
*
* :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
var stopwords = ["a", "and", "are", "as", "at", "be", "but", "by", "for", "if", "in", "into", "is", "it", "near", "no", "not", "of", "on", "or", "such", "that", "the", "their", "then", "there", "these", "they", "this", "to", "was", "will", "with"];
/* Non-minified version is copied as a separate JS file, is available */
/**
* Porter Stemmer
*/
var Stemmer = function() {
var step2list = {
ational: 'ate',
tional: 'tion',
enci: 'ence',
anci: 'ance',
izer: 'ize',
bli: 'ble',
alli: 'al',
entli: 'ent',
eli: 'e',
ousli: 'ous',
ization: 'ize',
ation: 'ate',
ator: 'ate',
alism: 'al',
iveness: 'ive',
fulness: 'ful',
ousness: 'ous',
aliti: 'al',
iviti: 'ive',
biliti: 'ble',
logi: 'log'
};
var step3list = {
icate: 'ic',
ative: '',
alize: 'al',
iciti: 'ic',
ical: 'ic',
ful: '',
ness: ''
};
var c = "[^aeiou]"; // consonant
var v = "[aeiouy]"; // vowel
var C = c + "[^aeiouy]*"; // consonant sequence
var V = v + "[aeiou]*"; // vowel sequence
var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0
var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1
var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1
var s_v = "^(" + C + ")?" + v; // vowel in stem
this.stemWord = function (w) {
var stem;
var suffix;
var firstch;
var origword = w;
if (w.length < 3)
return w;
var re;
var re2;
var re3;
var re4;
firstch = w.substr(0,1);
if (firstch == "y")
w = firstch.toUpperCase() + w.substr(1);
// Step 1a
re = /^(.+?)(ss|i)es$/;
re2 = /^(.+?)([^s])s$/;
if (re.test(w))
w = w.replace(re,"$1$2");
else if (re2.test(w))
w = w.replace(re2,"$1$2");
// Step 1b
re = /^(.+?)eed$/;
re2 = /^(.+?)(ed|ing)$/;
if (re.test(w)) {
var fp = re.exec(w);
re = new RegExp(mgr0);
if (re.test(fp[1])) {
re = /.$/;
w = w.replace(re,"");
}
}
else if (re2.test(w)) {
var fp = re2.exec(w);
stem = fp[1];
re2 = new RegExp(s_v);
if (re2.test(stem)) {
w = stem;
re2 = /(at|bl|iz)$/;
re3 = new RegExp("([^aeiouylsz])\\1$");
re4 = new RegExp("^" + C + v + "[^aeiouwxy]$");
if (re2.test(w))
w = w + "e";
else if (re3.test(w)) {
re = /.$/;
w = w.replace(re,"");
}
else if (re4.test(w))
w = w + "e";
}
}
// Step 1c
re = /^(.+?)y$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
re = new RegExp(s_v);
if (re.test(stem))
w = stem + "i";
}
// Step 2
re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
suffix = fp[2];
re = new RegExp(mgr0);
if (re.test(stem))
w = stem + step2list[suffix];
}
// Step 3
re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
suffix = fp[2];
re = new RegExp(mgr0);
if (re.test(stem))
w = stem + step3list[suffix];
}
// Step 4
re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/;
re2 = /^(.+?)(s|t)(ion)$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
re = new RegExp(mgr1);
if (re.test(stem))
w = stem;
}
else if (re2.test(w)) {
var fp = re2.exec(w);
stem = fp[1] + fp[2];
re2 = new RegExp(mgr1);
if (re2.test(stem))
w = stem;
}
// Step 5
re = /^(.+?)e$/;
if (re.test(w)) {
var fp = re.exec(w);
stem = fp[1];
re = new RegExp(mgr1);
re2 = new RegExp(meq1);
re3 = new RegExp("^" + C + v + "[^aeiouwxy]$");
if (re.test(stem) || (re2.test(stem) && !(re3.test(stem))))
w = stem;
}
re = /ll$/;
re2 = new RegExp(mgr1);
if (re.test(w) && re2.test(w)) {
re = /.$/;
w = w.replace(re,"");
}
// and turn initial Y back to y
if (firstch == "y")
w = firstch.toLowerCase() + w.substr(1);
return w;
}
}

BIN
_static/minus.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 90 B

BIN
_static/plus.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 90 B

75
_static/pygments.css Normal file
View File

@ -0,0 +1,75 @@
pre { line-height: 125%; }
td.linenos .normal { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
span.linenos { color: inherit; background-color: transparent; padding-left: 5px; padding-right: 5px; }
td.linenos .special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
span.linenos.special { color: #000000; background-color: #ffffc0; padding-left: 5px; padding-right: 5px; }
.highlight .hll { background-color: #ffffcc }
.highlight { background: #eeffcc; }
.highlight .c { color: #408090; font-style: italic } /* Comment */
.highlight .err { border: 1px solid #FF0000 } /* Error */
.highlight .k { color: #007020; font-weight: bold } /* Keyword */
.highlight .o { color: #666666 } /* Operator */
.highlight .ch { color: #408090; font-style: italic } /* Comment.Hashbang */
.highlight .cm { color: #408090; font-style: italic } /* Comment.Multiline */
.highlight .cp { color: #007020 } /* Comment.Preproc */
.highlight .cpf { color: #408090; font-style: italic } /* Comment.PreprocFile */
.highlight .c1 { color: #408090; font-style: italic } /* Comment.Single */
.highlight .cs { color: #408090; background-color: #fff0f0 } /* Comment.Special */
.highlight .gd { color: #A00000 } /* Generic.Deleted */
.highlight .ge { font-style: italic } /* Generic.Emph */
.highlight .ges { font-weight: bold; font-style: italic } /* Generic.EmphStrong */
.highlight .gr { color: #FF0000 } /* Generic.Error */
.highlight .gh { color: #000080; font-weight: bold } /* Generic.Heading */
.highlight .gi { color: #00A000 } /* Generic.Inserted */
.highlight .go { color: #333333 } /* Generic.Output */
.highlight .gp { color: #c65d09; font-weight: bold } /* Generic.Prompt */
.highlight .gs { font-weight: bold } /* Generic.Strong */
.highlight .gu { color: #800080; font-weight: bold } /* Generic.Subheading */
.highlight .gt { color: #0044DD } /* Generic.Traceback */
.highlight .kc { color: #007020; font-weight: bold } /* Keyword.Constant */
.highlight .kd { color: #007020; font-weight: bold } /* Keyword.Declaration */
.highlight .kn { color: #007020; font-weight: bold } /* Keyword.Namespace */
.highlight .kp { color: #007020 } /* Keyword.Pseudo */
.highlight .kr { color: #007020; font-weight: bold } /* Keyword.Reserved */
.highlight .kt { color: #902000 } /* Keyword.Type */
.highlight .m { color: #208050 } /* Literal.Number */
.highlight .s { color: #4070a0 } /* Literal.String */
.highlight .na { color: #4070a0 } /* Name.Attribute */
.highlight .nb { color: #007020 } /* Name.Builtin */
.highlight .nc { color: #0e84b5; font-weight: bold } /* Name.Class */
.highlight .no { color: #60add5 } /* Name.Constant */
.highlight .nd { color: #555555; font-weight: bold } /* Name.Decorator */
.highlight .ni { color: #d55537; font-weight: bold } /* Name.Entity */
.highlight .ne { color: #007020 } /* Name.Exception */
.highlight .nf { color: #06287e } /* Name.Function */
.highlight .nl { color: #002070; font-weight: bold } /* Name.Label */
.highlight .nn { color: #0e84b5; font-weight: bold } /* Name.Namespace */
.highlight .nt { color: #062873; font-weight: bold } /* Name.Tag */
.highlight .nv { color: #bb60d5 } /* Name.Variable */
.highlight .ow { color: #007020; font-weight: bold } /* Operator.Word */
.highlight .w { color: #bbbbbb } /* Text.Whitespace */
.highlight .mb { color: #208050 } /* Literal.Number.Bin */
.highlight .mf { color: #208050 } /* Literal.Number.Float */
.highlight .mh { color: #208050 } /* Literal.Number.Hex */
.highlight .mi { color: #208050 } /* Literal.Number.Integer */
.highlight .mo { color: #208050 } /* Literal.Number.Oct */
.highlight .sa { color: #4070a0 } /* Literal.String.Affix */
.highlight .sb { color: #4070a0 } /* Literal.String.Backtick */
.highlight .sc { color: #4070a0 } /* Literal.String.Char */
.highlight .dl { color: #4070a0 } /* Literal.String.Delimiter */
.highlight .sd { color: #4070a0; font-style: italic } /* Literal.String.Doc */
.highlight .s2 { color: #4070a0 } /* Literal.String.Double */
.highlight .se { color: #4070a0; font-weight: bold } /* Literal.String.Escape */
.highlight .sh { color: #4070a0 } /* Literal.String.Heredoc */
.highlight .si { color: #70a0d0; font-style: italic } /* Literal.String.Interpol */
.highlight .sx { color: #c65d09 } /* Literal.String.Other */
.highlight .sr { color: #235388 } /* Literal.String.Regex */
.highlight .s1 { color: #4070a0 } /* Literal.String.Single */
.highlight .ss { color: #517918 } /* Literal.String.Symbol */
.highlight .bp { color: #007020 } /* Name.Builtin.Pseudo */
.highlight .fm { color: #06287e } /* Name.Function.Magic */
.highlight .vc { color: #bb60d5 } /* Name.Variable.Class */
.highlight .vg { color: #bb60d5 } /* Name.Variable.Global */
.highlight .vi { color: #bb60d5 } /* Name.Variable.Instance */
.highlight .vm { color: #bb60d5 } /* Name.Variable.Magic */
.highlight .il { color: #208050 } /* Literal.Number.Integer.Long */

578
_static/searchtools.js Normal file
View File

@ -0,0 +1,578 @@
/*
* searchtools.js
* ~~~~~~~~~~~~~~~~
*
* Sphinx JavaScript utilities for the full-text search.
*
* :copyright: Copyright 2007-2023 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
"use strict";
/**
* Simple result scoring code.
*/
if (typeof Scorer === "undefined") {
var Scorer = {
// Implement the following function to further tweak the score for each result
// The function takes a result array [docname, title, anchor, descr, score, filename]
// and returns the new score.
/*
score: result => {
const [docname, title, anchor, descr, score, filename] = result
return score
},
*/
// query matches the full name of an object
objNameMatch: 11,
// or matches in the last dotted part of the object name
objPartialMatch: 6,
// Additive scores depending on the priority of the object
objPrio: {
0: 15, // used to be importantResults
1: 5, // used to be objectResults
2: -5, // used to be unimportantResults
},
// Used when the priority is not in the mapping.
objPrioDefault: 0,
// query found in title
title: 15,
partialTitle: 7,
// query found in terms
term: 5,
partialTerm: 2,
};
}
const _removeChildren = (element) => {
while (element && element.lastChild) element.removeChild(element.lastChild);
};
/**
* See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#escaping
*/
const _escapeRegExp = (string) =>
string.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&"); // $& means the whole matched string
const _displayItem = (item, searchTerms, highlightTerms) => {
const docBuilder = DOCUMENTATION_OPTIONS.BUILDER;
const docFileSuffix = DOCUMENTATION_OPTIONS.FILE_SUFFIX;
const docLinkSuffix = DOCUMENTATION_OPTIONS.LINK_SUFFIX;
const showSearchSummary = DOCUMENTATION_OPTIONS.SHOW_SEARCH_SUMMARY;
const contentRoot = document.documentElement.dataset.content_root
?? DOCUMENTATION_OPTIONS.URL_ROOT;
const [docName, title, anchor, descr, score, _filename] = item;
let listItem = document.createElement("li");
let requestUrl;
let linkUrl;
if (docBuilder === "dirhtml") {
// dirhtml builder
let dirname = docName + "/";
if (dirname.match(/\/index\/$/))
dirname = dirname.substring(0, dirname.length - 6);
else if (dirname === "index/") dirname = "";
requestUrl = contentRoot + dirname;
linkUrl = requestUrl;
} else {
// normal html builders
requestUrl = contentRoot + docName + docFileSuffix;
linkUrl = docName + docLinkSuffix;
}
let linkEl = listItem.appendChild(document.createElement("a"));
linkEl.href = linkUrl + anchor;
linkEl.dataset.score = score;
linkEl.innerHTML = title;
if (descr) {
listItem.appendChild(document.createElement("span")).innerHTML =
" (" + descr + ")";
// highlight search terms in the description
if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js
highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
}
else if (showSearchSummary)
fetch(requestUrl)
.then((responseData) => responseData.text())
.then((data) => {
if (data)
listItem.appendChild(
Search.makeSearchSummary(data, searchTerms)
);
// highlight search terms in the summary
if (SPHINX_HIGHLIGHT_ENABLED) // set in sphinx_highlight.js
highlightTerms.forEach((term) => _highlightText(listItem, term, "highlighted"));
});
Search.output.appendChild(listItem);
};
const _finishSearch = (resultCount) => {
Search.stopPulse();
Search.title.innerText = _("Search Results");
if (!resultCount)
Search.status.innerText = Documentation.gettext(
"Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories."
);
else
Search.status.innerText = _(
`Search finished, found ${resultCount} page(s) matching the search query.`
);
};
const _displayNextItem = (
results,
resultCount,
searchTerms,
highlightTerms,
) => {
// results left, load the summary and display it
// this is intended to be dynamic (don't sub resultsCount)
if (results.length) {
_displayItem(results.pop(), searchTerms, highlightTerms);
setTimeout(
() => _displayNextItem(results, resultCount, searchTerms, highlightTerms),
5
);
}
// search finished, update title and status message
else _finishSearch(resultCount);
};
/**
* Default splitQuery function. Can be overridden in ``sphinx.search`` with a
* custom function per language.
*
* The regular expression works by splitting the string on consecutive characters
* that are not Unicode letters, numbers, underscores, or emoji characters.
* This is the same as ``\W+`` in Python, preserving the surrogate pair area.
*/
if (typeof splitQuery === "undefined") {
var splitQuery = (query) => query
.split(/[^\p{Letter}\p{Number}_\p{Emoji_Presentation}]+/gu)
.filter(term => term) // remove remaining empty strings
}
/**
* Search Module
*/
const Search = {
_index: null,
_queued_query: null,
_pulse_status: -1,
htmlToText: (htmlString) => {
const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html');
htmlElement.querySelectorAll(".headerlink").forEach((el) => { el.remove() });
const docContent = htmlElement.querySelector('[role="main"]');
if (docContent !== undefined) return docContent.textContent;
console.warn(
"Content block not found. Sphinx search tries to obtain it via '[role=main]'. Could you check your theme or template."
);
return "";
},
init: () => {
const query = new URLSearchParams(window.location.search).get("q");
document
.querySelectorAll('input[name="q"]')
.forEach((el) => (el.value = query));
if (query) Search.performSearch(query);
},
loadIndex: (url) =>
(document.body.appendChild(document.createElement("script")).src = url),
setIndex: (index) => {
Search._index = index;
if (Search._queued_query !== null) {
const query = Search._queued_query;
Search._queued_query = null;
Search.query(query);
}
},
hasIndex: () => Search._index !== null,
deferQuery: (query) => (Search._queued_query = query),
stopPulse: () => (Search._pulse_status = -1),
startPulse: () => {
if (Search._pulse_status >= 0) return;
const pulse = () => {
Search._pulse_status = (Search._pulse_status + 1) % 4;
Search.dots.innerText = ".".repeat(Search._pulse_status);
if (Search._pulse_status >= 0) window.setTimeout(pulse, 500);
};
pulse();
},
/**
* perform a search for something (or wait until index is loaded)
*/
performSearch: (query) => {
// create the required interface elements
const searchText = document.createElement("h2");
searchText.textContent = _("Searching");
const searchSummary = document.createElement("p");
searchSummary.classList.add("search-summary");
searchSummary.innerText = "";
const searchList = document.createElement("ul");
searchList.classList.add("search");
const out = document.getElementById("search-results");
Search.title = out.appendChild(searchText);
Search.dots = Search.title.appendChild(document.createElement("span"));
Search.status = out.appendChild(searchSummary);
Search.output = out.appendChild(searchList);
const searchProgress = document.getElementById("search-progress");
// Some themes don't use the search progress node
if (searchProgress) {
searchProgress.innerText = _("Preparing search...");
}
Search.startPulse();
// index already loaded, the browser was quick!
if (Search.hasIndex()) Search.query(query);
else Search.deferQuery(query);
},
/**
* execute search (requires search index to be loaded)
*/
query: (query) => {
const filenames = Search._index.filenames;
const docNames = Search._index.docnames;
const titles = Search._index.titles;
const allTitles = Search._index.alltitles;
const indexEntries = Search._index.indexentries;
// stem the search terms and add them to the correct list
const stemmer = new Stemmer();
const searchTerms = new Set();
const excludedTerms = new Set();
const highlightTerms = new Set();
const objectTerms = new Set(splitQuery(query.toLowerCase().trim()));
splitQuery(query.trim()).forEach((queryTerm) => {
const queryTermLower = queryTerm.toLowerCase();
// maybe skip this "word"
// stopwords array is from language_data.js
if (
stopwords.indexOf(queryTermLower) !== -1 ||
queryTerm.match(/^\d+$/)
)
return;
// stem the word
let word = stemmer.stemWord(queryTermLower);
// select the correct list
if (word[0] === "-") excludedTerms.add(word.substr(1));
else {
searchTerms.add(word);
highlightTerms.add(queryTermLower);
}
});
if (SPHINX_HIGHLIGHT_ENABLED) { // set in sphinx_highlight.js
localStorage.setItem("sphinx_highlight_terms", [...highlightTerms].join(" "))
}
// console.debug("SEARCH: searching for:");
// console.info("required: ", [...searchTerms]);
// console.info("excluded: ", [...excludedTerms]);
// array of [docname, title, anchor, descr, score, filename]
let results = [];
_removeChildren(document.getElementById("search-progress"));
const queryLower = query.toLowerCase();
for (const [title, foundTitles] of Object.entries(allTitles)) {
if (title.toLowerCase().includes(queryLower) && (queryLower.length >= title.length/2)) {
for (const [file, id] of foundTitles) {
let score = Math.round(100 * queryLower.length / title.length)
results.push([
docNames[file],
titles[file] !== title ? `${titles[file]} > ${title}` : title,
id !== null ? "#" + id : "",
null,
score,
filenames[file],
]);
}
}
}
// search for explicit entries in index directives
for (const [entry, foundEntries] of Object.entries(indexEntries)) {
if (entry.includes(queryLower) && (queryLower.length >= entry.length/2)) {
for (const [file, id] of foundEntries) {
let score = Math.round(100 * queryLower.length / entry.length)
results.push([
docNames[file],
titles[file],
id ? "#" + id : "",
null,
score,
filenames[file],
]);
}
}
}
// lookup as object
objectTerms.forEach((term) =>
results.push(...Search.performObjectSearch(term, objectTerms))
);
// lookup as search terms in fulltext
results.push(...Search.performTermsSearch(searchTerms, excludedTerms));
// let the scorer override scores with a custom scoring function
if (Scorer.score) results.forEach((item) => (item[4] = Scorer.score(item)));
// now sort the results by score (in opposite order of appearance, since the
// display function below uses pop() to retrieve items) and then
// alphabetically
results.sort((a, b) => {
const leftScore = a[4];
const rightScore = b[4];
if (leftScore === rightScore) {
// same score: sort alphabetically
const leftTitle = a[1].toLowerCase();
const rightTitle = b[1].toLowerCase();
if (leftTitle === rightTitle) return 0;
return leftTitle > rightTitle ? -1 : 1; // inverted is intentional
}
return leftScore > rightScore ? 1 : -1;
});
// remove duplicate search results
// note the reversing of results, so that in the case of duplicates, the highest-scoring entry is kept
let seen = new Set();
results = results.reverse().reduce((acc, result) => {
let resultStr = result.slice(0, 4).concat([result[5]]).map(v => String(v)).join(',');
if (!seen.has(resultStr)) {
acc.push(result);
seen.add(resultStr);
}
return acc;
}, []);
results = results.reverse();
// for debugging
//Search.lastresults = results.slice(); // a copy
// console.info("search results:", Search.lastresults);
// print the results
_displayNextItem(results, results.length, searchTerms, highlightTerms);
},
/**
* search for object names
*/
performObjectSearch: (object, objectTerms) => {
const filenames = Search._index.filenames;
const docNames = Search._index.docnames;
const objects = Search._index.objects;
const objNames = Search._index.objnames;
const titles = Search._index.titles;
const results = [];
const objectSearchCallback = (prefix, match) => {
const name = match[4]
const fullname = (prefix ? prefix + "." : "") + name;
const fullnameLower = fullname.toLowerCase();
if (fullnameLower.indexOf(object) < 0) return;
let score = 0;
const parts = fullnameLower.split(".");
// check for different match types: exact matches of full name or
// "last name" (i.e. last dotted part)
if (fullnameLower === object || parts.slice(-1)[0] === object)
score += Scorer.objNameMatch;
else if (parts.slice(-1)[0].indexOf(object) > -1)
score += Scorer.objPartialMatch; // matches in last name
const objName = objNames[match[1]][2];
const title = titles[match[0]];
// If more than one term searched for, we require other words to be
// found in the name/title/description
const otherTerms = new Set(objectTerms);
otherTerms.delete(object);
if (otherTerms.size > 0) {
const haystack = `${prefix} ${name} ${objName} ${title}`.toLowerCase();
if (
[...otherTerms].some((otherTerm) => haystack.indexOf(otherTerm) < 0)
)
return;
}
let anchor = match[3];
if (anchor === "") anchor = fullname;
else if (anchor === "-") anchor = objNames[match[1]][1] + "-" + fullname;
const descr = objName + _(", in ") + title;
// add custom score for some objects according to scorer
if (Scorer.objPrio.hasOwnProperty(match[2]))
score += Scorer.objPrio[match[2]];
else score += Scorer.objPrioDefault;
results.push([
docNames[match[0]],
fullname,
"#" + anchor,
descr,
score,
filenames[match[0]],
]);
};
Object.keys(objects).forEach((prefix) => {
if (!(objects[prefix] instanceof Array)) {
objects[prefix] = Object.entries(objects[prefix]).map(([name, match]) => [...match, name]);
}
objects[prefix].forEach((array) =>
objectSearchCallback(prefix, array)
);
});
return results;
},
/**
* search for full-text terms in the index
*/
performTermsSearch: (searchTerms, excludedTerms) => {
// prepare search
const terms = Search._index.terms;
const titleTerms = Search._index.titleterms;
const filenames = Search._index.filenames;
const docNames = Search._index.docnames;
const titles = Search._index.titles;
const scoreMap = new Map();
const fileMap = new Map();
// perform the search on the required terms
searchTerms.forEach((word) => {
const files = [];
const arr = [
{ files: terms[word], score: Scorer.term },
{ files: titleTerms[word], score: Scorer.title },
];
// add support for partial matches
if (word.length > 2) {
const escapedWord = _escapeRegExp(word);
Object.keys(terms).forEach((term) => {
if (term.match(escapedWord) && !terms[word])
arr.push({ files: terms[term], score: Scorer.partialTerm });
});
Object.keys(titleTerms).forEach((term) => {
if (term.match(escapedWord) && !titleTerms[word])
arr.push({ files: titleTerms[word], score: Scorer.partialTitle });
});
}
// no match but word was a required one
if (arr.every((record) => record.files === undefined)) return;
// found search word in contents
arr.forEach((record) => {
if (record.files === undefined) return;
let recordFiles = record.files;
if (recordFiles.length === undefined) recordFiles = [recordFiles];
files.push(...recordFiles);
// set score for the word in each file
recordFiles.forEach((file) => {
if (!scoreMap.has(file)) scoreMap.set(file, {});
scoreMap.get(file)[word] = record.score;
});
});
// create the mapping
files.forEach((file) => {
if (fileMap.has(file) && fileMap.get(file).indexOf(word) === -1)
fileMap.get(file).push(word);
else fileMap.set(file, [word]);
});
});
// now check if the files don't contain excluded terms
const results = [];
for (const [file, wordList] of fileMap) {
// check if all requirements are matched
// as search terms with length < 3 are discarded
const filteredTermCount = [...searchTerms].filter(
(term) => term.length > 2
).length;
if (
wordList.length !== searchTerms.size &&
wordList.length !== filteredTermCount
)
continue;
// ensure that none of the excluded terms is in the search result
if (
[...excludedTerms].some(
(term) =>
terms[term] === file ||
titleTerms[term] === file ||
(terms[term] || []).includes(file) ||
(titleTerms[term] || []).includes(file)
)
)
break;
// select one (max) score for the file.
const score = Math.max(...wordList.map((w) => scoreMap.get(file)[w]));
// add result to the result list
results.push([
docNames[file],
titles[file],
"",
null,
score,
filenames[file],
]);
}
return results;
},
/**
* helper function to return a node containing the
* search summary for a given text. keywords is a list
* of stemmed words.
*/
makeSearchSummary: (htmlText, keywords) => {
const text = Search.htmlToText(htmlText);
if (text === "") return null;
const textLower = text.toLowerCase();
const actualStartPosition = [...keywords]
.map((k) => textLower.indexOf(k.toLowerCase()))
.filter((i) => i > -1)
.slice(-1)[0];
const startWithContext = Math.max(actualStartPosition - 120, 0);
const top = startWithContext === 0 ? "" : "...";
const tail = startWithContext + 240 < text.length ? "..." : "";
let summary = document.createElement("p");
summary.classList.add("context");
summary.textContent = top + text.substr(startWithContext, 240).trim() + tail;
return summary;
},
};
_ready(Search.init);

154
_static/sphinx_highlight.js Normal file
View File

@ -0,0 +1,154 @@
/* Highlighting utilities for Sphinx HTML documentation. */
"use strict";
const SPHINX_HIGHLIGHT_ENABLED = true
/**
* highlight a given string on a node by wrapping it in
* span elements with the given class name.
*/
const _highlight = (node, addItems, text, className) => {
if (node.nodeType === Node.TEXT_NODE) {
const val = node.nodeValue;
const parent = node.parentNode;
const pos = val.toLowerCase().indexOf(text);
if (
pos >= 0 &&
!parent.classList.contains(className) &&
!parent.classList.contains("nohighlight")
) {
let span;
const closestNode = parent.closest("body, svg, foreignObject");
const isInSVG = closestNode && closestNode.matches("svg");
if (isInSVG) {
span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
} else {
span = document.createElement("span");
span.classList.add(className);
}
span.appendChild(document.createTextNode(val.substr(pos, text.length)));
const rest = document.createTextNode(val.substr(pos + text.length));
parent.insertBefore(
span,
parent.insertBefore(
rest,
node.nextSibling
)
);
node.nodeValue = val.substr(0, pos);
/* There may be more occurrences of search term in this node. So call this
* function recursively on the remaining fragment.
*/
_highlight(rest, addItems, text, className);
if (isInSVG) {
const rect = document.createElementNS(
"http://www.w3.org/2000/svg",
"rect"
);
const bbox = parent.getBBox();
rect.x.baseVal.value = bbox.x;
rect.y.baseVal.value = bbox.y;
rect.width.baseVal.value = bbox.width;
rect.height.baseVal.value = bbox.height;
rect.setAttribute("class", className);
addItems.push({ parent: parent, target: rect });
}
}
} else if (node.matches && !node.matches("button, select, textarea")) {
node.childNodes.forEach((el) => _highlight(el, addItems, text, className));
}
};
const _highlightText = (thisNode, text, className) => {
let addItems = [];
_highlight(thisNode, addItems, text, className);
addItems.forEach((obj) =>
obj.parent.insertAdjacentElement("beforebegin", obj.target)
);
};
/**
* Small JavaScript module for the documentation.
*/
const SphinxHighlight = {
/**
* highlight the search words provided in localstorage in the text
*/
highlightSearchWords: () => {
if (!SPHINX_HIGHLIGHT_ENABLED) return; // bail if no highlight
// get and clear terms from localstorage
const url = new URL(window.location);
const highlight =
localStorage.getItem("sphinx_highlight_terms")
|| url.searchParams.get("highlight")
|| "";
localStorage.removeItem("sphinx_highlight_terms")
url.searchParams.delete("highlight");
window.history.replaceState({}, "", url);
// get individual terms from highlight string
const terms = highlight.toLowerCase().split(/\s+/).filter(x => x);
if (terms.length === 0) return; // nothing to do
// There should never be more than one element matching "div.body"
const divBody = document.querySelectorAll("div.body");
const body = divBody.length ? divBody[0] : document.querySelector("body");
window.setTimeout(() => {
terms.forEach((term) => _highlightText(body, term, "highlighted"));
}, 10);
const searchBox = document.getElementById("searchbox");
if (searchBox === null) return;
searchBox.appendChild(
document
.createRange()
.createContextualFragment(
'<p class="highlight-link">' +
'<a href="javascript:SphinxHighlight.hideSearchWords()">' +
_("Hide Search Matches") +
"</a></p>"
)
);
},
/**
* helper function to hide the search marks again
*/
hideSearchWords: () => {
document
.querySelectorAll("#searchbox .highlight-link")
.forEach((el) => el.remove());
document
.querySelectorAll("span.highlighted")
.forEach((el) => el.classList.remove("highlighted"));
localStorage.removeItem("sphinx_highlight_terms")
},
initEscapeListener: () => {
// only install a listener if it is really needed
if (!DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS) return;
document.addEventListener("keydown", (event) => {
// bail for input elements
if (BLACKLISTED_KEY_CONTROL_ELEMENTS.has(document.activeElement.tagName)) return;
// bail with special keys
if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) return;
if (DOCUMENTATION_OPTIONS.ENABLE_SEARCH_SHORTCUTS && (event.key === "Escape")) {
SphinxHighlight.hideSearchWords();
event.preventDefault();
}
});
},
};
_ready(() => {
/* Do not call highlightSearchWords() when we are on the search page.
* It will highlight words from the *previous* search query.
*/
if (typeof Search === "undefined") SphinxHighlight.highlightSearchWords();
SphinxHighlight.initEscapeListener();
});

311
developer/getting_started.html Normal file
View File

@ -0,0 +1,311 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Getting Started as a Contributor &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=cb25574f" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=888ff710"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="The Regression Test Suite" href="regression_tests.html" />
<link rel="prev" title="Icarus Verilog Developer Support" href="index.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="getting-started-as-a-contributor">
<h1>Getting Started as a Contributor<a class="headerlink" href="#getting-started-as-a-contributor" title="Link to this heading"></a></h1>
<p>Icarus Verilog development is centered around the github repository at
<a class="reference external" href="http://github.com/steveicarus/iverilog">github.com/steveicarus/iverilog</a>.
Contributing to Icarus Verilog requires a basic knowledge of git and github,
so see the github documentation for more information. The sections below will
step you through the basics of getting the source code from github, making a
branch, and submitting a pull request for review.</p>
<section id="getting-icarus-verilog">
<h2>Getting Icarus Verilog<a class="headerlink" href="#getting-icarus-verilog" title="Link to this heading"></a></h2>
<p>To start, you will need to clone the code. It is preferred that you use the
“ssh” method, and the ssh based clone with the command:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>git<span class="w"> </span>clone<span class="w"> </span>git@github.com:steveicarus/iverilog.git
</pre></div>
</div>
<p>This assumes that you have a github account (accounts are free) and you have
set up your ssh authentication keys. See the
<a class="reference external" href="https://docs.github.com/en/authentication">Authentication Guides here</a>.</p>
<p>The “git clone” command will get you all the source:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>git<span class="w"> </span>clone<span class="w"> </span>git@github.com:steveicarus/iverilog.git
<span class="go">Cloning into &#39;iverilog&#39;...</span>
<span class="go">remote: Enumerating objects: 66234, done.</span>
<span class="go">remote: Counting objects: 100% (6472/6472), done.</span>
<span class="go">remote: Compressing objects: 100% (4123/4123), done.</span>
<span class="go">remote: Total 66234 (delta 2412), reused 6039 (delta 2190), pack-reused 59762</span>
<span class="go">Receiving objects: 100% (66234/66234), 27.98 MiB | 2.53 MiB/s, done.</span>
<span class="go">Resolving deltas: 100% (50234/50234), done.</span>
<span class="gp">% </span><span class="nb">cd</span><span class="w"> </span>iverilog/
</pre></div>
</div>
<p>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 a
specific version, say for example version 11, the v11-branch, you checkout
that branch with the command:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>git<span class="w"> </span>checkout<span class="w"> </span>--track<span class="w"> </span>-b<span class="w"> </span>v11-branch<span class="w"> </span>origin/v11-branch
</pre></div>
</div>
<p>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.</p>
<p>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:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>git<span class="w"> </span>pull
<span class="go">Already up to date.</span>
</pre></div>
</div>
<p>Finally, configuration files are built by the extra step:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>sh<span class="w"> </span>autoconf.sh
<span class="go">Autoconf in root...</span>
<span class="go">Precompiling lexor_keyword.gperf</span>
<span class="go">Precompiling vhdlpp/lexor_keyword.gperf</span>
</pre></div>
</div>
<p>You will need autoconf and gperf installed in order for the script to work.
If you get errors such as:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>sh<span class="w"> </span>autoconf.sh
<span class="go">Autoconf in root...</span>
<span class="go">autoconf.sh: 10: autoconf: not found</span>
<span class="go">Precompiling lexor_keyword.gperf</span>
<span class="go">autoconf.sh: 13: gperf: not found.</span>
</pre></div>
</div>
<p>You will need to install download and install the autoconf and gperf tools.</p>
<p>Now you are ready to configure and compile the source.</p>
</section>
<section id="icarus-specific-configuration-options">
<h2>Icarus Specific Configuration Options<a class="headerlink" href="#icarus-specific-configuration-options" title="Link to this heading"></a></h2>
<p>Icarus takes many of the standard configuration options and those will not be
described here. The following are specific to Icarus Verilog:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>--enable-suffix[=suffix]
</pre></div>
</div>
<p>This option allows the user to build Icarus with a default suffix or when
provided a user defined suffix. 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).</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>--enable-libvvp
</pre></div>
</div>
<p>The vvp progam is built as a small stub linked to a shared library,
libvvp.so, that may be linked with other programs so that they can host
a vvp simulation.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>--enable-libveriuser
</pre></div>
</div>
<p>PLI version 1 (the ACC and TF routines) were deprecated in IEEE 1364-2005.
These are supported in Icarus Verilog by the libveriuser library and cadpli
module. Starting with v13, these will only be built if this option is used.</p>
<p>A debug options is:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>--with-valgrind
</pre></div>
</div>
<p>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
needed when checking for basic errors with valgrind.</p>
</section>
<section id="compiling-on-linux">
<h2>Compiling on Linux<a class="headerlink" href="#compiling-on-linux" title="Link to this heading"></a></h2>
<p>(Note: You will need to install bison, flex, g++ and gcc) This is probably the
easiest step. Given that you have the source tree from the above instructions,
the compile and install is generally as simple as:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>./configure
<span class="go">configure: loading site script /usr/share/site/x86_64-unknown-linux-gnu</span>
<span class="go">checking build system type... x86_64-unknown-linux-gnu</span>
<span class="go">checking host system type... x86_64-unknown-linux-gnu</span>
<span class="go">checking for gcc... gcc</span>
<span class="go">checking whether the C compiler works... yes</span>
<span class="go">checking for C compiler default output file name... a.out</span>
<span class="go">checking for suffix of executables...</span>
<span class="go">[...and so on...]</span>
<span class="gp">% </span>make
<span class="go">mkdir dep</span>
<span class="go">Using git-describe for VERSION_TAG</span>
<span class="go">g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c main.cc -o main.o</span>
<span class="go">mv main.d dep/main.d</span>
<span class="go">g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c async.cc -o async.o</span>
<span class="go">mv async.d dep/async.d</span>
<span class="go">g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c design_dump.cc -o design_dump.o</span>
<span class="go">mv design_dump.d dep/design_dump.d</span>
<span class="go">g++ -DHAVE_CONFIG_H -I. -Ilibmisc -Wall -Wextra -Wshadow -g -O2 -MD -c discipline.cc -o discipline.o</span>
<span class="go">[...and so on...]</span>
</pre></div>
</div>
<p>The end result is a complete build of Icarus Verilog. You can install your
compiled version with a command like this:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>sudo<span class="w"> </span>make<span class="w"> </span>install
</pre></div>
</div>
</section>
<section id="regression-tests">
<h2>Regression Tests<a class="headerlink" href="#regression-tests" title="Link to this heading"></a></h2>
<p>Icarus Verilog comes with a fairly extensive regression test suite. As of
2022, that test suite is included with the source in the “ivtest”
directory. Contained in that directory are a couple driver scripts that run
all the regression tests on the installed version of Icarus Verilog. So for
example:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span><span class="nb">cd</span><span class="w"> </span>ivtest
<span class="gp">% </span>./vvp_reg.pl<span class="w"> </span>--strict
</pre></div>
</div>
<p>will run all the regression tests for the simulation engine. (This is what
most people will want to do.) You should rerun this test before submitting
patches to the developers. Also, if you are adding a new feature, you should
add test programs to the regression test suite to validate your new feature
(or bug fix.)</p>
<p>Note that pull requests will be required to pass these regression tests before
being merged.</p>
</section>
<section id="forks-branches-and-pull-requests">
<h2>Forks, Branches and Pull Requests<a class="headerlink" href="#forks-branches-and-pull-requests" title="Link to this heading"></a></h2>
<p>Currently, the preferred way to submit patches to Icarus Verilog is via pull
requests.
<a class="reference external" href="https://docs.github.com/en/github-ae&#64;latest/pull-requests">Pull requests</a>
can be created from the main repository if you have write access (very few
people have write access) or more commonly from a fork, so the first step is
to create a fork that you can work with. It is easy enough to create a fork,
just go to the
<a class="reference external" href="http://github.com/steveicarus/iverilog">github.com/steveicarus/iverilog</a>
page and use the “fork” button in the upper right corner. This will create
a new repository that you can clone instead of the steveicarus/iverilog
repository. You then use your local repository to create feature branches,
then submit them for inclusion in the main repository as pull
requests. Remember to <a class="reference external" href="https://docs.github.com/en/github-ae&#64;latest/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork">synchronize your fork</a>
periodically with the main repository. This will make sure your work is based
on the latest upstream and avoid merge conflicts.</p>
<p>Create your patch by first creating a branch that contains your commits:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>git<span class="w"> </span>checkout<span class="w"> </span>-b<span class="w"> </span>my-github-id/branch-name
</pre></div>
</div>
<p>We are encouraging using this scheme for naming your branches that are
destined for pull requests. Use your github id in the branch name. So for
example:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>git<span class="w"> </span>checkout<span class="w"> </span>-b<span class="w"> </span>steveicarus/foo-feature
</pre></div>
</div>
<p>Do your work in this branch, then when you are ready to create a pull request,
first push the branch up to github:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">% </span>git<span class="w"> </span>push<span class="w"> </span>-u<span class="w"> </span>origin<span class="w"> </span>my-github-id/branch-name
</pre></div>
</div>
<p>Then go to github.com to create your pull request. <a class="reference external" href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork">Create your pull request
against the “master” branch of the upstream repository</a>,
or the version branch that you are working on. Your pull request will be run
through continuous integration, and reviewed by one of the main
authors. Feedback may be offered to your PR, and once accepted, an approved
individual will merge it for you. Then you are done.</p>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2 current"><a class="current reference internal" href="#">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2"><a class="reference internal" href="guide/index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../index.html">Documentation overview</a><ul>
<li><a href="index.html">Icarus Verilog Developer Support</a><ul>
<li>Previous: <a href="index.html" title="previous chapter">Icarus Verilog Developer Support</a></li>
<li>Next: <a href="regression_tests.html" title="next chapter">The Regression Test Suite</a></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../_sources/developer/getting_started.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

150
developer/glossary.html Normal file
View File

@ -0,0 +1,150 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Glossary &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=cb25574f" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=888ff710"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="prev" title="Xilinx Hint" href="guide/misc/xilinx-hint.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="glossary">
<h1>Glossary<a class="headerlink" href="#glossary" title="Link to this heading"></a></h1>
<p>Throughout Icarus Verilog descriptions and source code, I use a
variety of terms and acronyms that might be specific to Icarus
Verilog, have an Icarus Verilog specific meaning, or just aren’t
widely known. So here I define these terms.</p>
<dl class="simple">
<dt>LRM - Language Reference Manual</dt><dd><p>This is a generic acronym, but in the Verilog world we sometimes
mean <em>the</em> language reference manual, the IEEE1364 standard.</p>
</dd>
<dt>PLI - Programming Language Interface</dt><dd><p>This is a C API into Verilog simulators that is defined by the
IEEE1364. There are two major interfaces, sometimes called PLI 1
and PLI 2. PLI 2 is also often called VPI.</p>
</dd>
<dt>UDP - User Defined Primitive</dt><dd><p>These are objects that Verilog programmers define with the
“primitive” keyword. They are truth-table based devices. The
syntax for defining them is described in the LRM.</p>
</dd>
<dt>VPI - Verilog Procedural Interface</dt><dd><p>This is the C API that is defined by the Verilog standard, and
that Icarus Verilog partially implements. See also PLI.</p>
</dd>
<dt>VVM - Verilog Virtual Machine</dt><dd><p>This is the Icarus Verilog runtime that works with the code
generator that generates C++.</p>
</dd>
<dt>VVP - Verilog Virtual Processor</dt><dd><p>This is the Icarus Verilog runtime that reads in custom code in a
form that I call “VVP Assembly”.</p>
</dd>
<dt>LPM - Library of Parameterized Modules</dt><dd><p>LPM (Library of Parameterized Modules) is EIS-IS standard 103-A. It is
a standard library of abstract devices that are designed to be close
enough to the target hardware to be easily translated, yet abstract
enough to support a variety of target technologies without excessive
constraints. Icarus Verilog uses LPM internally to represent idealized
hardware, especially when doing target neutral synthesis.</p>
</dd>
</dl>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2"><a class="reference internal" href="guide/index.html">Developer Guide</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../index.html">Documentation overview</a><ul>
<li><a href="index.html">Icarus Verilog Developer Support</a><ul>
<li>Previous: <a href="guide/misc/xilinx-hint.html" title="previous chapter">Xilinx Hint</a></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../_sources/developer/glossary.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

149
developer/guide/cadpli/cadpli.html Normal file
View File

@ -0,0 +1,149 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Cadence PLI1 Modules &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Miscellaneous" href="../misc/index.html" />
<link rel="prev" title="Verilog-A math library" href="../vpi/va_math.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="cadence-pli1-modules">
<h1>Cadence PLI1 Modules<a class="headerlink" href="#cadence-pli1-modules" title="Link to this heading"></a></h1>
<p>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.</p>
<p>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”:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>vvp -mcadpli a.out -cadpli=./product.so:my_boot
</pre></div>
</div>
<p>The “-mcadpli” argument causes vvp to load the cadpli.vpl library
module. This activates the -cadpli= argument interpreter. The
-cadpli=&lt;module&gt;:&lt;boot_func&gt; 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.</p>
<p>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.</p>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li>Previous: <a href="../vpi/va_math.html" title="previous chapter">Verilog-A math library</a></li>
<li>Next: <a href="../misc/index.html" title="next chapter">Miscellaneous</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/cadpli/cadpli.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

299
developer/guide/index.html Normal file
View File

@ -0,0 +1,299 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Developer Guide &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../_static/alabaster.css?v=cb25574f" />
<script src="../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../_static/doctools.js?v=888ff710"></script>
<script src="../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="IVL - The Core Compiler" href="ivl/index.html" />
<link rel="prev" title="Files With Version Information" href="../version_stamps.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="developer-guide">
<h1>Developer Guide<a class="headerlink" href="#developer-guide" title="Link to this heading"></a></h1>
<p>The developer guide is intended to give you a gross structure of the
Icarus Verilog compiler source. This will help orient you to the
source code itself, so that you can find the global parts where you
can look for even better detail.</p>
<p>The documentation for getting, building and installing Icarus Verilog
is kept and maintained at <a class="reference internal" href="../getting_started.html"><span class="doc">Getting Started as a Contributer</span></a></p>
<p>See the Installation Guide for getting the current source from the git
repository (and how to use the git repository) and see the Developer Guide
for instructions on participating in the Icarus Verilog development process.
That information will not be repeated here.</p>
<p>Scroll down to a listing with further readings.</p>
<section id="compiler-components">
<h2>Compiler Components<a class="headerlink" href="#compiler-components" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p>The compiler driver (driver/)</p></li>
</ul>
<p>This is the binary that is installed as “iverilog”. This program takes
the command line arguments and assembles invocations of all the other
subcommands to perform the steps of compilation.</p>
<ul class="simple">
<li><p>The preprocessor (ivlpp/)</p></li>
</ul>
<p>This implements the Verilog pre-processor. In Icarus Verilog, the
compiler directives `define, `include, `ifdef and etc. are implemented
in an external program. The ivlpp/ directory contains the source for
this program.</p>
<ul class="simple">
<li><p>The core compiler (root directory)</p></li>
</ul>
<p>The “ivl” program is the core that does all the Verilog compiler
processing that is not handled elsewhere. This is the main core of the
Icarus Verilog compiler, not the runtime. See below for more details
on the core itself.</p>
<ul class="simple">
<li><p>The loadable code generators (tgt-*/)</p></li>
</ul>
<p>This core compiler, after it is finished with parsing and semantic
analysis, uses loadable code generators to emit code for supported
targets. The tgt-*/ directories contains the source for the target
code generators that are bundled with Icarus Verilog. The tgt-vvp/
directory in particular contains the code generator for the vvp
runtime.</p>
</section>
<section id="runtime-components">
<h2>Runtime Components<a class="headerlink" href="#runtime-components" title="Link to this heading"></a></h2>
<ul class="simple">
<li><p>The vvp runtime (vvp/)</p></li>
</ul>
<p>This program implements the runtime environment for Icarus
Verilog. It implements the “vvp” command described in the user
documentation. See the vvp/ subdirectory for further developer
documentation.</p>
<ul class="simple">
<li><p>The system tasks implementations (vpi/)</p></li>
</ul>
<p>The standard Verilog system tasks are implemented using VPI (PLI-2)
and the source is in this subdirectory.</p>
<ul class="simple">
<li><p>The PLI-1 compatibility library (libveriuser/)</p></li>
</ul>
<p>The Icarus Verilog support for the deprecated PLI-1 is in this
subdirectory. The vvp runtime does not directly support the
PLI-1. Instead, the libveriuser library emulates it using the builtin
PLI-2 support.</p>
<ul class="simple">
<li><p>The Cadence PLI module compatibility module (cadpli/)</p></li>
</ul>
<p>It is possible in some specialized situations to load and execute
PLI-1 code written for Verilog-XL. This directory contains the source
for the module that provides the Cadence PLI interface.</p>
</section>
<section id="the-core-compiler">
<h2>The Core Compiler<a class="headerlink" href="#the-core-compiler" title="Link to this heading"></a></h2>
<p>The “ivl” binary is the core compiler that does the heavy lifting of
compiling the Verilog source (including libraries) and generating the
output. This is the most complex component of the Icarus Verilog
compilation system.</p>
<p>The process in the abstract starts with the Verilog lexical analysis
and parsing to generate an internal “pform”. The pform is then
translated by elaboration into the “netlist” form. The netlist is
processed by some functors (which include some optimizations and
optional synthesis) then is translated into the ivl_target internal
form. And finally, the ivl_target form is passed via the ivl_target.h
API to the code generators.</p>
<ul class="simple">
<li><p>Lexical Analysis</p></li>
</ul>
<p>Lexical analysis and parsing use the tools “flex”, “gperf”, and
“bison”. The “flex” input file “lexor.lex” recognizes the tokens in
the input stream. This is called “lexical analysis”. The lexical
analyzer also does some processing of compiler directives that are not
otherwise taken care of by the external preprocessor. The lexical
analyzer uses a table of keywords that is generated using the “gperf”
program and the input file “lexor_keywords.gperf”. This table allows
the lexical analyzer to efficiently check input words with the rather
large set of potential keywords.</p>
<ul class="simple">
<li><p>Parsing</p></li>
</ul>
<p>The parser input file “parse.y” is passed to the “bison” program to
generate the parser. The parser uses the functions in parse*.h,
parse*.cc, pform.h, and pform*.cc to generate the pform from the
stream of input tokens. The pform is what compiler writers call a
“decorated parse tree”.</p>
<p>The pform itself is described by the classes in the header files
“PScope.h”, “Module.h”, “PGenerate.h”, “Statement.h”, and
“PExpr.h”. The implementations of the classes in those header files
are in the similarly named C++ files.</p>
<ul class="simple">
<li><p>Elaboration</p></li>
</ul>
<p>Elaboration transforms the pform to the netlist form. Elaboration is
conceptually divided into several major steps: Scope elaboration,
parameter overrides and defparam propagation, signal elaboration, and
statement and expression elaboration.</p>
<p>The elaboration of scopes and parameter overrides and defparam
propagation are conceptually separate, but are in practice
intermingled. The elaboration of scopes scans the pform to find and
instantiate all the scopes of the design. New scopes are created by
instantiation of modules (starting with the root instances) by user
defined tasks and functions, named blocks, and generate schemes. The
elaborate_scope methods implement scope elaboration, and the
elab_scope.cc source file has the implementations of those
methods.</p>
<p>The elaborate.cc source file contains the initial calls to the
elaborate_scope for the root scopes to get the process started. In
particular, see the “elaborate” function near the bottom of the
elaborate.cc source file. The calls to Design::make_root_scope create
the initial root scopes, and the creation and enqueue of the
elaborate_root_scope_t work items primes the scope elaboration work
list.</p>
<p>Intermingled in the work list are defparms work items that call the
Design::run_defparams and Design::evaluate_parameters methods that
override and evaluate parameters. The override and evaluation of
parameters must be intermingled with the elaboration of scopes because
the exact values of parameters may impact the scopes created (imagine
generate schemes and instance arrays) and the created scopes in turn
create new parameters that need override and evaluation.</p>
</section>
<section id="further-reading">
<h2>Further Reading<a class="headerlink" href="#further-reading" title="Link to this heading"></a></h2>
<p>For further information on the individual parts of Icarus Verilog, see this listing:</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="ivl/index.html">IVL - The Core Compiler</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ivl/netlist.html">Netlist Format</a></li>
<li class="toctree-l2"><a class="reference internal" href="ivl/attributes.html">Icarus Verilog Attributes</a></li>
<li class="toctree-l2"><a class="reference internal" href="ivl/ivl_target.html">Loadable Target API (ivl_target)</a></li>
<li class="toctree-l2"><a class="reference internal" href="ivl/lpm.html">What Is LPM</a></li>
<li class="toctree-l2"><a class="reference internal" href="ivl/t-dll.html">Loadable Targets</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="vvp/index.html">VVP - Verilog Virtual Processor</a><ul>
<li class="toctree-l2"><a class="reference internal" href="vvp/vvp.html">VVP Simulation Engine</a></li>
<li class="toctree-l2"><a class="reference internal" href="vvp/opcodes.html">Executable Instruction Opcodes</a></li>
<li class="toctree-l2"><a class="reference internal" href="vvp/vpi.html">VPI Within VVP</a></li>
<li class="toctree-l2"><a class="reference internal" href="vvp/vthread.html">Thread Details</a></li>
<li class="toctree-l2"><a class="reference internal" href="vvp/debug.html">Debug Aids For VVP</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="tgt-vvp/tgt-vvp.html">The VVP Target</a><ul>
<li class="toctree-l2"><a class="reference internal" href="tgt-vvp/tgt-vvp.html#symbol-name-conventions">Symbol Name Conventions</a></li>
<li class="toctree-l2"><a class="reference internal" href="tgt-vvp/tgt-vvp.html#general-functor-web-structure">General Functor Web Structure</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="vpi/index.html">VPI in Icarus Verilog</a><ul>
<li class="toctree-l2"><a class="reference internal" href="vpi/vpi.html">VPI Modules in Icarus Verilog</a></li>
<li class="toctree-l2"><a class="reference internal" href="vpi/va_math.html">Verilog-A math library</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="cadpli/cadpli.html">Cadence PLI1 Modules</a></li>
<li class="toctree-l1"><a class="reference internal" href="misc/index.html">Miscellaneous</a><ul>
<li class="toctree-l2"><a class="reference internal" href="misc/ieee1364-notes.html">IEEE1364 Notes</a></li>
<li class="toctree-l2"><a class="reference internal" href="misc/swift.html">Swift Model Support (Preliminary)</a></li>
<li class="toctree-l2"><a class="reference internal" href="misc/xilinx-hint.html">Xilinx Hint</a></li>
</ul>
</li>
</ul>
</div>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../index.html">Documentation overview</a><ul>
<li><a href="../index.html">Icarus Verilog Developer Support</a><ul>
<li>Previous: <a href="../version_stamps.html" title="previous chapter">Files With Version Information</a></li>
<li>Next: <a href="ivl/index.html" title="next chapter">IVL - The Core Compiler</a></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../_sources/developer/guide/index.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

205
developer/guide/ivl/attributes.html Normal file
View File

@ -0,0 +1,205 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Icarus Verilog Attributes &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Loadable Target API (ivl_target)" href="ivl_target.html" />
<link rel="prev" title="Netlist Format" href="netlist.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="icarus-verilog-attributes">
<h1>Icarus Verilog Attributes<a class="headerlink" href="#icarus-verilog-attributes" title="Link to this heading"></a></h1>
<section id="attribute-naming-conventions">
<h2>Attribute Naming Conventions<a class="headerlink" href="#attribute-naming-conventions" title="Link to this heading"></a></h2>
<p>Attributes that are specific to Icarus Verilog, and are intended to be
of use to programmers, start with the prefix “ivl_”.</p>
<p>Attributes with the “_ivl_” prefix are set aside for internal
use. They may be generated internally by the compiler. They need not
be documented here.</p>
</section>
<section id="attributes-to-control-synthesis">
<h2>Attributes To Control Synthesis<a class="headerlink" href="#attributes-to-control-synthesis" title="Link to this heading"></a></h2>
<p>The following is a summary of Verilog attributes that Icarus Verilog
understands within Verilog source files to control synthesis
behavior. This section documents generic synthesis attributes. For
target specific attributes, see target specific documentation.</p>
<p>These attributes only effect the behavior of the synthesizer. For
example, the ivl_combinational will not generate an error message
if the Verilog is being compiled for simulation. (It may generate a
warning.)</p>
<ul class="simple">
<li><p>Attributes for “always” and “initial” statements</p></li>
</ul>
<p>(* ivl_combinational *)</p>
<blockquote>
<div><p>This attribute tells the compiler that the statement models
combinational logic. If the compiler finds that it cannot make
combinational logic out of a marked always statement, it will
report an error.</p>
<p>This attribute can be used to prevent accidentally inferring
latches or flip-flops where the user intended combinational
logic.</p>
</div></blockquote>
<p>(* ivl_synthesis_on *)</p>
<blockquote>
<div><p>This attribute tells the compiler that the marked always statement
is synthesizable. The compiler will attempt to synthesize the
code in the marked “always” statement. If it cannot in any way
synthesize it, then it will report an error.</p>
</div></blockquote>
<p>(* ivl_synthesis_off *)</p>
<blockquote>
<div><p>If this value is attached to an “always” statement, then the
compiler will <em>not</em> synthesize the “always” statement. This can be
used, for example, to mark embedded test bench code.</p>
</div></blockquote>
<ul class="simple">
<li><p>Attributes for modules</p></li>
</ul>
<p>(* ivl_synthesis_cell *)</p>
<blockquote>
<div><p>If this value is attached to a module during synthesis, that
module will be considered a target architecture primitive, and
its interior will not be synthesized further. The module can
therefore hold a model for simulation purposes.</p>
</div></blockquote>
<ul class="simple">
<li><p>Attributes for signals (wire/reg/integer/tri/etc.)</p></li>
</ul>
<p>(* PAD = “&lt;pad assignment list&gt;” *)</p>
<blockquote>
<div><p>If this attribute is attached to a signal that happens to be a
root module port, then targets that support it will use the string
value as a list of pin assignments for the port/signal. The format
is a comma separated list of location tokens, with the format of
the token itself defined by the back-end tools in use.</p>
</div></blockquote>
<ul class="simple">
<li><p>Other Attributes</p></li>
</ul>
<p>[ none defined yet ]</p>
</section>
<section id="misc">
<h2>Misc<a class="headerlink" href="#misc" title="Link to this heading"></a></h2>
<p>(* _ivl_schedule_push *)</p>
<blockquote>
<div><p>If this attribute is attached to a thread object (always or
initial statement) then the vvp code generator will generate code
that causes the scheduler to push this thread at compile time. The
compiler may internally add this attribute to always statements if
it detects that it is combinational. This helps resolve time-0
races.</p>
</div></blockquote>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li><a href="index.html">IVL - The Core Compiler</a><ul>
<li>Previous: <a href="netlist.html" title="previous chapter">Netlist Format</a></li>
<li>Next: <a href="ivl_target.html" title="next chapter">Loadable Target API (ivl_target)</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/ivl/attributes.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

130
developer/guide/ivl/index.html Normal file
View File

@ -0,0 +1,130 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>IVL - The Core Compiler &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Netlist Format" href="netlist.html" />
<link rel="prev" title="Developer Guide" href="../index.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="ivl-the-core-compiler">
<h1>IVL - The Core Compiler<a class="headerlink" href="#ivl-the-core-compiler" title="Link to this heading"></a></h1>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="netlist.html">Netlist Format</a></li>
<li class="toctree-l1"><a class="reference internal" href="attributes.html">Icarus Verilog Attributes</a></li>
<li class="toctree-l1"><a class="reference internal" href="ivl_target.html">Loadable Target API (ivl_target)</a></li>
<li class="toctree-l1"><a class="reference internal" href="lpm.html">What Is LPM</a></li>
<li class="toctree-l1"><a class="reference internal" href="t-dll.html">Loadable Targets</a></li>
</ul>
</div>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li>Previous: <a href="../index.html" title="previous chapter">Developer Guide</a></li>
<li>Next: <a href="netlist.html" title="next chapter">Netlist Format</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/ivl/index.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

235
developer/guide/ivl/ivl_target.html Normal file
View File

@ -0,0 +1,235 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Loadable Target API (ivl_target) &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="What Is LPM" href="lpm.html" />
<link rel="prev" title="Icarus Verilog Attributes" href="attributes.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="loadable-target-api-ivl-target">
<h1>Loadable Target API (ivl_target)<a class="headerlink" href="#loadable-target-api-ivl-target" title="Link to this heading"></a></h1>
<p>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.</p>
<p>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.</p>
<section id="the-target-module-api">
<h2>The Target Module API<a class="headerlink" href="#the-target-module-api" title="Link to this heading"></a></h2>
<p>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.</p>
<p>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.</p>
</section>
<section id="compiling-target-modules">
<h2>Compiling Target Modules<a class="headerlink" href="#compiling-target-modules" title="Link to this heading"></a></h2>
<p>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.</p>
<p>This code:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># include &lt;ivl_target.h&gt;
int target_design(ivl_design_t des)
{
return 0;
}
</pre></div>
</div>
<p>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:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>% gcc -o empty.tgt -fpic -shared empty.c
</pre></div>
</div>
<p>This makes the “empty.tgt” file an a dynamically loaded shared object.</p>
</section>
<section id="creating-the-target-config-file">
<h2>Creating the Target Config File<a class="headerlink" href="#creating-the-target-config-file" title="Link to this heading"></a></h2>
<p>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.</p>
<p>The stub target, included in most distributions, demonstrates the config
files. The “stub.conf” file is:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>functor:cprop
functor:nodangle
-t:dll
flag:DLL=stub.tgt
</pre></div>
</div>
<p>and the “stub-s.conf” file is:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>functor:synth2
functor:synth
functor:syn-rules
functor:cprop
functor:nodangle
-t:dll
flag:DLL=stub.tgt
</pre></div>
</div>
<p>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.</p>
<p>In general, only the last line (The “flag:DLL=&lt;name&gt;.tgt” record) varies for
each target. For your target, replace the &lt;name&gt; 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.</p>
<p>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.</p>
</section>
<section id="installing-the-target-module">
<h2>Installing the Target Module<a class="headerlink" href="#installing-the-target-module" title="Link to this heading"></a></h2>
<p>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”.</p>
</section>
<section id="lpm-devices">
<h2>LPM Devices<a class="headerlink" href="#lpm-devices" title="Link to this heading"></a></h2>
<p>All LPM devices support a small set of common LPM functions, as
described in the ivl_target header file. The ivl_lpm_t object has a
type enumerated by ivl_lpm_type_t, and that type is accessible via the
ivl_lpm_type function.</p>
<p>The following are type specific aspects of LPM devices.</p>
<ul class="simple">
<li><p>IVL_LPM_UFUNC</p></li>
</ul>
<p>This LPM represents a user defined function. It is a way to connect
behavioral code into a structural network. The UFUNC device has a
vector output and a set of inputs. The ivl_lpm_define function returns
the definition as an ivl_scope_t object.</p>
<p>The output vector is accessible through the ivl_lpm_q, and the output
has the width defined by ivl_lpm_width. This similar to most every
other LPM device with outputs.</p>
<p>There are ivl_lpm_size() input ports, each with the width
ivl_lpm_data2_width(). The actual nexus is indexed by ivl_lpm_data2().</p>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li><a href="index.html">IVL - The Core Compiler</a><ul>
<li>Previous: <a href="attributes.html" title="previous chapter">Icarus Verilog Attributes</a></li>
<li>Next: <a href="lpm.html" title="next chapter">What Is LPM</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/ivl/ivl_target.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

144
developer/guide/ivl/lpm.html Normal file
View File

@ -0,0 +1,144 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>What Is LPM &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Loadable Targets" href="t-dll.html" />
<link rel="prev" title="Loadable Target API (ivl_target)" href="ivl_target.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="what-is-lpm">
<h1>What Is LPM<a class="headerlink" href="#what-is-lpm" title="Link to this heading"></a></h1>
<p>LPM (Library of Parameterized Modules) is EIS-IS standard 103-A. It is
a standard library of abstract devices that are designed to be close
enough to the target hardware to be easily translated, yet abstract
enough to support a variety of target technologies without excessive
constraints. Icarus Verilog uses LPM internally to represent idealized
hardware, especially when doing target neutral synthesis.</p>
<p>In general, the user does not even see the LPM that Icarus Verilog
generates, because the LPM devices are translated into technology
specific devices by the final code generator or target specific
optimizers.</p>
<section id="internal-uses-of-lpm">
<h2>Internal Uses Of LPM<a class="headerlink" href="#internal-uses-of-lpm" title="Link to this heading"></a></h2>
<p>Internally, Icarus Verilog uses LPM devices to represent the design in
abstract, especially when synthesizing such functions as addition,
flip-flops, etc. The <cite>synth</cite> functor generates LPM modules when
interpreting procedural constructs. The functor generates the LPM
objects needed to replace a behavioral description, and uses
attributes to tag the devices with LPM properties.</p>
<p>Code generators need to understand the supported LPM devices so that
they can translate the devices into technology specific devices.</p>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li><a href="index.html">IVL - The Core Compiler</a><ul>
<li>Previous: <a href="ivl_target.html" title="previous chapter">Loadable Target API (ivl_target)</a></li>
<li>Next: <a href="t-dll.html" title="next chapter">Loadable Targets</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/ivl/lpm.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

364
developer/guide/ivl/netlist.html Normal file
View File

@ -0,0 +1,364 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Netlist Format &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Icarus Verilog Attributes" href="attributes.html" />
<link rel="prev" title="IVL - The Core Compiler" href="index.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="netlist-format">
<h1>Netlist Format<a class="headerlink" href="#netlist-format" title="Link to this heading"></a></h1>
<p>The output from the parse and elaboration steps is a “netlist” rooted
in a Design object. Parsing translates the design described in the
initial source file into a temporary symbolic “pform”. Elaboration
then expands the design, resolving references and expanding
hierarchies, to produce a flattened netlist. This is the form that
optimizers and code generators use.</p>
<p>The design optimization processes all manipulate the netlist,
translating it to a (hopefully) better netlist after each step. The
complete netlist is then passed to the code generator, the emit
function, where the final code (in the target format) is produced.</p>
<section id="structural-items-netnode-and-netnet">
<h2>Structural Items: NetNode and NetNet<a class="headerlink" href="#structural-items-netnode-and-netnet" title="Link to this heading"></a></h2>
<p>Components and wires, memories and registers all at their base are
either NetNode objects or NetNet objects. Even these classes are
derived from the NetObj class.</p>
<p>All NetNode and NetNet objects have a name and some number of
pins. The name usually comes from the Verilog source that represents
that object, although objects that are artifacts of elaboration will
have a generated (and probably unreadable) name. The pins are the
ports into the device. NetNode objects have a pin for each pin of the
component it represents, and NetNet objects have a pin for each signal
in the vector.</p>
<p>Node and net pins can be connected together via the connect
function. Connections are transitive (A==B and B==c means A==C) so
connections accumulate on a link as items are connected to it. The
destructors for nets and nodes automatically arrange for pins to be
disconnected when the item is deleted, so that the netlist can be
changed during processing.</p>
</section>
<section id="structural-links">
<h2>Structural Links<a class="headerlink" href="#structural-links" title="Link to this heading"></a></h2>
<p>The NetNode and NetNet classes contain arrays of Link objects, one
object per pin. Each pin is a single bit. The Link objects link to all
the NetNode and NetNet objects’ links that are connected together in
the design, and to a Nexus object. This way, code that examines a node
of the design can discover what is connected to each pin.</p>
<p>The connected set of links also has common properties that are stored
or access from the Nexus object. All the Links that are connected
together are also connected to a single Nexus object. This object is
useful for accessing the properties and values that come from the
connected set of links. The Nexus object is also handy for iterating
over the connected set of Links.</p>
<p>See the Link class definition in netlist.h for a description of the link
methods, and the Nexus class for nexus global methods.</p>
<p>Currently, a link has 3 possible direction properties:</p>
<blockquote>
<div><dl class="simple">
<dt>PASSIVE – These pins are sampled by the object that holds the</dt><dd><p>pin based on some external event. These are used,
for example, by NetESignal objects that read a
point for a procedural expression.</p>
</dd>
<dt>INPUT – These pins potentially react to the setting of its</dt><dd><p>input.</p>
</dd>
<dt>OUTPUT – These pins potentially drive the node. (They may be</dt><dd><p>three-state.)</p>
</dd>
</dl>
</div></blockquote>
</section>
<section id="behavioral-items-netproctop-netproc-and-derived-classes">
<h2>Behavioral Items: NetProcTop, NetProc and derived classes<a class="headerlink" href="#behavioral-items-netproctop-netproc-and-derived-classes" title="Link to this heading"></a></h2>
<p>Behavioral items are not in general linked to the netlist. Instead,
they represent elaborated behavioral statements. The type of the object
implies what the behavior of the statement does. For example, a
NetCondit object represents an <cite>if</cite> statement, and carries a
condition expression and up to two alternative sub-statements.</p>
<p>At the root of a process is a NetProcTop object. This class carries a
type flag (initial or always) and a single NetProc object. The
contained statement may, depending on the derived class, refer to
other statements, compound statements, so on. But at the root of the
tree is the NetProcTop object. The Design class keeps a list of the
elaborated NetProcTop objects. That list represents the list of
processes in the design.</p>
</section>
<section id="interaction-of-behavioral-and-structural-netassign">
<h2>Interaction Of Behavioral And Structural: NetAssign_<a class="headerlink" href="#interaction-of-behavioral-and-structural-netassign" title="Link to this heading"></a></h2>
<p>The behavioral statements in a Verilog design effect the structural
aspects through assignments to registers. Registers are structural
items represented by the NetNet class, linked to the assignment
statement through pins. This implies that the l-value of an assignment
is structural. It also implies that the statement itself is
structural, and indeed it is derived from NetNode.</p>
<p>The NetAssign_ class is also derived from the NetProc class because
what it does is brought on by executing the process. By multiple
inheritance we have therefore that the assignment is both a NetNode
and a NetProc. The NetAssign_ node has pins that represent the l-value
of the statement, and carries behavioral expressions that represent
the r-value of the assignment.</p>
</section>
<section id="memories">
<h2>Memories<a class="headerlink" href="#memories" title="Link to this heading"></a></h2>
<p>The netlist form includes the NetMemory type to hold the content of a
memory. Instances of this type represent the declaration of a memory,
and occur once for each memory. References to the memory are managed
by the NetEMemory and NetAssignMem_ classes.</p>
<p>An instance of the NetEMemory class is created whenever a procedural
expression references a memory element. The operand is the index to
use to address (and read) the memory.</p>
<p>An instance of the NetAssignMem_ class is created when there is a
procedural assignment to the memory. The NetAssignMem_ object
represents the l-value reference (a write) to the memory. As with the
NetEMemory class, this is a procedural reference only.</p>
<p>When a memory reference appears in structural context (i.e. continuous
assignments) elaboration creates a NetRamDq. This is a LPM_RAM_DQ
device. Elaboration leaves the write control and data input pins
unconnected for now, because memories cannot appear is l-values of
continuous assignments. However, the synthesis functor may connect
signals to the write control lines to get a fully operational RAM.</p>
<p>By the time elaboration completes, there may be many NetAssignMem_,
NetEMemory and NetRamDq objects referencing the same NetMemory
object. Each represents a port into the memory. It is up to the
synthesis steps (and the target code) to figure out what to do with
these ports.</p>
</section>
<section id="expressions">
<h2>Expressions<a class="headerlink" href="#expressions" title="Link to this heading"></a></h2>
<p>Expressions are represented as a tree of NetExpr nodes. The NetExpr
base class contains the core methods that represent an expression
node, including virtual methods to help with dealing with nested
complexities of expressions.</p>
<p>Expressions (as expressed in the source and p-form) may also be
elaborated structurally, where it makes sense. For example, assignment
l-value expressions are represented as connections to pins. Also,
continuous assignment module items are elaborated as gates instead of
as a procedural expression. Event expressions are also elaborated
structurally as events are like devices that trigger behavioral
statements.</p>
<p>However, typical expressions the behavioral description are
represented as a tree of NetExpr nodes. The derived class of the node
encodes what kind of operator the node represents.</p>
</section>
<section id="expression-bit-width">
<h2>Expression Bit Width<a class="headerlink" href="#expression-bit-width" title="Link to this heading"></a></h2>
<p>The expression (represented by the NetExpr class) has a bit width that
it either explicitly specified, or implied by context or contents.
When each node of the expression is first constructed during
elaboration, it is given, by type and parameters, an idea what its
width should be. It certain cases, this is definitive, for example
with signals. In others, it is ambiguous, as with unsized constants.</p>
<p>As the expression is built up by elaboration, operators that combine
expressions impose bit widths of the environment or expose the bit
widths of the sub expressions. For example, the bitwise AND (&amp;)
operator has a bit size implied by its operands, whereas the
comparison (==) operator has a bit size of 1. The building up of the
elaborated expression checks and adjusts the bit widths as the
expression is built up, until finally the context of the expression
takes the final bit width and makes any final adjustments.</p>
<p>The NetExpr::expr_width() method returns the calculated (or guessed)
expression width. This method will return 0 until the width is set by
calculation or context. If this method returns false, then it is up to
the context that wants the width to set one. The elaboration phase
will call the NetExpr::set_width method on an expression as soon as it
gets to a point where it believes that it knows what the width should
be.</p>
<p>The NetExpr::set_width(unsigned) virtual method is used by the context
of an expression node to note to the expression that the width is
determined and please adapt. If the expression cannot reasonably
adapt, it will return false. Otherwise, it will adjust bit widths and
return true.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>I do not yet properly deal with cases where elaboration knows for
certain that the bit width does not matter. In this case, I
really should tell the expression node about it so that it can
pick a practical (and optimal) width.
</pre></div>
</div>
</section>
<section id="interaction-of-expressions-and-structure-netesignal">
<h2>Interaction Of Expressions And Structure: NetESignal<a class="headerlink" href="#interaction-of-expressions-and-structure-netesignal" title="Link to this heading"></a></h2>
<p>The NetAssign_ class described above is the means for processes to
manipulate the net, but values are read from the net by NetESignal
objects. These objects are class NetExpr because they can appear in
expressions (and have width). They are not NetNode object, but hold
pointers to a NetNet object, which is used to retrieve values with the
expression is evaluated.</p>
</section>
<section id="hierarchy-in-netlists">
<h2>Hierarchy In Netlists<a class="headerlink" href="#hierarchy-in-netlists" title="Link to this heading"></a></h2>
<p>The obvious hierarchical structure of Verilog is the module. The
Verilog program may contain any number of instantiations of modules in
order to form an hierarchical design. However, the elaboration of the
design into a netlist erases module boundaries. Modules are expanded
each place they are used, with the hierarchical instance name used to
name the components of the module instance. However, the fact that a
wire or register is a module port is lost.</p>
<p>The advantage of this behavior is first the simplification of the
netlist structure itself. Backends that process netlists only need to
cope with a list of nets, a list of nodes and a list of
processes. This eases the task of the backend code generators.</p>
<p>Another advantage of this flattening of the netlist is that optimizers
can operate globally, with optimizations freely crossing module
boundaries. This makes coding of netlist transform functions such as
constant propagation more effective and easier to write.</p>
</section>
<section id="scope-representation-in-netlists">
<h2>Scope Representation In Netlists<a class="headerlink" href="#scope-representation-in-netlists" title="Link to this heading"></a></h2>
<p>In spite of the literal flattening of the design, scope information is
preserved in the netlist, with the NetScope class. The Design class
keeps a single pointer to the root scope of the design. This is the
scope of the root module. Scopes that are then created within that
(or any nested) module are placed as children of the root scope, and
those children can have further children, and so on.</p>
<p>Each scope in the tree carries its own name, and its relationship to
its parent and children. This makes it possible to walk the tree of
scopes. In practice, the walking of the scopes is handled by recursive
methods.</p>
<p>Each scope also carries the parameters that are applicable to the
scope itself. The parameter expression (possibly evaluated) can be
located by name, given the scope object itself. The scan of the pform
to generate scopes also places the parameters that are declared in the
scope. Overrides are managed during the scan, and once the scan is
complete, defparam overrides are applied.</p>
</section>
<section id="tasks-in-netlists">
<h2>Tasks In Netlists<a class="headerlink" href="#tasks-in-netlists" title="Link to this heading"></a></h2>
<p>The flattening of the design does not include tasks and named
begin-end blocks. Tasks are behavioral hierarchy (whereas modules are
structural) so do not easily succumb to the flattening process. In
particular, it is logically impossible to flatten tasks that
recurse. (The elaboration process does reserve the right to flatten
some task calls. C++ programmers recognize this as inlining a task.)</p>
</section>
<section id="time-scale-in-netlists">
<h2>Time Scale In Netlists<a class="headerlink" href="#time-scale-in-netlists" title="Link to this heading"></a></h2>
<p>The Design class and the NetScope classes carry time scale and
resolution information of the elaborated design. There is a global
resolution, and there are scope specific units and resolutions. Units
and resolutions are specified as signed integers, and interpreted as
the power of 10 of the value. For example, a resolution “-9” means
that “1” is 1ns (1e-9). The notation supports units from -128 to +127.
It is up to the back-ends to interpret “-4” as “100us”.</p>
<p>Delays are expressed in the netlist by integers. The units of these
delays are always given in the units of the design precision. This
allows everything to work with integers, and generally places the
burden of scaling delays into elaboration. This is, after all, a
common task. The Design::get_precision() method gets the global design
precision.</p>
<p>Each NetScope also carries its local time_units and time_precision
values. These are filled in during scope elaboration and are used in
subsequent elaboration phases to arrange for scaling of delays. This
information can also be used by the code generator to scale times back
to the units of the scope, if that is desired.</p>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li><a href="index.html">IVL - The Core Compiler</a><ul>
<li>Previous: <a href="index.html" title="previous chapter">IVL - The Core Compiler</a></li>
<li>Next: <a href="attributes.html" title="next chapter">Icarus Verilog Attributes</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/ivl/netlist.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

173
developer/guide/ivl/t-dll.html Normal file
View File

@ -0,0 +1,173 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Loadable Targets &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="VVP - Verilog Virtual Processor" href="../vvp/index.html" />
<link rel="prev" title="What Is LPM" href="lpm.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="loadable-targets">
<h1>Loadable Targets<a class="headerlink" href="#loadable-targets" title="Link to this heading"></a></h1>
<p>Icarus Verilog supports dynamically loading code generator modules to
perform the back-end processing of the completed design. The user
specifies on the command line the module to load. The compiler loads
the module (once the design is compiled and elaborated) and calls it
to finally handle the design.</p>
<p>Loadable target modules implement a set of functions that the core
compiler calls to pass the design to it, and the module in turn uses a
collection of functions in the core (the API) to access details of the
design.</p>
<section id="loading-target-modules">
<h2>Loading Target Modules<a class="headerlink" href="#loading-target-modules" title="Link to this heading"></a></h2>
<p>The target module loader is invoked with the ivl flag “-tdll”. That
is, the DLL loader is a linked in target type. The name of the target
module to load is then specified with the DLL flag, i.e. “-fDLL=&lt;path&gt;”.</p>
</section>
<section id="compiling-target-modules">
<h2>Compiling Target Modules<a class="headerlink" href="#compiling-target-modules" title="Link to this heading"></a></h2>
<p>&lt;write me&gt;</p>
</section>
<section id="loadable-target-module-api">
<h2>Loadable Target Module Api<a class="headerlink" href="#loadable-target-module-api" title="Link to this heading"></a></h2>
<p>The target module API is defined in the ivl_target.h header file. This
declares all the type and functions that a loadable module needs to
access the design.</p>
</section>
<section id="about-specific-expression-types">
<h2>About Specific Expression Types<a class="headerlink" href="#about-specific-expression-types" title="Link to this heading"></a></h2>
<p>In this section find notes about the various kinds of expression
nodes. The notes here are in addition to the more general
documentation in the ivl_target.h header file.</p>
<ul>
<li><p>IVL_EX_CONCAT</p>
<p>The concatenation operator forms an expression node that holds the
repeat count and all the parameter expressions. The repeat count is
an integer that is calculated by the core compiler so it fully
evaluated, and <em>not</em> an expression.</p>
<p>The parameter expressions are retrieved by the ivl_expr_parm method,
with the index increasing as parameters go from left to right, from
most significant to least significant. (Note that this is different
from the order of bits within an expression node.)</p>
</li>
<li><p>IVL_EX_NUMBER</p>
<p>This is a constant number. The width is fully known, and the bit
values are all represented by the ASCII characters 0, 1, x or z. The
ivl_expr_bits method returns a pointer to the least significant bit,
and the remaining bits are ordered from least significant to most
significant. For example, 5’b1zzx0 is the 5 character string “0xzz1”.</p>
</li>
</ul>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li><a href="index.html">IVL - The Core Compiler</a><ul>
<li>Previous: <a href="lpm.html" title="previous chapter">What Is LPM</a></li>
<li>Next: <a href="../vvp/index.html" title="next chapter">VVP - Verilog Virtual Processor</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/ivl/t-dll.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

576
developer/guide/misc/ieee1364-notes.html Normal file
View File

@ -0,0 +1,576 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>IEEE1364 Notes &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Swift Model Support (Preliminary)" href="swift.html" />
<link rel="prev" title="Miscellaneous" href="index.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="ieee1364-notes">
<h1>IEEE1364 Notes<a class="headerlink" href="#ieee1364-notes" title="Link to this heading"></a></h1>
<p>The IEEE1364 standard is the bible that defines the correctness of the
Icarus Verilog implementation and behavior of the compiled
program. The IEEE1364.1 is also referenced for matters of
synthesis. So the ultimate definition of right and wrong comes from
those documents.</p>
<p>That does not mean that a Verilog implementation is fully
constrained. The standard document allows for implementation specific
behavior that, when properly accounted for, does not effect the
intended semantics of the specified language. It is therefore possible
and common to write programs that produce different results when run
by different Verilog implementations.</p>
<section id="standardization-issues">
<h2>Standardization Issues<a class="headerlink" href="#standardization-issues" title="Link to this heading"></a></h2>
<p>These are some issues where the IEEE1364 left unclear, unspecified or
simply wrong. I’ll try to be precise as I can, and reference the
standard as needed. I’ve made implementation decisions for Icarus
Verilog, and I will make clear what those decisions are and how they
affect the language.</p>
<ul class="simple">
<li><p>OBJECTS CAN BE DECLARED ANYWHERE IN THE MODULE</p></li>
</ul>
<p>Consider this module:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>module sample1;
initial foo = 1;
reg foo;
wire tmp = bar;
initial #1 $display(&quot;foo = %b, bar = %b&quot;, foo, tmp);
endmodule
</pre></div>
</div>
<p>Notice that the <cite>reg foo;</cite> declaration is placed after the first
initial statement. It turns out that this is a perfectly legal module
according to the -1995 and -2000 versions of the standard. The
statement <cite>reg foo;</cite> is a module_item_declaration which is in turn a
module_item. The BNF in the appendix of IEEE1364-1995 treats all
module_item statements equally, so no order is imposed.</p>
<p>Furthermore, there is no text (that I can find) elsewhere in the
standard that imposes any ordering restriction. The sorts of
restrictions I would look for are “module_item_declarations must
appear before all other module_items” or “variables must be declared
textually before they are referenced.” Such statements simply do not
exist. (Personally, I think it is fine that they don’t.)</p>
<p>The closest is the rules for implicit declarations of variables that
are otherwise undeclared. In the above example, <cite>bar</cite> is implicitly
declared and is therefore a wire. However, although <cite>initial foo = 1;</cite>
is written before foo is declared, foo <em>is</em> declared within the
module, and declared legally by the BNF of the standard.</p>
<p>Here is another example:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>module sample2;
initial x.foo = 1;
test x;
initial #1 $display(&quot;foo = %b&quot;, x.foo);
endmodule
module test;
reg foo;
endmodule;
</pre></div>
</div>
<p>From this example one can clearly see that foo is once again declared
after its use in behavioral code. One also sees a forward reference of
an entire module. Once again, the standard places no restriction on
the order of module declarations in a source file, so this program is,
according to the standard, perfectly well formed.</p>
<p>Icarus Verilog interprets both of these examples according to “The
Standard As I Understand It.” However, commercial tools in general
break down with these programs. In particular, the first example
may generate different errors depending on the tool. The most common
error is to claim that <cite>foo</cite> is declared twice, once (implicitly) as
a wire and once as a reg.</p>
<p>So the question now becomes, “Is the standard broken, or are the tools
limited?” Coverage of the standard seems to vary widely from tool to
tool so it is not clear that the standard really is at fault. It is
clear, however, that somebody goofed somewhere.</p>
<p>My personal opinion is that there is no logical need to require that
all module_item_declarations precede any other module items. I
personally would oppose such a restriction. It may make sense to
require that declarations of variables within a module be preceded by
their use, although even that is not necessary for the implementation
of efficient compilers.</p>
<p>However, the existence hierarchical naming syntax as demonstrated in
sample2 can have implications that affect any declaration order
rules. When reaching into a module with a hierarchical name, the
module being referenced is already completely declared (or not
declared at all, as in sample2) so module_item order is completely
irrelevant. But a “declare before use” rule would infect module
ordering, by requiring that modules that are used be first defined.</p>
<ul class="simple">
<li><p>TASK AND FUNCTION PARAMETERS CANNOT HAVE EXPLICIT TYPES</p></li>
</ul>
<p>Consider a function negate that wants to take a signed integer value
and return its negative:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>function integer negate;
input [15:0] val;
negate = -val;
endfunction
</pre></div>
</div>
<p>This is not quite right, because the input is implicitly a reg type,
which is unsigned. The result, then, will always be a negative value,
even if a negative val is passed in.</p>
<p>It is possible to fix up this specific example to work properly with
the bit pattern of a 16bit number, but that is not the point. What’s
needed is clarification on whether an input can be declared in the
port declaration as well as in the contained block declaration.</p>
<p>As I understand the situation, this should be allowed:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>function integer negate;
input [15:0] val;
reg signed [15:0] val;
negate = -val;
endfunction
</pre></div>
</div>
<p>In the -1995 standard, the variable is already implicitly a reg if
declared within a function or task. However, in the -2000 standard
there is now (as in this example) a reason why one might want to
actually declare the type explicitly.</p>
<p>I think that a port <em>cannot</em> be declared as an integer or time type
(though the result can) because the range of the port declaration must
match the range of the integer/time declaration, but the range of
integers is unspecified. This, by the way, also applies to module
ports.</p>
<p>With the above in mind, I have decided to <em>allow</em> function and task
ports to be declared with types, as long as the types are variable
types, such as reg or integer. Without this, there would be no
portable way to pass integers into functions/tasks. The standard does
not say it is allowed, but it doesn’t <em>disallow</em> it, and other
commercial tools seem to work similarly.</p>
<ul class="simple">
<li><p>ROUNDING OF TIME</p></li>
</ul>
<p>When the `timescale directive is present, the compiler is supposed to
round fractional times (after scaling) to the nearest integer. The
confusing bit here is that it is apparently conventional that if the
`timescale directive is <em>not</em> present, times are rounded towards zero
always.</p>
<ul class="simple">
<li><p>VALUE OF X IN PRIMITIVE OUTPUTS</p></li>
</ul>
<p>The IEEE1364-1995 standard clearly states in Table 8-1 that the x
symbols is allowed in input columns, but is not allowed in
outputs. Furthermore, none of the examples have an x in the output of
a primitive. Table 8-1 in the IEEE1364-2000 also says the same thing.</p>
<p>However, the BNF clearly states that 0, 1, x and X are valid
output_symbol characters. The standard is self contradictory. So I
take it that x is allowed, as that is what Verilog-XL does.</p>
<ul class="simple">
<li><p>REPEAT LOOPS vs. REPEAT EVENT CONTROL</p></li>
</ul>
<p>There seems to be ambiguity in how code like this should be parsed:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>repeat (5) @(posedge clk) &lt;statement&gt;;
</pre></div>
</div>
<p>There are two valid interpretations of this code, from the
IEEE1364-1995 standard. One looks like this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>procedural_timing_control_statement ::=
delay_or_event_control statement_or_null
delay_or_event_control ::=
event_control
| repeat ( expression ) event_control
</pre></div>
</div>
<p>If this interpretation is used, then the statement &lt;statement&gt; should
be executed after the 5th posedge of clk. However, there is also this
interpretation:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>loop_statement ::=
repeat ( expression ) statement
</pre></div>
</div>
<p>If <em>this</em> interpretation is used, then &lt;statement&gt; should be executed
5 times on the posedge of clk. The way the -1995 standard is written,
these are both equally valid interpretations of the example, yet they
produce very different results. The standard offers no guidance on how
to resolve this conflict, and the IEEE1364-2000 DRAFT does not improve
the situation.</p>
<p>Practice suggests that a repeat followed by an event control should be
interpreted as a loop head, and this is what Icarus Verilog does, as
well as all the other major Verilog tools, but the standard does not
say this.</p>
<ul class="simple">
<li><p>UNSIZED NUMERIC CONSTANTS ARE NOT LIMITED TO 32 BITS</p></li>
</ul>
<p>The Verilog standard allows Verilog implementations to limit the size
of unsized constants to a bit width of at least 32. That means that a
constant 17179869183 (36’h3_ffff_ffff) may overflow some compilers. In
fact, it is common to limit these values to 32bits. However, a
compiler may just as easily choose another width limit, for example
64bits. That value is equally good.</p>
<p>However, it is not <em>required</em> that an implementation truncate at 32
bits, and in fact Icarus Verilog does not truncate at all. It will
make the unsized constant as big as it needs to be to hold the value
accurately. This is especially useful in situations like this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>reg [width-1:0] foo = 17179869183;
</pre></div>
</div>
<p>The programmer wants the constant to take on the width of the reg,
which in this example is parameterized. Since constant sizes cannot be
parameterized, the programmer ideally gives an unsized constant, which
the compiler then expands/contracts to match the l-value.</p>
<p>Also, by choosing to not ever truncate, Icarus Verilog can handle code
written for a 64bit compiler as easily as for a 32bit compiler. In
particular, any constants that the user does not expect to be
arbitrarily truncated by his compiler will also not be truncated by
Icarus Verilog, no matter what that other compiler chooses as a
truncation point.</p>
<ul class="simple">
<li><p>UNSIZED EXPRESSIONS AS PARAMETERS TO CONCATENATION {}</p></li>
</ul>
<p>The Verilog standard clearly states in 4.1.14:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&quot;Unsized constant numbers shall not be allowed in
concatenations. This is because the size of each
operand in the concatenation is needed to calculate
the complete size of the concatenation.&quot;
</pre></div>
</div>
<p>So for example the expression {1’b0, 16} is clearly illegal. It
also stands to reason that {1’b0, 15+1} is illegal, for exactly the
same justification. What is the size of the expression (15+1)?
Furthermore, it is reasonable to expect that (16) and (15+1) are
exactly the same so far as the compiler is concerned.</p>
<p>Unfortunately, Cadence seems to feel otherwise. In particular, it has
been reported that although {1’b0, 16} causes an error, {1’b0, 15+1}
is accepted. Further testing shows that any expression other than a
simple unsized constant is accepted there, even if all the operands of
all the operators that make up the expression are unsized integers.</p>
<p>This is a semantic problem. Icarus Verilog doesn’t limit the size of
integer constants. This is valid as stated in 2.5.1 Note 3:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&quot;The number of bits that make up an unsized number
(which is a simple decimal number or a number without
the size specification) shall be *at*least* 32.&quot;
[emphasis added]
</pre></div>
</div>
<p>Icarus Verilog will hold any integer constant, so the size will be as
large as it needs to be, whether that is 64bits, 128bits, or
more. With this in mind, what is the value of these expressions?</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>{&#39;h1_00_00_00_00}
{&#39;h1 &lt;&lt; 32}
{&#39;h0_00_00_00_01 &lt;&lt; 32}
{&#39;h5_00_00_00_00 + 1}
</pre></div>
</div>
<p>These examples show that the standard is justified in requiring that
the operands of concatenation have size. The dispute is what it takes
to cause an expression to have a size, and what that size is.
Verilog-XL claims that (16) does not have a size, but (15+1) does. The
size of the expression (15+1) is the size of the adder that is
created, but how wide is the adder when adding unsized constants?</p>
<p>One might note that the quote from section 4.1.14 says “Unsized
<em>constant*numbers</em> shall not be allowed.” It does not say “Unsized
expressions…”, so arguably accepting (15+1) or even (16+0) as an
operand to a concatenation is not a violation of the letter of the
law. However, the very next sentence of the quote expresses the
intent, and accepting (15+1) as having a more defined size than (16)
seems to be a violation of that intent.</p>
<p>Whatever a compiler decides the size is, the user has no way to
predict it, and the compiler should not have the right to treat (15+1)
any differently than (16). Therefore, Icarus Verilog takes the
position that such expressions are <em>unsized</em> and are not allowed as
operands to concatenations. Icarus Verilog will in general assume that
operations on unsized numbers produce unsized results. There are
exceptions when the operator itself does define a size, such as the
comparison operators or the reduction operators. Icarus Verilog will
generate appropriate error messages.</p>
<ul class="simple">
<li><p>MODULE INSTANCE WITH WRONG SIZE PORT LIST</p></li>
</ul>
<p>A module declaration like this declares a module that takes three ports:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>module three (a, b, c);
input a, b, c;
reg x;
endmodule
</pre></div>
</div>
<p>This is fine and obvious. It is also clear from the standard that
these are legal instantiations of this module:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>three u1 (x,y,z);
three u2 ( ,y, );
three u3 ( , , );
three u4 (.b(y));
</pre></div>
</div>
<p>In some of the above examples, there are unconnected ports. In the
case of u4, the pass by name connects only port b, and leaves a and c
unconnected. u2 and u4 are the same thing, in fact, but using
positional or by-name syntax. The next example is a little less
obvious:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>three u4 ();
</pre></div>
</div>
<p>The trick here is that strictly speaking, the parser cannot tell
whether this is a list of no pass by name ports (that is, all
unconnected) or an empty positional list. If this were an empty
positional list, then the wrong number of ports is given, but if it is
an empty by-name list, it is an obviously valid instantiation. So it
is fine to accept this case as valid.</p>
<p>These are more doubtful:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>three u5(x,y);
three u6(,);
</pre></div>
</div>
<p>These are definitely positional port lists, and they are definitely
the wrong length. In this case, the standard is not explicit about
what to do about positional port lists in module instantiations,
except that the first is connected to the first, second to second,
etc. It does not say that the list must be the right length, but every
example of unconnected ports used by-name syntax, and every example of
ordered list has the right size list.</p>
<p>Icarus Verilog takes the (very weak) hint that ordered lists should be
the right length, and will therefore flag instances u5 and u6 as
errors. The IEEE1364 standard should be more specific one way or the
other.</p>
<ul class="simple">
<li><p>UNKNOWN VALUES IN L-VALUE BIT SELECTS</p></li>
</ul>
<p>Consider this example:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>reg [7:0] vec;
wire [4:0] idx = &lt;expr&gt;;
[...]
vec[idx] = 1;
</pre></div>
</div>
<p>So long as the value of idx is a valid bit select address, the
behavior of this assignment is obvious. However, there is no explicit
word in the standard as to what happens if the value is out of
range. The standard clearly states the value of an expression when the
bit-select or part select is out of range (the value is x) but does
not address the behavior when the expression is an l-value.</p>
<p>Icarus Verilog will take the position that bit select expressions in
the l-value will select oblivion if it is out of range. That is, if
idx has a value that is not a valid bit select of vec, then the
assignment will have no effect.</p>
<ul class="simple">
<li><p>SCHEDULING VALUES IN LOGIC</p></li>
</ul>
<p>The interaction between blocking assignments in procedural code and
logic gates in gate-level code and expressions is poorly defined in
Verilog. Consider this example:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>reg a;
reg b;
wire q = a &amp; b;
initial begin
a = 1;
b = 0;
#1 b = 1;
if (q !== 0) begin
$display(&quot;FAILED -- q changed too soon? %b&quot;, q);
$finish;
end
end
</pre></div>
</div>
<p>This is a confusing situation. It is clear from the Verilog standard
that an assignment to a variable using a blocking assign causes the
l-value to receive the value before the assignment completes. This
means that a subsequent read of the assigned variable <em>must</em> read back
what was blocking-assigned.</p>
<p>However, in the example above, the “wire q = a &amp; b” expresses some
gate logic between a/b and q. The standard does not say whether a read
out of logic should read the value computed from previous assigns to
the input from the same thread. Specifically, when “a” and “b” are
assigned by blocking assignments, will a read of “q” get the computed
value or the existing value?</p>
<p>In fact, existing commercial tools do it both ways. Some tools print
the FAILED message in the above example, and some do not. Icarus
Verilog does not print the FAILED message in the above example,
because the gate value change is <em>scheduled</em> when inputs are assigned,
but not propagated until the thread gives up the processor.</p>
<p>Icarus Verilog chooses this behavior in order to filter out zero-width
pulses as early as possible. The implication of this is that a read of
the output of combinational logic will most likely <em>not</em> reflect the
changes in inputs until the thread that changed the inputs yields
execution.</p>
<ul class="simple">
<li><p>BIT AND PART SELECTS OF PARAMETERS</p></li>
</ul>
<p>Bit and part selects are supposed to only be supported on vector nets
and variables (wires, regs, etc.) However, it is common for Verilog
compilers to also support bit and part select on parameters. Icarus
Verilog also chooses to support bit and part selects on parameter
names, but we need to define what that means.</p>
<p>A bit or a part select on a parameter expression returns an unsigned
value with a defined size. The parameter value is considered be a
constant vector of bits foo[X:0]. That is, zero based. The bit and
part selects operate from that assumption.</p>
<p>Verilog 2001 adds syntax to allow the user to explicitly declare the
parameter range (i.e. parameter [5:0] foo = 9;) so Icarus Verilog will
(or should) use the explicitly declared vector dimensions to interpret
bit and part selects.</p>
<ul class="simple">
<li><p>EDGES OF VECTORS</p></li>
</ul>
<p>Consider this example:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>reg [ 5:0] clock;
always @(posedge clock) [do stuff]
</pre></div>
</div>
<p>The IEEE1364 standard clearly states that the &#64;(posedge clock) looks
only at the bit clock[0] (the least significant bit) to search for
edges. It has been pointed out by some that Verilog XL instead
implements it as <cite>&#64;(posedge |clock)</cite>: it looks for a rise in the
reduction or of the vector. Cadence Design Systems technical support
has been rumored to claim that the IEEE1364 specification is wrong,
but NC-Verilog behaves according to the specification, and thus
different from XL.</p>
<p>Icarus Verilog, therefore, takes the position that the specification
is clear and correct, and it behaves as does NC-Verilog in this
matter.</p>
<ul class="simple">
<li><p>REAL VARIABLES IN $dumpoff DEAD-ZONES</p></li>
</ul>
<p>The IEEE1364 standard clearly states that in VCD files, the $dumpoff
section checkpoints all the dumped variables as X values. For reg and
wire bits/vectors, this obviously means ‘bx values. Icarus Verilog
does this, for example:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$dumpoff
x!
x&quot;
$end
</pre></div>
</div>
<p>Real variables can also be included in VCD dumps, but it is not at
all obvious what is supposed to be dumped into the $dumpoff-$end
section of the VCD file. Verilog-XL dumps “r0 !” to set the real
variables to the dead-zone value of 0.0, whereas other tools, such as
ModelTech, ignore real variables in this section.</p>
<p>For example (from XL):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$dumpoff
r0 !
r0 &quot;
$end
</pre></div>
</div>
<p>Icarus Verilog dumps NaN values for real variables in the
$dumpoff-$end section of the VCD file. The NaN value is the IEEE754
equivalent of an unknown value, and so better reflects the unknown
(during the dead zone) status of the variable, like this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$dumpoff
rNaN !
rNaN &quot;
$end
</pre></div>
</div>
<p>It turns out that NaN is conventionally accepted by scanf functions,
and viewers that support real variables support NaN values. So while
the IEEE1364 doesn’t require this behavior, and given the variety that
already seems to exist amongst VCD viewers in the wild, this behavior
seems to be acceptable according to the standard, is a better mirror
of 4-value behavior in the dead zone, and appears more user friendly
when viewed by reasonable viewers.</p>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li><a href="index.html">Miscellaneous</a><ul>
<li>Previous: <a href="index.html" title="previous chapter">Miscellaneous</a></li>
<li>Next: <a href="swift.html" title="next chapter">Swift Model Support (Preliminary)</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/misc/ieee1364-notes.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

128
developer/guide/misc/index.html Normal file
View File

@ -0,0 +1,128 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Miscellaneous &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="IEEE1364 Notes" href="ieee1364-notes.html" />
<link rel="prev" title="Cadence PLI1 Modules" href="../cadpli/cadpli.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="miscellaneous">
<h1>Miscellaneous<a class="headerlink" href="#miscellaneous" title="Link to this heading"></a></h1>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="ieee1364-notes.html">IEEE1364 Notes</a></li>
<li class="toctree-l1"><a class="reference internal" href="swift.html">Swift Model Support (Preliminary)</a></li>
<li class="toctree-l1"><a class="reference internal" href="xilinx-hint.html">Xilinx Hint</a></li>
</ul>
</div>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li>Previous: <a href="../cadpli/cadpli.html" title="previous chapter">Cadence PLI1 Modules</a></li>
<li>Next: <a href="ieee1364-notes.html" title="next chapter">IEEE1364 Notes</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/misc/index.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

189
developer/guide/misc/swift.html Normal file
View File

@ -0,0 +1,189 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Swift Model Support (Preliminary) &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Xilinx Hint" href="xilinx-hint.html" />
<link rel="prev" title="IEEE1364 Notes" href="ieee1364-notes.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="swift-model-support-preliminary">
<h1>Swift Model Support (Preliminary)<a class="headerlink" href="#swift-model-support-preliminary" title="Link to this heading"></a></h1>
<blockquote>
<div><blockquote>
<div><p>Copyright 2003-2024 Stephen Williams</p>
</div></blockquote>
<p>NOTE: SWIFT support does not work yet, these are provisional
instructions, intended to show what’s supposed to happen when I get
it working.</p>
</div></blockquote>
<p>Icarus Verilog support for SWIFT models is based on the LMTV interface
module from Synopsys. This module is normally distributed along with
the SWIFT models proper. This module can be linked with Icarus Verilog
via the cadpli compatibility object. (See cadpli.txt.)</p>
<ul class="simple">
<li><p>Preliminaries</p></li>
</ul>
<p>First, you need the LMC_HOME environment variable set to point to the
installed directory for your SWIFT software. This setup is documented
in your SWIFT model documentation.</p>
<ul class="simple">
<li><p>Compilation</p></li>
</ul>
<p>When compiling your Verilog design to include a SWIFT model, you need
to include wrappers for the model you intend to use. You may choose to
use ncverilog or verilogxl compatible wrappers, they work the
same. Locate your smartmodel directory, and include it in your command
file like so:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>+libdir+.../smartmodel/sol/wrappers/verilogxl
</pre></div>
</div>
<p>The wrappers directory includes Verilog modules that wrap your SWIFT
module, and with this +libdir+ statement in your command file, the
Icarus Verilog compiler will be able to locate these wrappers. The
wrappers in turn invoke the $lm_model system tasks that are the LMTV
support for your model.</p>
<blockquote>
<div><p>NOTE: This example uses the solaris directory of VerilogXL support
files as a source of wrappers. The files of interest, however, are
written in Verilog and are identical for all supported platforms, so
long as you choose the verilogxl or ncverilog files.</p>
</div></blockquote>
<ul class="simple">
<li><p>Execution</p></li>
</ul>
<p>After your simulation is compiled, run the simulation with the vvp
command, like this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>% vvp -mcadpli a.out -cadpli=$LMC_HOME/lib/x86_linux.lib/swiftpli.so:swift_boot
</pre></div>
</div>
<p>What this command line means is:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>-mcadpli
Include the cadpli compatibility module
a.out
This is your compiled vvp file
-cadpli=$LMC_HOME/lib/x86_linux.lib/swiftpli.so:swift_boot
This tells the cadpli module to load the swiftpli.so
shared object, and boot it. This is code that comes with
your SWIFT modules, and provides the generic SWIFT
capabilities (lm_* system tasks) needed by the module
itself.
</pre></div>
</div>
<p>Once you start the vvp command, the SWIFT infrastructure will be
initialized as part of the simulation setup, and all should work
normally from here.</p>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li><a href="index.html">Miscellaneous</a><ul>
<li>Previous: <a href="ieee1364-notes.html" title="previous chapter">IEEE1364 Notes</a></li>
<li>Next: <a href="xilinx-hint.html" title="next chapter">Xilinx Hint</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/misc/swift.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

226
developer/guide/misc/xilinx-hint.html Normal file
View File

@ -0,0 +1,226 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Xilinx Hint &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Glossary" href="../../glossary.html" />
<link rel="prev" title="Swift Model Support (Preliminary)" href="swift.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="xilinx-hint">
<h1>Xilinx Hint<a class="headerlink" href="#xilinx-hint" title="Link to this heading"></a></h1>
<p>For those of you who wish to use Icarus Verilog, in combination with
the Xilinx back end (Foundation or Alliance), it can be done. I have
run some admittedly simple (2300 equivalent gates) designs through this
setup, targeting a Spartan XCS10.</p>
<section id="verilog">
<h2>Verilog:<a class="headerlink" href="#verilog" title="Link to this heading"></a></h2>
<p>Older versions of Icarus Verilog (like 19990814) couldn’t synthesize
logic buried in procedural (flip-flop) assignment. Newer versions
(like 20000120) don’t have this limitation.</p>
<p>Procedural assignments have to be given one at a time, to be
“found” by xnfsyn. Say</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>always @ (posedge Clk) Y = newY;
always @ (posedge Clk) Z = newZ;
</pre></div>
</div>
<p>rather than</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>always @ (posedge Clk) begin
Y = newY;
Z = newZ;
end
</pre></div>
</div>
<p>Steve’s xnf.txt covers most buffer and pin constructs, but I had reason
to use a global clock net not connected to an input pin. The standard
Verilog for a buffer, combined with a declaration to turn that into a
BUFG, is:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>buf BUFG( your_output_here, your_input_here );
$attribute(BUFG,&quot;XNF-LCA&quot;,&quot;BUFG:O,I&quot;)
</pre></div>
</div>
<p>I use post-processing on my .xnf files to add “FAST” attributes to
output pins.</p>
</section>
<section id="running-ivl">
<h2>Running ivl:<a class="headerlink" href="#running-ivl" title="Link to this heading"></a></h2>
<p>The -F switches are important. The following order seems to robustly
generate valid XNF files, and is used by “verilog -X”:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>-Fsynth -Fnodangle -Fxnfio
</pre></div>
</div>
</section>
<section id="generating-pcf-files">
<h2>Generating .pcf files:<a class="headerlink" href="#generating-pcf-files" title="Link to this heading"></a></h2>
<p>The ngdbuild step seems to lose pin placement information that ivl
puts in the XNF file. Use xnf2pcf to extract this information to
a .pcf file, which the Xilinx place-and-route software _will_ pay
attention to. Steve says he now makes that information available
in an NCF file, with -fncf=&lt;path&gt;, but I haven’t tested that.</p>
<p>Running the Xilinx back end:</p>
<p>You can presumably use the GUI, but that doesn’t fit in Makefiles :-).
Here is the command sequence in pseudo-shell-script:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>ngdbuild -p $part $1.xnf $1.ngd
map -p $part -o map.ncd $1.ngd
xnf2pcf &lt;$1.xnf &gt;$1.pcf # see above
par -w -ol 2 -d 0 map.ncd $1.ncd $1.pcf
bitgen_flags = -g ConfigRate:SLOW -g TdoPin:PULLNONE -g DonePin:PULLUP \
-g CRC:enable -g StartUpClk:CCLK -g SyncToDone:no \
-g DoneActive:C1 -g OutputsActive:C3 -g GSRInactive:C4 \
-g ReadClk:CCLK -g ReadCapture:enable -g ReadAbort:disable
bitgen $1.ncd -l -w $bitgen_flags
</pre></div>
</div>
<p>The Xilinx software has diarrhea of the temp files (14, not including
.xnf, .pcf, .ngd, .ncd, and .bit), so this sequence is best done in a
dedicated directory. Note in particular that map.ncd is a generic name.</p>
<p>I had reason to run this remotely (and transparently within a Makefile)
via ssh. I use the gmake rule:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>%.bit : %.xnf
ssh -x -a -o &#39;BatchMode yes&#39; ${ALLIANCE_HOST} \
remote_alliance ${REMOTE_DIR} $(basename $@) 2&gt;&amp;1 &lt; $&lt;
scp ${ALLIANCE_HOST}:${REMOTE_DIR}/$@ .
</pre></div>
</div>
<p>and the remote_alliance script (on ${ALLIANCE_HOST}):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>/bin/csh
cd $1
cat &gt;! $2.xnf
xnf2pcf &lt;$2.xnf &gt;! $2.pcf
./backend $2
</pre></div>
</div>
<p>There is now a “Xilinx on Linux HOWTO” at <a class="reference external" href="http://www.polybus.com/xilinx_on_linux.html">http://www.polybus.com/xilinx_on_linux.html</a>
I haven’t tried this yet, it looks interesting.</p>
</section>
<section id="downloading">
<h2>Downloading:<a class="headerlink" href="#downloading" title="Link to this heading"></a></h2>
<p>I use the XESS (<a class="reference external" href="http://www.xess.com/">http://www.xess.com/</a>) XSP-10 development board, which
uses the PC parallel (printer) port for downloading and interaction
with the host. They made an old version of their download program
public domain, posted it at <a class="reference external" href="http://www.xess.com/FPGA/xstools.zip">http://www.xess.com/FPGA/xstools.zip</a> ,
and now there is a Linux port at <a class="reference external" href="ftp://ftp.microux.com/pub/pilotscope/xstools.tar.gz">ftp://ftp.microux.com/pub/pilotscope/xstools.tar.gz</a> .</p>
<p>The above hints are based on my experience with Foundation 1.5 on NT
(gack) and Alliance 2.1i on Solaris. Your mileage may vary. Good luck!</p>
<blockquote>
<div><ul class="simple">
<li><dl class="simple">
<dt>Larry Doolittle &lt;<a class="reference external" href="mailto:LRDoolittle&#37;&#52;&#48;lbl&#46;gov">LRDoolittle<span>&#64;</span>lbl<span>&#46;</span>gov</a>&gt; August 19, 1999</dt><dd><p>updated February 1, 2000</p>
</dd>
</dl>
</li>
</ul>
</div></blockquote>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li><a href="index.html">Miscellaneous</a><ul>
<li>Previous: <a href="swift.html" title="previous chapter">Swift Model Support (Preliminary)</a></li>
<li>Next: <a href="../../glossary.html" title="next chapter">Glossary</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/misc/xilinx-hint.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

149
developer/guide/tgt-vvp/tgt-vvp.html Normal file
View File

@ -0,0 +1,149 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>The VVP Target &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="VPI in Icarus Verilog" href="../vpi/index.html" />
<link rel="prev" title="Debug Aids For VVP" href="../vvp/debug.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="the-vvp-target">
<h1>The VVP Target<a class="headerlink" href="#the-vvp-target" title="Link to this heading"></a></h1>
<section id="symbol-name-conventions">
<h2>Symbol Name Conventions<a class="headerlink" href="#symbol-name-conventions" title="Link to this heading"></a></h2>
<p>There are some naming conventions that the vvp target uses for
generating symbol names.</p>
<ul class="simple">
<li><p>wires and regs</p></li>
</ul>
<p>Nets and variables are named V_&lt;full-name&gt; where &lt;full-name&gt; is the
full hierarchical name of the signal.</p>
<ul class="simple">
<li><p>Logic devices</p></li>
</ul>
<p>Logic devices (and, or, buf, bufz, etc.) are named L_&lt;full_name&gt;. In
this case the symbol is attached to a functor that is the output of
the logic device.</p>
</section>
<section id="general-functor-web-structure">
<h2>General Functor Web Structure<a class="headerlink" href="#general-functor-web-structure" title="Link to this heading"></a></h2>
<p>The net of gates, signals and resolvers is formed from the input
design. The basic structure is wrapped around the nexus, which is
represented by the ivl_nexus_t.</p>
<p>Each nexus represents a resolved value. The input of the nexus is fed
by a single driver. If the nexus in the design has multiple drivers,
the drivers are first fed into a resolver (or a tree of resolvers) to
form a single output that is the nexus.</p>
<p>The nexus, then, feeds its output to the inputs of other gates, or to
the .net objects in the design.</p>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li>Previous: <a href="../vvp/debug.html" title="previous chapter">Debug Aids For VVP</a></li>
<li>Next: <a href="../vpi/index.html" title="next chapter">VPI in Icarus Verilog</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/tgt-vvp/tgt-vvp.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

127
developer/guide/vpi/index.html Normal file
View File

@ -0,0 +1,127 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>VPI in Icarus Verilog &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="VPI Modules in Icarus Verilog" href="vpi.html" />
<link rel="prev" title="The VVP Target" href="../tgt-vvp/tgt-vvp.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="vpi-in-icarus-verilog">
<h1>VPI in Icarus Verilog<a class="headerlink" href="#vpi-in-icarus-verilog" title="Link to this heading"></a></h1>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="vpi.html">VPI Modules in Icarus Verilog</a></li>
<li class="toctree-l1"><a class="reference internal" href="va_math.html">Verilog-A math library</a></li>
</ul>
</div>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li>Previous: <a href="../tgt-vvp/tgt-vvp.html" title="previous chapter">The VVP Target</a></li>
<li>Next: <a href="vpi.html" title="next chapter">VPI Modules in Icarus Verilog</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/vpi/index.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

214
developer/guide/vpi/va_math.html Normal file
View File

@ -0,0 +1,214 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Verilog-A math library &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Cadence PLI1 Modules" href="../cadpli/cadpli.html" />
<link rel="prev" title="VPI Modules in Icarus Verilog" href="vpi.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="verilog-a-math-library">
<h1>Verilog-A math library<a class="headerlink" href="#verilog-a-math-library" title="Link to this heading"></a></h1>
<section id="license">
<h2>License.<a class="headerlink" href="#license" title="Link to this heading"></a></h2>
<blockquote>
<div><p>Verilog-A math library built for Icarus Verilog
<a class="reference external" href="https://github.com/steveicarus/iverilog/">https://github.com/steveicarus/iverilog/</a></p>
<p>Copyright (C) 2007-2024 Cary R. (<a class="reference external" href="mailto:cygcary&#37;&#52;&#48;yahoo&#46;com">cygcary<span>&#64;</span>yahoo<span>&#46;</span>com</a>)</p>
<p>This program is free software; you can redistribute it and/or modify
it 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.</p>
<p>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.</p>
<p>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.</p>
</div></blockquote>
</section>
<section id="standard-verilog-a-mathematical-functions">
<h2>Standard Verilog-A Mathematical Functions.<a class="headerlink" href="#standard-verilog-a-mathematical-functions" title="Link to this heading"></a></h2>
<p>The va_math VPI module implements all the standard math functions provided
by Verilog-A as Verilog-D system functions. The names are the same except
like all Verilog-D system functions the name must be prefixed with a ‘$’.
For reference the functions are:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>$ln(x) -- Natural logarithm
$log10(x) -- Decimal logarithm
$exp(x) -- Exponential
$sqrt(x) -- Square root
$min(x,y) -- Minimum
$max(x,y) -- Maximum
$abs(x) -- Absolute value
$floor(x) -- Floor
$ceil(x) -- Ceiling
$pow(x,y) -- Power (x**y)
$sin(x) -- Sine
$cos(x) -- Cosine
$tan(x) -- Tangent
$asin(x) -- Arc-sine
$acos(x) -- Arc-cosine
$atan(x) -- Arc-tangent
$atan2(y,x) -- Arc-tangent of y/x
$hypot(x,y) -- Hypotenuse (sqrt(x**2 + y**2))
$sinh(x) -- Hyperbolic sine
$cosh(x) -- Hyperbolic cosine
$tanh(x) -- Hyperbolic tangent
$asinh(x) -- Arc-hyperbolic sine
$acosh(x) -- Arc-hyperbolic cosine
$atanh(x) -- Arc-hyperbolic tangent
</pre></div>
</div>
<p>The only limit placed on the x and y arguments by the library is that they
must be numbers (not constant strings). The underlying C library controls
any other limits placed on the arguments. Most libraries return +-Inf or
NaN for results that cannot be represented with real numbers. All functions
return a real result.</p>
</section>
<section id="standard-verilog-a-mathematical-constants">
<h2>Standard Verilog-A Mathematical Constants.<a class="headerlink" href="#standard-verilog-a-mathematical-constants" title="Link to this heading"></a></h2>
<p>The Verilog-A mathematical constants can be accessed by including the
“constants.vams” header file. It is located in the standard include
directory. Recent version of Icarus Verilog (0.9.devel) automatically
add this directory to the end of the list used to find include files.
For reference the mathematical constants are:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>`M_PI -- Pi
`M_TWO_PI -- 2*Pi
`M_PI_2 -- Pi/2
`M_PI_4 -- Pi/4
`M_1_PI -- 1/Pi
`M_2_PI -- 2/Pi
`M_2_SQRTPI -- 2/sqrt(Pi)
`M_E -- e
`M_LOG2E -- log base 2 of e
`M_LOG10E -- log base 10 of e
`M_LN2 -- log base e of 2
`M_LN10 -- log base e of 10
`M_SQRT2 -- sqrt(2)
`M_SQRT1_2 -- 1/sqrt(2)
</pre></div>
</div>
</section>
<section id="using-the-library">
<h2>Using the Library.<a class="headerlink" href="#using-the-library" title="Link to this heading"></a></h2>
<p>Just add “-m va_math” to your iverilog command line/command file and
`include the “constants.vams” file as needed.</p>
</section>
<section id="thanks">
<h2>Thanks<a class="headerlink" href="#thanks" title="Link to this heading"></a></h2>
<p>I would like to thank Larry Doolittle for his suggestions and
Stephen Williams for developing Icarus Verilog.</p>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li><a href="index.html">VPI in Icarus Verilog</a><ul>
<li>Previous: <a href="vpi.html" title="previous chapter">VPI Modules in Icarus Verilog</a></li>
<li>Next: <a href="../cadpli/cadpli.html" title="next chapter">Cadence PLI1 Modules</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/vpi/va_math.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

164
developer/guide/vpi/vpi.html Normal file
View File

@ -0,0 +1,164 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>VPI Modules in Icarus Verilog &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Verilog-A math library" href="va_math.html" />
<link rel="prev" title="VPI in Icarus Verilog" href="index.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="vpi-modules-in-icarus-verilog">
<h1>VPI Modules in Icarus Verilog<a class="headerlink" href="#vpi-modules-in-icarus-verilog" title="Link to this heading"></a></h1>
<p>The VPI interface for Icarus Verilog works by creating from a
collection of PLI applications a single vpi module. The vpi module
includes compiled code for the applications linked together (with any
other libraries that the applications need) into a module with two
exported symbols, the vpip_set_callback function and the
vlog_startup_routines array.</p>
<p>The product that wishes to invoke the module (normally at run time) loads
the module, locates and calls the vpip_set_callback function to pass the
the module a jump table that allows the module to access the VPI routines
implemented by the product, then locates the vlog_startup_routines table
and calls all the startup routines contained in that table. It is possible
for a product to link with many modules. In that case, all the modules are
linked in and startup routines are called in order.</p>
<p>The product that uses vpi modules uses the environment variable
VPI_MODULE_PATH as a ‘:’ separated list of directories. This is the
module search path. When a module is specified by name (using whatever
means the product supports) the module search path is scanned until
the module is located.</p>
<p>The special module names “system.vpi”, “v2005_math.vpi”, “v2009.vpi”,
and “va_math.vpi” are part of the core Icarus Verilog distribution and
include implementations of the standard system tasks/functions. The
additional special module names “vhdl_sys.vpi” and “vhdl_textio.vpi”
include implementations of private functions used to support VHDL.</p>
<section id="compiling-a-vpi-module">
<h2>Compiling A VPI Module<a class="headerlink" href="#compiling-a-vpi-module" title="Link to this heading"></a></h2>
<p>See the documentation under: <a class="reference internal" href="../../../usage/vpi.html"><span class="doc">Using VPI</span></a></p>
</section>
<section id="tracing-vpi-use">
<h2>Tracing VPI Use<a class="headerlink" href="#tracing-vpi-use" title="Link to this heading"></a></h2>
<p>The vvp command includes the ability to trace VPI calls. This is
useful if you are trying to debug a problem with your code. To
activate tracing simply set the VPI_TRACE environment variable, with
the path to a file where trace text gets written. For example:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>setenv VPI_TRACE /tmp/foo.txt
</pre></div>
</div>
<p>This tracing is pretty verbose, so you don’t want to run like this
normally. Also, the format of the tracing messages will change
according to my needs (and whim) so don’t expect to be able to parse
it in software.</p>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li><a href="index.html">VPI in Icarus Verilog</a><ul>
<li>Previous: <a href="index.html" title="previous chapter">VPI in Icarus Verilog</a></li>
<li>Next: <a href="va_math.html" title="next chapter">Verilog-A math library</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/vpi/vpi.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

138
developer/guide/vvp/debug.html Normal file
View File

@ -0,0 +1,138 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Debug Aids For VVP &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="The VVP Target" href="../tgt-vvp/tgt-vvp.html" />
<link rel="prev" title="Thread Details" href="vthread.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="debug-aids-for-vvp">
<h1>Debug Aids For VVP<a class="headerlink" href="#debug-aids-for-vvp" title="Link to this heading"></a></h1>
<p>Debugging vvp can be fiendishly difficult, so there are some built in
debugging aids. These are enabled by setting the environment variable
VVP_DEBUG to the path to an output file. Then, various detailed debug
tools can be enabled as described below.</p>
<ul class="simple">
<li><p>.resolv</p></li>
</ul>
<p>The .resolv can print debug information along with a label by
specifying the debug output label on the .resolv line:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>.resolv tri$&lt;label&gt;
</pre></div>
</div>
<p>In this case, the “$” character directly after the “tri” enables debug
dumps for this node, and the &lt;label&gt; is the label to prepend to log
messages from this node.</p>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li><a href="index.html">VVP - Verilog Virtual Processor</a><ul>
<li>Previous: <a href="vthread.html" title="previous chapter">Thread Details</a></li>
<li>Next: <a href="../tgt-vvp/tgt-vvp.html" title="next chapter">The VVP Target</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/vvp/debug.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

130
developer/guide/vvp/index.html Normal file
View File

@ -0,0 +1,130 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>VVP - Verilog Virtual Processor &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="VVP Simulation Engine" href="vvp.html" />
<link rel="prev" title="Loadable Targets" href="../ivl/t-dll.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="vvp-verilog-virtual-processor">
<h1>VVP - Verilog Virtual Processor<a class="headerlink" href="#vvp-verilog-virtual-processor" title="Link to this heading"></a></h1>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="vvp.html">VVP Simulation Engine</a></li>
<li class="toctree-l1"><a class="reference internal" href="opcodes.html">Executable Instruction Opcodes</a></li>
<li class="toctree-l1"><a class="reference internal" href="vpi.html">VPI Within VVP</a></li>
<li class="toctree-l1"><a class="reference internal" href="vthread.html">Thread Details</a></li>
<li class="toctree-l1"><a class="reference internal" href="debug.html">Debug Aids For VVP</a></li>
</ul>
</div>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li>Previous: <a href="../ivl/t-dll.html" title="previous chapter">Loadable Targets</a></li>
<li>Next: <a href="vvp.html" title="next chapter">VVP Simulation Engine</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/vvp/index.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

1388
developer/guide/vvp/opcodes.html Normal file
View File

File diff suppressed because it is too large Load Diff

265
developer/guide/vvp/vpi.html Normal file
View File

@ -0,0 +1,265 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>VPI Within VVP &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Thread Details" href="vthread.html" />
<link rel="prev" title="Executable Instruction Opcodes" href="opcodes.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="vpi-within-vvp">
<h1>VPI Within VVP<a class="headerlink" href="#vpi-within-vvp" title="Link to this heading"></a></h1>
<p>System tasks and functions in Verilog are implemented in Icarus
Verilog by C routines written with VPI. This implies that the vvp
engine must provide at least a subset of the Verilog VPI
interface. The minimalist concepts of vvp, however, make the method
less than obvious.</p>
<p>Within a Verilog design, there is a more or less fixed web of
vpiHandles that is the design database as is available to VPI
functions. The Verilog standard defines quite a lot of types, but the
vvp only implements the ones it needs. The VPI web is added into the
design using special pseudo-ops that create the needed objects.</p>
<section id="loading-vpi-modules">
<h2>Loading VPI Modules<a class="headerlink" href="#loading-vpi-modules" title="Link to this heading"></a></h2>
<p>The vvp runtime loads VPI modules at runtime before the parser reads
in the source files. This gives the modules a chance to register tasks
and functions before the source is compiled. This allows the compiler
to resolve references to system tasks and system functions to a
vpiHandle at compile time. References to missing tasks/function can
thus be caught before the simulation is run.</p>
<blockquote>
<div><p>NOTE: This also, miraculously, allows for some minimal support of
the compiletf call. From the perspective of VPI code, compilation
of the VVP source is not unlike compilation of the original
Verilog.</p>
</div></blockquote>
<p>The handle that the vvp threads have to the VPI are the vpiHandles of
the system tasks and functions. The %vpi_call instruction, once compiled,
carries the vpiHandle of the system task.</p>
</section>
<section id="system-task-calls">
<h2>System Task Calls<a class="headerlink" href="#system-task-calls" title="Link to this heading"></a></h2>
<p>A system task call invokes a VPI routine, and makes available to that
routine the arguments to the system task. The called routine gets
access to the system task call by calling back the VPI requesting the
handle. It uses the handle, in turn, to get hold of the operands for
the task.</p>
<p>All that vvp needs to know about a system task call is the handle of
the system task definitions (created by the vpi_register_systf
function) and the arguments of the actual call. The arguments are
tricky because the list has no bound, even though each particular call
in the Verilog source has a specific set of parameters.</p>
<p>Since each call takes a fixed number of parameters, the input source
can include in the statement the list of arguments. The argument list
will not fit in a single generated instruction, but a vpiHandle that
refers to a vpiSysTfCall does. Therefore, the compiler can take the
long argument list and form a vpiSysTaskCall object. The generated
instruction then only needs to be a %vpi_call with the single parameter
that is the vpiHandle for the call.</p>
</section>
<section id="system-function-calls">
<h2>System Function Calls<a class="headerlink" href="#system-function-calls" title="Link to this heading"></a></h2>
<p>System function calls are similar to system tasks. The only
differences are that all the arguments are input only, and there is a
single magic output that is the return value. The same %vpi_call can
even be used to call a function.</p>
<p>System functions, like system tasks, can only be called from thread
code. However, they can appear in expressions, even when that
expression is entirely structural. The desired effect is achieved by
writing a wrapper thread that calls the function when inputs change,
and that writes the output into the containing expression.</p>
</section>
<section id="system-task-function-arguments">
<h2>System Task/Function Arguments<a class="headerlink" href="#system-task-function-arguments" title="Link to this heading"></a></h2>
<p>The arguments to each system task or call are not stored in the
instruction op-code, but in the vpiSysTfCall object that the compiler
creates and that the %vpi_call instruction ultimately refers to. All
the arguments must be some sort of object that can be represented by a
vpiHandle at compile time.</p>
<p>Arguments are handled at compile time by the parser, which uses the
argument_list rule to build a list of vpiHandle objects. Each argument
in the argument_list invokes whatever function is appropriate for the
token in order to make a vpiHandle object for the argument_list. When
all this is done, an array of vpiHandles is passed to code to create a
vpiSysTfCall object that has all that is needed to make the call.</p>
</section>
<section id="scopes">
<h2>Scopes<a class="headerlink" href="#scopes" title="Link to this heading"></a></h2>
<p>VPI can access scopes as objects of type vpiScope. Scopes have names
and can also contain other sub-scopes, all of which the VPI function
can access by the vpiInternalScope reference. Therefore, the run-time
needs to form a tree of scopes into which other scoped VPI objects are
placed.</p>
<p>A scope is created with a .scope directive, like so:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>&lt;label&gt; .scope &quot;name&quot; [, &lt;parent&gt;];
.timescale &lt;units&gt;;
</pre></div>
</div>
<p>The scope takes a string name as the first parameter. If there is an
additional parameter, it is a label of the directive for the parent
scope. Scopes that have no parent are root scopes. It is an error to
declare a scope with the same name more than once in a parent scope.</p>
<p>The name string given when creating the scope is the basename for the
scope. The vvp automatically constructs full names from the scope
hierarchy, and runtime VPI code can access that full name with the
vpiFullName reference.</p>
<p>The .timescale directive changes the scope units from the simulation
precision to the specified precision. The .timescale directive affects
the current scope.</p>
<p>Objects that place themselves in a scope place themselves in the
current scope. The current scope is the one that was last mentioned by
a .scope directive. If the wrong scope is current, the label on a
scope directive can be used to resume a scope. The syntax works like
this:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>.scope &lt;symbol&gt;;
</pre></div>
</div>
<p>In this case, the &lt;symbol&gt; is the label of a previous scope directive,
and is used to identify the scope to be resumed. A scope resume
directive cannot have a label.</p>
</section>
<section id="variables">
<h2>Variables<a class="headerlink" href="#variables" title="Link to this heading"></a></h2>
<p>Reg vectors (scalars are vectors of length 1) are created by .var
statements in the source. The .var statement includes the declared
name of the variable, and the indices of the MSB and LSB of the
vector. The vpiHandle is then created with this information, and the
vpi_ipoint_t pointer to the LSB functor of the variable. VPI programs
access the vector through the vpiHandle and related functions. The VPI
code gets access to the declared indices.</p>
<p>The VPI interface to variable (vpiReg objects) uses the MSB and LSB
values that the user defined to describe the dimensions of the
object.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>/*
* Copyright (c) 2001-2024 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.
*/
</pre></div>
</div>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li><a href="index.html">VVP - Verilog Virtual Processor</a><ul>
<li>Previous: <a href="opcodes.html" title="previous chapter">Executable Instruction Opcodes</a></li>
<li>Next: <a href="vthread.html" title="next chapter">Thread Details</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/vvp/vpi.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

175
developer/guide/vvp/vthread.html Normal file
View File

@ -0,0 +1,175 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../../../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Thread Details &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../../../_static/alabaster.css?v=cb25574f" />
<script src="../../../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../../../_static/doctools.js?v=888ff710"></script>
<script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Debug Aids For VVP" href="debug.html" />
<link rel="prev" title="VPI Within VVP" href="vpi.html" />
<link rel="stylesheet" href="../../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="thread-details">
<h1>Thread Details<a class="headerlink" href="#thread-details" title="Link to this heading"></a></h1>
<p>Thread objects in vvp are created by <cite>.thread</cite> statements in the
input source file.</p>
<p>A thread object includes a program counter and private bit
registers. The program counter is used to step the processor through
the code space as it executes instructions. The bit registers each
hold Verilog-style 4-value bits and are for use by the arithmetic
operators as they operate.</p>
<p>The program counter normally increments by one instruction after the
instruction is fetched. If the instruction is a branching instruction,
then the execution of the instruction sets a new value for the pc.</p>
<p>Instructions that use the bit registers have as an operand a &lt;bit&gt;
value. There is usually space in the instruction for 2 &lt;bit&gt;
operands. Instructions that work on vectors pull the vector values
from the bit registers starting with the LSB and up.</p>
<p>The bit addresses 0, 1, 2 and 3 are special constant bits 0, 1, x and
z, and are used as read-only immediate values. If the instruction
takes a single bit operand, then the appropriate value is simply read
out. If the instruction expects a vector, then a vector of the
expected width is created by replicating the constant value.</p>
<p>Bits 4, 5, 6 and 7 are read/write bits but are reserved by many
instructions for special purposes. Comparison operators, for example,
use these as comparison flag bits.</p>
<p>The remaining 64K-8 possible &lt;bit&gt; values are read-write bit registers
that can be accessed singly or as vectors. This obviously implies that
a bit address is 16 bits.</p>
<p>Threads also contain 16 numeric registers. These registers can hold a
real value or a 64bit integer, and can be used in certain cases where
numeric values are needed. The thread instruction set includes
%ix/* instructions to manipulate these registers. The instructions
that use these registers document which register is used, and what the
numeric value is used for. Registers 0-3 are often given fixed
meanings to instructions that need an integer value.</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>/*
* Copyright (c) 2001-2024 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.
*/
</pre></div>
</div>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../../../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../../../index.html">Documentation overview</a><ul>
<li><a href="../../index.html">Icarus Verilog Developer Support</a><ul>
<li><a href="../index.html">Developer Guide</a><ul>
<li><a href="index.html">VVP - Verilog Virtual Processor</a><ul>
<li>Previous: <a href="vpi.html" title="previous chapter">VPI Within VVP</a></li>
<li>Next: <a href="debug.html" title="next chapter">Debug Aids For VVP</a></li>
</ul></li>
</ul></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../../../_sources/developer/guide/vvp/vthread.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

1215
developer/guide/vvp/vvp.html Normal file
View File

File diff suppressed because it is too large Load Diff

128
developer/index.html Normal file
View File

@ -0,0 +1,128 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Icarus Verilog Developer Support &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=cb25574f" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=888ff710"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Getting Started as a Contributor" href="getting_started.html" />
<link rel="prev" title="The BLIF Code Generator (-tblif)" href="../targets/tgt-blif.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="icarus-verilog-developer-support">
<h1>Icarus Verilog Developer Support<a class="headerlink" href="#icarus-verilog-developer-support" title="Link to this heading"></a></h1>
<p>This section contains documents to help support developers who contribute to
Icarus Verilog.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l1"><a class="reference internal" href="regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l1"><a class="reference internal" href="version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l1"><a class="reference internal" href="guide/index.html">Developer Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary</a></li>
</ul>
</div>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Icarus Verilog Developer Support</a><ul>
<li class="toctree-l2"><a class="reference internal" href="getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2"><a class="reference internal" href="regression_tests.html">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2"><a class="reference internal" href="guide/index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../index.html">Documentation overview</a><ul>
<li>Previous: <a href="../targets/tgt-blif.html" title="previous chapter">The BLIF Code Generator (-tblif)</a></li>
<li>Next: <a href="getting_started.html" title="next chapter">Getting Started as a Contributor</a></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../_sources/developer/index.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

223
developer/regression_tests.html Normal file
View File

@ -0,0 +1,223 @@
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>The Regression Test Suite &#8212; Icarus Verilog documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=cb25574f" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=888ff710"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="icon" href="../_static/favicon.ico"/>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Files With Version Information" href="version_stamps.html" />
<link rel="prev" title="Getting Started as a Contributor" href="getting_started.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="the-regression-test-suite">
<h1>The Regression Test Suite<a class="headerlink" href="#the-regression-test-suite" title="Link to this heading"></a></h1>
<p>Icarus Verilog development includes a regression test suite that is included
along with the source. The “ivtest” directory contains the regression test
suite, and this suite is used by the github actions as continuous integration
to make sure the code is always going forward.</p>
<p>NOTE: There are scripts written in perl to run the regression tests, but they
are being gradually replaced with a newer set of scripts. It is the newer
method that is described here.</p>
<section id="test-descriptions">
<h2>Test Descriptions<a class="headerlink" href="#test-descriptions" title="Link to this heading"></a></h2>
<p>Regression tests are listed in the regress-vvp.list file. Each line lists the
name of the test and the path to the dest description. The list file is
therefore pretty simple, and all the description of the test is in the
description file:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">macro_str_esc vvp_tests/macro_str_esc.json</span>
</pre></div>
</div>
<p>The “name” is a simple name, and the test-description-file is the path (relative
the ivtest directory) to the description file. A simple test description file
is a JSON file, like this:</p>
<div class="highlight-java notranslate"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="w"> </span><span class="s">&quot;type&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s">&quot;normal&quot;</span><span class="p">,</span>
<span class="w"> </span><span class="s">&quot;source&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s">&quot;macro_str_esc.v&quot;</span><span class="p">,</span>
<span class="w"> </span><span class="s">&quot;gold&quot;</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s">&quot;macro_str_esc&quot;</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This description file contains all the information that the vvp_reg.py script
needs to run the regression test. The sections below describe the keys and
values in the description file dictionary.</p>
<section id="source-required">
<h3>source (required)<a class="headerlink" href="#source-required" title="Link to this heading"></a></h3>
<p>This specifies the name of the source file. The file is actually to be found
in the ivltests/ directory.</p>
</section>
<section id="type-required">
<h3>type (required)<a class="headerlink" href="#type-required" title="Link to this heading"></a></h3>
<p>This describes the kind of test to run. The valid values are:</p>
<ul class="simple">
<li><p><strong>normal</strong> - Compile the source using the iverilog compiler vvp target, and if
that succeeds execute it using the vvp command. If there is no gold file
specified, then look for an output line with the “PASSED” string.</p></li>
<li><p><strong>normal-vlog95</strong> - This is similar to the normal case, but uses
the -tvlog95 target in a first pass to generate simplified verilog, then a
regular iverilog command with the -tvvp target to generate the actual
executable. This tests the -tvlog95 target.</p></li>
<li><p><strong>NI</strong> - Mark the test as not implemented. The test will be skipped without
running or reporting an error.</p></li>
<li><p><strong>CE</strong> - Compile, but expect the compiler to fail. This means the compiler
command process must return an error exit.</p></li>
<li><p><strong>EF</strong> - Compile and run, but expect the run time to fail. This means the
run time program must return an error exit.</p></li>
</ul>
</section>
<section id="gold-optional">
<h3>gold (optional)<a class="headerlink" href="#gold-optional" title="Link to this heading"></a></h3>
<p>If this is specified, it replaces the “Passed” condition with a comparison of
the output with a gold file. The argument is the name of the gold file set,
which will be found in the “gold/” directory. The name here is actually the
basename of the gold files, with separate actual gold files for the iverilog
and vvp stderr and stdout. For example, if a “normal” test includes a gold
file, then the program is compiled and run, and the outputs are compared with
the gold file to make sure it ran properly.</p>
<p>The way the regression suite works, there are 4 log files created for each
test:</p>
<ul class="simple">
<li><p>foo-iverilog-stdout.log</p></li>
<li><p>foo-iverilog-stderr.log</p></li>
<li><p>foo-vvp-stdout.log</p></li>
<li><p>foo-vvp-stderr.log</p></li>
</ul>
<p>The “gold” value is the name of the gold file set. If the gold value is “foo”,
Then the actual gold files are called:</p>
<ul class="simple">
<li><p>gold/foo-iverilog-stdout.gold</p></li>
<li><p>gold/foo-iverilog-stderr.gold</p></li>
<li><p>gold/foo-vvp-stdout.gold</p></li>
<li><p>gold/foo/vvp-stderr.gold</p></li>
</ul>
<p>If any of those files is empty, then the gold file doesn’t need to be
present at all. The log files and the gold files are compared byte for
byte, so if the output you are getting is correct, then copy the log to
the corresponding gold, and you’re done.</p>
<p>If the run type is “CE” or “RE”, then the gold files still work, and can
be used to check that the error message is correct. If the gold file setting
is present, the error return is required, and also the gold files must match.</p>
</section>
<section id="iverilog-args-optional">
<h3>iverilog-args (optional)<a class="headerlink" href="#iverilog-args-optional" title="Link to this heading"></a></h3>
<p>If this is specified, it is a list of strings that are passed as arguments to
the iverilog command line.</p>
</section>
<section id="vvp-args-optional">
<h3>vvp-args (optional)<a class="headerlink" href="#vvp-args-optional" title="Link to this heading"></a></h3>
<p>If this is specified, it is a list of strings that are passed as arguments to
the vvp command. These arguments go before the vvp input file that is to be
run.</p>
</section>
<section id="vvp-args-extended-optional">
<h3>vvp-args-extended (optional)<a class="headerlink" href="#vvp-args-extended-optional" title="Link to this heading"></a></h3>
<p>If this is specified, it is a lost of strings that are passed as arguments to
the vvp command. These are extended arguments, and are placed after the vvp
input file that is being run. This is where you place things like plusargs.</p>
</section>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../index.html">Icarus Verilog</a></h1>
<h3>Navigation</h3>
<p class="caption" role="heading"><span class="caption-text">Contents:</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../usage/index.html">Icarus Verilog Usage</a></li>
<li class="toctree-l1"><a class="reference internal" href="../targets/index.html">The Icarus Verilog Targets</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Icarus Verilog Developer Support</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="getting_started.html">Getting Started as a Contributor</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">The Regression Test Suite</a></li>
<li class="toctree-l2"><a class="reference internal" href="version_stamps.html">Files With Version Information</a></li>
<li class="toctree-l2"><a class="reference internal" href="guide/index.html">Developer Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="glossary.html">Glossary</a></li>
</ul>
</li>
</ul>
<div class="relations">
<h3>Related Topics</h3>
<ul>
<li><a href="../index.html">Documentation overview</a><ul>
<li><a href="index.html">Icarus Verilog Developer Support</a><ul>
<li>Previous: <a href="getting_started.html" title="previous chapter">Getting Started as a Contributor</a></li>
<li>Next: <a href="version_stamps.html" title="next chapter">Files With Version Information</a></li>
</ul></li>
</ul></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy;2024-2025, Stephen Williams.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="../_sources/developer/regression_tests.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>

Some files were not shown because too many files have changed in this diff Show More