Refine annotate and Targetable (backport #4698) (#4703)

* Refine annotate and Targetable (#4698)

Some minor improvements to the user API for annotating with Targetable
* Support annotating Seq[Targetable] and provide Targetable for AnyTargetable.
* Add AnyTargetable.apply for simpler manual conversions.
* Show tests annotating Seq[Targetable] and manual use of AnyTargetable.

(cherry picked from commit e20069e)

* Run formatting

---------

Co-authored-by: Jack Koenig <[email protected]>

Author: chiselbot

core/src/main/scala/chisel3/Annotation.scala

@@ -69,6 +69,17 @@ object annotate {
       def toFirrtl: Seq[Annotation] = mkAnnos
     }
   }
+
+  /** Create annotations.
+    *
+    * Avoid this API if possible.
+    *
+    * Anything being annotated must be passed as arguments so that Chisel can do safety checks.
+    * The caller is still responsible for calling .toTarget on those arguments in mkAnnos.
+    */
+  def apply[T: Targetable](targets: Seq[T])(mkAnnos: => Seq[Annotation]): Unit = {
+    annotate(targets.map(t => AnyTargetable.toAnyTargetable(t)): _*)(mkAnnos)
+  }
 }
 
 /** Marks that a module to be ignored in Dedup Transform in Firrtl pass

core/src/main/scala/chisel3/experimental/Targetable.scala

@@ -95,6 +95,14 @@ object Targetable {
     def toRelativeTargetToHierarchy(a: HasTarget, root: Option[Hierarchy[BaseModule]]): IsMember =
       a.toRelativeTargetToHierarchy(root)
   }
+
+  implicit def forAnyTargetable: Targetable[AnyTargetable] = new Targetable[AnyTargetable] {
+    def toTarget(a:                    AnyTargetable):      IsMember = a.toTarget
+    def toAbsoluteTarget(a:            AnyTargetable): IsMember = a.toAbsoluteTarget
+    def toRelativeTarget(a:            AnyTargetable, root: Option[BaseModule]): IsMember = a.toRelativeTarget(root)
+    def toRelativeTargetToHierarchy(a: AnyTargetable, root: Option[Hierarchy[BaseModule]]): IsMember =
+      a.toRelativeTargetToHierarchy(root)
+  }
 }
 
 /** Existential Type class for types that can be converted to a Target
@@ -116,8 +124,11 @@ sealed trait AnyTargetable {
 
 object AnyTargetable {
 
-  /** Implicit conversion making working with Targetables easier */
-  implicit def toAnyTargetable[A](a: A)(implicit targetable: Targetable[A]): AnyTargetable = {
+  /** Convert any Targetable A to an AnyTargetable
+    *
+    * This effectively erases the type parameter and allows mixing of different concrete Targetable objects.
+    */
+  def apply[A](a: A)(implicit targetable: Targetable[A]): AnyTargetable = {
     type _A = A
     val _a = a
     val _targetable = targetable
@@ -127,4 +138,7 @@ object AnyTargetable {
       val targetable: Targetable[A] = _targetable
     }
   }
+
+  /** Implicit conversion making working with Targetables easier */
+  implicit def toAnyTargetable[A: Targetable](a: A): AnyTargetable = apply(a)
 }

src/test/scala/chiselTests/NewAnnotationsSpec.scala

@@ -1,15 +1,20 @@
+// SPDX-License-Identifier: Apache-2.0
+
 package chiselTests
+
+import circt.stage.ChiselStage
+
 import chisel3._
-import chisel3.experimental.annotate
+import chisel3.experimental.{annotate, AnyTargetable}
 import chisel3.stage.ChiselGeneratorAnnotation
-import circt.stage.ChiselStage
-import firrtl.stage.FirrtlCircuitAnnotation
+import chiselTests.experimental.hierarchy.Utils
+
+import firrtl.transforms.{DontTouchAnnotation, NoDedupAnnotation}
+
 import org.scalatest.freespec.AnyFreeSpec
 import org.scalatest.matchers.should.Matchers
-import firrtl.transforms.NoDedupAnnotation
-import firrtl.transforms.DontTouchAnnotation
 
-class NewAnnotationsSpec extends AnyFreeSpec with Matchers {
+class NewAnnotationsSpec extends AnyFreeSpec with Matchers with ChiselRunners with Utils {
 
   class MuchUsedModule extends Module {
     val io = IO(new Bundle {
@@ -41,9 +46,10 @@ class NewAnnotationsSpec extends AnyFreeSpec with Matchers {
     annotate(mod3)(Seq(new NoDedupAnnotation(mod3.toNamed)))
 
     // Pass multiple annotations in the same seq - should get emitted out correctly.
-    annotate(mod1.io.in, mod1.io.out)(
-      Seq(new DontTouchAnnotation(mod1.io.in.toNamed), new DontTouchAnnotation(mod1.io.out.toNamed))
-    )
+    val ports = Seq(mod1.io.in, mod1.io.out)
+    annotate(ports)({
+      ports.map(p => new DontTouchAnnotation(p.toTarget))
+    })
   }
 
   val stage = new ChiselStage
@@ -66,7 +72,30 @@ class NewAnnotationsSpec extends AnyFreeSpec with Matchers {
       noDedupAnnosCombined should include("~UsesMuchUsedModule|MuchUsedModule_3")
       dontTouchAnnosCombined should include("~UsesMuchUsedModule|MuchUsedModule_1>io.out")
       dontTouchAnnosCombined should include("~UsesMuchUsedModule|MuchUsedModule_1>io.in")
+    }
 
+    "It should be possible to annotate heterogeneous Targetable things" in {
+      val (_, annotations) = getFirrtlAndAnnos(new RawModule {
+        override def desiredName: String = "Top"
+        val in = IO(Input(UInt(8.W)))
+        val out = IO(Output(UInt(8.W)))
+        out := in
+        // Given a Seq[UInt]
+        val xs: Seq[UInt] = Seq(in, out)
+        // We can manually use AnyTargetable to also include a Module
+        // Using either type ascriptions to invoke the implicit conversion, or manually
+        val ys = Seq[AnyTargetable](this) ++ xs.map(AnyTargetable(_))
+        annotate(ys)(
+          Seq(
+            DontTouchAnnotation(in.toTarget),
+            DontTouchAnnotation(out.toTarget),
+            NoDedupAnnotation(this.toNamed)
+          )
+        )
+      })
+      annotations should contain(DontTouchAnnotation("~Top|Top>in".rt))
+      annotations should contain(DontTouchAnnotation("~Top|Top>out".rt))
+      annotations should contain(NoDedupAnnotation("~Top|Top".mt))
     }
   }
 }