Merge branch 'master' into reconstruction_grids_with_LegalizationClusterId

Author: haydar-c

doc/src/Images/Net_Settings.png

@@ -2485,7 +2485,7 @@ The full format is documented below.
     Defined under the ``<switchfuncs>`` XML node, one or more ``<func...>`` entries is used to specify permutation functions that connect different sides of a switch block.
 
 
-.. arch:tag:: <wireconn num_conns="expr" from_type="string, string, string, ..." to_type="string, string, string, ..." from_switchpoint="int, int, int, ..." to_switchpoint="int, int, int, ..." from_order="{fixed | shuffled}" to_order="{fixed | shuffled}" switch_override="string"/>
+.. arch:tag:: <wireconn num_conns="expr" from_type="string, string, string, ..." to_type="string, string, string, ..." from_switchpoint="int, int, int, ..." to_switchpoint="int, int, int, ..." from_order="{fixed | shuffled}" to_order="{fixed | shuffled}" switch_override="string" side="string"/>
 
     :req_param num_conns:
         Specifies how many connections should be created between the from_type/from_switchpoint set and the to_type/to_switchpoint set.
@@ -2592,6 +2592,10 @@ The full format is documented below.
         By using a zero-delay and zero-resistance switch one can also create T and L shaped wire segments.
 
         **Default:** If no override is specified, the usual wire_switch that drives the ``to`` wire will be used. 
+    
+    :opt_param side:
+       Specifies the sides that connections are gathered from or scattered to. Valid sides are right, left, top and bottom and are represented by characters 'r', 'l', 't' and 'b'.
+       For example, to select connections from right, left and bottom set this attribute to "rlb". Note that this attribute is used only for :ref:`scatter_gather_patterns` and does not do anything for other usages of this tag. 
 
     .. arch:tag:: <from type="string" switchpoint="int, int, int, ..."/>
 
@@ -2634,6 +2638,110 @@ The full format is documented below.
     The 'to' set is all L4 switchpoint 0's.
     Note that since different switchpoints are selected from different segment types it is not possible to specify this without using ``<from>`` sub-tags.
 
