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

Move textfiles to documentation

This commit is contained in:
mole99 2023-06-09 13:30:44 +02:00
parent 41496040e8
commit b0c1eab51e
41 changed files with 781 additions and 1115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

174
BUGS.txt
View File

@ -1,174 +0,0 @@
HOW TO REPORT BUGS
Before I can fix an error, I need 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. Include a
description of what Icarus Verilog does that is wrong, and what you
expect should happen. And include the command line flags passed to the
compiler to make the error happen. (This is often overlooked, and
sometimes important.)
* The Compiler Doesn't Compile
If Icarus Verilog doesn't compile, I need to know about the
compilation tools you are using. Specifically, I need to know:
- Operating system and processor type,
- Compiler w/ version,
- Versions of any libraries being linked, and
- anything else you think relevant.
Be aware that I do not have at my disposal a porting lab. I have the
workstation on my desk, a Mac laptop, and the Linux/Intel box with a
logic analyzer and 'scope hanging off it.
* The Compiler Crashes
No compiler should crash, no matter what kind of garbage is fed to
it. If the compiler crashes, you definitely found a bug and I need to
know about it.
Icarus Verilog internally checks its state while it works, and if it
detects something wrong that it cannot recover from, it will abort
intentionally. The "assertion failure" message that the program
prints in the process of dying is very important. It tells me where in
the source the bad thing happened. Include that message in the bug
report.
If there are no assertion messages, I need to know that as well.
I also need a complete test program that demonstrates the crash.
* It Doesn't Like My Perfectly Valid Program(tm)
I need to know what you think is right that Icarus Verilog gets
wrong. Does it reject your "Perfectly Valid Program(tm)" or does it
compile it but give incorrect results? The latter is the most
insidious as it doesn't scream out to be fixed unless someone is
watching closely. However, if I get a sample program from you, and I
can compile it, and I run it and nuclear junk doesn't fall from the
sky, I'm moving on to the next problem.
So, if your program doesn't compile, tell me so, tell me where the
error occurs, and include a complete Perfectly Valid Test Program(tm).
You tell me that it fails to compile for you, and I find that it
compiles for me, then hooray I fixed it. It can happen, you
know. What's on my disk is more recent than the latest snapshot.
If your program does compile, but generates incorrect output, I need
to know what it says and what you think it should say. From this I can
take your sample program and work on Icarus Verilog until it gets the
proper results. For this to work, of course, I first need to know what
is wrong with the output. Spell it out, because I've been known to
miss the obvious. Compiler writers often get buried in the details of
the wrong problem.
* It Generates Incorrect Target Code
As Icarus Verilog adds target code generators, there will be cases
where errors in the output netlist format occur. This is a tough nut
because I might not have all the tools to test the target format you
are reporting problems with. However, if you clearly explain what is
right and wrong about the generated output, I will probably be able
to fix the problem. It may take a few iterations.
In this case, if possible include not only the sample Verilog program,
but the generated netlist file(s) and a clear indication of what went
wrong or what is expected. If it is not clear to me, I will ask for
clarification.
* The Output is Correct, But Less Than Ideal
If the output is strictly correct, but just not good enough for
practical use, I would like to know. These sorts of problems are
likely to be more subjective than a core dump, but are worthy of
consideration. However, realize that outright errors will get more
attention than missed optimizations.
THE MAKING OF A GOOD TEST PROGRAM
If at all possible, please submit a complete source file that
demonstrates the problem. If the error occurs after elaboration,
please include a top level module in the program that is suitable for
the target format. If I have to write the module myself, I might not
write it in a way that tickles the bug. So please, send all the
Verilog source that I need to invoke the error.
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
If the error occurs with the null target (``-tnull'') then a top level
module may not be needed as long as the ``-s <name>'' switch is
given.
So when you send a test case, ask yourself "Can poor overworked Steve
invoke the error without any Verilog other than what is included?" And
while we are at it, please place a copyright notice in your test
program and include a GPL license statement if you can. Your test
program may find its way into the test suite, and the notices will
make it all nice and legal. Please look at the existing tests in the
test suite <http://sourceforge.net/ivtest> for examples of good test
programs.
RESEARCHING EXISTING/PAST BUGS, AND FILING REPORTS
The URL <https://sourceforge.net/p/iverilog/bugs/> is the main
bug tracking system, although some users have reported bugs at
<https://github.com/steveicarus/iverilog/issues/>. Once you believe
you have found a bug, 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. Also, consider if you are reporting a bug or really
asking for a new feature, and use the appropriate tracker.
system (although you will also find bug rep
The bug database supports basic keyword searches, and you can
optionally limit your search to active bugs, or fixed bugs. You may
also browse the bug database, just to get an idea what is still
broken. You may for example find a related bug that explains your
symptom.
The root page of the bug report database describes how to submit your
completed bug report.
HOW TO SEND PATCHES
Bug reports with patches are very welcome, especially if they are
formatted such that I can inspect them, decide that they are obviously
correct, and apply them without worry.
I prefer patches generated by the git source code tracking system. If
you are editing the source, you really should be using the latest
version from git. Please see the developer documentation for more
detailed instructions -- <http://iverilog.wikia.com/wiki/>.
When you make a patch, submit it to the "Patches" tracker at
<https://sourceforge.net/p/iverilog/patches/>. Patches added to
the "Patches" tracker enter the developer workflow, are checked,
applied to the appropriate git branch, and are pushed. Then the
tracker item is closed.
If you send patches, *please* tell me what this patch is supposed to
accomplish, which branch you intended to be patched, and if
appropriate include a test program that demonstrates the efficacy of
the patch. (If I have no idea what the patch is for, I will ask for
clarification before applying it.)
COPYRIGHT ISSUES
Icarus Verilog is Copyright (c) 1998-2018 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.

6
Documentation/conf.py
View File

@ -20,7 +20,7 @@
# -- Project information -----------------------------------------------------
project = 'Icarus Verilog'
copyright = '2022, Stephen Williams'
copyright = '2023, Stephen Williams'
author = 'Stephen Williams'
# The short X.Y version
@ -68,6 +68,8 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If no language is specified, use none
highlight_language = 'none'
# -- Options for HTML output -------------------------------------------------
@ -152,4 +154,4 @@ texinfo_documents = [
(master_doc, 'IcarusVerilog', 'Icarus Verilog Documentation',
author, 'IcarusVerilog', 'One line description of project.',
'Miscellaneous'),
]
]

15
glossary.txt → Documentation/developer/glossary.rst
View File

@ -1,4 +1,7 @@
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
@ -22,7 +25,7 @@ UDP - User Defined Primitive
syntax for defining them is described in the LRM.
VPI -
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.
@ -34,6 +37,12 @@ VVM - Verilog Virtual Machine
VVP - Verilog Virtual Processor
This is the Icarus Verilog runtime that reads in custom code in a
form that I call "VVP Assembly". See the vvp/ directory for
documentation on that.
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.

7
cadpli/cadpli.txt → Documentation/developer/guide/cadpli/cadpli.rst
View File

@ -1,7 +1,6 @@
CADENCE PLI1 MODULES
Copyright 2003 Stephen Williams
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
@ -17,7 +16,7 @@ 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":
bootstrap function "my_boot"::
vvp -mcadpli a.out -cadpli=./product.so:my_boot

54
developer-quick-start.txt → Documentation/developer/guide/index.rst
View File

