Document all targets

Documentation/targets/index.rst

@@ -3,16 +3,21 @@ 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
+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
-   vhdl
-   verilog95
-   pcb
+   tgt-vvp
+   tgt-stub
+   tgt-null
+   tgt-vhdl
+   tgt-vlog95
+   tgt-pcb
+   tgt-fpga
+   tgt-pal
+   tgt-sizer
+   tgt-verilog
+   tgt-blif

Documentation/targets/stub.rst

@@ -1,7 +0,0 @@
-
-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/tgt-blif.rst

@@ -0,0 +1,44 @@
+
+The BLIF Code Generator (-tblif)
+================================
+
+The BLIF code generator supports emitting the design to a blif format
+file as accepted by:
+
+    ABC: A System for Sequential Synthesis and Verification
+    <http://www.eecs.berkeley.edu/~alanmi/abc/>
+
+This package contains tools sometimes used by ASIC designers. This
+blif target emits .blif file that the ABC system can read int via
+the "read_blif" command.
+
+
+USAGE
+-----
+
+This code generator is intended to process structural Verilog source
+code. To convert a design to blif, use this command::
+
+  % iverilog -tblif -o<path>.blif  <source files>...
+
+The source files can be Verilog, SystemVerilog, VHDL, whatever Icarus
+Verilog supports, so long as it elaborates down to the limited subset
+that the code generator supports. In other words, the files must be
+structural.
+
+The root module of the elaborated design becomes the model is
+generated. That module may instantiate sub-modules and so on down the
+design, completing the design. The output model is flattened, so it
+doesn't invoke any subcircuits. Bit vectors are exploded out at the
+model ports and internally. This is necessary since blif in particular
+and ABC in general processes bits, not vectors.
+
+
+LIMITATIONS
+-----------
+
+Currently, only explicit logic gates and continuous assignments are
+supported.
+
+The design must contain only one root module. The name of that root
+module becomes the name of the blif model in the ".model" record.

Documentation/targets/tgt-fpga.rst