+.. _scatter_gather_patterns:
+
+Scatter-Gather Patterns
+---------------------
+
+The content under the ``<scatter_gather_list>`` tag consists of one or more ``<sg_pattern>`` tags that are used to specify a scatter-gather pattern.
+Scatter-gather patterns can be used to specify multi-level switch patterns, rather than the direct wire-to-wire switch patterns of conventional switch blocks.
+These additional switches, wires and/or muxes will be added to the architecture, augmenting wires created using segment specifications and swiches created using switch box specifications.
+The number of any additional wires or muxes created by scatter-gather specifications will not vary with routing channel width.
+
+.. figure:: scatter_gather_images/scattergather_diagram.svg
+
+    Overview of how scatter-gather patterns work. First, connections from a switchblock location are selected according to the specification.
+    These selected connection are then muxed and passed through the scatter-gather node, which is typically a wire segment. The scatter-gather node then fans out or scatters in another switchblock location.
+
+.. note:: Scatter-Gather patterns are work in progress and experimental. Currently, VPR does not support this specification and using this tag would not result in any modifications to the RR-Graph.
+
+When instantiated, a scatter-gather pattern gathers connections from a switchblock and passes the connection through a multiplexer and the scatter-gather node which is typically a wire segment, then scatters or fans out somewhere else in the device. These patterns can be used to define 3D switchblocks. An example is shown below:
+
+    .. code-block:: xml
+
+        <scatter_gather_list>
+            <sg_pattern name="name" type="unidir">
+                <gather>
+                    <!-- Gather 30 connections from the 0, 4, 8 or 12 position of L16 wires of all four sides of a switchblock location -->
+                    <wireconn num_conns="30" from_type="L16" from_switchpoint="0,12,8,4" side="rltb"/> 
+                <gather/>
+
+                <scatter>
+                    <!-- Scatter 30 connections to the starting position of L16 wires of all four sides of a switchblock location -->
+                    <wireconn num_conns="30" to_type="L16" to_switchpoint="0" side="rtlb"/>
+                <scatter/>
+                
+                <sg_link_list>
+                    <!-- Link going up one layer, using the '3D_SB_MUX' multiplexer to gather connections from the bottom layer and using the 'TSV' node/wire to move up one layer -->
+                    <sg_link name="L_UP" z_offset="1" x_offset="0" y_offset="0" mux="3D_SB_MUX" seg_type="TSV"/> 
+                    <!-- Same as above but moving one layer down -->
+                    <sg_link name="L_DOWN" z_offset="-1" mux="3D_SB_MUX" seg_type="TSV"/>
+                <sg_link_list/>
+                
+                <!-- Instantiate 10 'L_UP' sg_links per switchblock location everywhere on the device -->
+                <sg_location type="EVERYWHERE" num="10" sg_link="L_UP"/>
+                <!-- Instantiate 10 'L_DOWN' sg_links per switchblock location everywhere on the device -->
+                <sg_location type="EVERYWHERE" num="10" sg_link="L_DOWN"/>
+            <sg_pattern/>
+
+            <sg_pattern name="interposer_conn_sg" type="bidir">
+                ... <!-- Another scatter-gather pattern specification -->
+            <sg_pattern/>
+        <scatter_gather_list/>
+
+.. arch:tag:: <sg_pattern name="string" type={unidir|bidir}>
+
+    :req_param name: A unique alphanumeric string
+    :req_param type: ``unidir`` or ``bidir``.
+
+'unidir': Added connections are unidirectional; all the gather connections are combined in a mux that then drives the scatter-gather node which in turn drives the wires specified in the scatter specification.
+
+'bidir': The gather and scatter connections are mirrored; the same scatter pattern is implemented at each end of the scatter-gather pattern. This implies the two muxes driving the scatter-gather node can have their outputs tri-stated. 
+
+.. arch:tag:: <gather>
+
+    Contains a <wireconn> tag specifying how the fan-in or gather connections are selected. See ``wireconn`` for the relevant specification.
+    This <wireconn> tag supports an additioinal 'side' attribute which selects the sides that connections are gathered from (e.g. any of the top, bottom, left and right).
+
+.. arch:tag:: <scatter>
+
+    Contains a <wireconn> tag specifying how the fan-out or scatter connections are selected. See ``wireconn`` for the relevant specification.
+    This <wireconn> tag supports an additioinal 'side' attribute which selects the sides that connections are scattered to (e.g. any of the top, bottom, left and right).
+
+.. arch:tag:: <sg_link_list>
+
+    Contains one or more <sg_link> tags specifying how the pattern of how connections move from the gather location to the scatter location i.e. defines the used mux and scatter-gather node.
+    
+    .. note:: <sg_link> tags are not instantiations of the pattern and would not result in any changes to the device. instead, the <sg_location> tag instantiates the pattern and selects one of the <sg_link> tags to be used for the instantiation.
+
+.. arch:tag:: <sg_link  name="string" x_offset="int" y_offset="int" z_offset="int" mux="string" seg_type="string">
+
+    :req_param name: A unique alphanumeric string
+    :req_param mux: Name of the multiplexer used to gather connections
+    :req_param seg_type: Name of the segment/wire used to move through the device to the scatter location (i.e. the type of the scatter-gather node)
+
+    :opt_param x_offset: Offset of the scatter relative to the gather in the x-axis
+    :opt_param y_offset: Offset of the scatter relative to the gather in the y-axis
+    :opt_param z_offset: Offset of the scatter relative to the gather in the z-axis
+
+    .. note:: One and only one of the offset fields for the sg_link tag should be set. The magnitude of the offset will generally be chosen by the architecture file creator to match the length of the sg_link segment type.
+
+.. arch:tag:: <sg_location type="string" num="int" sg_link_name="string">
+
+    Instantiates the scatter-gather pattern with the specified sg_link.
+
+    :req_param num: number of scatter-gather instances per matching location (e.g. per switch block)
+    :req_param sg_link_name: name of the sg_link used in the instantiation
+    :req_param type: Can be one of the following strings:
+
+        * ``EVERYWHERE`` – at each switch block of the FPGA
+        * ``PERIMETER`` – at each perimeter switch block (x-directed and/or y-directed channel segments may terminate here)
+        * ``CORNER`` – only at the corner switch blocks (both x and y-directed channels terminate here)
+        * ``FRINGE`` – same as PERIMETER but excludes corners
+        * ``CORE`` – everywhere but the perimeter
+    Sets the location on the FPGA where the connections described by this scatter-gather pattern be instantiated.
+
+
 .. _arch_metadata:
 
 Architecture metadata

