legalizer documentation

Author: KA7E

doc/src/vpr/command_line_usage.rst

@@ -95,6 +95,12 @@ VPR runs all stages of (pack, place, route, and analysis) if none of :option:`--
 
     **Default:** ``off``
 
+.. option:: --legalize
+
+    Reconstruct a clustering and placement solution from an input flat placement file (use of this option supercedes option:: --pack).
+
+    **Default:** ``off``
+
 .. _graphics_options:
 
 Graphics Options
@@ -334,6 +340,12 @@ Use the options below to override this default naming behaviour.
 
     **Default:** :option:`circuit <circuit>`.route
 
+.. option:: --flat_place_file <file>
+
+    Path to input :ref:`flat placement file <vpr_flat_placement_file>`.
+
+    **Default:** :option:`circuit <circuit>`.route
+
 .. option:: --sdc_file <file>
 
     Path to SDC timing constraints file.
@@ -927,6 +939,11 @@ Setting any of the following 5 options selects :ref:`Dusty's annealing schedule
 
     **Default:** ``-2``
 
+.. option:: --write_flat_place <file>
+
+    Write out a post-placement flat placement file (see :ref:`Flat Placement File Format<vpr_flat_placement_file>`).
+
+    **Default:** ``off``
 
 .. _timing_driven_placer_options:
 
@@ -1845,6 +1862,18 @@ The following options are used to enable server mode in VPR.
 
     **Default:** ``60555``
 
+Legalizer Options
+^^^^^^^^^^^^^^^^^^^^^^^^
+The following options are available when VPR's legalizer is invoked to reconstruct a clustering and placement solution from a flat placement file (see :ref:`Flat Placement File Format<vpr_flat_placement_file>`).
+
+.. note:: Use :option:`vpr --legalize` and `vpr --flat_place_file <file>` to invoke the legalizer and specify an input flat placement file.
+
+.. option:: --write_fixed_clusters <file>
+
+    Write out a (possibly incomplete) clustered placement file listing placement coordinates for clusters reconstructed from an input flat placement file. If placement is run after the legalizer, this file is automatically set as an input placement constraints file.
+
+    **Default:** ``fixed_clusters.out``
+
 Command-line Auto Completion
 ----------------------------
 

doc/src/vpr/file_formats.rst

@@ -738,6 +738,68 @@ An example listing for a global net is given below.
     Block pksi_185_ (#432) at (5,48), pinclass 2
     Block n_n2879 (#433) at (49,23), pinclass 2
 
+.. _vpr_flat_placement_file:
+
+Flat Placement File Format (.flat_place)
+----------------------------------------
+The flat placement file contains the information needed for VPR's legalizer to reconstruct a clustering and placement solution,
+inferring mode and intra-cluster routing information and correcting legality violations as needed. 
+
+Each line in the flat placement file corresponds to a netlist primitive and has the following format::
+
+    primitive_name    X    Y    Subtile    Site   # optional extra info
+
+The ``primitive_name`` is the netlist name of the primitive (see :ref:`VPR netlist naming conventions<vpr_blif_naming_convention_primitives>`).
+``X``, ``Y``, and ``Subtile`` describe the placement coordinates of the complex block within which the primitive should be placed (see :ref:`VPR Placement File Format<vpr_place_file>`).
+``Site`` is the ``flat site index`` on which the primitive should be placed. The flat site index is the index of a primitive site within its primitive type within its complex block type. Values are in [0...total_primitive_count-1], e.g. if there are 10 ALMs per cluster, 2 FFS and 2 LUTs per ALM, then flat site indices for FFs would run from 0 to 19, and flat site indices for LUTs would run from 0 to 19.
+Optional information, e.g. cluster index or primitive type name, may be included after the `Site`; the legalizer ignores this information.
+
+Example flat placement file entries are shown below:
+
+.. code-block:: none
+   :caption: Example flat placement file entries
+   :linenos:
+
+   # netlist primitive name         X    Y  subtile   site    # optional info
+   hh_core:hh_core_0|cycles_lo[0]  53   24     0       19     # 86 dffeas
+   hh_core:hh_core_0|cycles_lo[1]  53   24     0       18     # 86 dffeas
+   hh_core:hh_core_0|cycles_lo[2]  53   24     0       17     # 86 dffeas
+   hh_core:hh_core_0|cycles_lo[3]  53   24     0       16     # 86 dffeas
+   hh_core:hh_core_0|cycles_lo[4]  53   24     0       15     # 86 dffeas
+   hh_core:hh_core_0|cycles_lo[5]  53   24     0       14     # 86 dffeas
+   hh_core:hh_core_0|cycles_lo[6]  53   24     0       13     # 86 dffeas
+   # below is the root of a carry chain segment
+   hh_core:hh_core_0|Add0~2        53   24     0        0     # 86 lcell_comb
+   # below is the rest of the carry chain segment (ignored by the VPR legalizer)
+   hh_core:hh_core_0|Add0~6        53   24     0        1     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~10       53   24     0        2     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~14       53   24     0        3     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~18       53   24     0        4     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~22       53   24     0        5     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~26       53   24     0        6     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~30       53   24     0        7     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~34       53   24     0        8     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~38       53   24     0        9     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~42       53   24     0       10     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~46       53   24     0       11     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~50       53   24     0       12     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~54       53   24     0       13     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~58       53   24     0       14     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~62       53   24     0       15     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~66       53   24     0       16     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~70       53   24     0       17     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~74       53   24     0       18     # 86 lcell_comb
+   hh_core:hh_core_0|Add0~78       53   24     0       19     # 86 lcell_comb
+
+For complex pack molecules such as carry chains (see :ref: `Pack Patterns in <arch_complex_blocks>`), it is only necessary to include the root primitive in the flat placement file; the legalizer ignores non-root primitives and places all primitives in each pack molecule based on the root primitive entry. In the example file above, all lcell_comb instances shown are part of a carry chain segment, and so all except the root primitive are ignored.
+VPR's legalizer does not require the flat placement file to contain every primitive in the netlist; it will reconstruct the portion of the netlist and print a warning if the file does not cover the entire netlist. This functionality is useful for debugging legalization in an external placement tool.
+
+.. note:: Use :option:`vpr --legalize` and `vpr --flat_place_file <file>` to invoke the legalizer and specify an input flat placement file.
+
+.. note: Use :option:`vpr --write_flat_place <file>` to write out a post-placement flat placement file. Use :option:`vpr --echo_file on` to write out a (possibly incomplete) post-legalization flat placement file (the file will be named `post_legalizer_flat_placement.echo`).
+
+.. note: A flat placement file must correspond to a specific XML architecture file and a specific fixed size device layout (see :ref: `FPGA Grid Layout <arch_grid_layout>`). Use :option:`vpr --device <fixed layout name>` to specify a fixed device layout.
+
 .. _vpr_route_resource_file:
 
 Routing Resource Graph File Format (.xml)