Start Icarus Verilog Documentation using Sphinx

Embed the Icarus Verilog documentation, and format it so that the
Sphinx tools can process it into html or other formats. This will
make the documentation easier to keep up to date with the actual
software.

Documentation/.gitignore

@@ -0,0 +1 @@
+_build/

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'),
+]

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
+

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

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`

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

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
+

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.
+

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.

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.

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

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.

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

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.

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 <flags> foo.vvp <extended arguments>
+
+Options/Flags
+-------------
+
+These options/flags go before the path to the vvp-executable program. They
+effect behavior of the vvp runtime engine, including preparation for
+simulation.
+
+* -l<logfile>
+
+  This flag specifies a logfile where all MCI <stdlog> output goes. Specify
+  logfile as '-' to send log output to <stderr>. $display and friends send
+  their output both to <stdout> and <stdlog>.
+
+* -M<path>
+
+  Add the directory path to the (VPI) module search path. Multiple "-M" flags
+  are allowed, and the directories are added in the order that they are given
+  on the command line.
+
+  The string "-M-" is special, in that it doesn't add a directory to the
+  path. It instead *removes* the compiled directory. This is generally used
+  only for development of the vvp engine.
+
+* -m<module>
+
+  Name a VPI module that should be loaded. The vvp engine looks for the named
+  module in the module search path, which includes the compiled in default
+  directory and directories given by "-M" flags.
+
+  NOTE: Starting with v11.0, the VPI modules to be loaded can be specified
+  when you compile your design. This allows the compiler to automatically
+  determine the return types of user-defined system functions. If specified at
+  compile-time, there is no need to specify them again here.
+
+* -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
+