Documentation: Transferring more content from the wiki

This finishes up most of the User Guide from the Wiki. Some bits
from the wiki are just too aweful, or obsolete, so are left out.

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