@ -1,21 +1,24 @@
Developer Quick Start for Icarus Verilog
Developer Guide
===============
The documentation for getting, building and installing Icarus Verilog
is kept and maintained at the iverilog documentation wiki at
<http://iverilog.wikia.com>. 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.
What this documentation *will* cover is the gross structure of the
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>`
* Compiler Components
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/)
@ -26,28 +29,29 @@ 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
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 (this directory)
- 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-*/)
- 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
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
Runtime Components
------------------
- The vvp runtime (vvp/)
@ -75,7 +79,8 @@ 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 Core Compiler
-----------------
The "ivl" binary is the core compiler that does the heavy lifting of
compiling the Verilog source (including libraries) and generating the
@ -147,3 +152,18 @@ 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

26
attributes.txt → Documentation/developer/guide/ivl/attributes.rst
View File

@ -1,14 +1,19 @@
ATTRIBUTE NAMING CONVENTIONS
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_".
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
Attributes To Control Synthesis
-------------------------------
The following is a summary of Verilog attributes that Icarus Verilog
understands within Verilog source files to control synthesis
@ -23,7 +28,7 @@ warning.)
* Attributes for "always" and "initial" statements
(* ivl_combinational *)
(\* ivl_combinational \*)
This attribute tells the compiler that the statement models
combinational logic. If the compiler finds that it cannot make
@ -34,14 +39,14 @@ warning.)
latches or flip-flops where the user intended combinational
logic.
(* ivl_synthesis_on *)
(\* 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 *)
(\* ivl_synthesis_off \*)
If this value is attached to an "always" statement, then the
compiler will *not* synthesize the "always" statement. This can be
@ -50,7 +55,7 @@ warning.)
* Attributes for modules
(* ivl_synthesis_cell *)
(\* ivl_synthesis_cell \*)
If this value is attached to a module during synthesis, that
module will be considered a target architecture primitive, and
@ -60,7 +65,7 @@ warning.)
* Attributes for signals (wire/reg/integer/tri/etc.)
(* PAD = "<pad assignment list>" *)
(\* 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
@ -73,9 +78,10 @@ warning.)
[ none defined yet ]
MISC
Misc
----
(* _ivl_schedule_push *)
(\* _ivl_schedule_push \*)
If this attribute is attached to a thread object (always or
initial statement) then the vvp code generator will generate code

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

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

29
Documentation/usage/ivl_target.rst → Documentation/developer/guide/ivl/ivl_target.rst
View File

@ -1,6 +1,6 @@
Loadable Target API (ivl_target.h)
==================================
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
@ -104,3 +104,28 @@ 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().

8
lpm.txt → Documentation/developer/guide/ivl/lpm.rst
View File

@ -1,5 +1,6 @@
WHAT IS LPM
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
@ -13,11 +14,12 @@ generates, because the LPM devices are translated into technology
specific devices by the final code generator or target specific
optimizers.
INTERNAL USES OF LPM
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
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.

87
netlist.txt → Documentation/developer/guide/ivl/netlist.rst
View File

@ -1,27 +1,6 @@
/*
* Copyright (c) 1998-1999 Stephen Williams (steve@icarus.com)
*
* This source code is free software; you can redistribute it
* and/or modify it in source code form under the terms of the GNU
* General Public License as published by the Free Software
* Foundation; either version 2 of the License, or (at your option)
* any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
Note that the netlist.h header contains detailed descriptions of how
things work. This is just an overview.
NETLIST FORMAT
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
@ -35,7 +14,8 @@ 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
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
@ -56,7 +36,8 @@ 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
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
@ -88,12 +69,13 @@ Currently, a link has 3 possible direction properties:
three-state.)
BEHAVIORAL ITEMS: NetProcTop, NetProc and derived classes
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
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
@ -104,7 +86,8 @@ 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_
Interaction Of Behavioral And Structural: NetAssign\_
-----------------------------------------------------
The behavioral statements in a Verilog design effect the structural
aspects through assignments to registers. Registers are structural
@ -113,26 +96,27 @@ 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
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
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
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.
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
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.
@ -143,13 +127,14 @@ 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_,
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
-----------
Expressions are represented as a tree of NetExpr nodes. The NetExpr
base class contains the core methods that represent an expression
@ -168,7 +153,8 @@ 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
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.
@ -200,14 +186,17 @@ determined and please adapt. If the expression cannot reasonably
adapt, it will return false. Otherwise, it will adjust bit widths and
return true.
XXXX I do not yet properly deal with cases where elaboration knows for
XXXX certain that the bit width does not matter. In this case, I
XXXX really should tell the expression node about it so that it can
XXXX pick a practical (and optimal) width.
::
INTERACTION OF EXPRESSIONS AND STRUCTURE: NetESignal
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.
The NetAssign_ class described above is the means for processes to
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
@ -215,7 +204,8 @@ pointers to a NetNet object, which is used to retrieve values with the
expression is evaluated.
HIERARCHY IN NETLISTS
Hierarchy In Netlists
---------------------
The obvious hierarchical structure of Verilog is the module. The
Verilog program may contain any number of instantiations of modules in
@ -236,7 +226,8 @@ boundaries. This makes coding of netlist transform functions such as
constant propagation more effective and easier to write.
SCOPE REPRESENTATION IN NETLISTS
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
@ -258,7 +249,8 @@ scope. Overrides are managed during the scan, and once the scan is
complete, defparam overrides are applied.
TASKS IN NETLISTS
Tasks In Netlists
-----------------
The flattening of the design does not include tasks and named
begin-end blocks. Tasks are behavioral hierarchy (whereas modules are
@ -268,7 +260,8 @@ 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
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

15
t-dll.txt → Documentation/developer/guide/ivl/t-dll.rst
View File

@ -1,5 +1,6 @@
LOADABLE TARGETS
Loadable Targets
================
Icarus Verilog supports dynamically loading code generator modules to
perform the back-end processing of the completed design. The user
@ -12,24 +13,28 @@ 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
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
Compiling Target Modules
------------------------
<write me>
LOADABLE TARGET MODULE API
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
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

7
extensions.txt → Documentation/developer/guide/misc/extensions.rst
View File

@ -1,5 +1,6 @@
Icarus Verilog Extensions
=========================
Icarus Verilog supports certain extensions to the baseline IEEE1364
standard. Some of these are picked from extended variants of the
@ -23,7 +24,7 @@ from the proposal.
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:
type. The primitive types available are::
logic - The familiar 0, 1, x and z, optionally with strength.
bool - Limited to only 0 and 1
@ -40,13 +41,13 @@ 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:
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:
or bool. Some valid examples::
wire real foo = 1.0;
tri logic bus[31:0];

74
ieee1364-notes.txt → Documentation/developer/guide/misc/ieee1364-notes.rst
View File

@ -1,9 +1,6 @@
NOTE: THE CONTENTS OF THIS FILE ARE BEING MOVED TO THE DOCUMENTATION
WIKI AT http://iverilog.wikia.com. PLEASE ADD NEW ENTRIES THERE.
Icarus Verilog vs. IEEE1364
Copyright 2000 Stephen Williams
IEEE1364 Notes
==============
The IEEE1364 standard is the bible that defines the correctness of the
Icarus Verilog implementation and behavior of the compiled
@ -19,7 +16,8 @@ and common to write programs that produce different results when run
by different Verilog implementations.
STANDARDIZATION ISSUES
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
@ -29,19 +27,19 @@ affect the language.
* OBJECTS CAN BE DECLARED ANYWHERE IN THE MODULE
Consider this module:
Consider this module::
module sample1;
initial foo = 1;
reg foo;
wire tmp = bar;
initial #1 $display("foo = %b, bar = %b", foo, tmp);
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
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
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.
@ -53,12 +51,12 @@ 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;''
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:
Here is another example::
module sample2;
initial x.foo = 1;
@ -80,7 +78,7 @@ 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
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
@ -107,7 +105,7 @@ 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:
and return its negative::
function integer negate;
input [15:0] val;
@ -123,7 +121,7 @@ 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:
As I understand the situation, this should be allowed::
function integer negate;
input [15:0] val;
@ -152,10 +150,10 @@ commercial tools seem to work similarly.
* ROUNDING OF TIME
When the `timescale directive is present, the compiler is supposed to
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
\`timescale directive is *not* present, times are rounded towards zero
always.
@ -173,12 +171,12 @@ 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:
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:
IEEE1364-1995 standard. One looks like this::
procedural_timing_control_statement ::=
delay_or_event_control statement_or_null
@ -189,7 +187,7 @@ IEEE1364-1995 standard. One looks like this:
If this interpretation is used, then the statement <statement> should
be executed after the 5th posedge of clk. However, there is also this
interpretation:
interpretation::
loop_statement ::=
repeat ( expression ) statement
@ -218,7 +216,7 @@ compiler may just as easily choose another width limit, for example
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;
accurately. This is especially useful in situations like this::
reg [width-1:0] foo = 17179869183;
@ -237,7 +235,7 @@ truncation point.
* UNSIZED EXPRESSIONS AS PARAMETERS TO CONCATENATION {}
The Verilog standard clearly states in 4.1.14:
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
@ -257,7 +255,7 @@ 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:
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
@ -268,6 +266,8 @@ 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}
@ -301,7 +301,7 @@ generate appropriate error messages.
* MODULE INSTANCE WITH WRONG SIZE PORT LIST
A module declaration like this declares a module that takes three ports:
A module declaration like this declares a module that takes three ports::
module three (a, b, c);
input a, b, c;
@ -309,7 +309,7 @@ A module declaration like this declares a module that takes three ports:
endmodule
This is fine and obvious. It is also clear from the standard that
these are legal instantiations of this module:
these are legal instantiations of this module::
three u1 (x,y,z);
three u2 ( ,y, );
@ -320,7 +320,7 @@ 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:
obvious::
three u4 ();
@ -331,7 +331,7 @@ 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:
These are more doubtful::
three u5(x,y);
three u6(,);
@ -351,7 +351,7 @@ other.
* UNKNOWN VALUES IN L-VALUE BIT SELECTS
Consider this example:
Consider this example::
reg [7:0] vec;
wire [4:0] idx = <expr>;
@ -375,7 +375,7 @@ assignment will have no effect.
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:
Verilog. Consider this example::
reg a;
reg b;
@ -438,7 +438,7 @@ bit and part selects.
* EDGES OF VECTORS
Consider this example:
Consider this example::
reg [ 5:0] clock;
always @(posedge clock) [do stuff]
@ -446,7 +446,7 @@ Consider this example:
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
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
@ -462,7 +462,7 @@ matter.
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:
does this, for example::
$dumpoff
x!
@ -475,7 +475,7 @@ 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):
For example (from XL)::
$dumpoff
r0 !
@ -485,7 +485,7 @@ For example (from XL):
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:
(during the dead zone) status of the variable, like this::
$dumpoff
rNaN !

11
Documentation/developer/guide/misc/index.rst Normal file
View File

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

9
swift.txt → Documentation/developer/guide/misc/swift.rst
View File

@ -1,5 +1,6 @@
SWIFT MODEL SUPPORT FOR Icarus Verilog (PRELIMINARY)
Swift Model Support (Preliminary)
=================================
Copyright 2003 Stephen Williams
@ -24,7 +25,7 @@ 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:
file like so::
+libdir+.../smartmodel/sol/wrappers/verilogxl
@ -42,11 +43,11 @@ support for your model.
* Execution
After your simulation is compiled, run the simulation with the vvp
command, like this:
command, like this::
% vvp -mcadpli a.out -cadpli=$LMC_HOME/lib/x86_linux.lib/swiftpli.so:swift_boot
What this command line means is:
What this command line means is::
-mcadpli
Include the cadpli compatibility module

113
Documentation/developer/guide/misc/xilinx-hint.rst 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

9
tgt-vvp/README.txt → Documentation/developer/guide/tgt-vvp/tgt-vvp.rst
View File

@ -1,7 +1,9 @@
THE VVP TARGET
The VVP Target
==============
SYMBOL NAME CONVENTIONS
Symbol Name Conventions
-----------------------
There are some naming conventions that the vvp target uses for
generating symbol names.
@ -18,7 +20,8 @@ this case the symbol is attached to a functor that is the output of
the logic device.
GENERAL FUNCTOR WEB STRUCTURE
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

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

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

27
va_math.txt → Documentation/developer/guide/vpi/va_math.rst
View File

@ -1,15 +1,12 @@
The following is from the README.va_math that was included with the
initial contribution of the va_math module. I've removed the parts
that are obviously not applicable, i.e. how to compile the library, to
this bundled version of the library.
Verilog-A math library
======================
--------
License.
--------
Verilog-A math library built for Icarus Verilog
http://www.icarus.com/eda/verilog/
https://github.com/steveicarus/iverilog/
Copyright (C) 2007-2010 Cary R. (cygcary@yahoo.com)
@ -27,15 +24,13 @@ License.
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:
For reference the functions are::
$ln(x) -- Natural logarithm
$log10(x) -- Decimal logarithm
@ -68,8 +63,6 @@ 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.
------------------------------------------
@ -77,7 +70,7 @@ 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:
For reference the mathematical constants are::
`M_PI -- Pi
`M_TWO_PI -- 2*Pi
@ -94,22 +87,14 @@ For reference the mathematical constants are:
`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.
\`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.
--------
The End.
--------

13
vpi.txt → Documentation/developer/guide/vpi/vpi.rst
View File

@ -1,5 +1,6 @@
HOW IT WORKS
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
@ -28,16 +29,18 @@ 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
Compiling A VPI Module
----------------------
See the iverilog-vpi documentation.
See the documentation under: :doc:`Using VPI <../../../usage/vpi>`
TRACING VPI USE
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:
the path to a file where trace text gets written. For example::
setenv VPI_TRACE /tmp/foo.txt

5
vvp/debug.txt → Documentation/developer/guide/vvp/debug.rst
View File

@ -1,5 +1,6 @@
DEBUG AIDS FOR VVP
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
@ -9,7 +10,7 @@ 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:
specifying the debug output label on the .resolv line::
.resolv tri$<label>

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

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

54
vvp/opcodes.txt → Documentation/developer/guide/vvp/opcodes.rst
View File

@ -1,11 +1,5 @@
/*
* Copyright (c) 2001-2021 Stephen Williams (steve@icarus.com)
*
*/
EXECUTABLE INSTRUCTION OPCODES
Executable Instruction Opcodes
==============================
Instruction opcodes all start with a % character and have 0 or more
operands. In no case are there more than 3 operands. This chapter
@ -32,7 +26,8 @@ experience of implementing it for strings, I'll want to change other
types around to using this method as well. Keep this in mind whenever
considering adding new instructions to vvp.
FLAGS
Flags
-----
There are up to 16 bits in each thread that are available for
flags. These are used as destinations for operations that return
@ -302,7 +297,7 @@ The results of the comparison go into flags 4, 5, 6 and 7:
The eeq bit is set to 1 if all the bits in the vectors are exactly the
same, or 0 otherwise. The eq bit is true if the values are logically
the same. That is, x and z are considered equal. In other words the eq
bit is the same as ``=='' and the eeq bit ``===''.
bit is the same as `==` and the eeq bit `===`.
The lt bit is 1 if the left vector is less than the right vector, or 0
if greater than or equal to the right vector. It is the equivalent of
@ -534,7 +529,9 @@ an arbitrary value to the event to trigger the event.
This command emits the provided file and line information along with
the description when it is executed. The output is sent to stderr and
the format of the output is:
<file>:<line>: <description>
<file> is the unsigned numeric file index.
<line> is the unsigned line number.
<description> is a string, if string is 0 then the following default
@ -1338,22 +1335,23 @@ table for the xor is:
1 xor 1 --> 0
otherwise x
::
/*
* Copyright (c) 2001-2017 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.
*/
/*
* Copyright (c) 2001-2023 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.
*/

68
vvp/vpi.txt → Documentation/developer/guide/vvp/vpi.rst
View File

@ -1,10 +1,6 @@
/*
* Copyright (c) 2001 Stephen Williams (steve@icarus.com)
*
*/
VPI WITHIN VVP
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
@ -19,7 +15,8 @@ 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
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
@ -38,7 +35,8 @@ the system tasks and functions. The %vpi_call instruction, once compiled,
carries the vpiHandle of the system task.
SYSTEM TASK CALLS
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
@ -61,7 +59,8 @@ 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
---------------------
System function calls are similar to system tasks. The only
differences are that all the arguments are input only, and there is a
@ -75,7 +74,8 @@ writing a wrapper thread that calls the function when inputs change,
and that writes the output into the containing expression.
SYSTEM TASK/FUNCTION ARGUMENTS
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
@ -91,7 +91,8 @@ 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
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
@ -99,7 +100,7 @@ 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:
A scope is created with a .scope directive, like so::
<label> .scope "name" [, <parent>];
.timescale <units>;
@ -122,7 +123,7 @@ 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:
this::
.scope <symbol>;
@ -131,7 +132,8 @@ and is used to identify the scope to be resumed. A scope resume
directive cannot have a label.
VARIABLES
Variables
---------
Reg vectors (scalars are vectors of length 1) are created by .var
statements in the source. The .var statement includes the declared
@ -145,21 +147,23 @@ 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 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.
*/
::
/*
* Copyright (c) 2001 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.
*/

49
vvp/vthread.txt → Documentation/developer/guide/vvp/vthread.rst
View File

@ -1,13 +1,8 @@
/*
* Copyright (c) 2001 Stephen Williams (steve@icarus.com)
*
*/
Thread Details
==============
THREAD DETAILS
Thread objects in vvp are created by ``.thread'' statements in the
Thread objects in vvp are created by `.thread` statements in the
input source file.
A thread object includes a program counter and private bit
@ -47,21 +42,23 @@ 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 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.
*/
::
/*
* Copyright (c) 2001 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.
*/

287
vvp/README.txt → Documentation/developer/guide/vvp/vvp.rst
View File

@ -1,9 +1,6 @@
/*
* Copyright (c) 2001-2021 Stephen Williams (steve@icarus.com)
*
*/
VVP SIMULATION ENGINE
VVP Simulation Engine
=====================
The VVP simulator takes as input source code not unlike assembly
language for a conventional processor. It is intended to be machine
@ -12,7 +9,8 @@ compiler, so the syntax, though readable, is not necessarily
convenient for humans.
GENERAL FORMAT
General Format
--------------
The source file is a collection of statements. Each statement may have
a label, an opcode, and operands that depend on the opcode. For some
@ -21,7 +19,7 @@ required.
Every statement is terminated by a semicolon. The semicolon is also
the start of a comment line, so you can put comment text after the
semicolon that terminates a statement. Like so:
semicolon that terminates a statement. Like so::
Label .functor and, 0x5a, x, y ; This is a comment.
@ -31,7 +29,8 @@ Statements may span multiple lines, as long as there is no text (other
then the first character of a label) in the first column of the
continuation line.
HEADER SYNTAX
Header Syntax
-------------
Before any other non-commentary code starts, the source may contain
some header statements. These are used for passing parameters or
@ -57,9 +56,10 @@ expressed as a power of 10. For example, +0 is 1 second, and -9 is 1
nanosecond. If the record is left out, then the precision is taken to
be +0.
LABELS AND SYMBOLS
Labels and Symbols
------------------
Labels and symbols consist of the characters:
Labels and symbols consist of the characters::
a-z
A-Z
@ -88,14 +88,16 @@ There are some special symbols that in certain contexts have special
meanings. As inputs to functors, the symbols "C<0>", "C<1>", "C<x>"
and "C<z>" represent a constant driver of the given value.
NUMBERS:
Numbers
-------
decimal number tokens are limited to 64bits, and are unsigned. Some
contexts may constrain the number size further.
SCOPE STATEMENTS:
Scope Statements
----------------
The syntax of a scope statement is:
The syntax of a scope statement is::
<label> .scope <type>, <name> <type-name> <file> <lineno> ;
@ -125,13 +127,14 @@ The <is-cell> flag is only useful for module instances. It is true
The short form of the scope statement is only used for root scopes.
PARAMETER STATEMENTS:
Parameter Statements
--------------------
Parameters are named constants within a scope. These parameters have a
type and value, and also a label so that they can be referenced as VPI
objects.
The syntax of a parameter is:
The syntax of a parameter is::
<label> .param/str <name> <local-flag> <file-idx> <lineno>, <value>;
<label> .param/l <name> <local-flag> <file-idx> <lineno>, <value>;
@ -139,13 +142,13 @@ The syntax of a parameter is:
The <name> is a string that names the parameter. The name is placed in
the current scope as a vpiParameter object. The .param suffix
specifies the parameter type.
specifies the parameter type::
.param/str -- The parameter has a string value
.param/l -- The parameter has a logic vector value
.param/r -- The parameter has a real value
The value, then, is appropriate for the data type. For example:
The value, then, is appropriate for the data type. For example::
P_123 .param/str "hello", "Hello, World.";
@ -153,14 +156,15 @@ The boolean and logic values can also be signed or not. If signed, the
value is preceded by a '+' character. (Note that the value is 2s
complement, so the '+' says only that it is signed, not positive.)
FUNCTOR STATEMENTS:
Functor Statements
------------------
A functor statement is a statement that uses the ``.functor''
A functor statement is a statement that uses the `.functor`
opcode. Functors are the basic structural units of a simulation, and
include a type (in the form of a truth table) and up to four inputs. A
label is required for functors.
The general syntax of a functor is:
The general syntax of a functor is::
<label> .functor <type>, symbol_list ;
<label> .functor <type> [<drive0> <drive1>], symbol_list ;
@ -187,17 +191,20 @@ combining up to four inputs down to one output.
- MUXZ
::
Q | A B S n/a
--+-------------
A | * * 0
B | * * 1
DFF AND LATCH STATEMENTS:
DFF and Latch Statements
------------------------
The Verilog language itself does not have a DFF primitive, but post
synthesis readily creates DFF devices that are best simulated with a
common device. Thus, there is the DFF statement to create DFF devices:
common device. Thus, there is the DFF statement to create DFF devices::
<label> .dff/p <width> <d>, <clk>, <ce>;
<label> .dff/n <width> <d>, <clk>, <ce>;
@ -218,7 +225,7 @@ propagate, and disables the clock until the aynchronous input is
deasserted. Thus, they implement DFF with asynchronous clr or set.
Similarly, synthesis creates D-type latches, so there is the LATCH
statement to support this:
statement to support this::
<label> .latch <width> <d>, <en>;
@ -227,7 +234,8 @@ type of datum at all. The device will transfer the input to the output
whenever <en> is a logic 1.
UDP STATEMENTS:
UDP Statements
--------------
A UDP statement either defines a User Defined Primitive, or
instantiates a previously defined UDP by creating a UDP functor. A
@ -254,6 +262,8 @@ UDPs may also have "-": no change.
An input or current output state can be
::
"1": 1
"0": 0
"x": x
@ -265,6 +275,8 @@ An input or current output state can be
For Sequential UDPs, at most one input state specification may be
replaced by an edge specification. Valid edges are:
::
"*": (??) "_": (?0) "+": (?1) "%": (?x)
"P": (0?) "r": (01) "Q": (0x)
"N": (1?) "f": (10) "M": (1x)
@ -273,13 +285,13 @@ replaced by an edge specification. Valid edges are:
"n": (1?) | (?0)
"p": (0?) | (?1)
A combinatorial UDP is defined like this:
A combinatorial UDP is defined like this::
<type> .udp/comb "<name>", <number>, "<row0>", "<row1>", ... ;
<type> is a label that identifies the UDP. <number> is the number of
inputs. "<name>" is there for public identification. Sequential UDPs
need an additional initialization value:
need an additional initialization value::
<type> .udp/sequ "<name>", <number>, <init>, "<row0>", "<row1>", ... ;
@ -287,7 +299,7 @@ need an additional initialization value:
provide initial values for individual instances. <init> must be a
number 0, 1, or 2 (for 1'bx).
A UDP functor instance is created so:
A UDP functor instance is created so::
<label> .udp <type>, <symbol_list> ;
@ -296,11 +308,12 @@ defined earlier, and <symbol_list> is a list of symbols, one for each
input of the UDP.
VARIABLE STATEMENTS:
Variable Statements
-------------------
A variable is a bit vector that can be written by behavioral code (so
has no structural input) and propagates its output to a functor. The
general syntax of a variable is:
general syntax of a variable is::
<label> .var "name", <msb> <lsb>; Unsigned logic variable
<label> .var/s "name", <msb> <lsb>; Signed logic variable
@ -336,12 +349,13 @@ Behavioral code may also invoke %force/v statements that write to port-2
to invoke force mode. This overrides continuous assign mode until a
long(2) is written to port-3 to disable force mode.
NET STATEMENTS:
Net Statements
--------------
A net is similar to a variable, except that a thread cannot write to
it (unless it uses a force) and it is given a different VPI type
code. The syntax of a .net statement is also similar to but not
exactly the same as the .var statement:
exactly the same as the .var statement::
<label> .net "name", <msb>, <lsb>, <symbol>;
<label> .net/s "name", <msb>, <lsb>, <symbol>;
@ -375,11 +389,12 @@ The .alias statements do not create new nodes, but instead create net
names that are aliases of an existing node. This handles special cases
where a net has different names, possibly in different scopes.
CAST STATEMENTS:
Cast Statements
---------------
Sometimes nets need to be cast from a real valued net to a bit based
net or from a bit based net to a real valued net. These statements
are used to perform that operation:
are used to perform that operation::
<label> .cast/int <width>, <symbol>;
<label> .cast/2 <width>, <symbol>;
@ -394,7 +409,8 @@ For .cast/real the output <label> is a real valued net. The input
<symbol> is expected to put bit based values and for .cast/real.s
the bits will be interpreted as a signed value.
DELAY STATEMENTS:
Delay Statements
----------------
Delay nodes are structural net delay nodes that carry and manage
propagation delays. Delay nodes can have fixed delays or variable
@ -403,6 +419,8 @@ delayed. The delay amount is given on the node line. Variable delay
nodes have three extra inputs to receive the rise, fall and decay
times that are used for delay.
::
.delay <width> ( <rise>, <fall>, <decay> ) <input> ;
.delay <width> <input>, <rise>, <fall>, <decay> ;
@ -412,20 +430,24 @@ inputs, with the first being the value to delay, and the remaining to
be the delay values to use. <width> specifies the bit width of the
input net, with a width of 0 used to identify a real valued net.
MODULE PATH DELAY STATEMENTS:
Module Path Delay Statements
----------------------------
A module path delay takes data from its input, then a list of module
path delays. The <src> for each possible delay set is a trigger that
activates the delay.
::
.modpath <width> <input> , [ <src> (<delays> [? <condition>]) ] ;
<width> specifies the bit width of the input net.
ARRAY INDEX STATEMENTS:
Array Index Statements
----------------------
Variables can be collected into arrays. The words of the array are
declared separately, this statement collects them together:
declared separately, this statement collects them together::
<label> .array "name", <last> <first> ;
@ -436,15 +458,18 @@ The syntax below is different, in that it creates an alias for an
existing array. The dimensions and storage are taken from the .array
at <src>.
::
<label> .array "name", <src> ;
EVENT STATEMENTS
Event Statements
----------------
Threads need to interact with the functors of a netlist synchronously,
as well as asynchronously. There are cases where the web of functors
needs to wake up a waiting thread. The web of functors signals threads
through .event objects, that are declared like so:
through .event objects, that are declared like so::
<label> .event <type>, <symbols_list>;
<label> .event "name";
@ -470,7 +495,7 @@ events of the same edge in an event OR expression, the compiler may
combine up to 4 into a single event.
If many more events need to be combined together (for example due to
an event or expression in the Verilog) then this form can be used:
an event or expression in the Verilog) then this form can be used::
<label> .event/or <symbols_list>;
@ -479,13 +504,16 @@ to trigger this event. Only one of the input events needs to trigger
to make this one go.
RESOLVER STATEMENTS:
Resolver Statements
-------------------
Resolver statements are strength-aware functors with 4 inputs, but
their job typically is to calculate a resolved output using strength
resolution. The type of the functor is used to select a specific
resolution function.
::
<label> .resolv tri, <symbols_list>;
<label> .resolv tri0, <symbols_list>;
<label> .resolv tri1, <symbols_list>;
@ -494,13 +522,16 @@ The output from the resolver is vvp_vector8_t value. That is, the
result is a vector with strength included.
PART SELECT STATEMENTS:
Part Select Statements
----------------------
Part select statements are functors with three inputs. They take in at
port-0 a vector, and output a selected (likely smaller) part of that
vector. The other inputs specify what those parts are, as a canonical
bit number, and a width. Normally, those bits are constant values.
::
<label> .part <symbol>, <base>, <wid>;
<label> .part/pv <symbol>, <base>, <wid>, <vector_wid>;
<label> .part/v <symbol>, <symbol>, <wid>;
@ -520,13 +551,16 @@ The .part/v variation takes a vector (or long) input on port-1 as the
base of the part select. Thus, the part select can move around. The
.part/v.s variation treats the vector as a signed value.
PART CONCATENATION STATEMENTS:
Part Concatenation Statements
-----------------------------
The opposite of the part select statement is the part concatenation
statement. The .concat statement is a functor node that takes at input
vector values and produces a single vector output that is the
concatenation of all the inputs.
::
<label> .concat [W X Y Z], <symbols_list> ;
The "[" and "]" tokens surround a set of 4 numbers that are the
@ -541,11 +575,12 @@ propagated, the bits are placed in the correct place in the output
vector value, and a new output value is propagated.
REPEAT VECTOR STATEMENTS:
Repeat Vector Statements
------------------------
The repeat vector statement is similar to the concatenation statement,
expect that the input is repeated a constant number of times. The
format of the repeat vector statement is:
format of the repeat vector statement is::
<label> .repeat <wid>, <rept count>, <symbol> ;
@ -554,15 +589,16 @@ the *output* vector. The <rept count> is the number of time the input
vector value is repeated to make the output width. The input width is
implicit from these numbers. The <symbol> is then the input source.
SUBSTITUTION STATEMENTS:
Substitution Statements
-----------------------
The substitution statement doesn't have a direct analog in Verilog, it
only turns up in synthesis. It is a shorthand for forms like this:
only turns up in synthesis. It is a shorthand for forms like this::
foo = <a>;
foo[n] = <s>;
The format of the substitute statement is:
The format of the substitute statement is::
<label> .substitute <wid>, <soff> <swid>, <symbol>, <symbol> ;
@ -570,11 +606,14 @@ The first <symbol> must have the width <wid>, and is passed through,
except for the bits within [<soff> +: <swid>]. The second <symbol>
collects a vector that goes into that part.
REDUCTION LOGIC
Reduction Logic
---------------
The reduction logic statements take in a single vector, and propagate
a single bit.
::
<label> .reduce/and <symbol> ;
<label> .reduce/or <symbol> ;
<label> .reduce/xor <symbol> ;
@ -586,22 +625,28 @@ the device has a single input, which is a vector of any width. The
device performs the logic on all the bits of the vector (a la Verilog)
and produces and propagates a single bit width vector.
EXPANSION LOGIC
Expansion Logic
---------------
Sign extension nodes are the opposite of reduction logic, in that they
take a narrow vector, or single bit, and pad it out to a wider
vector.
::
<label> .expand/s <wid>, <symbol> ;
The .expand/s node takes an input symbol and sign-extends it to the
given width.
FORCE STATEMENTS (old method - remove me):
Force Statements (old method - remove me)
-----------------------------------------
A force statement creates functors that represent a Verilog force
statement.
::
<label> .force <signal>, <symbol_list>;
The symbol <signal> represents the signal which is to be forced. The
@ -610,7 +655,7 @@ forced on the <signal>. The <label> identifies the force functors.
There will be as many force functors as there are symbols in the
<symbol_list>.
To activate and deactivate a force on a single bit, use:
To activate and deactivate a force on a single bit, use::
%force <label>, <width>;
%release <signal>;
@ -619,13 +664,14 @@ To activate and deactivate a force on a single bit, use:
<signal> is the label of the functor that drives the signal that is
being forced.
FORCE STATEMENTS (new method - implement me):
Force Statements (new method - implement me)
--------------------------------------------
A %force instruction, as described in the .var section, forces a
constant value onto a .var or .net, and the matching %release releases
that value. However, there are times when the value of a functor
(i.e. another .net) needs to be forced onto a .var or .net. For this
task, the %force/link instruction exists:
task, the %force/link instruction exists::
%force/link <dst>, <src> ;
%release/link <dst> ;
@ -638,20 +684,23 @@ node. The matching %release/link instruction removes the link (a
releases the last %force/link, no matter where the link is from. A new
%force/link will remove a previous link.
The instructions:
The instructions::
%cassign/link <dst>, <src> ;
%deassign/link <dst> ;
are the same concept, but for the continuous assign port.
STRUCTURAL ARITHMETIC STATEMENTS:
Structural Arithmetic Statements
--------------------------------
The various Verilog arithmetic operators (+-*/%) are available to
The various Verilog arithmetic operators (`+-*/%`) are available to
structural contexts as two-input functors that take in vectors. All of
these operators take two inputs and generate a fixed width output. The
input vectors will be padded if needed to get the desired output width.
::
<label> .arith/sub <wid>, <A>, <B>;
<label> .arith/sum <wid>, <A>, <B>;
<label> .arith/mult <wid>, <A>, <B>;
@ -667,12 +716,13 @@ output. I have not decided how to handle this.
These devices support .s and .r suffixes. The .s means the node is a
signed vector device, the .r a real valued device.
STRUCTURAL COMPARE STATEMENTS:
Structural Compare Statements
-----------------------------
The arithmetic statements handle various arithmetic operators that
have wide outputs, but the comparators have single bit output, so they
are implemented a bit differently. The syntax, however, is very
similar:
similar::
<label> .cmp/eeq <wid>, <A>, <B>;
<label> .cmp/nee <wid>, <A>, <B>;
@ -691,10 +741,11 @@ versions do unsigned comparison, but the ".s" versions to signed
comparisons. (Equality doesn't need to care about sign.)
STRUCTURAL SHIFTER STATEMENTS:
Structural Shifter Statements
-----------------------------
Variable shifts in structural context are implemented with .shift
statements:
statements::
<label> .shift/l <wid>, <data symbol>, <shift symbol>;
<label> .shift/r <wid>, <data symbol>, <shift symbol>;
@ -706,10 +757,13 @@ data to be shifted and must have exactly the width of the output. The
input to port 1 is the amount to shift.
STRUCTURAL FUNCTION CALLS:
Structural Function Calls
-------------------------
The .ufunc statements define a call to a user defined function.
::
<label> .ufunc/real <flabel>, <wid>,
<isymbols> ( <psymbols> ) <ssymbol>;
@ -742,12 +796,15 @@ before calling the function.
The <ssymbol> is the function scope name.
THREAD STATEMENTS:
Thread Statements
-----------------
Thread statements create the initial threads for a simulation. These
represent the initial and always blocks, and possibly other causes to
create threads at startup.
::
.thread <symbol> [, <flag>]
This statement creates a thread with a starting address at the
@ -756,7 +813,7 @@ created for the .thread statement, and it starts at the <symbol>
addressed instruction.
The <flag> modifies the creation/execution behavior of the
thread. Supported flags are:
thread. Supported flags are::
$push -- Cause the thread to be pushed in the scheduler. This
only effects startup (time 0) by arranging for pushed
@ -766,7 +823,7 @@ thread. Supported flags are:
* Threads in general
Thread statements create the initial threads of a design. These
include the ``initial'' and ``always'' statements of the original
include the `initial` and `always` statements of the original
Verilog, and possibly some other synthetic threads for various
purposes. It is also possible to create transient threads from
behavioral code. These are needed to support such constructs as
@ -815,7 +872,7 @@ words have a distinct address space from the bits.
* Threads and scopes
The Verilog ``disable'' statement deserves some special mention
The Verilog `disable` statement deserves some special mention
because of how it interacts with threads. In particular, threads
throughout the design can affect (end) other threads in the design
using the disable statement.
@ -838,10 +895,11 @@ by the fork atomically joins that scope. Once the transient thread
joins the scope, it stays there until it ends. Threads never change
scopes, not even transient threads.
VPI TASK/FUNCTION CALLS
Vpi Task/Function Calls
-----------------------
Threads call vpi tasks with the %vpi_call or %vpi_func
instructions. The formats are:
instructions. The formats are::
%vpi_call <file-index> <lineno> <name>, <args>... ;
%vpi_call/w <file-index> <lineno> <name>, <args>... ;
@ -870,7 +928,7 @@ value returned by a system function called as a task.
* The &A<> argument
The &A<> argument is a reference to the word of a variable array. The
syntax is:
syntax is::
&A '<' <symbol> , <number> '>'
&A '<' <symbol> , <base_symbol> '>'
@ -884,7 +942,7 @@ starting at <base>). The base value may be signed or unsigned.
* The &PV<> argument
The &PV<> argument is a reference to part of a signal. The syntax is:
The &PV<> argument is a reference to part of a signal. The syntax is::
&PV '<' <symbol> , <base> , <width> '>'
&PV '<' <symbol> , <base_symbol> , <width> '>'
@ -897,7 +955,8 @@ or &A<>/&PV<> select. The third form retrieves the <base> from thread
space using <twid> bits starting at <tbase>. The base value may be
signed or unsigned.
TRUTH TABLES
Truth Tables
------------
The logic that a functor represents is expressed as a truth table. The
functor has four inputs and one output. Each input and output has one
@ -910,7 +969,7 @@ implement the logic.
To implement the truth table, we need to assign 2-bit encodings for
the 4-value signals. I choose, pseudo-randomly, the following
encoding:
encoding::
1'b0 : 00
1'b1 : 01
@ -919,11 +978,12 @@ encoding:
The table is an array of 64 bytes, each byte holding 4 2-bit
outputs. Construct a 6-bit byte address with inputs 1, 2 and 3 like
so:
so::
332211
The input 0 2-bits can then be used to select which of the 4 2-bit
pairs in the 8-bit byte are the output:
pairs in the 8-bit byte are the output::
MSB -> zzxx1100 <- LSB
@ -934,7 +994,8 @@ none needs to be given by the programmer. It is sufficient to name the
type to get that truth table.
EXECUTABLE INSTRUCTIONS
Executable Instructions
-----------------------
Threads run executable code, much like a processor executes machine
code. VVP has a variety of opcodes for executable instructions. All of
@ -947,7 +1008,8 @@ The opcodes.txt file has a more detailed description of all the
various instructions.
THE RELATIONSHIP BETWEEN FUNCTORS, THREADS AND EVENTS
The Relationship Between Functors, Threads And Events
-----------------------------------------------------
Given the above summary of the major components of vvp, some
description of their relationship is warranted. Functors provide a
@ -966,7 +1028,7 @@ it is connected to, and those functors in turn create new events if
needed.
Assignment events (the second of three types of events) are created
by non-blocking assignments in behavioral code. When the ``<='' is
by non-blocking assignments in behavioral code. When the `<=` is
executed (a %assign in vvp) an assign event is created, which includes
the vvp_ipoint_t pointer to the functor input to receive the value,
as well as the value. These are distinct from propagation events because:
@ -991,7 +1053,7 @@ the right kind of code to cause things to happen in the design. If the
event is a propagate or assignment event, the network of functors is
tickled; if the event is a thread schedule, then a thread is run. The
implementation of the event queue is not important, but currently is
implemented as a ``skip list''. That is, it is a sorted singly linked
implemented as a `skip list`. That is, it is a sorted singly linked
list with skip pointers that skip over delta-time events.
The functor net and the threads are distinct. They communicate through
@ -1000,7 +1062,8 @@ is concerned, the functor net is a blob of structure that it pokes and
prods via certain functor access instructions.
VVP COMPILATION AND EXECUTION
VVP Compilation And Execution
-----------------------------
The vvp program operates in a few steps:
@ -1023,7 +1086,7 @@ The vvp program operates in a few steps:
The initialization step is performed by the compile_init() function in
compile.cc. This function in turn calls all the *_init() functions in
compile.cc. This function in turn calls all the \*_init() functions in
other parts of the source that need initialization for compile. All
the various sub-init functions are called <foo>_init().
@ -1044,7 +1107,8 @@ the schedule_simulate() function. This does any final setup and starts
the simulation running and the event queue running.
HOW TO GET FROM THERE TO HERE
How To Get From There To Here
-----------------------------
The vvp simulation engine is designed to be able to take as input a
compiled form of Verilog. That implies that there is a compiler that
@ -1055,22 +1119,22 @@ compiles Verilog into a form that the vvp engine can read.
Gates like AND, OR and NAND are implemented simply and obviously by
functor statements. Any logic up to 4 inputs can be implemented with a
single functor. For example:
single functor. For example::
and gate (out, i1, i2, i3);
becomes:
becomes::
gate .functor and, i1, i2, i3;
Notice the first parameter of the .functor is the type. The type
includes a truth table that describes the output with a given
input. If the gate is wider than four inputs, then cascade
functors. For example:
functors. For example::
and gate (out, i1, i2, i3, i4, i5, i6, i7, i8);
becomes:
becomes::
gate.0 .functor and, i1, i2, i3, i4;
gate.1 .functor and, i5, i6, i7, i8;
@ -1079,16 +1143,16 @@ becomes:
* reg and other variables
Reg and integer are cases of what Verilog calls ``variables.''
Reg and integer are cases of what Verilog calls `variables`.
Variables are, simply put, things that behavioral code can assign
to. These are not the same as ``nets,'' which include wires and the
to. These are not the same as `nets`, which include wires and the
like.
Each bit of a variable is created by a ``.var'' statement. For example:
Each bit of a variable is created by a `.var` statement. For example::
reg a;
becomes:
becomes::
a .var "a", 0, 0;
@ -1097,16 +1161,17 @@ becomes:
Events in general are implemented as functors, but named events in
particular have no inputs and only the event output. The way to
generate code for these is like so:
generate code for these is like so::
a .event "name";
This creates a functor and makes it into a mode-2 functor. Then the
trigger statement, "-> a", cause a ``%set a, 0;'' statement be
trigger statement, "-> a", cause a `%set a, 0;` statement be
generated. This is sufficient to trigger the event.
AUTOMATICALLY ALLOCATED SCOPES
Automatically Allocated Scopes
------------------------------
If a .scope statement has a <type> of autofunction or autotask, the
scope is flagged as being an automatically allocated scope. The functor
@ -1159,21 +1224,23 @@ variable or event, the associated functor indirects through the
current read or write context of the running thread, using its
stored context index.
/*
* Copyright (c) 2001-2009 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.
*/
::
/*
* Copyright (c) 2001-2009 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.
*/

3
Documentation/developer/index.rst
View File

@ -11,4 +11,5 @@ Icarus Verilog.
getting_started
regression_tests
version_stamps
guide/index
glossary

5
Documentation/usage/index.rst
View File

@ -14,9 +14,10 @@ Icarus Verilog.
command_line_flags
command_files
verilog_attributes
ivlpp_flags
vvp_flags
gtkwave
vvp_debug
vhdlpp_flags
gtkwave
vpi
ivl_target
reporting_issues

31
Documentation/usage/installation.rst
View File

@ -144,3 +144,34 @@ be updated to version 3. ::
Icarus Verilog is also available through the Homebrew package manager: "brew
install icarus-verilog".
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.
There is also a MSYS2 build recipe which you can find under `msys2/` in the repository.

92
ivlpp/ivlpp.txt → Documentation/usage/ivlpp_flags.rst
View File

@ -1,23 +1,6 @@
Copyright (c) 1999 Stephen Williams (steve@icarus.com)
This source code is free software; you can redistribute it
and/or modify it in source code form under the terms of the GNU
General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option)
any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
THE IVL PREPROCESSOR
IVLPP - IVL Preprocessor
========================
The ivlpp command is a Verilog preprocessor that handles file
inclusion and macro substitution. The program runs separate from the
@ -33,49 +16,58 @@ 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
* -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
This option does *not* override existing \`define
directives in the source file.
-F <path>
* -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>
* -f <path>
Read ivlpp input files from a file list. There can be no
more than one file list.
-I <dir>
* -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
* -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>
* -o <file>
Send the output to the named file, instead of to standard
output.
-v
* -v
Print version and copyright information before processing
input files.
-V
* -V
Print version and copyright information, then exit WITHOUT
processing any input files.
FLAGS FILE
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.
@ -84,44 +76,50 @@ 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:
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>
* D:name=<value>
This is exactly the same as the "-Dname=<value>" described above.
I:<dir>
* I:<dir>
This is exactly the same as "-I<dir>".
relative include:<flag>
* relative include:<flag>
The <flag> can be "true" or "false". This enables "relative
includes" nesting behavior.
vhdlpp:<path>
* vhdlpp:<path>
Give the path to the vhdlpp program. This program is used to
process VHDL input files.
LOCATING INCLUDED FILES
Locating Included Files
-----------------------
The ivlpp preprocessor implements the `include directives by
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
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
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''
starts with the '/' character. These file names are `rooted names`
and must be in the rooted location specified.
GENERATED LINE DIRECTIVES
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
@ -130,19 +128,19 @@ 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:
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:
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
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.

