.github/workflows/release-notes.yml

@@ -19,6 +19,8 @@ jobs:
   generate_release_notes:
     name: Generate Release Notes
     runs-on: ubuntu-22.04
+    permissions:
+      contents: write
 
     steps:
       - name: Checkout
@@ -41,7 +43,7 @@ jobs:
         run: echo "$CHANGELOG" >> $GITHUB_STEP_SUMMARY
       - name: Upload Release Notes (on release)
         if: github.event_name == 'release'
-        uses: softprops/action-gh-release@v2.0.5
+        uses: softprops/action-gh-release@v2.1.0
         with:
           body: ${{ steps.release-notes.outputs.changelog }}
       - name: Error on uncategorized PRs

.github/workflows/scala-cli-example.yml

@@ -14,6 +14,8 @@ jobs:
     name: Generate Chisel Scala CLI Example
     needs: [generate_scala_cli_example]
     runs-on: ubuntu-22.04
+    permissions:
+      contents: write
 
     steps:
       - name: Download Generated CLI Example
@@ -27,6 +29,6 @@ jobs:
           echo '```' >> $GITHUB_STEP_SUMMARY
       - name: Upload To Release Page
         if: github.event_name == 'release'
-        uses: softprops/action-gh-release@v2.0.5
+        uses: softprops/action-gh-release@v2.1.0
         with:
           files: chisel-example.scala

build.sbt

@@ -77,7 +77,12 @@ lazy val warningSuppression = Seq(
     "cat=deprecation&origin=chisel3\\.aop\\.Aspect:s",
     "cat=deprecation&origin=chisel3\\.aop\\.Aspect$:s",
     "cat=deprecation&origin=chisel3\\.stage\\.phases.AspectPhase:s",
-    "cat=deprecation&origin=chisel3\\.stage\\.phases.MaybeAspectPhase:s"
+    "cat=deprecation&origin=chisel3\\.stage\\.phases.MaybeAspectPhase:s",
+    "cat=deprecation&origin=chisel3\\.InstanceId:s",
+    "cat=deprecation&origin=chisel3\\.testers\\.BasicTester:s",
+    "cat=deprecation&origin=chisel3\\.testers\\.TesterDriver:s",
+    "cat=deprecation&origin=firrtl\\.util\\.BackendCompilationUtilities.*:s",
+    "cat=deprecation&origin=firrtl\\.transforms\\.BlackBoxSourceHelper.*:s"
   ).mkString(",")
 )
 
@@ -242,7 +247,8 @@ lazy val pluginScalaVersions = Seq(
   "2.13.12",
   "2.13.13",
   "2.13.14",
-  "2.13.15"
+  "2.13.15",
+  "2.13.16"
 )
 
 lazy val plugin = (project in file("plugin"))
@@ -406,7 +412,12 @@ lazy val unipublish =
         ProblemFilters.exclude[DirectMissingMethodProblem]("chisel3.*._circuit"),
         ProblemFilters.exclude[DirectMissingMethodProblem]("chisel3.*._circuit_="),
         // setRef was package private
-        ProblemFilters.exclude[IncompatibleMethTypeProblem]("chisel3.*.setRef")
+        ProblemFilters.exclude[IncompatibleMethTypeProblem]("chisel3.*.setRef"),
+        // ChiselOptions constructor is package private
+        ProblemFilters.exclude[DirectMissingMethodProblem]("chisel3.stage.ChiselOptions.this"),
+        // ChiselLoadMemoryAnnotation was private
+        ProblemFilters.exclude[MissingClassProblem]("chisel3.util.experimental.ChiselLoadMemoryAnnotation"),
+        ProblemFilters.exclude[MissingClassProblem]("chisel3.util.experimental.ChiselLoadMemoryAnnotation$")
       ),
       // Forward doc command to unidoc
       Compile / doc := (ScalaUnidoc / doc).value,

core/src/main/scala/chisel3/Aggregate.scala

