Contest-specific DCP to FPGA Interchange Format Utility (#10)

* Add DcpToFPGAIF.java

Signed-off-by: Eddie Hung <[email protected]>

* Discover alternate sources

Signed-off-by: Eddie Hung <[email protected]>

* Add import, fix exit code

Signed-off-by: Eddie Hung <[email protected]>

* Update README.md

* Update README.md

* Update details.md

* Update FAQ.md

* Update README.md

---------

Signed-off-by: Eddie Hung <[email protected]>

README.md

@@ -4,7 +4,13 @@ Please see website at https://xilinx.github.io/fpga24_routing_contest.
 
 Please report all issues using the GitHub [Issues](https://github.com/Xilinx/fpga24_routing_contest/issues) feature, and ask questions under [Discussions](https://github.com/Xilinx/fpga24_routing_contest/discussions).
 
-All content in this repository except for third-party software (Gradle) is licensed under:
+---
+All content in this repository except for third-party software ([Gradle](https://gradle.org)) is licensed under:
 ```
 SPDX-License-Identifier: MIT
 ```
+---
+
+Utilities:
+* [`net_printer`](https://github.com/Xilinx/fpga24_routing_contest/tree/master/net_printer) -- inspect the routing of nets in a Physical Netlist.
+* [`DcpToFPGAIF`](https://github.com/Xilinx/fpga24_routing_contest/pull/10) -- process a DCP into FPGAIF Logical and Physical Netlists for use with this contest.

docs/FAQ.md

@@ -55,6 +55,8 @@ Any router provided that generates a legal solution will be accepted.  We welcom
 
 We welcome and are interested in any ML and DL approaches.  We recognize the need for large amounts of training data and will provide ways of generating many more benchmark designs beyond the examples that are provided.  For example, Vivado can be used to synthesize and place any compatible design onto the contest device, and [RapidWright](https://github.com/Xilinx/RapidWright) used to convert that into the FPGA Interchange Format to serve as training data.  
 
+*EDIT (2023/10/11):* The [`DcpToFPGAIF`](https://github.com/Xilinx/fpga24_routing_contest/pull/10) utility can now process any DCP into FPGAIF Logical and Physical Netlists for use with this contest.
+
 ### Will you provide access to ML/DL libraries to support inference? 
 
 Although the specific mechanics of solution delivery are still being finalized, teams will be able to provide containerized solutions (e.g. Docker) where teams can configure their environment to include the necessary libraries to run their solution.  

docs/details.md

@@ -34,7 +34,10 @@ Starting from benchmarks described in RTL, Vivado is used to synthesize, place,
 nets (preserving only global, VCC and GND nets) and writes this result out into FPGA Interchange Format
 Logical and Physical Netlists.
 These steps are not mandatory for contestants to run -- a number of FPGAIF benchmarks are provided (with more
-to follow). 
+to follow).
+
+Should contestants wish to test/train with more benchmarks than those that are provided, the 
+[`DcpToFPGAIF`](https://github.com/Xilinx/fpga24_routing_contest/pull/10) utility is provided.
 
 #### Router
 With just the pre-placed but partially-routed input Physical Netlist, competitors are required to route all

src/com/xilinx/fpga24_routing_contest/DcpToFPGAIF.java

@@ -0,0 +1,63 @@
+/*
+ * Copyright (C) 2023, Advanced Micro Devices, Inc.  All rights reserved.
+ *
+ * Author: Eddie Hung, AMD
+ *
+ * SPDX-License-Identifier: MIT
+ *
+ */
+
+package com.xilinx.fpga24_routing_contest;
+
+import com.xilinx.rapidwright.design.Design;
+import com.xilinx.rapidwright.design.DesignTools;
+import com.xilinx.rapidwright.design.SitePinInst;
+import com.xilinx.rapidwright.design.Net;
+import com.xilinx.rapidwright.interchange.LogNetlistWriter;
+import com.xilinx.rapidwright.interchange.PhysNetlistWriter;
+import com.xilinx.rapidwright.util.FileTools;
+
+import java.io.IOException;
+
+public class DcpToFPGAIF {
+    public static void main(String[] args) throws IOException {
+        if (args.length != 3) {
+            System.err.println("USAGE: <input.dcp> <output.netlist> <output.phys>");
+            System.exit(1);
+        }
+
+        Design design = Design.readCheckpoint(args[0]);
+
+        // Even though the design is fully placed-and-routed, still need to call this to
+        // infer any unrouted SitePinInst-s from nets with hierarchical ports --- not for
+        // routing to since they are out-of-context ports --- but so that it's clear to
+        // other nets that those nodes are off limits
+        DesignTools.createMissingSitePinInsts(design);
+
+        for (Net net : design.getNets()) {
+            if (net.isStaticNet() || net.isClockNet()) {
+                continue;
+            }
+
+            // Where a net only has a single source, try and discover if an alternate
+            // source exists
+	    SitePinInst altSource = net.getAlternateSource();
+	    if (altSource == null) {
+	            altSource = DesignTools.getLegalAlternativeOutputPin(net);
+	            if (altSource != null) {
+                            // Commit this pin to the SiteInst
+                            altSource.getSiteInst().addPin(altSource);
+                            DesignTools.routeAlternativeOutputSitePin(net, altSource);
+	            }
+	    }
+
+            net.unroute();
+        }
+
+        PhysNetlistWriter.writePhysNetlist(design, args[2]);
+
+        // Write logical netlist after physical since it collapses macros
+        LogNetlistWriter.writeLogNetlist(design.getNetlist(), args[1]);
+    }
+}
+