39
Documentation/usage/reporting_issues.rst
View File

@ -7,6 +7,11 @@ 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
@ -15,12 +20,25 @@ 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,
@ -35,3 +53,24 @@ 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-2018 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.

27
vhdlpp/README.txt → Documentation/usage/vhdlpp_flags.rst
View File

@ -1,34 +1,41 @@
vhdlpp COMMAND LINE FLAGS:
vhdlpp Command Line Flags
=========================
* -D <token>
-D <token>
Debug flags. The token can be:
* yydebug | no-yydebug
* entities=<path>
-L <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
* -V
Display version on stdout
-v
* -v
Verbose: Display version on stderr, and enable verbose messages to
stderr.
-w <path>
* -w <path>
Work path. This is the directory where the working directory is.
LIBRARY FORMAT:
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:
are packages in files named <foo>.pkg. For example::
<directory>/...
sample/...
@ -39,14 +46,14 @@ are packages in files named <foo>.pkg. For example:
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:
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 \*.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.

2
Documentation/usage/vvp_debug.rst
View File

@ -1,4 +1,4 @@
Vvp Interactive Mode
VVP Interactive Mode
====================
The vvp command has an interactive debug mode, where you can stop the

83
QUICK_START.txt
View File

@ -1,83 +0,0 @@
* Getting Started with Icarus Verilog
Icarus Verilog is a Verilog compiler. It is suitable for use as a
simulator, and, to some degree, synthesizer. Icarus Verilog runs under
Linux and a variety of UNIX systems, as well as Windows as a command
line tool, so the instructions are generally applicable to all
environments. Note that this is only a quick start. For more detailed
documentation, see the manual page for the iverilog command.
* Hello, World!
The first thing you want to do as a user 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:
module main;
initial
begin
$display("Hello, World");
$finish ;
end
endmodule
By a text editor (or copy hello.vl from the Icarus Verilog examples
directory) arrange for this program to be in a text file, "hello.vl".
Next, compile this program with a command like this:
% iverilog -o hello hello.vl
The results of this compile are placed into the file "hello", as 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 form is the VVP
format, which is actually run by the "vvp" command.
The "iverilog" and "vvp" commands are the only commands that users
use to invoke Icarus Verilog. What the compiler actually does is
controlled by command line switches. In our little example, we asked
the compiler to compile the source program to the default vvp form,
which is in turn executed by the vvp program.
* Windows Install
The easiest way to install under Windows is to get a precompiled
installer for the version you wish to install. Icarus Verilog is
distributed for Windows users as a self-installing .exe. Just execute
the installer and follow the instructions. During the install, take
note of the directory where the program is installed: for example,
C:\iverilog is a good place to install.
Once the binary is installed, you need to add the bin directory to
your execution path. The executables you need are in C:\iverilog\bin,
where the "C:\iverilog" part is actually the root of where you
installed the package. The programs are in the bin subdirectory. Put
this directory in your PATH environment variable, and the above
commands become accessible to you at the command line prompt, or even
in batch files.
* Linux Install
Under Linux, the install is even easier. For RedHat and Mandrake based
systems, there is the appropriate RPM file. Just install the package
with the "rpm -U <file>" command. Debian users should get Icarus
Verilog packages from the main Debian software site.
* Install From Source
In this case, see README.txt and other documentation that comes with
the source.