@@ -83,6 +83,10 @@ sealed abstract class Aggregate extends Data {
     */
   def getElements: Seq[Data]
 
+  /** Save this result, as it can be very expensive to determine this otherwise */
+  private[chisel3] lazy val elementsContainProbe: Boolean =
+    elementsIterator.exists(d => chisel3.internal.containsProbe(d))
+
   /** Similar to [[getElements]] but allows for more optimized use */
   private[chisel3] def elementsIterator: Iterator[Data]
 
@@ -209,6 +213,9 @@ sealed class Vec[T <: Data] private[chisel3] (gen: => T, val length: Int) extend
 
   override def containsAFlipped = sample_element.containsAFlipped
 
+  /** Save this result, as it can be very expensive to determine this otherwise */
+  override private[chisel3] lazy val elementsContainProbe: Boolean = chisel3.internal.containsProbe(sample_element)
+
   private[chisel3] override def bind(target: Binding, parentDirection: SpecifiedDirection): Unit = {
     this.maybeAddToParentIds(target)
     binding = target

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

@@ -3,8 +3,10 @@
 package chisel3.experimental
 
 import scala.language.existentials
+import scala.annotation.nowarn
 import chisel3.internal.Builder
-import chisel3.{Data, InstanceId, RawModule}
+import chisel3.{Data, HasTarget, InstanceId, RawModule}
+import chisel3.experimental.AnyTargetable
 import firrtl.annotations._
 import firrtl.options.Unserializable
 import firrtl.transforms.{DedupGroupAnnotation, NoDedupAnnotation}
@@ -13,6 +15,10 @@ import firrtl.transforms.{DedupGroupAnnotation, NoDedupAnnotation}
   *
   * Defines a conversion to a corresponding FIRRTL Annotation
   */
+@deprecated(
+  "Avoid custom annotations. If you must use annotations, use annotate.apply method that takes Data",
+  "Chisel 6.7.0"
+)
 trait ChiselAnnotation {
 
   /** Conversion to FIRRTL Annotation */
@@ -23,16 +29,56 @@ trait ChiselAnnotation {
   *
   *  Defines a conversion to corresponding FIRRTL Annotation(s)
   */
+@deprecated(
+  "Avoid custom annotations. If you must use annotations, use annotate.apply method that takes Data",
+  "Chisel 6.7.0"
+)
 trait ChiselMultiAnnotation {
   def toFirrtl: Seq[Annotation]
 }
 
+@nowarn("msg=Avoid custom annotations")
 object annotate {
-  def apply(anno: ChiselAnnotation): Unit = {
+  @deprecated(
+    "Avoid custom annotations. If you must use annotations, use annotate.apply method that takes Data",
+    "Chisel 6.7.0"
+  )
+  def apply(anno: ChiselAnnotation): Unit =
     Builder.annotations += anno
-  }
-  def apply(annos: ChiselMultiAnnotation): Unit = {
+
+  @deprecated(
+    "Avoid custom annotations. If you must use annotations, use annotate.apply method that takes Data",
+    "Chisel 6.7.0"
+  )
+  def apply(annos: ChiselMultiAnnotation): Unit =
     Builder.newAnnotations += annos
+
+  /** 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(targets: AnyTargetable*)(mkAnnos: => Seq[Annotation]): Unit = {
+    targets.map(_.a).foreach {
+      case d: Data => requireIsAnnotatable(d, "Data marked with annotation")
+      case _ => ()
+    }
+    Builder.newAnnotations += new ChiselMultiAnnotation {
+      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)
   }
 }
 
@@ -76,7 +122,7 @@ object doNotDedup {
     * @return Unmodified signal `module`
     */
   def apply[T <: RawModule](module: T): Unit = {
-    annotate(new ChiselAnnotation { def toFirrtl = NoDedupAnnotation(module.toNamed) })
+    annotate(module)(Seq(NoDedupAnnotation(module.toNamed)))
   }
 }
 
@@ -89,6 +135,6 @@ object dedupGroup {
     * @return Unmodified signal `module`
     */
   def apply[T <: BaseModule](module: T, group: String): Unit = {
-    annotate(new ChiselAnnotation { def toFirrtl = DedupGroupAnnotation(module.toTarget, group) })
+    annotate(module)(Seq(DedupGroupAnnotation(module.toTarget, group)))
   }
 }

core/src/main/scala/chisel3/ChiselEnum.scala

@@ -5,6 +5,7 @@ package chisel3
 import scala.language.experimental.macros
 import scala.language.existentials
 import scala.reflect.macros.blackbox.Context
+import scala.annotation.nowarn
 import scala.collection.mutable
 import chisel3.experimental.{annotate, requireIsHardware, ChiselAnnotation, SourceInfo, UnlocatableSourceInfo}
 import chisel3.internal.Builder.pushOp
@@ -25,6 +26,9 @@ import chisel3.internal.{
 
 import chisel3.experimental.EnumAnnotations._
 
+// Rather than refactoring the annotation work here, we should just remove ChiselEnum annotations
+@nowarn("msg=Avoid custom annotations")
+@nowarn("msg=Enum annotations will be removed")
 abstract class EnumType(private[chisel3] val factory: ChiselEnum, selfAnnotating: Boolean = true) extends Element {
 
   // Use getSimpleName instead of enumTypeName because for debugging purposes
@@ -228,10 +232,15 @@ abstract class EnumType(private[chisel3] val factory: ChiselEnum, selfAnnotating
   }
 }
 
+// Rather than refactoring the annotation work here, we should just remove ChiselEnum annotations
+@nowarn("msg=Avoid custom annotations")
 private[chisel3] object ChiselEnum {
   private[chisel3] case object CacheKey extends BuilderContextCache.Key[mutable.HashSet[ChiselAnnotation]]
 }
 
+// Rather than refactoring the annotation work here, we should just remove ChiselEnum annotations
+@nowarn("msg=Avoid custom annotations")
+@nowarn("msg=Enum annotations will be removed")
 abstract class ChiselEnum {
   class Type extends EnumType(this)
   object Type {

core/src/main/scala/chisel3/ElaboratedCircuit.scala

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3
+
+import firrtl.annotations.Annotation
+import firrtl.ir.{CircuitWithAnnos, Serializer}
+import firrtl.options.{CustomFileEmission, Unserializable}
+import chisel3.experimental.{BaseModule, SourceInfo, UnlocatableSourceInfo}
+import chisel3.experimental.hierarchy.Definition
+import chisel3.internal.firrtl.ir.Circuit
+import chisel3.internal.firrtl.Converter
+
+/** The result of running Chisel elaboration
+  *
+  * Provides limited APIs for inspection of the resulting circuit.
+  */
+// This is an important interface so let's keep it separate from the implementation.
+sealed trait ElaboratedCircuit {
+
+  /** The name of the circuit, also the name of the top public module */
+  def name: String
+
+  /** The circuit and annotations as a string of FIRRTL IR
+    *
+    * This will include annotations passed to Chisel to build the circuit and those created during elaboration.
+    * For large circuits (> 2 GiB of text) use `lazilySerialize`.
+    */
+  def serialize: String
+
+  /** The circuit and annotations as a string of FIRRTL IR
+    *
+    * For large circuits (> 2 GiB of text) use `lazilySerialize`.
+    *
+    * @param annotations annotations to include in the FIRRTL IR. No other annotations will be included.
+    */
+  def serialize(annotations: Iterable[Annotation]): String
+
+  /** The circuit and annotations as a lazy buffer of strings of FIRRTL IR
+    *
+    * This will include annotations passed to Chisel to build the circuit and those created during elaboration.
+    * Serialized lazily to reduce peak memory use and support cicuits larger than 2 GiB.
+    */
+  def lazilySerialize: Iterable[String]
+
+  /** The circuit and annotations as a lazy buffer of strings of FIRRTL IR
+    *
+    * Serialized lazily to reduce peak memory use and support cicuits larger than 2 GiB.
+    *
+    * @param annotations annotations to include in the FIRRTL IR. No other annotations will be included.
+    */
+  def lazilySerialize(annotations: Iterable[Annotation]): Iterable[String]
+
+  /** The annotations created during elaboration of this circuit
+    *
+    * This does not include annotations passed to elaboration.
+    */
+  def annotations: Iterable[Annotation]
+
+  /** The Definition of the top module in the elaborated circuit */
+  def topDefinition: Definition[BaseModule]
+
+  /** The underlying circuit, for private use only */
+  private[chisel3] def _circuit: Circuit
+}
+
+private class ElaboratedCircuitImpl(circuit: Circuit, initialAnnotations: Seq[Annotation]) extends ElaboratedCircuit {
+
+  // Source locator needed for toDefinition
+  private implicit def sourceInfo: SourceInfo = UnlocatableSourceInfo
+
+  override def name: String = circuit.name
+
+  override def serialize: String = lazilySerialize.mkString
+
+  override def serialize(annotations: Iterable[Annotation]): String = lazilySerialize(annotations).mkString
+
+  override def lazilySerialize: Iterable[String] = {
+    val annotations = (initialAnnotations.view ++ circuit.firrtlAnnotations).flatMap {
+      case _: Unserializable     => None
+      case _: CustomFileEmission => None
+      case a => Some(a)
+    }.toVector
+    lazilySerialize(annotations)
+  }
+
+  override def lazilySerialize(annotations: Iterable[Annotation]): Iterable[String] = {
+    val prelude = {
+      val dummyCircuit = circuit.copy(components = Nil)
+      val converted = Converter.convert(dummyCircuit)
+      val withAnnos = CircuitWithAnnos(converted, annotations.toVector)
+      Serializer.lazily(withAnnos)
+    }
+    val typeAliases: Seq[String] = circuit.typeAliases.map(_.name)
+    val modules = circuit.components.iterator.map(c => Converter.convert(c, typeAliases))
+    val moduleStrings = modules.flatMap { m =>
+      Serializer.lazily(m, 1) ++ Seq("\n\n")
+    }
+    prelude ++ moduleStrings
+  }
+
+  override def annotations: Iterable[Annotation] = circuit.firrtlAnnotations
+
+  // TODO come up with a better way to figure this out than "last"
+  override def topDefinition: Definition[BaseModule] = circuit.components.last.id.toDefinition
+
+  private[chisel3] override def _circuit: Circuit = circuit
+}
+
+object ElaboratedCircuit {
+  private[chisel3] def apply(circuit: Circuit, initialAnnotations: Seq[Annotation]): ElaboratedCircuit =
+    new ElaboratedCircuitImpl(circuit, initialAnnotations)
+}

core/src/main/scala/chisel3/Module.scala

@@ -578,6 +578,12 @@ package experimental {
       _ports.toSeq
     }
 
+    /** Get IOs that are currently bound to this module.
+      */
+    private[chisel3] def getIOs: Seq[Data] = {
+      _ports.map(_._1).toSeq
+    }
+
     // These methods allow checking some properties of ports before the module is closed,
     // mainly for compatibility purposes.
     protected def portsContains(elem: Data): Boolean = {

core/src/main/scala/chisel3/dontTouch.scala

@@ -38,9 +38,8 @@ object dontTouch {
     data match {
       case d if DataMirror.hasProbeTypeModifier(d) => ()
       case _:   Property[_] => ()
-      case agg: Aggregate => agg.getElements.foreach(dontTouch.apply)
-      case _:   Element =>
-        annotate(new ChiselAnnotation { def toFirrtl = DontTouchAnnotation(data.toNamed) })
+      case agg: Aggregate   => agg.getElements.foreach(dontTouch.apply)
+      case _:   Element     => annotate(data)(Seq(DontTouchAnnotation(data.toNamed)))
       case _ => throw new ChiselException("Non-hardware dontTouch")
     }
     data