From f13014869efb423509751aac96b0fd4f5c00b823 Mon Sep 17 00:00:00 2001 From: KA7E Date: Wed, 19 Jun 2024 07:10:25 -0400 Subject: [PATCH 1/5] legalizer documentation --- doc/src/vpr/command_line_usage.rst | 29 ++++++++++++++ doc/src/vpr/file_formats.rst | 62 ++++++++++++++++++++++++++++++ 2 files changed, 91 insertions(+) diff --git a/doc/src/vpr/command_line_usage.rst b/doc/src/vpr/command_line_usage.rst index 3895d071ee5..44a658d3781 100644 --- a/doc/src/vpr/command_line_usage.rst +++ b/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 `.route +.. option:: --flat_place_file + + Path to input :ref:`flat placement file `. + + **Default:** :option:`circuit `.route + .. option:: --sdc_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 + + Write out a post-placement flat placement file (see :ref:`Flat Placement File Format`). + + **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`). + +.. note:: Use :option:`vpr --legalize` and `vpr --flat_place_file ` to invoke the legalizer and specify an input flat placement file. + +.. option:: --write_fixed_clusters + + 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 ---------------------------- diff --git a/doc/src/vpr/file_formats.rst b/doc/src/vpr/file_formats.rst index cc114105810..cc61539b8f7 100644 --- a/doc/src/vpr/file_formats.rst +++ b/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`). +``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`). +``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 `), 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 ` to invoke the legalizer and specify an input flat placement file. + +.. note: Use :option:`vpr --write_flat_place ` 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 `). Use :option:`vpr --device ` to specify a fixed device layout. + .. _vpr_route_resource_file: Routing Resource Graph File Format (.xml) From cea8247bfff95b03f789b121a951255a4c0eea83 Mon Sep 17 00:00:00 2001 From: KA7E Date: Wed, 19 Jun 2024 07:28:54 -0400 Subject: [PATCH 2/5] nitpicks --- doc/src/vpr/command_line_usage.rst | 6 ++++-- doc/src/vpr/file_formats.rst | 17 +++++++++++------ 2 files changed, 15 insertions(+), 8 deletions(-) diff --git a/doc/src/vpr/command_line_usage.rst b/doc/src/vpr/command_line_usage.rst index 44a658d3781..4187d3dd72b 100644 --- a/doc/src/vpr/command_line_usage.rst +++ b/doc/src/vpr/command_line_usage.rst @@ -97,7 +97,8 @@ VPR runs all stages of (pack, place, route, and analysis) if none of :option:`-- .. option:: --legalize - Reconstruct a clustering and placement solution from an input flat placement file (use of this option supercedes option:: --pack). + Reconstruct a clustering and placement solution from an input flat placement file. + Use of this option supercedes option:: --pack. **Default:** ``off`` @@ -1870,7 +1871,8 @@ The following options are available when VPR's legalizer is invoked to reconstru .. option:: --write_fixed_clusters - 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. + 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 legalization, this file is automatically set as an input placement constraints file. **Default:** ``fixed_clusters.out`` diff --git a/doc/src/vpr/file_formats.rst b/doc/src/vpr/file_formats.rst index cc61539b8f7..bf400bd2162 100644 --- a/doc/src/vpr/file_formats.rst +++ b/doc/src/vpr/file_formats.rst @@ -747,13 +747,18 @@ inferring mode and intra-cluster routing information and correcting legality vio 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 + 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`). -``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`). -``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. + +``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`). + +The``site`` specifies the ``flat site index`` of the primitive site on which the primitive should be placed, i.e. the index of the primitive type site within its complex block type. For example, if there are 10 ALMs per cluster, 2 FFs and 2 LUTs per ALM, then flat site indices for FFs and LUTs would each 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. +.. note:: The primitives in a flat placement file can be listed in any order. + Example flat placement file entries are shown below: .. code-block:: none @@ -791,14 +796,14 @@ Example flat placement file entries are shown below: 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 `), 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. +For complex pack molecules such as carry chains (see :ref:`Pack Patterns in `), 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 ` to invoke the legalizer and specify an input flat placement file. +.. note:: Use :option:`vpr --legalize` and :option:`vpr --flat_place_file ` to invoke the legalizer and specify an input flat placement file. .. note: Use :option:`vpr --write_flat_place ` 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 `). Use :option:`vpr --device ` to specify a fixed device layout. +.. 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 `). Use :option:`vpr --device ` to specify a fixed device layout. .. _vpr_route_resource_file: From 23651f104f3e488e5c736c682b698a80c9fa0eb5 Mon Sep 17 00:00:00 2001 From: KA7E Date: Wed, 19 Jun 2024 07:33:48 -0400 Subject: [PATCH 3/5] more nitpicks --- doc/src/vpr/command_line_usage.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/src/vpr/command_line_usage.rst b/doc/src/vpr/command_line_usage.rst index 4187d3dd72b..17a7a44412e 100644 --- a/doc/src/vpr/command_line_usage.rst +++ b/doc/src/vpr/command_line_usage.rst @@ -98,7 +98,8 @@ VPR runs all stages of (pack, place, route, and analysis) if none of :option:`-- .. option:: --legalize Reconstruct a clustering and placement solution from an input flat placement file. - Use of this option supercedes option:: --pack. + Must be used with :option:`--flat_place_file '. + Use of this option supercedes option::`--pack`. **Default:** ``off`` @@ -1867,7 +1868,7 @@ 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`). -.. note:: Use :option:`vpr --legalize` and `vpr --flat_place_file ` to invoke the legalizer and specify an input flat placement file. +.. note:: Use :option:`vpr --legalize` and :option:`vpr --flat_place_file ` to invoke the legalizer and specify an input flat placement file. .. option:: --write_fixed_clusters From c70db45b4ebb7a8a6adf1e57353075675f6f966a Mon Sep 17 00:00:00 2001 From: KA7E Date: Fri, 21 Jun 2024 07:32:18 -0400 Subject: [PATCH 4/5] updates based on Vaughn's comments --- doc/src/vpr/command_line_usage.rst | 4 ++-- doc/src/vpr/file_formats.rst | 6 ++++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/doc/src/vpr/command_line_usage.rst b/doc/src/vpr/command_line_usage.rst index 17a7a44412e..3637fb9098a 100644 --- a/doc/src/vpr/command_line_usage.rst +++ b/doc/src/vpr/command_line_usage.rst @@ -346,7 +346,7 @@ Use the options below to override this default naming behaviour. Path to input :ref:`flat placement file `. - **Default:** :option:`circuit `.route + **Default:** :option:`circuit `.flat_place .. option:: --sdc_file @@ -1873,7 +1873,7 @@ The following options are available when VPR's legalizer is invoked to reconstru .. option:: --write_fixed_clusters 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 legalization, this file is automatically set as an input placement constraints file. + If placement is run after legalization (in the same vpr run), this file is automatically used to constrain the placement of the clusters listed within it. If placement is run in a separate vpr run, this file should be specified using :option:`--fix_clusters `. **Default:** ``fixed_clusters.out`` diff --git a/doc/src/vpr/file_formats.rst b/doc/src/vpr/file_formats.rst index bf400bd2162..d086f6b772e 100644 --- a/doc/src/vpr/file_formats.rst +++ b/doc/src/vpr/file_formats.rst @@ -744,7 +744,7 @@ 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. - +This input file format can be used as an alternative to the packed netlist (.net) and clustered placment (.place) files; the more succinct and higher-level input format permits an external tool to more easily provide a packing and placement solution to VPR. 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 @@ -797,7 +797,7 @@ Example flat placement file entries are shown below: 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 `), 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. +VPR's legalizer does not require the flat placement file to contain every primitive in the netlist; it will reconstruct the packing and placement for the specified 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 :option:`vpr --flat_place_file ` to invoke the legalizer and specify an input flat placement file. @@ -805,6 +805,8 @@ VPR's legalizer does not require the flat placement file to contain every primit .. 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 `). Use :option:`vpr --device ` to specify a fixed device layout. +.. note: Currently, this file format only supports 2D FPGA architectures. + .. _vpr_route_resource_file: Routing Resource Graph File Format (.xml) From 842d8510ae929d913eee77993e2f254bffa685de Mon Sep 17 00:00:00 2001 From: KA7E <54366706+KA7E@users.noreply.github.com> Date: Mon, 15 Jul 2024 12:09:42 -0400 Subject: [PATCH 5/5] Update command_line_usage.rst --- doc/src/vpr/command_line_usage.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/src/vpr/command_line_usage.rst b/doc/src/vpr/command_line_usage.rst index 3637fb9098a..7054ae882c0 100644 --- a/doc/src/vpr/command_line_usage.rst +++ b/doc/src/vpr/command_line_usage.rst @@ -98,8 +98,7 @@ VPR runs all stages of (pack, place, route, and analysis) if none of :option:`-- .. option:: --legalize Reconstruct a clustering and placement solution from an input flat placement file. - Must be used with :option:`--flat_place_file '. - Use of this option supercedes option::`--pack`. + Use of this option supercedes :option:`--pack`. **Default:** ``off``