doc/src/Images/Routing_Options.png

@@ -1270,13 +1270,17 @@ Analytical Placement is generally split into three stages:
 
     **Default:** ``lp-b2b``
 
-.. option:: --ap_partial_legalizer {bipartitioning | flow-based}
+.. option:: --ap_partial_legalizer {none | bipartitioning | flow-based}
 
     Controls which Partial Legalizer the Global Placer will use in the AP Flow.
     The Partial Legalizer legalizes a placement generated by an Analytical Solver.
     It is used within the Global Placer to guide the solver to a more legal
     solution.
 
+    * ``none`` Does not partially legalize the global placement solution and just
+      passes the last solved solution through. This partial legalizer is only
+      used for testing and debugging and should not be part of any real AP flow.
+
     * ``bipartitioning`` Creates minimum windows around over-dense regions of
       the device bi-partitions the atoms in these windows such that the region
       is no longer over-dense and the atoms are in tiles that they can be placed
@@ -1897,6 +1901,9 @@ The following options are only valid when the router is in timing-driven mode (t
 
      * ``classic``: The classic VPR lookahead
      * ``map``: A more advanced lookahead which accounts for diverse wire types and their connectivity
+     * ``compressed_map``: The algorithm is similar to map lookahead with the exception of sparse sampling of the chip to reduce the run-time to build the router lookahead and also its memory footprint.
+     * ``extended_map``: A more advanced and extended lookahead which accounts for a more exhaustive node sampling method.
+     * ``simple``: A purely distance-based lookahead loaded from an external file using :option:`--read_router_lookahead`. This lookahead returns a cost estimate for channel nodes by querying a lookup table, while for any other node type it returns zero.
 
      **Default:** ``map``
 

doc/src/Images/highlight_flylines.png

@@ -67,27 +67,36 @@ If the **Placement Macros** drop down is set, any placement macros (e.g. carry c
 
     Placement with macros (carry chains) highlighted
 
-Visualizing Netlist Connectivity
---------------------------------
-The **Toggle Nets** drop-down list under the **Net Settings** tab toggles the nets in the circuit to be visible/invisible. Options include **Cluster Nets** and **Primitive Nets**.
+Visualizing Nets
+----------------
+To visualize nets, first enable the **Display Nets** switch under the **Net** Tab.
+
+The user can choose between drawing nets as **Flylines** (direct connections between sources and sinks) or as **Routing** (the actual routed path of the net).
+Only the **Flylines** option is available during placement, as routing has not yet been performed.
+
+The Inter-Cluster Nets and Intra-Cluster Nets options allow the user to choose whether to visualize nets between clbs or within a clb, respectively. The Intra-Cluster Routed Nets option is currently only available when **flat routing is enabled**.
 
 .. figure:: ../Images/Net_Settings.png
     :align: center 
-    :height: 200
 
-    Toggle Nets drop-down under Net Settings tab
+    Net Tab
 
-When a placement is being displayed, routing information is not yet known so nets are simply drawn as a “star;” that is, a straight line is drawn from the net source to each of its sinks.
-Click on any clb in the display, and it will be highlighted in green, while its fanin and fanout are highlighted in blue and red, respectively.
-Once a circuit has been routed the true path of each net will be shown.
+If routing is shown, clicking on a pin or channel wire will highlight the whole net in magenta.
+Multiple nets can be highlighted by pressing ctrl + mouse click.
 
-.. figure:: https://www.verilogtorouting.org/img/des90_nets.gif
+.. figure:: ../Images/show_nets.gif
     :align: center
 
-    Logical net connectivity during placement
+    Visualizing Nets
 
-If the nets routing are shown, click on a clb or pad to highlight its fanins and fanouts, or click on a pin or channel wire to highlight a whole net in magenta.
-Multiple nets can be highlighted by pressing ctrl + mouse click.
+When the **Highlight Block Fan-in and Fan-out** option is enabled, clicking on an internal block will draw its fan-in, fan-out, and internal flylines in blue, red, and yellow, respectively. 
+
+.. figure:: ../Images/highlight_flylines.png
+    :align: center
+
+    Highlight Block Fan-in and Fan-out Flylines
+
+Clicking on a clb (not the internal physical blocks) will also highlight all the fan-in and fan-out routed nets in blue and red, respectively.
 
 Visualizing the Critical Path
 -----------------------------
@@ -113,33 +122,60 @@ The **Crit. Path** drop-down will toggle through the various visualizations:
 Visualizing Routing Architecture
 --------------------------------
 
-When a routing is on screen, the **Routing Options** tab provides various options to gain more visual information.
+During the route stage, the **Route** tab provides various options to visualize router resources and statistics.
 
 .. figure:: ../Images/Routing_Options.png
     :align: center 
     :height: 300
 
     Routing Options
 
-Clicking on **Toggle RR** lets you to choose between various views of the routing resources available in the FPGA.
+To visualize routing architecture, first enable the **Display Routing Resources** switch under the Route tab. Then, click on the checkboxes below to show/hide the types of nodes and edges you want to visualize. 
 
-.. figure:: https://github.com/verilog-to-routing/verilog-to-routing.github.io/raw/master/img/routing_arch.gif
-    :align: center
+The intra-cluster options are currently only available when **flat routing is enabled**. 
+
+The **Highlight Fan-In Fan-Out Edges** option will highlight the fan-in and fan-out edges of the selected routing resource in blue and red, respectively. 
 
-    Routing Architecture Views
+Multiple routing resources can be highlighted by pressing ctrl + mouse click.
+
+.. figure:: ../Images/show_rr_graph.gif
+    :align: center
 
-The routing resource view can be very useful in ensuring that you have correctly described your FPGA in the architecture description file -- if you see switches where they shouldn’t be or pins on the wrong side of a clb, your architecture description needs to be revised.
+    Visualizing Routing Architecture
+
+**Node Colors**:
+
++------------+--------+
+| Node Type  | Color  |
++============+========+
+| Channel    | Black  |
++------------+--------+
+| Input Pin  | Purple |
++------------+--------+
+| Output Pin | Pink   |
++------------+--------+
+
+**Edge Colors**:
+
++-----------------------+---------------+
+| Edge Type             | Color         |
++=======================+===============+
+| Pin to Output Pin     | Light Pink    |
++-----------------------+---------------+
+| Pin to Input Pin      | Medium Purple |
++-----------------------+---------------+
+| Output Pin to Channel | Pink          |
++-----------------------+---------------+
+| Channel to Input Pin  | Purple        |
++-----------------------+---------------+
+| Channel to Channel    | Dark Green    |
++-----------------------+---------------+
+| Non-Configurable Edge | Dark Grey     |
++-----------------------+---------------+
 
-Wiring segments are drawn in black, input pins are drawn in sky blue, and output pins are drawn in pink.
-Sinks are drawn in dark slate blue, and sources in plum.
-Direct connections between output and input pins are shown in medium purple.
-Connections from wiring segments to input pins are shown in sky blue, connections from output pins to wiring segments are shown in pink, and connections between wiring segments are shown in green.
 The points at which wiring segments connect to clb pins (connection box switches) are marked with an ``x``.
 
 Switch box connections will have buffers (triangles) or pass transistors (circles) drawn on top of them, depending on the type of switch each connection uses.
-Clicking on a clb or pad will overlay the routing of all nets connected to that block on top of the drawing of the FPGA routing resources, and will label each of the pins on that block with its pin number.
-Clicking on a routing resource will highlight it in magenta, and its fanouts will be highlighted in red and fanins in blue.
-Multiple routing resources can be highlighted by pressing ctrl + mouse click.
 
 Visualizing Routing Congestion
 ------------------------------