Merge branch 'master' into gui_update

Author: SamuelHo10

doc/src/arch/reference.rst

@@ -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/arch/scatter_gather_images/scattergather_diagram.png

@@ -1240,14 +1240,19 @@ Analytical Placement is generally split into three stages:
 
     Analytical Placement is experimental and under active development.
 
-.. option:: --ap_analytical_solver {qp-hybrid | lp-b2b}
+.. option:: --ap_analytical_solver {identity | qp-hybrid | lp-b2b}
 
     Controls which Analytical Solver the Global Placer will use in the AP Flow.
     The Analytical Solver solves for a placement which optimizes some objective
     function, ignorant of the FPGA legality constraints. This provides a "lower-
     bound" solution. The Global Placer will legalize this solution and feed it
     back to the analytical solver to make its solution more legal.
 
+    * ``identity`` Does not formulate any equations and just passes the last
+      legalized solution through. In the first iteration, it initializes all blocks
+      to the center of the device. This solver is only used for testing and
+      debugging and should not be part of any real AP flow.
+
     * ``qp-hybrid`` Solves for a placement that minimizes the quadratic HPWL of
       the flat placement using a hybrid clique/star net model (as described in
       FastPlace :cite:`Viswanathan2005_FastPlace`).
@@ -1261,13 +1266,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
@@ -1882,6 +1891,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``