Relatively Placed Macro by amin1377 · Pull Request #3717 · verilog-to-routing/vtr-verilog-to-routing

amin1377 · 2026-07-21T17:37:52Z

This PR adds support for user-defined relative placement macros (RPMs) in VPR constraint files. An RPM fixes the placement of groups of primitives relative to one another without assigning absolute locations, preserving the internal geometry of a hand-optimized block (a DSP with its control logic, a bit-sliced datapath, an IP block) while leaving the placer free to choose where the whole macro goes.

Usage

Add a <relative_macro_list> section to the VPR constraints file passed with --read_vpr_constraints (alongside the existing <partition_list>):

<vpr_constraints tool_name="vpr">
    <relative_macro_list>
        <relative_macro name="dsp_with_ctrl_logic">
            <reference_group>
                <add_atom name_pattern="mult_36.out_reg"/>
            </reference_group>
            <relative_group x_offset="1" y_offset="0" sub_tile_offset="0">
                <add_atom name_pattern="^ctrl_lut_[0-4]$" is_regex="true"/>
            </relative_group>
        </relative_macro>
    </relative_macro_list>
</vpr_constraints>

Each macro has one <reference_group> (the anchor) and one or more <relative_group> elements at fixed (x, y, sub_tile) offsets from it. <add_atom> uses the same matching semantics as in a <partition>.

The group/offset constraints control placement at cluster granularity. To also control placement inside a cluster, <add_atom> optionally takes a site_path attribute that pins the atom to a specific primitive site within its group's cluster. The site is given as the hierarchical path of the primitive in the cluster's pb hierarchy, e.g.:

site_path="clb[0][default]/lab[0][default]/fle[3][n1_lut6]/ble6[0][default]/lut6[0]"

The packer places the atom on exactly that site (packing fails with an error if it can't); atoms without a site_path are placed on whatever site the packer picks. Together, offsets plus site_path allow reproducing a known-good placement exactly, down to the primitive level.

The atoms of each group are packed into a single cluster (groups never share a cluster), and the resulting clusters are placed as one rigid macro — like an architectural carry chain, but supporting heterogeneous block types. The final placement is validated against the constraints.

See doc/src/vpr/relative_placement_constraints.rst for the file-format reference, detailed semantics, and restrictions.

Notes

Offsets are exact: they must be realizable on the device grid, or placement fails after an exhaustive search.
Supported in the classic pack/place flow; the AP flow rejects RPM constraints for now.
Rigid macros reduce annealer mobility, so some QoR degradation versus an unconstrained run is expected as macro size and coverage grow. Unconstrained flows are unaffected.

Testing

Unit tests for the constraints data model, plus a new vtr_reg_strong task (strong_relative_placement) covering mixed-type macros, regex matching, molecule interactions, and end-to-end packing/placement. Also validated on Titan benchmarks with constraint sets derived from baseline placements: all macros placed at their exact offsets with no consistency violations.

… macro tags

… legalizer

…g attraction groups

…rilog-to-routing into relative_placement

…t succeed

…rilog-to-routing into relative_placement

AlexandreSinger

I got up to and including greedy_clusterer.h

I had a lot of blocking comments on this PR. We can discuss offline if needed.

AlexandreSinger · 2026-08-27T19:29:52Z

+
+``site_path`` is the hierarchical path of the primitive the atom was placed on within its
+cluster (``t_pb_graph_node::hierarchical_type_name()``), including the mode selected at each
+level.


This is going to BALLOON the flat placement file size. We should make this optional in my opinion. Can we add a CLI argument so the user can request this?

I agree that this is useful, but AP does use this file as an intermediate file (when used to start from specific stages).

I added a new CLI parameter, --flat_place_verbose, which is off by default. We can also use it later if we want to include more information in the flat place file.

AlexandreSinger · 2026-08-27T19:39:25Z

+                            "of the architecture.\n",
+                            atom_ctx.netlist().block_name(atom).c_str(),
+                            site_path.c_str());
+        }


I do not like this. I think this should be a warning and nothing should be printed. Something like "ERROR" in the file is sufficient to me. Failing the entire flat place file write for optional metadata is very strange to me.

