Merge pull request #675 from steveicarus/steve/documentation-directory

Start Icarus Verilog Documentation using Sphinx

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
+