@@ -0,0 +1,201 @@
+
+The FPGA Code Generator (-tfpga)
+================================
+
+.. warning::
+    This code generator is currently not included in Icarus Verilog.
+
+The FPGA code generator supports a variety of FPGA devices, writing
+XNF or EDIF depending on the target. You can select the architecture
+of the device, and the detailed part name. The architecture is used to
+select library primitives, and the detailed part name is written into
+the generated file for the use of downstream tools.
+
+INVOKING THE FPGA TARGET
+------------------------
+
+The code generator is invoked with the -tfpga flag to iverilog. It
+understands the part= and the arch= parameters, which can be set with
+the -p flag of iverilog:
+
+	iverilog -parch=virtex -ppart=v50-pq240-6 -tfpga foo.vl
+
+This example selects the Virtex architecture, and give the detailed
+part number as v50-pq240-6. The output is written into a.out unless a
+different output file is specified with the -o flag.
+
+The following is a list of architecture types that this code generator
+supports.
+
+* arch=lpm
+
+This is a device independent format, where the gates are device types
+as defined by the LPM 2 1 0 specification. Some backend tools may take
+this format, or users may write interface libraries to connect these
+netlists to the device in question.
+
+* arch=generic-edif (obsolete)
+
+This is generic EDIF code. It doesn't necessarily work because the
+external library is not available to the code generator. But, what it
+does is generate generic style gates that a portability library can
+map to target gates if desired.
+
+* arch=generic-xnf (obsolete)
+
+If this is selected, then the output is formatted as an XNF file,
+suitable for most any type of device. The devices that it emits
+are generic devices from the unified library. Some devices are macros,
+you may need to further resolve the generated XNF to get working
+code for your part.
+
+* arch=virtex
+
+If this is selected, then the output is formatted as an EDIF 200 file,
+suitable for Virtex class devices. This is supposed to know that you
+are targeting a Virtex part, so can generate primitives instead of
+using external macros. It includes the VIRTEX internal library, and
+should work properly for any Virtex part.
+
+* arch=virtex2
+
+If this is selected, then the output is EDIF 2 0 0 suitable for
+Virtex-II and Virtex-II Pro devices. It uses the VIRTEX2 library, but
+is very similar to the Virtex target.
+
+XNF ROOT PORTS
+--------------
+
+  NOTE: As parts are moved over to EDIF format, XNF support will be
+  phased out. Current Xilinx implementation tools will accept EDIF
+  format files even for the older parts, and non-Xilinx implementation
+  tools accept nothing else.
+
+When the output format is XNF, the code generator will generate "SIG"
+records for the signals that are ports of the root module. The name is
+declared as an external pin that this macro makes available.
+
+The name given to the macro pin is generated from the base name of the
+signal. If the signal is one bit wide, then the pin name is exactly
+the module port name. If the port is a vector, then the pin number is
+given as a vector. For example, the module:
+
+.. code-block::
+
+	module main(out, in);
+	    output out;
+	    input [2:0] in;
+	    [...]
+	endmodule
+
+leads to these SIG, records:
+
+.. code-block::
+
+	SIG, main/out, PIN=out
+	SIG, main/in<2>, PIN=in2
+	SIG, main/in<1>, PIN=in1
+	SIG, main/in<0>, PIN=in0
+
+
+EDIF ROOT PORTS
+---------------
+
+The EDIF format is more explicit about the interface into an EDIF
+file. The code generator uses that control to generate an explicit
+interface definition into the design. (This is *not* the same as the
+PADS of a part.) The generated EDIF interface section contains port
+definitions, including the proper direction marks.
+
+With the (rename ...) s-exp in EDIF, it is possible to assign
+arbitrary text to port names. The EDIF code generator therefore does
+not resort to the mangling that is needed for the XNF target. The base
+name of the signal that is an input or output is used as the name of
+the port, complete with the proper case.
+
+However, since the ports are single bit ports, the name of vectors
+includes the string "[0]" where the number is the bit number. For
+example, the module:
+
+.. code-block::
+
+	module main(out, in);
+	    output out;
+	    input [2:0] in;
+	    [...]
+	endmodule
+
+creates these ports:
+
+.. code-block::
+
+	out   OUTPUT
+	in[0] INPUT
+	in[1] INPUT
+	in[2] INPUT
+
+Target tools, including Xilinx Foundation tools, understand the []
+characters in the name and recollect the signals into a proper bus
+when presenting the vector to the user.
+
+
+PADS AND PIN ASSIGNMENT
+-----------------------
+
+The ports of a root module may be assigned to specific pins, or to a
+generic pad. If a signal (that is a port) has a PAD attribute, then
+the value of that attribute is a list of locations, one for each bit
+of the signal, that specifies the pin for each bit of the signal. For
+example:
+
+.. code-block::
+
+	module main( (* PAD = "P10" *)         output out,
+		     (* PAD = "P20,P21,P22" *) input [2:0] in);
+	    [...]
+	endmodule
+
+In this example, port `out` is assigned to pin 10, and port `in`
+is assigned to pins 20-22. If the architecture supports it, a pin
+number of 0 means let the back end tools choose a pin. The format of
+the pin number depends on the architecture family being targeted, so
+for example Xilinx family devices take the name that is associated
+with the "LOC" attribute.
+
+NOTE: If a module port is assigned to a pin (and therefore attached to
+a PAD) then it is *not* connected to a port of the EDIF file. This is
+because the PAD (and possibly IBUF or OBUF) would become an extra
+driver to the port. An error.
+
+
+SPECIAL DEVICES
+---------------
+
+The code generator supports the "cellref" attribute attached to logic
+devices to cause specific device types be generated, instead of the
+usual device that the code generator might generate. For example, to
+get a clock buffer out of a Verilog buf:
+
+	buf my_gbuf(out, in);
+	$attribute(my_buf, "cellref", "GBUF:O,I");
+
+The "cellref" attribute tells the code generator to use the given
+cell. The syntax of the value is:
+
+	<cell type>:<pin name>,...
+
+The cell type is the name of the library part to use. The pin names
+are the names of the type in the library, in the order that the logic
+device pins are connected.
+
+
+COMPILING WITH XILINX FOUNDATION
+--------------------------------
+
+Compile a single-file design with command line tools like so::
+
+  % iverilog -parch=virtex -o foo.edf foo.vl
+  % edif2ngd foo.edf foo.ngo
+  % ngdbuild -p v50-pq240 foo.ngo foo.ngd
+  % map -o map.ncd foo.ngd
+  % par -w map.ncd foo.ncd

Documentation/targets/tgt-pal.rst

@@ -0,0 +1,8 @@
+
+The PAL Code Generator (-tpal)
+==============================
+
+.. warning::
+    This code generator is currently not included in Icarus Verilog.
+
+The PAL target generates JEDEC output for a Programmable Array Logic.

Documentation/targets/tgt-pcb.rst

@@ -1,6 +1,6 @@
 
-Using the PCB code generator
-============================
+The PCB Code Generator (-tpcb)
+==============================
 
 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.

Documentation/targets/tgt-sizer.rst

