diff --git a/BUGS.txt b/BUGS.txt deleted file mode 100644 index 3d201b240..000000000 --- a/BUGS.txt +++ /dev/null @@ -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 '' 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 for examples of good test -programs. - -RESEARCHING EXISTING/PAST BUGS, AND FILING REPORTS - -The URL is the main -bug tracking system, although some users have reported bugs at -. 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 -- . - -When you make a patch, submit it to the "Patches" tracker at -. 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. diff --git a/Documentation/conf.py b/Documentation/conf.py index 783b083ca..46f8f45a3 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -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'), -] \ No newline at end of file +] diff --git a/glossary.txt b/Documentation/developer/glossary.rst similarity index 68% rename from glossary.txt rename to Documentation/developer/glossary.rst index 3e2b3b43d..4bbf64814 100644 --- a/glossary.txt +++ b/Documentation/developer/glossary.rst @@ -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. diff --git a/cadpli/cadpli.txt b/Documentation/developer/guide/cadpli/cadpli.rst similarity index 94% rename from cadpli/cadpli.txt rename to Documentation/developer/guide/cadpli/cadpli.rst index a2381b809..c08b617a7 100644 --- a/cadpli/cadpli.txt +++ b/Documentation/developer/guide/cadpli/cadpli.rst @@ -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 diff --git a/developer-quick-start.txt b/Documentation/developer/guide/index.rst similarity index 83% rename from developer-quick-start.txt rename to Documentation/developer/guide/index.rst index 33506b62c..677c35110 100644 --- a/developer-quick-start.txt +++ b/Documentation/developer/guide/index.rst @@ -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 -. 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 diff --git a/attributes.txt b/Documentation/developer/guide/ivl/attributes.rst similarity index 86% rename from attributes.txt rename to Documentation/developer/guide/ivl/attributes.rst index ed8280196..48fb143e7 100644 --- a/attributes.txt +++ b/Documentation/developer/guide/ivl/attributes.rst @@ -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 = "" \*) 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 diff --git a/Documentation/developer/guide/ivl/index.rst b/Documentation/developer/guide/ivl/index.rst new file mode 100644 index 000000000..c581fed5a --- /dev/null +++ b/Documentation/developer/guide/ivl/index.rst @@ -0,0 +1,12 @@ + +IVL - The Core Compiler +======================= + +.. toctree:: + :maxdepth: 1 + + netlist + attributes + ivl_target + lpm + t-dll diff --git a/Documentation/usage/ivl_target.rst b/Documentation/developer/guide/ivl/ivl_target.rst similarity index 81% rename from Documentation/usage/ivl_target.rst rename to Documentation/developer/guide/ivl/ivl_target.rst index 192e00e9b..6deacd901 100644 --- a/Documentation/usage/ivl_target.rst +++ b/Documentation/developer/guide/ivl/ivl_target.rst @@ -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(). diff --git a/lpm.txt b/Documentation/developer/guide/ivl/lpm.rst similarity index 89% rename from lpm.txt rename to Documentation/developer/guide/ivl/lpm.rst index f475d2402..0774be457 100644 --- a/lpm.txt +++ b/Documentation/developer/guide/ivl/lpm.rst @@ -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. diff --git a/netlist.txt b/Documentation/developer/guide/ivl/netlist.rst similarity index 85% rename from netlist.txt rename to Documentation/developer/guide/ivl/netlist.rst index 2c4dd800a..0baaea0d6 100644 --- a/netlist.txt +++ b/Documentation/developer/guide/ivl/netlist.rst @@ -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 diff --git a/t-dll.txt b/Documentation/developer/guide/ivl/t-dll.rst similarity index 88% rename from t-dll.txt rename to Documentation/developer/guide/ivl/t-dll.rst index 1f8c17378..fa446614a 100644 --- a/t-dll.txt +++ b/Documentation/developer/guide/ivl/t-dll.rst @@ -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=". -COMPILING TARGET MODULES +Compiling Target Modules +------------------------ -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 diff --git a/extensions.txt b/Documentation/developer/guide/misc/extensions.rst similarity index 96% rename from extensions.txt rename to Documentation/developer/guide/misc/extensions.rst index cf0a985ea..7352a70c5 100644 --- a/extensions.txt +++ b/Documentation/developer/guide/misc/extensions.rst @@ -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 ... ; The , 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]; diff --git a/ieee1364-notes.txt b/Documentation/developer/guide/misc/ieee1364-notes.rst similarity index 92% rename from ieee1364-notes.txt rename to Documentation/developer/guide/misc/ieee1364-notes.rst index 17e1751a0..39785298c 100644 --- a/ieee1364-notes.txt +++ b/Documentation/developer/guide/misc/ieee1364-notes.rst @@ -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) ; 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 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 = ; @@ -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 ! diff --git a/Documentation/developer/guide/misc/index.rst b/Documentation/developer/guide/misc/index.rst new file mode 100644 index 000000000..5bc9aae35 --- /dev/null +++ b/Documentation/developer/guide/misc/index.rst @@ -0,0 +1,11 @@ + +Miscellaneous +============= + +.. toctree:: + :maxdepth: 1 + + extensions + ieee1364-notes + swift + xilinx-hint diff --git a/swift.txt b/Documentation/developer/guide/misc/swift.rst similarity index 94% rename from swift.txt rename to Documentation/developer/guide/misc/swift.rst index e4b0ad8a7..95191f72f 100644 --- a/swift.txt +++ b/Documentation/developer/guide/misc/swift.rst @@ -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 diff --git a/Documentation/developer/guide/misc/xilinx-hint.rst b/Documentation/developer/guide/misc/xilinx-hint.rst new file mode 100644 index 000000000..9cb7dfcc8 --- /dev/null +++ b/Documentation/developer/guide/misc/xilinx-hint.rst @@ -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=, 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 August 19, 1999 + updated February 1, 2000 diff --git a/tgt-vvp/README.txt b/Documentation/developer/guide/tgt-vvp/tgt-vvp.rst similarity index 86% rename from tgt-vvp/README.txt rename to Documentation/developer/guide/tgt-vvp/tgt-vvp.rst index f07323021..bc2b863ab 100644 --- a/tgt-vvp/README.txt +++ b/Documentation/developer/guide/tgt-vvp/tgt-vvp.rst @@ -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 diff --git a/Documentation/developer/guide/vpi/index.rst b/Documentation/developer/guide/vpi/index.rst new file mode 100644 index 000000000..77a0754c4 --- /dev/null +++ b/Documentation/developer/guide/vpi/index.rst @@ -0,0 +1,9 @@ + +VPI in Icarus Verilog +===================== + +.. toctree:: + :maxdepth: 1 + + vpi + va_math diff --git a/va_math.txt b/Documentation/developer/guide/vpi/va_math.rst similarity index 85% rename from va_math.txt rename to Documentation/developer/guide/vpi/va_math.rst index b5cb3e6b1..b671b1dea 100644 --- a/va_math.txt +++ b/Documentation/developer/guide/vpi/va_math.rst @@ -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. --------- diff --git a/vpi.txt b/Documentation/developer/guide/vpi/vpi.rst similarity index 87% rename from vpi.txt rename to Documentation/developer/guide/vpi/vpi.rst index d19a2f28a..65aa06a37 100644 --- a/vpi.txt +++ b/Documentation/developer/guide/vpi/vpi.rst @@ -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 diff --git a/vvp/debug.txt b/Documentation/developer/guide/vvp/debug.rst similarity index 84% rename from vvp/debug.txt rename to Documentation/developer/guide/vvp/debug.rst index d2729789a..bef2f6829 100644 --- a/vvp/debug.txt +++ b/Documentation/developer/guide/vvp/debug.rst @@ -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$