Unless you can prove that its impossible to get spaces from the hierarchical_type_name method; but we would need a guarantee that it implies a bug.

AlexandreSinger · 2026-08-27T19:39:57Z

                static_cast<size_t>(blk_id),
-                atom_pbgn->pb_type->name);
+                atom_pbgn->pb_type->name,
+                site_path.c_str());


See my comment from the documentation. I think that the site_path should be optional.

AlexandreSinger · 2026-08-27T19:47:01Z

+     *
+     * @return The id of the newly added macro.
+     */
+    UserRelativeMacroId add_macro(const UserRelativeMacro& macro);


I like this class a lot since it manages the existing macros in the design (similar to the netlist). Normally for these type of classes, we construct the objects being managed inside the class itself. So I would expect to see a create_macro class which takes the needed arguments. This instead passes in an object and copies it in. This seems a bit odd to me from an API perspective since for a time there will be two copies of the same object in the codebase.

Is there a way that we can have this class construct the macro itself?

I understand that there may be limitation due to the XML parsers; I understand if this is cleaner. If so, you should update the comment slightly to say that this class will now maintain the object. A better solution is to use move semantics for this function: this would imply that ownership is being transferred to this class. The vector of strings in the macro will also be expensive to copy; so using move semantics would also be much faster.

AlexandreSinger · 2026-08-27T19:49:34Z

+    /// @brief Reverse lookup: atom -> the hierarchical path of the primitive
+    ///        site it is locked to. Only holds the locked atoms; a missing atom
+    ///        is unlocked.
+    std::unordered_map<AtomBlockId, std::string> atom_to_site_path_;


This seems a bit expensive to store for what it is. These site paths can be very very long, so the strings are very large. It would be good to only keep a single copy of them in the datastructures.

Why not just use the atom_to_group variable and get the path from within the macro?

AlexandreSinger · 2026-08-27T21:16:19Z

+                                                                       legalization_cluster_id,
+                                                                       cluster_legalizer,
+                                                                       attraction_groups);
+    }


This is speicific to relative groups. I think its confusing to have here. I think we should have a different code path for relative groups.

AlexandreSinger · 2026-08-27T21:18:00Z

+    // matches the sites in the constraints file, so it is not worth keeping
+    // while another sequence is still untried. On the last attempt the cluster
+    // is kept regardless - the leftovers are then reported as a split group by
+    // the end-of-pass check.


I do not understand what this comment is saying. Why does the last attempt matter here?

AlexandreSinger · 2026-08-27T21:18:48Z

+                                 + "). A site path also fixes the block type and the mode at every level, so a "
+                                   "path recorded on another architecture or another mode never matches. "
+                                   "Regenerate the macro against this netlist and architecture.\n";
+        }


This should be outlined to relative macro specific code.

AlexandreSinger · 2026-08-27T21:21:30Z

+    // equivalent LUT/crossbar inputs each net enters through greedily as
+    // molecules arrive, so a sequence that leaves two nets contending for one
+    // input fails where another routes. No variant can move an atom off its
+    // site, and verify_clustering re-checks that afterwards.


I think this is far too much for the packer to deal with. Its super strange to me that we are reversing this explicitly here.

Why not push this on the user? We are going to pack in constraint-file order. If the user put things in a bad order, we can tell them to reverse it. Its a bit arbitrary to me that reversing the order would all of a sudden fix this issue.

AlexandreSinger · 2026-08-27T21:22:32Z

+    // group-4 flip-flops are locked into FF slots of arithmetic-mode FLEs that
+    // the group's own 40-atom carry chain claims first. Molecules that are
+    // never admitted are reported as a split group by the end-of-pass check in
+    // pack.cpp.


I am not following what this paragraph is saying.

amin1377 added 14 commits July 16, 2026 13:59

[vpr][constraint] update constrain file to include relative placement…

01e6e3a

… macro tags

[vpr][base] add UserRelativeGroup to store rel macro info

277d561

[vpr][base] add UserRelativeMacros to VprConstraints

d07fdc3

[vpr][base] add relative_macros to FloorplanningContext

1eb1322

[vpr][base] add functions related to rel placement

c7f4117

[vpr][base] rel place: update autogenerated files

d879710

