Update Verilog fabric netlist documentation

docs/source/manual/fpga_verilog/fabric_netlist.rst

@@ -0,0 +1,132 @@
+.. _fabric_netlists:
+
+Fabric Netlists
+---------------
+
+In this paper, we will introduce the hierarchy, dependency and functionality of each Verilog netlist, which are generated to model the FPGA fabric.
+
+.. note:: These netlists are automatically generated by the OpenFPGA command ``write_fabric_verilog``. See :ref:`openfpga_verilog_commands` for its detailed usage. 
+
+All the generated Verilog netlists are located in the directory as you specify in the OpenFPGA command ``write_fabric_verilog``.
+Inside the directory, the Verilog netlists are organized as illustrated in :numref:`fig_fabric_netlist_hierarchy`.
+
+.. _fig_fabric_netlist_hierarchy:
+
+.. figure:: ./figures/fabric_netlist_hierarchy.png
+   :scale: 90%
+
+   Hierarchy of Verilog netlists modeling a FPGA fabric
+
+.. _fig_generic_fabric:
+
+.. figure:: ./figures/generic_fabric.png
+   :scale: 80%
+
+   An illustrative FPGA fabric modelled by the Verilog netlists
+
+Top-level Netlists
+~~~~~~~~~~~~~~~~~~
+
+.. option:: fabric_netlists.v
+
+   This file includes all the related Verilog netlists that are used by the ``fpga_top.v``.
+   This file is created to simplify the netlist addition for HDL simulator and backend tools.
+   This is the only file you need to add to a simulator or backend project.
+
+   .. note:: User-defined (external) Verilog netlists will be included in this file.
+
+.. option:: fpga_top.v
+
+   This netlist contains the top-level module of the fpga fabric, corresponding to the fabric shown in :numref:`fig_generic_fabric`.
+
+.. option:: fpga_defines.v
+
+   This file includes pre-processing flags required by the ``fpga_top.v``, to smooth HDL simulation.
+   It will include the folliwng pre-procesing flags:
+   
+   - ```define ENABLE_TIMING`` When enabled, all the delay values defined in primitive Verilog modules will be considered in compilation. This flag is added when ``--include_timing`` option is enabled when calling the ``write_fabric_verilog`` command. 
+
+   .. note:: We strongly recommend users to turn on this flag as it can help simulators to converge quickly.
+
+   - ```define ENABLE_SIGNAL_INITIALIZATION`` When enabled, all the outputs of primitive Verilog modules will be initialized with a random value. This flag is added when ``--include_signal_init`` option is enabled when calling the ``write_fabric_verilog`` command. 
+
+   .. note:: We strongly recommend users to turn on this flag as it can help simulators to converge quickly.
+   
+   - ```define ICARUS_SIMULATOR`` When enabled, Verilog netlists are generated to be compatible with the syntax required by `icarus iVerilog simulator`__. This flag is added when ``--support_icarus_simulator`` option is enabled when calling the ``write_fabric_verilog`` command. 
+
+   .. warning:: Please disable this flag if you are not using icarus iVerilog simulator.
+
+__ iverilog_website_
+
+.. _iverilog_website: http://iverilog.icarus.com/
+
+Logic Blocks
+~~~~~~~~~~~~
+This sub-directory contains all the Verilog modules modeling configurable logic blocks, heterogeneous blocks as well as I/O blocks.
+Take the example in :numref:`fig_generic_fabric`, the modules are CLBs, DSP blocks, I/Os and Block RAMs.
+
+.. option:: <physical_tile_name>.v
+
+   For each ``<physical_tile>`` defined in the VPR architecture description, a Verilog netlist will be generated to model its internal structure.
+
+   .. note:: For I/O blocks, separated ``<physical_tile_name>.v`` will be generated for each side of a FPGA fabric.
+
+.. option:: <logical_tile_name>.v
+
+   For each root ``pb_type`` defined in the ``<complexblock>`` of VPR architecture description, a Verilog netlist will be generated to model its internal structure.
+
+Routing Blocks
+~~~~~~~~~~~~~~
+This sub-directory contains all the Verilog modules modeling Switch Blocks (SBs) and Connection Blocks (CBs).
+Take the example in :numref:`fig_generic_fabric`, the modules are the Switch Blocks, X- and Y- Connection Blocks of a tile.
+
+.. option:: sb_<x>_<y>.v
+
+  For each unique Switch Block (SB) created by VPR routing resource graph generator, a Verilog netlist will be generated. The ``<x>`` and ``<y>`` denote the coordinate of the Switch Block in the FPGA fabric.
+
+.. option:: cbx_<x>_<y>.v
+
+  For each unique X-direction Connection Block (CBX) created by VPR routing resource graph generator, a Verilog netlist will be generated. The ``<x>`` and ``<y>`` denote the coordinate of the Connection Block in the FPGA fabric.
+
+.. option:: cby_<x>_<y>.v
+
+  For each unique Y-direction Connection Block (CBY) created by VPR routing resource graph generator, a Verilog netlist will be generated. The ``<x>`` and ``<y>`` denote the coordinate of the Connection Block in the FPGA fabric.
+
+Primitive Modules
+~~~~~~~~~~~~~~~~~
+This sub-directory contains all the primitive Verilog modules, which are used to build the logic blocks and routing blocks.
+
+.. option:: luts.v
+
+  Verilog modules for all the Look-Up Tables (LUTs), which are defined as ``<circuit_model name="lut">`` of OpenFPGA architecture description. See details in :ref:`circuit_library`.
+
+.. option:: wires.v
+
+  Verilog modules for all the routing wires, which are defined as ``<circuit_model name="wire|chan_wire">`` of OpenFPGA architecture description. See details in :ref:`circuit_library`.
+
+.. option:: memories.v
+
+  Verilog modules for all the configurable memories, which are defined as ``<circuit_model name="ccff|sram">`` of OpenFPGA architecture description. See details in :ref:`circuit_library`.
+
+.. option:: muxes.v
+
+  Verilog modules for all the routing multiplexers, which are defined as ``<circuit_model name="mux">`` of OpenFPGA architecture description. See details in :ref:`circuit_library`.
+
+  .. note:: multiplexers used in Look-Up Tables are also defined in this netlist.
+
+.. option:: inv_buf_passgate.v
+
+  Verilog modules for all the inverters, buffers and pass-gate logics, which are defined as ``<circuit_model name="inv_buf|pass_gate">`` of OpenFPGA architecture description. See details in :ref:`circuit_library`.
+
+.. option:: local_encoder.v
+
+  Verilog modules for all the encoders and decoders, which are created when routing multiplexers are defined to include local encoders. See details in :ref:`circuit_model_examples`.
+
+.. option:: user_defined_templates.v
+
+  This is a template netlist, which users can refer to when writing up their user-defined Verilog modules.
+  The user-defined Verilog modules are those ``<circuit_model>`` in the OpenFPGA architecture description with a specific ``verilog_netlist`` path.
+  It contains Verilog modules with ports declaration (compatible to other netlists that are auto-generated by OpenFPGA) but without any functionality.
+  This file is created only when the option ``--print_user_defined_template`` is enabled when calling the ``write_fabric_verilog`` command. 
+
+  .. warning:: Do not include this netlist in simulation without any modification to its content!

docs/source/manual/fpga_verilog/file_organization.rst

@@ -1,20 +0,0 @@
-Hierarchy of Verilog Output Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-All the generated Verilog Netlists are located in the <verilog_dir>/SRC as you specify in the command-line options. Under the <verilog_dir>/SRC, FPGA-Verilog creates the top file name_top.v and some folders: lb (logic blocks), routing and sub_modules. 
-
-.. csv-table:: Folder hierarchy of FPGA-Verilog
-   :header: "File/Folder", "Content" 
-   :widths: 10, 20
-        
-   "name_top.v", "Contains the top module and calls all the other .v files"   
-   "name.bitstream", "Only if --fpga_verilog_print_top_testbench or --fpga_verilog_print_top_auto_testbench is chosen. Contains the bitstream programming the generated FPGA."
-   "name_top_tb.v", "Only if --fpga_verilog_print_top_testbench. Contains a testbench used for the simulation."
-   "name_autocheck_top_tb.v", "Only if --fpga_verilog_print_autocheck_top_testbench is chosen. Contains a testbench used for the simulation."
-   "name_formal_random_top_tb.v", "Only if --fpga_verilog_print_formal_verification_top_netlist is chosen. Contains a testbench used for the simulation."
-   "name_top_formal_verification.v", "Only if --fpga_verilog_print_formal_verification_top_netlist is chosen. Contains a top fil used for formal verification and by name_formal_random_top_tb.v."
-   "fpga_defines.v", "Contains all the defines set as 'include_timing'"
-   "name_include_netlists.v", "Contains all the netlists and defines paths used for the simulation."
-   "lb", "Logic Block. Contains all the CLBs. The logic_block.v includes all the CLB and is called by the top module afterward."
-   "routing", "Contains all the routing in the circuit. You can find in it the Switch Boxes, the Connection Blocks and the routing needed to connect the different blocks. The routing.v file packs them all and is called by the top module."
-   "sub_modules", "Contains the modules generated by the flow to build the CLBs."

docs/source/manual/fpga_verilog/index.rst

@@ -7,7 +7,7 @@ FPGA-Verilog
 .. toctree::
    :maxdepth: 2
   
-   file_organization
+   fabric_netlist
  
    func_verify
 

docs/source/manual/openfpga_shell/openfpga_commands.rst

@@ -140,6 +140,8 @@ FPGA-Bitstream
   - ``--file`` or ``-f`` Output the fabric bitstream to an plain text file (only 0 or 1)
 
   - ``--verbose`` Show verbose log
+
+.. _openfpga_verilog_commands:
   
 FPGA-Verilog
 ~~~~~~~~~~~~