Renaming Nets

[Laura L.]

Hello,

I am trying to play around with RapidWright's advertised functionality of being able to read in .dcp files, modify them, and write them back out. To this end, I'm trying to rename a net after reading in a .dcp file and write it back out to open in Vivado. I attempted with the following code:

Design d = Design.readCheckpoint("file.dcp")

Net net = d.getNet("and2")

net.rename("and1")

d.writeCheckpoint("new_file.dcp")

where file.dcp is just any .dcp file, for example, I was trying with the one outputted by the HelloWorld tutorial. I also tried net.setName and net.updateName, but when I open the new file in Vivado, the net name isn't updated. Am I misunderstanding how to rename things? I also printed out the names of all of the nets for the design and it seems to have changed but Vivado doesn't reflect this.

Thank you,

Laura

[RapidWright]

Hi Laura,

That is a good question.  The API Net.rename() has the following Javadoc: 

"Updates the physical net to the name provided. Does not support updating physical net names that belong to Modules or ModuleInsts. Does not update logical net in any way."

So to give some background, designs have two views or representations.  There is a logical view--this is the netlist with hierarchy and is produced after synthesis.  There is also a physical view which captures the placement and routing or the mapping of the logical netlist to the actual device being targeted.  The Net and Cell class are used for the physical netlist representation.  Figures 5 and 6 from our FPGA'2019 paper illustrate how multiple logical nets map to a single physical net:

Your example correctly updates the physical net name, however, there is a logical net name (in other cases, potentially more) that also needs to be changed.  So, I believe you'll also want to change the logical net name as well.  Since the logical net is not a hierarchical one, it should be straight forward.  If you were to make a net name change from "a/b/c" to "x/y/z", that would be quite involved and would probably need another discussion.

It turns out there was not a EDIFNet.rename() (logical net) method, so I wrote one and just added it.  So my example code that I believe does what you intended is below:

        Design d = Design.readCheckpoint("HelloWorld.dcp");

        Net n = d.getNet("and2");

        String newName = "and1";

        n.rename(newName);

        n.getLogicalNet().rename(newName);

        d.writeCheckpoint("HelloWorld_renamed.dcp");

You'll have to pull the latest changes from the RapidWright repo on GitHub to get it to work, but it does show the net correctly renamed in Vivado.

Let me know if you have any questions.

Chris

[Laura L.]

Hi,

I see, that makes sense, I also got it working on my end with this fix. Also, I noticed there are other methods in the Net class, setName and updateName, what is the difference between these methods and rename?

Now, I am also a bit curious about the hierarchical case though. Would this use the EDIFHierNet class, perhaps with the method of setHierarchalInstName?

Thank you,

Laura

[RapidWright]

Hi Laura,

It can be confusing with Net.rename(), Net.setName() and Net.updateName().  Ideally we wouldn't have so many similar APIs, however, because the Net class is not open source, we have to provide some different functionality for different situations that has to compromise. To summarize their usage:

Net.rename() - Renames a physical net such that all locations where the physical net name is used is updated.  However, as we already discussed, it doesn't update the logical name because of some complications due to hierarchy.

Net.setName() - Simply updates the name inside the Net object.  It doesn't propagate the name change anywhere else it is used (SiteInst, Design, etc).  Probably not one you'd want to use.

Net.updateName() - When instantiating modules (ModuleInst class), a level of physical hierarchy is created and this method is used for updating the name of the net accordingly.

Regarding the renaming of hierarchical net names, you have to be careful as a hierarchical name describes where the net resides in the hierarchy.  Consider this simple netlist:

There are 3 logical nets, A, B, and C which form one physical net called disneyland/tomorrowland/monorail (The physical net name almost always takes on the logical name of the source of the net).  If you wanted to change the net name from:

disneyland/tomorrowland/monorail -> disneyworld/adventureland/peoplemover

You'd be changing two instance names and one logical net name.  Changing hierarchical netlists is doable, but comes with some overhead.  To summarize:

1. Cell instance "disneyland" -> "disneyworld"
2. Cell instance "tomorrowland" -> "adventureland"
3. Logical net "monorail" -> "peoplemover"

The local logical net name "monorail" in each cell type would stay the same except in the tomorrowland instance, so, to list out the new hierarchical names of A, B and C post transformation it would be:

A: disneyworld/adventureland/peoplemover

B: disneyworld/monorail

C: monorail

The A, B and C logical nets are called "Aliases" in Vivado if you select a physical net and navigate to the Net Properties window, for example:

Hope that helps.

Chris

[Laura L.]

Hi,

Thank you so much this explanation is very helpful!

Laura