[vpr][pack] add check_cluster_relative_group and rel_group to cluster…

fc1a0cf

… legalizer

[vpr][pack] add relative macro attraction group functions

ad0d21a

[vpr][pack] add rel mol attraction group in candidate sel

d8bd6b1

[vpr][pack] add check_clustering_relative_group_consistency

f3d36c1

[vpr][pack] add BLK_FAILED_RELATIVE_GROUP to errors

d165bce

[vpr][pack] increase gain for rpm so they get packed firt

fa9dfe0

[vpr][pack] update try pack to check for rpm

2c55729

[vpr][pack] pass group gain and pull_in_initial_search when rebuildin…

d5c82d6

…g attraction groups

github-actions Bot added VPR VPR FPGA Placement & Routing Tool lang-cpp C/C++ code labels Jul 21, 2026

amin1377 added 6 commits July 21, 2026 15:48

[vpr][place] add append_user_defined_macros_

9b2eba4

[vpr][place] fix root location issue with rmp

3ed8f00

[doc][vpr] add rmp doc

05d77c6

[vpr][test] add unit test for UserRelativeMacro

887a988

[ci][strong] add rmp test

8539cd4

Merge branch 'master' of https://github.com/verilog-to-routing/vtr-ve…

d728376

…rilog-to-routing into relative_placement

github-actions Bot added docs Documentation lang-netlist labels Jul 22, 2026

amin1377 added 6 commits July 22, 2026 14:20

make format

86ddaaf

[vpr][pack] recreate attraction group for rel group if packing doesn'…

d230e69

…t succeed

[vpr][pack] remove duplicate attraction groups

0f16846

[vpr][pack] check macro conflict with rel placement

e9e5c9c

[vpr][base] add fast path for get_atom_group

6c4e68c

[vpr][base] improve rmp log msg

91a1bae

amin1377 added 28 commits August 18, 2026 07:51

[vpr][pack] remove bypass paramter

10085e9

[vpr][pack] remove bypass parameter

9de704d

Merge branch 'master' of https://github.com/verilog-to-routing/vtr-ve…

ec0c71b

…rilog-to-routing into relative_placement

[vpr][pack] choose group atoms first

188d87c

[vpr][pack] remove rel group from attraction groups

e0210a5

[vpr][pack] pack rpm clusters first

3851b99

[vpr][pack] remove rpm reservations from cluster legalizer

424f6c7

[vpr][pack] remove attraction group provisions for rpm in pack.cpp

462ec85

[vpr][pack] add get_molecule_relative_group

2b3d0f5

[vpr][place] fix rpm comments

3e4f37c

[vpr][pack] remove remaining code related to prev version of rpm

01f7cd2

[ci] update rpm golden results

9d667b0

[doc][vpr][rpm] add site_path

f4bb71d

[doc][vpr] add doc related to site_path

32f786a

[vpr][constraint] add site_path

862ad89

[vpr][base] print site_path when writing flat place file

633ba3e

[vpr][base] add atom sith path to rpm ds

14bf26b

[vpr][pack] use forced_placement in cluster_placement

7e9082e

[vpr][pack] record why atom in rpm cannot be placed

9880676

[vpr][pack] pack rpm forced sites first in greedy clusterer

c2f6244

[doc] update RPM doc

c5f4f46

[vpr][base] update constrain serializer with site_path

58e121a

[vpr][pack] check for molecule root rpm constraint

c54be42

[vpr][pack] verify site_path is honored

e0bc8d5

[vpr][test] add unit test for rpm

189a507

[ci] update rpm test

d4ab376

Merge branch 'master' of https://github.com/verilog-to-routing/vtr-ve…

8b29a8f

…rilog-to-routing into relative_placement

Merge branch 'master' of https://github.com/verilog-to-routing/vtr-ve…

ddf2fb6

…rilog-to-routing into relative_placement

amin1377 changed the title ~~Relative placement macro~~ Relatively Placed Macro Aug 27, 2026

AlexandreSinger requested changes Aug 27, 2026

View reviewed changes

Uh oh!

Conversation

amin1377 commented Jul 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Usage

Notes

Testing

Uh oh!

AlexandreSinger left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

amin1377 commented Jul 21, 2026 •

edited

Loading