35
cygwin.txt
View File

@ -1,35 +0,0 @@
This file describes the build procedure under cygwin32 (Windows 95/98/NT/2K)
----------------------------------------------------------------------------
Note: Icarus Verilog also compiles to native Windows binaries if you
use the instructions in the mingw.txt file. Some people prefer cygwin
binaries, and these instructions apply.
To build using cygwin:
Prerequisites:
o Latest net release (1.1.4) of cygwin (sources.redhat.com/cygwin)
Procedure:
o Get the source code - see the main Icarus Verilog page for how to
do this
o cd to the verilog directory
o autoconf.sh
o ./configure
o make
o make install
That's all that's needed.
To build your own extensions - just include vpi_user.h and link with
a command like this:
$(CC) -shared -o <dllname> <objects> -Wl,--enable-auto-image-base -L../vvm -lvvm -lvpip
- Venkat Iyer <venkat@comit.com>

39
ivl_target.txt
View File

@ -1,39 +0,0 @@
Icarus Verilog LOADABLE TARGET API (ivl_target)
Copyright 2002 Stephen Williams <steve@icarus.com>
The ivl_target API is the interface available to modules that the
Icarus Verilog compiler loads to act as a code generator. The API
provides an interface to the elaborated, possibly synthesized, design
for code generators that are intended to write netlist files or
executable programs.
The functions and types of the API are summarized in the ivl_target.h
header file. This document describes how the functions and types of
the API are used to access and interpret the netlist of the design.
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().

27
mingw-cross.txt
View File

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

5
mingw.txt
View File

@ -1,5 +0,0 @@
Please see the following references for instruction on building and installing
Icarus Verilog as a native Windows application using the MinGW tools:
* README.md in subdir 'msys2'
* Icarus Verilog Wiki: http://iverilog.wikia.com/wiki/Installation_Guide#Compiling_on_MS_Windows_.28MinGW.29

44
tgt-blif/README-BLIF.txt
View File

@ -1,44 +0,0 @@
BLIF TARGET
-----------
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.

187
tgt-fpga/fpga.txt
View File

@ -1,187 +0,0 @@
FPGA LOADABLE CODE GENERATOR FOR Icarus Verilog
Copyright 2001 Stephen Williams
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:
module main(out, in);
output out;
input [2:0] in;
[...]
endmodule
leads to these SIG, records:
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:
module main(out, in);
output out;
input [2:0] in;
[...]
endmodule
creates these ports:
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:
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

96
xilinx-hint.txt
View File

@ -1,96 +0,0 @@
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