Merge pull request #679 from steveicarus/steveicarus/more-documentation

Documentation: Transferring more content from the wiki

Documentation/targets/index.rst

@@ -13,4 +13,6 @@ Icarus Verilog. The code generator is selected by the "-t" command line flag.
    vvp
    stub
    null
-
+   vhdl
+   verilog95
+   pcb

Documentation/targets/pcb.rst

@@ -0,0 +1,61 @@
+
+Using the PCB code generator
+============================
+
+The PCB target code generator is designed to allow a user to enter a netlist
+in Verilog format, then generate input files for the GNU PCB layout program.
+
+Invocation
+----------
+
+The PCB target code generation is invoked with the -tpcb flag to the iverilog
+command. The default output file, "a.out", contains the generated .PCB
+file. Use the "-o" flag to set the output file name explicitly. The default
+output file contains only the elements. To generate a "netlist" file, add the
+flag "-pnetlist=<path>" command line flag.
+
+Altogether, this example generates the foo.net and foo.pcb files from the
+foo.v source file::
+
+  % iverilog -tpcb -ofoo.pcb -pnetlist=foo.net foo.v
+
+Flags
+-----
+
+* -o <path>
+
+  Set the output (pcb) file path
+
+* -pnetlist=path
+
+  Write a netlist file to the given path.
+
+Attributes Summary
+------------------
+
+Attributes are attached to various constructs using the Verilog "(* *)"
+attribute syntax.
+
+* ivl_black_box
+
+  Attached to a module declaration or module instantiation, this indicates
+  that the module is a black box. The code generator will create an element
+  for black box instances.
+
+Parameters Summary
+------------------
+
+Within modules, The PCB code generator uses certain parameters to control
+details. Parameters may have defaults, and can be overridden using the usual
+Verilog parameter override syntax. Parameters have preferred types.
+
+* description (string, default="")
+
+  The "description" is a text string that describes the black box. This string
+  is written into the description field of the PCB Element.
+
+* value (string, default="")
+
+  The "value" is a text tring that describes some value for the black
+  box. Like the description, the code generator does not interpret this value,
+  other then to write it to the appropriate field in the PCB Element."

Documentation/targets/verilog95.rst

@@ -0,0 +1,101 @@
+
+Using The Verilog '95 Code Generator
+====================================
+
+Icarus Verilog contains a code generator to emit 1995 compliant Verilog from
+the input Verilog netlist. This allows Icarus Verilog to function as a Verilog
+> 1995 to Verilog 1995 translator. The main goal of the project was to convert
+@*, ANSI style arguments and other constructs to something allowed in 1995
+Verilog.
+
+Invocation
+----------
+
+To translate a Verilog program to 1995 compliant Verilog, invoke "iverilog"
+with the -tvlog95 flag::
+
+  % iverilog -tvlog95 -o my_design_95.v my_design.v
+
+The generated Verilog will be placed in a single file (a.out by default), even
+if the input Verilog is spread over multiple files.
+
+Generator Flags
+---------------
+
+* -pspacing=N
+
+  Set the indent spacing (the default is 2).
+
+* -pallowsigned=1
+
+  Allow emitting the various signed constructs as an extension to 1995 Verilog
+  (off by default).
+
+* -pfileline=1
+
+  Emit the original file and line information as a comment for each generated
+  line (off by default).
+
+Structures that cannot be converted to 1995 compatible Verilog
+--------------------------------------------------------------
+
+The following Verilog constructs are not translatable to 1995 compatible Verilog:
+
+* Automatic tasks or functions.
+
+* The power operator (**). Expressions of the form (2**N)**<variable> (where N
+  is a constant) can be converter to a shift.
+
+* Some System Verilog constructs (e.g. final blocks, ++/-- operators,
+  etc.). 2-state variables are converted to 4-state variables.
+
+Icarus extensions that cannot be translated:
+
+* Integer constants greater than 32 bits.
+
+* Real valued nets.
+
+* Real modulus.
+
+* Most Verilog-A constructs.
+
+
+Known Issues and Limitations
+----------------------------
+
+Some things are just not finished and should generate an appropriate
+warning. Here is a list of the major things that still need to be looked at.
+
+* There are still a few module instantiation port issues (pr1723367 and
+  partselsynth).
+
+* inout ports are not converted (tran-VP).
+
+* Variable selects of a non-zero based vector in a continuous assignment are
+  not converted.
+
+* There is no support for translating a zero repeat in a continuous
+  assignment. It is currently just dropped.
+
+* A pull device connected to a signal select is not translated correctly (this
+  may be fixed).
+
+* L-value indexed part selects with a constant undefined base in a continuous
+  assignment are not translated.
+
+* Logic gates are not arrayed exactly the same as the input and the instance
+  name is not always the same.
+
+* The signed support does not generate $signed() or $unsigned() function calls
+  in a continuous assignment expression.
+
+* The special power operator cases are not converted in a continuous
+  assignment.
+
+* Currently a signed constant that sets the MSB in an unsigned context will be
+  displayed as a negative value (e.g. bit = 1 translates to bit = -1).
+
+* Can net arrays, etc. be unrolled?
+
+* Can generate blocks be converted?
+

Documentation/targets/vhdl.rst

@@ -0,0 +1,82 @@
+
+The VHDL Code Generator (-tvhdl)
+================================
+
+Icarus Verilog contains a code generator to emit VHDL from the Verilog
+netlist. This allows Icarus Verilog to function as a Verilog to VHDL
+translator.
+
+Invocation
+----------
+
+To translate a Verilog program to VHDL, invoke "iverilog" with the -tvhdl
+flag::
+
+  % iverilog -t vhdl -o my_design.vhd my_design.v
+
+The generated VHDL will be placed in a single file (a.out by default), even if
+the Verilog is spread over multiple files.
+
+Flags
+-----
+
+* -pdebug=1
+
+  Print progress messages as the code generator visits each part of the
+  design.
+
+* -pdepth=N
+
+  Only output VHDL entities for modules found at depth < N in the
+  hierarchy. N=0, the default, outputs all entities. For example, -pdepth=1
+  outputs only the top-level entity.
+
+Supported Constructs
+--------------------
+
+TODO
+
+Limitations
+-----------
+
+Signal Values and Resolution
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+There are several cases where the behaviour of the translated VHDL deviates
+from the source Verilog:
+
+* The result of division by zero is x in Verilog but raises an exception in
+  VHDL.
+
+* Similarly, the result of reading past the end of an array in Verilog is x,
+  whereas VHDL raises an exception.
+
+* Any signal that is driven by two or more processes will have the value
+  'U'. This is the result of the signal resolution function in the
+  std_logic_1164 package.
+
+Constructs Not Supported
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following Verilog constructs cannot be translated to VHDL:
+
+* fork and join
+
+* force and release
+
+* disable
+
+* real-valued variables
+
+* switches
+
+* hierarchical dereferencing
+
+Other Limitations
+^^^^^^^^^^^^^^^^^
+
+* The test expressions in case statements must be constant.
+
+* Translation of a parameter to a corresponding VHDL generic
+  declaration. Instead the default parameter value is used.
+