From 24de2f286865367589fca5a66f36e7829fd76e1f Mon Sep 17 00:00:00 2001
From: Tynan McAuley <tynan@niobiummicrosystems.com>
Date: Wed, 10 Jan 2024 12:17:29 -0800
Subject: [PATCH] Add Instance.suggestName (#2886)

Co-authored-by: Aditya Naik <aditya.naik@sifive.com>
Co-authored-by: Jack Koenig <koenig@sifive.com>
---
 .../experimental/hierarchy/ModuleClone.scala  |  6 +++
 .../hierarchy/core/Instance.scala             |  8 +++-
 .../experimental/hierarchy/InstanceSpec.scala | 46 ++++++++++++++++++-
 3 files changed, 58 insertions(+), 2 deletions(-)

diff --git a/core/src/main/scala/chisel3/experimental/hierarchy/ModuleClone.scala b/core/src/main/scala/chisel3/experimental/hierarchy/ModuleClone.scala
index c10d3e396f1..ae9ca157d73 100644
--- a/core/src/main/scala/chisel3/experimental/hierarchy/ModuleClone.scala
+++ b/core/src/main/scala/chisel3/experimental/hierarchy/ModuleClone.scala
@@ -71,4 +71,10 @@ private[chisel3] class ModuleClone[T <: BaseModule](val getProto: T)(implicit si
 
     this.setRef(Ref(instName))
   }
+
+  override def suggestName(seed: => String): this.type = {
+    // Forward the suggestName to the underlying _portsRecord
+    _portsRecord.suggestName(seed)
+    this
+  }
 }
diff --git a/core/src/main/scala/chisel3/experimental/hierarchy/core/Instance.scala b/core/src/main/scala/chisel3/experimental/hierarchy/core/Instance.scala
index e448d3361c1..1b957dc10a5 100644
--- a/core/src/main/scala/chisel3/experimental/hierarchy/core/Instance.scala
+++ b/core/src/main/scala/chisel3/experimental/hierarchy/core/Instance.scala
@@ -6,7 +6,7 @@ import scala.language.experimental.macros
 import chisel3._
 import chisel3.experimental.hierarchy.{InstantiableClone, ModuleClone}
 import chisel3.internal.{throwException, Builder}
-import chisel3.experimental.{BaseModule, ExtModule, SourceInfo}
+import chisel3.experimental.{BaseModule, ExtModule, SourceInfo, UnlocatableSourceInfo}
 import chisel3.internal.sourceinfo.InstanceTransform
 import chisel3.internal.firrtl.{Component, DefBlackBox, DefClass, DefIntrinsicModule, DefModule, Port}
 import firrtl.annotations.IsModule
@@ -93,6 +93,12 @@ object Instance extends SourceInfoDoc {
       case Clone(x: IsClone[_] with BaseModule) => x.toAbsoluteTarget
       case _ => throw new InternalErrorException("Match error: i.underlying=${i.underlying}")
     }
+
+    def suggestName(name: String): Unit = i.underlying match {
+      case Clone(m: BaseModule) => m.suggestName(name)
+      case Proto(m) => m.suggestName(name)
+      case x        => Builder.exception(s"Cannot call .suggestName on $x")(UnlocatableSourceInfo)
+    }
   }
 
   /** A constructs an [[Instance]] from a [[Definition]]
diff --git a/src/test/scala/chiselTests/experimental/hierarchy/InstanceSpec.scala b/src/test/scala/chiselTests/experimental/hierarchy/InstanceSpec.scala
index 169f36fdc28..45d56a563f7 100644
--- a/src/test/scala/chiselTests/experimental/hierarchy/InstanceSpec.scala
+++ b/src/test/scala/chiselTests/experimental/hierarchy/InstanceSpec.scala
@@ -3,6 +3,7 @@
 package chiselTests
 package experimental.hierarchy
 
+import circt.stage.ChiselStage.emitCHIRRTL
 import chisel3._
 import chisel3.experimental.BaseModule
 import chisel3.experimental.hierarchy.{instantiable, public, Definition, Instance}
@@ -453,7 +454,6 @@ class InstanceSpec extends ChiselFunSpec with Utils {
       }
       def f(i: Seq[Instance[AddTwo]]): Data = i.head.i0.innerWire
       val (c, annos) = getFirrtlAndAnnos(new Top)
-      println(c.serialize)
       //TODO: Should this be ~Top|Top... ??
       annos.collect { case c: MarkAnnotation => c } should contain(
         MarkAnnotation("~Top|AddTwo/i0:AddOne>innerWire".rt, "blah")
@@ -1213,4 +1213,48 @@ class InstanceSpec extends ChiselFunSpec with Utils {
       getFirrtlAndAnnos(new HasMultipleTypeParamsInside, Seq(aspect))
     }
   }
+  describe("(11) .suggestName") {
+    it("11.1 suggestName for Instances") {
+      class Top extends Module {
+        val definition = Definition(new AddOne)
+        val inst0 = Instance(definition)
+        val inst1 = Module(new AddOne).toInstance
+        inst0.suggestName("potato")
+        inst1.suggestName("potato")
+      }
+      val chirrtl = emitCHIRRTL(new Top)
+      chirrtl should include("inst potato of AddOne")
+      chirrtl should include("inst potato_1 of AddOne_1")
+    }
+    it("11.2 suggestName at instantiation") {
+      class Top extends Module {
+        val k = Instance(Definition(new AddOne)).suggestName("potato")
+      }
+      val chirrtl = emitCHIRRTL(new Top)
+      chirrtl should include("inst potato of AddOne")
+    }
+    it("11.3 suggestName with sanitization") {
+      class Top extends Module {
+        val definition = Definition(new AddOne)
+        val inst0 = Instance(definition)
+        val inst1 = Instance(definition)
+        inst0.suggestName("potato")
+        inst1.suggestName("potato")
+      }
+      val chirrtl = emitCHIRRTL(new Top)
+      chirrtl should include("inst potato of AddOne")
+      chirrtl should include("inst potato_1 of AddOne")
+    }
+    it("11.4 suggestName with multi-def collision sanitization") {
+      class Top extends Module {
+        val potato = Wire(UInt(8.W))
+        val inst0 = Module(new AddOne()).suggestName("potato")
+        val inst1 = Instance(Definition(new AddOne)).suggestName("potato")
+      }
+      val chirrtl = emitCHIRRTL(new Top)
+      chirrtl should include("wire potato : UInt<8>")
+      chirrtl should include("inst potato_1 of AddOne")
+      chirrtl should include("inst potato_2 of AddOne_1")
+    }
+  }
 }