@@ -0,0 +1,49 @@
+
+The sizer Code Analyzer (-tvvp)
+===============================
+
+The sizer target does not generate any code. Instead it will print statistics about the Verilog code.
+
+It is important to synthesize the Verilog code before invoking the sizer. This can be done with the `-S` flag passed to iverilog. Note, that behavioral code can not be synthesized and will generate a warning when passed to the sizer.
+
+Example command::
+
+    % iverilog -o sizer.txt -tsizer -S -s top input.v
+
+With this example code:
+
+.. code-block:: verilog
+
+    module top (
+        input clock,
+        input reset,
+        output blink
+    );
+        reg out;
+
+        always @(posedge clock) begin
+            if (reset) begin
+                out = 1'b0;
+            end else begin
+                out <= !out;
+            end
+        end
+        
+        assign blink = out;
+
+    endmodule
+
+The resulting `sizer.txt` will contain::
+
+    **** module/scope: top
+         Flip-Flops   : 1
+         Logic Gates  : 3
+         MUX[2]: 1 slices
+         LOG[13]: 1 unaccounted
+         LOG[14]: 1 unaccounted
+    **** TOTALS
+         Flip-Flops   : 1
+         Logic Gates  : 3
+         MUX[2]: 1 slices
+         LOG[13]: 1 unaccounted
+         LOG[14]: 1 unaccounted

Documentation/targets/tgt-stub.rst

@@ -0,0 +1,30 @@
+
+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.
+
+Example command::
+
+    % iverilog -o stub.txt -tstub -s top input.v
+
+With this example code:
+
+.. code-block:: verilog
+
+    module top;
+        initial $display("Hello World!");
+    endmodule
+
+The resulting `stub.txt` will contain::
+
+    root module = top
+    scope: top (0 parameters, 0 signals, 0 logic) module top time units = 1e0
+     time precision = 1e0
+    end scope top
+    # There are 0 constants detected
+    initial
+        Call $display(1 parameters); /* hello_world.v:2 */
+            <string="Hello World!", width=96, type=bool>

Documentation/targets/tgt-verilog.rst

@@ -0,0 +1,6 @@
+
+The Verilog Code Generator (-tverilog)
+======================================
+
+.. warning::
+    This code generator is currently not included in Icarus Verilog.

Documentation/targets/tgt-vlog95.rst

@@ -1,6 +1,6 @@
 
-Using The Verilog '95 Code Generator
-====================================
+The Verilog '95 Code Generator (-tvlog95)
+=========================================
 
 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

Documentation/targets/tgt-vvp.rst

@@ -0,0 +1,63 @@
+
+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.
+
+Example command::
+
+    %  iverilog -o top.vvp -s top hello_world.v
+
+Equivalent command::
+
+    %  iverilog -o top.vvp -tvvp -s top hello_world.v
+
+With this example code in `hello_world.v`:
+
+.. code-block:: verilog
+
+    module top;
+        initial $display("Hello World!");
+    endmodule
+
+The resulting `top.vvp` will contain something similar to::
+
+    #! /usr/local/bin/vvp
+    :ivl_version "13.0 (devel)" "(s20221226-119-g8cb2e1a05-dirty)";
+    :ivl_delay_selection "TYPICAL";
+    :vpi_time_precision + 0;
+    :vpi_module "/usr/local/lib/ivl/system.vpi";
+    :vpi_module "/usr/local/lib/ivl/vhdl_sys.vpi";
+    :vpi_module "/usr/local/lib/ivl/vhdl_textio.vpi";
+    :vpi_module "/usr/local/lib/ivl/v2005_math.vpi";
+    :vpi_module "/usr/local/lib/ivl/va_math.vpi";
+    S_0x563c3c5d1540 .scope module, "top" "top" 2 1;
+     .timescale 0 0;
+        .scope S_0x563c3c5d1540;
+    T_0 ;
+        %vpi_call 2 2 "$display", "Hello World!" {0 0 0};
+        %end;
+        .thread T_0;
+    # The file index is used to find the file name in the following table.
+    :file_names 3;
+        "N/A";
+        "<interactive>";
+        "hello_world.v";
+
+The first line contains the shebang. If this file is executed, the shebang tells the shell to use vvp for the execution of this file.
+
+To run the simulation, execute::
+
+    %  ./top.vvp
+
+Or you can call vvp directly::
+
+    %  vvp top.vvp
+
+Next are some directives. The first one, `:ivl_version` specifies which version of iverilog this file was created with. Next is the delay selection with "min:typical:max" values and the time precision, which we did not set specifically, so the default value is used. The next lines tell vvp which VPI modules to load and in which order. The next lines tell vvp which VPI modules to load and in what order. Next, a new scope is created with the `.scope` directive and the timescale is set with `.timescale`. A thread `T_0` is created that contains two instructions: `%vpi_call` executes the VPI function `$display` with the specified arguments, and `%end` terminates the simulation.
+
+Opcodes
+-------
+
+The various available opcodes can be seen in :doc:`Opcodes <../developer/guide/vvp/opcodes>` 

Documentation/targets/vvp.rst

@@ -1,6 +0,0 @@
-
-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.