diff --git a/Documentation/.gitignore b/Documentation/.gitignore new file mode 100644 index 000000000..69fa449dd --- /dev/null +++ b/Documentation/.gitignore @@ -0,0 +1 @@ +_build/ diff --git a/Documentation/conf.py b/Documentation/conf.py new file mode 100644 index 000000000..783b083ca --- /dev/null +++ b/Documentation/conf.py @@ -0,0 +1,155 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'Icarus Verilog' +copyright = '2022, Stephen Williams' +author = 'Stephen Williams' + +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path . +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'IcarusVerilogdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'IcarusVerilog.tex', 'Icarus Verilog Documentation', + 'Stephen Williams', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'icarusverilog', 'Icarus Verilog Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +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/Documentation/developer/index.rst b/Documentation/developer/index.rst new file mode 100644 index 000000000..a30d2b7ff --- /dev/null +++ b/Documentation/developer/index.rst @@ -0,0 +1,12 @@ + +Icarus Verilog Developer Support +================================ + +This section contains documents to help support developers who contribute to +Icarus Verilog. + +.. toctree:: + :maxdepth: 1 + + version_stamps + diff --git a/Documentation/developer/version_stamps.rst b/Documentation/developer/version_stamps.rst new file mode 100644 index 000000000..c5edff394 --- /dev/null +++ b/Documentation/developer/version_stamps.rst @@ -0,0 +1,29 @@ + +Files With Version Information +============================= + +These are the only files that have version information in them: + +* version_base.h -- This should be the 1 source for version info. +* version_tag.h -- Generated automatically with git tag information. +* verilog.spec -- Used to stamp RPM packages + +When versions are changed, the above files need to be edited to account for +the new version information. The following used to have verion information in +them, but now their version information is generated: + +Replaced with version_base.h, which is edited manually, and +version_tag.h which is generated from git tag information. + +* version-base.in -- Most compiled code gets version from here + +These are now edited by the makefile and the version.exe program. + +* iverilog-vpi.man -- The .TH tag has a version string +* driver/iverilog.man -- The .TH tag has a version string +* driver-vpi/res.rc -- Used to build Windows version stamp +* vvp/vvp.man -- The .TH tag has a version string + +This now includes version_base.h to get the version + +* vpi/vams_simparam.c -- Hard coded result to simulatorVersion query diff --git a/Documentation/index.rst b/Documentation/index.rst new file mode 100644 index 000000000..0a135f95e --- /dev/null +++ b/Documentation/index.rst @@ -0,0 +1,25 @@ +.. Icarus Verilog documentation master file, created by + sphinx-quickstart on Sun Apr 10 16:28:38 2022. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Icarus Verilog +============== + +Welcome to the documentation for Icarus Verilog. + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + usage/index + targets/index + developer/index + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/Documentation/make.bat b/Documentation/make.bat new file mode 100644 index 000000000..ea5874b52 --- /dev/null +++ b/Documentation/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build +set SPHINXPROJ=IcarusVerilog + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/Documentation/targets/index.rst b/Documentation/targets/index.rst new file mode 100644 index 000000000..6e8bbbe4f --- /dev/null +++ b/Documentation/targets/index.rst @@ -0,0 +1,16 @@ + +The Icarus Verilog Targets +========================== + +Icarus Verilog elaborates the design, then sends to the design to code +generates (targets) for processing. new code generators can be added by +external packages, but these are the code generators that are bundled with +Icarus Verilog. The code generator is selected by the "-t" command line flag. + +.. toctree:: + :maxdepth: 1 + + vvp + stub + null + diff --git a/Documentation/targets/null.rst b/Documentation/targets/null.rst new file mode 100644 index 000000000..8af3cbbbb --- /dev/null +++ b/Documentation/targets/null.rst @@ -0,0 +1,7 @@ + +The null Code Generator (-tnull) +================================ + +The null target generates no code. Invoking this code generator causes no code +generation to happen. + diff --git a/Documentation/targets/stub.rst b/Documentation/targets/stub.rst new file mode 100644 index 000000000..95688fc33 --- /dev/null +++ b/Documentation/targets/stub.rst @@ -0,0 +1,7 @@ + +The stub Code Generator (-tstub) +============================== + +The stub code generator is a debugging aid for the Icarus Verilog compiler +itself. It outputs a text dump of the elaborated design as it is passed to +code generators. diff --git a/Documentation/targets/vvp.rst b/Documentation/targets/vvp.rst new file mode 100644 index 000000000..983df3d06 --- /dev/null +++ b/Documentation/targets/vvp.rst @@ -0,0 +1,6 @@ + +The vvp Code Generator (-tvvp) +============================== + +The vvp target generates code for the "vvp" run time. This is the most +commonly used target for Icarus Verilog, as it is the main simulation engine. diff --git a/Documentation/usage/command_line_flags.rst b/Documentation/usage/command_line_flags.rst new file mode 100644 index 000000000..4d8028dcc --- /dev/null +++ b/Documentation/usage/command_line_flags.rst @@ -0,0 +1,439 @@ + + +iverilog Command Line Flags +=========================== + +The iverilog command is the compiler/driver that takes the Verilog input and +generates the output format, whether the simulation file or synthesis +results. This information is at least summarized in the iverilog man page +distributed in typical installations, but here we try to include more detail. + +General +------- + +These flags affect the general behavior of the compiler. + +* -c + + This flag selects the command file to use. The command file is an + alternative to writing a long command line with a lot of file names and + compiler flags. See the Command File Format page for more information. + +* -d + + Enable compiler debug output. These are aids for debugging Icarus Verilog, + and this flag is not commonly used. + The flag is one of these debug classes: + + * scope + * eval_tree + * elaborate + * synth2 + +* -g + the generation is the compiler language, and specifies the language and + extensions to use during the compile. The language level can be selected + by a major level selector, and by controlling various features. Various + "-g" flags can be compined. For example, to get Verilog 2001 without + specify supoprt, use "-g2001 -gno-specify". + + The supported flags are: + + * 1995 + + This flag enables the IEEE1364-1995 standard. + + * 2001 + + This flag enables the IEEE1364-2001 standard. + + * 2001-noconfig + + This flag enables the IEEE1364-2001 standard with config file support + disabled. This eliminates the config file keywords from the language and + so helps some programs written to older 2001 support compile. + + * 2005 + This flag enables the IEEE1364-2005 standard. This is default enabled + after v0.9. + + * 2009 + This flag enables the IEEE1800-2009 standard, which includes + SystemVerilog. The SystemVerilog support is not present in v0.9 and + earlier. It is new to git master as of November 2009. Actual SystemVerilog + support is ongoing. + + * 2012 + + This flag enables the IEEE1800-2012 standard, which includes + SystemVerilog. + + * verilog-ams + + This flag enables Verilog-AMS features that are supported by Icarus + Verilog. (This is new as of 5 May 2008.) + + * assertions/supported-assertions/no-assertions + + Enable or disable SystemVerilog assertions. When enabled, assertion + statements are elaborated. When disabled, assertion statements are parsed + but ignored. The supported-assertions option only enables assertions that + are currently supported by the compiler. + + * specify/no-specify + + Enable or disable support for specify block timing controls. When + disabled, specify blocks are parsed but ignored. When enabled, specify + blocks cause timing path and timing checks to be active. + + * std-include/no-std-include + + Enable or disable the search of a standard installation include directory + after all other explicit include directories. This standard include + directory is a convenient place to install standard header files that a + Verilog program may include. + + * relative-include/no-relative-include + + Enable or disable adding the local files directory to the beginning of the + include file search path. This allows files to be included relative to the + current file. + + * xtypes/no-xtypes + + Enable or disable support for extended types. Enabling types allows for + new types and type syntax that are Icarus Verilog extensions. + + * io-range-error/no-io-range-error + + When enabled the range for a port and any associated net declaration must + match exactly. When disabled a scalar port is allowed to have a net + declaration with a range (obsolete usage). A warning message will be + printed for this combination. All other permutations are still considered + an error. + + * strict-ca-eval/no-strict-ca-eval + + The standard requires that if any input to a continuous assignment + expression changes value, the entire expression is re-evaluated. By + default, parts of the expression that do not depend on the changed input + value(s) are not re-evaluated. If an expression contains a call to a + function that doesn't depend solely on its input values or that has side + effects, the resulting behavior will differ from that required by the + standard. Enabling strict-ca-eval will force standard compliant behavior + (with some loss in performance). + + * strict-expr-width/no-strict-expr-width + + Enable or disable strict compliance with the standard rules for + determining expression bit lengths. When disabled, the RHS of a parameter + assignment is evaluated as a lossless expression, as is any expression + containing an unsized constant number, and unsized constant numbers are + not truncated to integer width. + + * shared-loop-index/no-shared-loop-index + + Enable or disable the exclusion of for-loop control variables from + implicit event_expression lists. When enabled, if a for-loop control + variable (loop index) is only used inside the for-loop statement, the + compiler will not include it in an implicit event_expression list it + calculates for that statement or any enclosing statement. This allows the + same control variable to be used in multiple processes without risk of + entering an infinite loop caused by each process triggering all other + processes that use the same variable. For strict compliance with the + standards, this behaviour should be disabled. + +* -i + + Ignore missing modules. Normally it is an error if a module instantiation + refers to an undefined module. This option causes the compiler to skip over + that instantiation. It will also stop the compiler returning an error if + there are no top level modules. This allows the compiler to be used to check + incomplete designs for errors. + + NOTE: The "-i" flag was added in v11.0. + +* -L + + Add the specified directory to the path list used to locate VPI modules. The + default path includes only the install directory for the system.vpi module, + but this flag can add other directories. Multiple paths are allowed, and the + paths will be searched in order. + + NOTE: The "-L" flag was added in v11.0. + +* -l + + Add the specified file to the list of source files to be compiled, but mark + it as a library file. All modules contained within that file will be treated + as library modules, and only elaborated if they are instantiated by other + modules in the design. + + NOTE: The "-l" flag is new as of 2 October 2016. It will become available in + releases and snapshots made after that date. + +* -M= + + Write into the file specified by path a list of files that contribute to the + compilation of the design. + + If _mode_ is *all* or *prefix*, this includes files that are included by + include directives and files that are automatically loaded by library + support as well as the files explicitly specified by the user. + + If _mode_ is *include*, only files that are included by include directives + are listed. + + If _mode_ is *module*, only files that are specified by the user or that are + automatically loaded by library support are listed. The output is one file + name per line, with no leading or trailing space. + + If _mode_ is *prefix*, files that are included by include directives are + prefixed by "I " and other files are prefixed by "M ". + +* -m + + Add this module to the list of VPI modules to be loaded by the + simulation. Many modules can be specified, and all will be loaded, in the + order specified. The system module is implicit and always included (and + loaded last). + + If the specified name includes at least one directory character, it is + assumed to be prefixed by the path to the module, otherwise the module is + searched for in the paths specified by preceding -L options, and if not + found there, in the iverilog base directory. + + NOTE: The "-m" flag was added in v11.0. + +* -o + + Specify the output file. The is the name of the file to hold the + output. The default is "a.out". + +* -S + + Activate synthesis. This flag tells the compiler to do what synthesis it can + do before calling the code generator. This flag is rarely used explicitly, + and certain code generators will implicitly enable this flag. + +* -u + + Treat each source file as a separate compilation unit (as defined in + SystemVerilog). If compiling for an IEEE1364 generation, this will just + reset all compiler directives (including macro definitions) before each new + file is processed. + + NOTE: The "-u" flag was added in v11.0. + +* -v + + Be verbose. Print copyright information, progress messages, and some timing + information about various compilation phases. + + (New in snapshots after 2014-12-16) If the selected target is vvp, the -v + switch is appended to the shebang line in the compiler output file, so + directly executing the compiler output file will turn on verbose messages in + vvp. This extra verbosity can be avoided by using the vvp command to + indirectly execute the compiler output file. + +* -V + + Print the version information. This skips all compilation. Just print the + version information, including version details for the various components of + the compiler. + +* -W + + Enable/disable warnings. All the warning types (other then "all") can be + prefixed with no- to disable that warning. + + * all + + This enables almost all of the available warnings. More specifically, it + enables these warnings:: + + -Wanachronisms + -Wimplicit + -Wimplicit-dimensions + -Wmacro-replacement + -Wportbind + -Wselect-range + -Wtimescale + -Wsensitivity-entire-array + + * anachronisms + + This enables warnings for use of features that have been deprecated or + removed in the selected generation of the Verilog language. + + * implicit + + This enables warnings for creation of implicit declarations. For example, + if a scalar wire X is used but not declared in the Verilog source, this + will print a warning at its first use. + + * implicit-dimensions + + This enables warnings for the case where a port declaration or a var/net + declaration for the same name is missing dimensions. Normally, Verilog + allows you to do this (the undecorated declaration gets its dimensions + form the decorated declaration) but this is no longer common, and some + other tools (notable Xilix synthesizers) do not handle this correctly. + + This flag is supported in release 10.1 or master branch snapshots after + 2016-02-06. + + * macro-redefinition + + This enables warnings when a macro is redefined, even if the macro text + remains the same. + + NOTE: The "macro-redefinition" flag was added in v11.0. + + * macro-replacement + + This enables warnings when a macro is redefined and the macro text + changes. Use no-macro-redefinition to disable this, + + NOTE: The "macro-replacement" flag was added in v11.0. + + * portbind + + This enables warnings for ports of module instantiations that are not + connected properly, but probably should be. Dangling input ports, for + example, will generate a warning. + + * select-range + + This enables warnings for constant out-of-bound selects. This includes + partial or fully out-of-bound select as well as a select containing a 'bx + or 'bz in the index. + + * timescale + + This enables warnings for inconsistent use of the timescale directive. It + detects if some modules have no timescale, or if modules inherit timescale + from another file. Both probably mean that timescales are inconsistent, + and simulation timing can be confusing and dependent on compilation order. + + * infloop + + This enables warnings for always statements that may have runtime infinite + loops (i.e. has paths with zero or no delay). This class of warnings is + not included in -Wall and hence does not have a no- variant. A fatal error + message will always be printed when the compiler can determine that there + will definitely be an infinite loop (all paths have no or zero delay). + + When you suspect an always statement is producing a runtine infinite loop, + use this flag to find the always statements that need to have their logic + verified. it is expected that many of the warnings will be false + positives, since the code treats the value of all variables and signals as + indeterninite. + + * sensitivity-entire-vector + + This enables warnings for when a part select with an "always @*" statement + results in the entire vector being added to the implicit sensitivity + list. Although this behavior is prescribed by the IEEE standard, it is not + what might be expected and can have performance implications if the vector + is large. + + * sensitivity-entire-array + + This enables warnings for when a word select with an "always @*" statement + results in the entire array being added to the implicit sensitivity + list. Although this behavior is prescribed by the IEEE standard, it is not + what might be expected and can have performance implications if the array + is large. + + * floating-nets + + This enables warnings for nets that are present but have no drivers. + + This flag was added in version 11.0 or later (and is in the master branch + as of 2015-10-01). + +* -y + + Append the directory to the library module search path. When the compiler + finds an undefined module, it looks in these directories for files with the + right name. + +* -Y + + Appends suf to the list of file extensions that are used to resolve an + undefined module to a file name. Should be specified before any -y flag. For + example, this command:: + + % iverilog -Y .sv -y sources src.v + + will try to resolve any undefined module m by looking into the directory + sources and checking if there exist files named m.v or m.sv. + + +Preprocessor Flags +------------------ + +These flags control the behavior of the preprocessor. They are similar to +flags for the typical "C" compiler, so C programmers will find them familiar. + +* -E + + This flag is special in that it tells the compiler to only run the + preprocessor. This is useful for example as a way to resolve preprocessing + for other tools. For example, this command:: + + % iverilog -E -ofoo.v -DKEY=10 src1.v src2.v + + runs the preprocessor on the source files src1.v and src2.v and produces the + single output file foo.v that has all the preprocessing (including header + includes and ifdefs) processed. + +* -D + + Assign a value to the macro name. The format of this flag is one of:: + + -Dkey=value + -Dkey + + The key is defined to have the given value. If no value is given, then it is + assumed to be "1". The above examples are the same as these defines in + Verilog source:: + + `define key value + `define key + +* -I + + Append directory to list of directories searched for Verilog include + files. The -I switch may be used many times to specify several directories + to search, the directories are searched in the order they appear on the + command line. + +Elaboration Flags +----------------- + +These are flags that pass information to the elaboration steps. + +* -P= + + Define a parameter using the defparam behavior to override a parameter + values. This can only be used for parameters of root module instances. + +* -s + + Specify the top level module to elaborate. Icarus Verilog will by default + choose modules that are not instantiated in any other modules, but sometimes + that is not sufficient, or instantiates too many modules. If the user + specifies one or more root modules with "-s" flags, then they will be used + as root modules instead. + +* -Tmin, -Ttyp, -Tmax + + Select the timings to use. The Verilog language allows many timings to be + specified as three numbers, min:typical:max, but for simulation you need to + choose which set to use. The "-Tmin" flag tells the compiler to at + elaboration time choose "min" times. The default is "-Ttyp". + +Target Flags +------------ diff --git a/Documentation/usage/getting_started.rst b/Documentation/usage/getting_started.rst new file mode 100644 index 000000000..d4c6c946d --- /dev/null +++ b/Documentation/usage/getting_started.rst @@ -0,0 +1,161 @@ + +Getting Started With Icarus Verilog +=================================== + +Before getting started with actual examples, here are a few notes on +conventions. First, command lines and sequences take the same arguments on all +supported operating environments, including Linux, Windows and the various +Unix systems. When an example command is shown in a figure, the generic prompt +character "% " takes the place of whatever prompt string is appropriate for +your system. Under Windows, the commands are invoked in a command window. + +Second, when creating a file to hold Verilog code, it is common to use the +".v" or the ".vl" suffix. This is not a requirement imposed by Icarus Verilog, +but a useful convention. Some people also use the suffixes ".ver" or even +".vlg". Examples in this book will use the ".v" suffix. + +So let us start. Given that you are going to use Icarus Verilog as part of +your design process, the first thing to do as a designer is learn how to +compile and execute even the most trivial design. For the purposes of +simulation, we use as our example the most trivial simulation, a simple Hello, +World program. :: + + module hello; + initial + begin + $display("Hello, World"); + $finish ; + end + endmodule + +Use a text editor to place the program in a text file, hello.v, then compile +this program with the command:: + + % iverilog -o hello hello.v + +The results of this compile are placed into the file "hello", because the "-o" +flag tells the compiler where to place the compiled result. Next, execute the +compiled program like so:: + + % vvp hello + Hello, World + +And there it is, the program has been executed. So what happened? The first +step, the "iverilog" command, read and interpreted the source file, then +generated a compiled result. The compiled form may be selected by command line +switches, but the default is the "vvp" format, which is actually run later, as +needed. The "vvp" command of the second step interpreted the "hello" file from +the first step, causing the program to execute. + +The "iverilog" and "vvp" commands are the most important commands available to +users of Icarus Verilog. The "iverilog" command is the compiler, and the "vvp" +command is the simulation runtime engine. What sort of output the compiler +actually creates is controlled by command line switches, but normally it +produces output in the default vvp format, which is in turn executed by the +vvp program. + +As designs get larger and more complex, they gain hierarchy in the form of +modules that are instantiated within others, and it becomes convenient to +organize them into multiple files. A common convention is to write one +moderate sized module per file (or group related tiny modules into a single +file) then combine the files of the design together during compilation. For +example, the counter model in counter.v:: + + module counter(output, clk, reset); + + parameter WIDTH = 8; + + output [WIDTH-1 : 0] output; + input clk, reset; + + reg [WIDTH-1 : 0] out; + wire clk, reset; + + always @(posedge clk or posedge reset) + if (reset) + output <= 0; + else + output <= output + 1; + + endmodule // counter + +and the test bench in counter_tb.v:: + + module test; + + /* Make a reset that pulses once. */ + reg reset = 0; + initial begin + # 17 reset = 1; + # 11 reset = 0; + # 29 reset = 1; + # 11 reset = 0; + # 100 $stop; + end + + /* Make a regular pulsing clock. */ + reg clk = 0; + always #5 clk = !clk; + + wire [7:0] value; + counter c1 (value, clk, reset); + + initial + $monitor("At time %t, value = %h (%0d)", + $time, value, value); + endmodule // test + +are written into different files. + +The "iverilog" command supports multi-file designs by two methods. The +simplest is to list the files on the command line:: + + % iverilog -o my_design counter_tb.v counter.v + % vvp my_design + +This command compiles the design, which is spread across two input files, and +generates the compiled result into the "my_design" file. This works for small +to medium sized designs, but gets cumbersome when there are lots of files. + +Another technique is to use a commandfile, which lists the input files in a +text file. For example, create a text file called "file_list.txt" with the +files listed one per line:: + + counter.v + counter_tb.v + +Then compile and execute the design with a command like so:: + + % iverilog -o my_design -c file_list.txt + % vvp my_design + +The command file technique clearly supports much larger designs simply by +saving you the trouble of listing all the source files on the command +line. Name the files that are part of the design in the command file and use +the "-c" flag to tell iverilog to read the command file as a list of Verilog +input files. + +As designs get more complicated, they almost certainly contain many Verilog +modules that represent the hierarchy of your design. Typically, there is one +module that instantiates other modules but is not instantiated by any other +modules. This is called a root module. Icarus Verilog chooses as roots (There +can be more than one root) all the modules that are not instantiated by other +modules. If there are no such modules, the compiler will not be able to choose +any root, and the designer must use the "-sroot" switch to identify the root +module, like this:: + + % iverilog -s main -o hello hello.v + +If there are multiple candidate roots, all of them will be elaborated. The +compiler will do this even if there are many root modules that you do not +intend to simulate, or that have no effect on the simulation. This can happen, +for example, if you include a source file that has multiple modules, but are +only really interested in some of them. The "-s" flag identifies a specific +root module and also turns off the automatic search for other root +modules. You can use this feature to prevent instantiation of unwanted roots. + +As designs get even larger, they become spread across many dozens or even +hundreds of files. When designs are that complex, more advanced source code +management techniques become necessary. These are described in later chapters, +along with other advanced design management techniques supported by Icarus +Verilog. diff --git a/Documentation/usage/index.rst b/Documentation/usage/index.rst new file mode 100644 index 000000000..e4292bc73 --- /dev/null +++ b/Documentation/usage/index.rst @@ -0,0 +1,14 @@ + +Icarus Verilog Usage +==================== + +This section contains documents to help support developers who contribute to +Icarus Verilog. + +.. toctree:: + :maxdepth: 1 + + getting_started + command_line_flags + verilog_attributes + vvp_flags diff --git a/Documentation/usage/verilog_attributes.rst b/Documentation/usage/verilog_attributes.rst new file mode 100644 index 000000000..96fd95fd1 --- /dev/null +++ b/Documentation/usage/verilog_attributes.rst @@ -0,0 +1,35 @@ + +Verilog Attributes +================== + +This is a description of the various attributes that the Icarus Verilog tools +understand. The attributes are attached to objects using the "(* ... *)" +syntax, which is described by the Verilog LRM. + +Attributes that start with "ivl_" are Icarus Verilog specific are are probably +ignored by other tools. + +Optimizations +------------- + +* ivl_do_not_elide (snapshot 20140619 or later) + + This applies to signals (i.e. reg, wire, etc.) and tells the optimizer to + not elide the signal, even if it is not referenced anywhere in the + design. This is useful if the signal is for some reason only accessed by + VPI/PLI code. + +Synthesis +--------- + +* ivl_synthesis_cell + + Applied to a module definition, this tells the synthesizer that the module + is a cell. The synthesizer does not descend into synthesis cells, as they + are assumed to be primitives in the target technology. + +* ivl_synthesis_off + + Attached to an "always" statement, this tells the synthesizer that the + statement is not to be synthesized. This may be useful, for example, to tell + the compiler that a stretch of code is test-bench code. diff --git a/Documentation/usage/vvp_flags.rst b/Documentation/usage/vvp_flags.rst new file mode 100644 index 000000000..f39f21b69 --- /dev/null +++ b/Documentation/usage/vvp_flags.rst @@ -0,0 +1,104 @@ +VVP Command Line Flags +====================== + +The vvp command is the simulation run-time engine. The command line for vvp +execution is first the options and flags, then the vvp input file, and finally +extended arguments. Typical usage looks like this:: + + % vvp foo.vvp + +Options/Flags +------------- + +These options/flags go before the path to the vvp-executable program. They +effect behavior of the vvp runtime engine, including preparation for +simulation. + +* -l + + This flag specifies a logfile where all MCI output goes. Specify + logfile as '-' to send log output to . $display and friends send + their output both to and . + +* -M + + Add the directory path to the (VPI) module search path. Multiple "-M" flags + are allowed, and the directories are added in the order that they are given + on the command line. + + The string "-M-" is special, in that it doesn't add a directory to the + path. It instead *removes* the compiled directory. This is generally used + only for development of the vvp engine. + +* -m + + Name a VPI module that should be loaded. The vvp engine looks for the named + module in the module search path, which includes the compiled in default + directory and directories given by "-M" flags. + + NOTE: Starting with v11.0, the VPI modules to be loaded can be specified + when you compile your design. This allows the compiler to automatically + determine the return types of user-defined system functions. If specified at + compile-time, there is no need to specify them again here. + +* -v + + Show verbose progress while setting up or cleaning up the runtime + engine. This also displays some performance information. + +Extended Arguments +------------------ + +The extended arguments are available to the simulation runtime, especially +system tasks, system functions and any VPI/PLI code. Extended arguments that +start with a "+" character are left for use by the user via the $plus$flag and +$plus$value functions. + +VCD/FST/LXT Arguments +^^^^^^^^^^^^^^^^^^^^^ + +If not otherwise specified, the vvp engine will by default use VCD formats to +support the $dumpvars system task. The flags described here can alter that +behavior. + +* -none/-vcd-none/-vcd-off/-fst-none + + Disable trace output. The trace output will be stubbed so that no trace file + is created and the cost of dumping is avoided. All off these options are + synonyms for turning of dumping. + +* -fst + + Generate FST format outputs instead of VCD format waveform dumps. This is + the preferred output format if using GTKWave for viewing waveforms. + +* -lxt/-lxt2 + + Generate LXT or LXT2format instead of VCD format waveform dumps. The LXT2 + format is more advanced. + +SDF Support +^^^^^^^^^^^ + +The Icarus Verilog support for SDF back-annotation can take some extended +arguments to control aspects of SDF support. + +* -sdf-warn + + Print warnings during load of/annotation from an SDF file. + +* -sdf-info + + Print interesting information about an SDF file while parsing it. + +* -sdf-verbose + + Print warnings and info messages. + +Environment Variables +--------------------- + +The vvp program pays attention to certain environment variables. + +* IVERILOG_DUMPER +