Implement FIRRTL type alias mechanism for Bundles

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

@@ -8,12 +8,21 @@ import chisel3.experimental.dataview.{isView, reifySingleData, InvalidViewExcept
 import scala.collection.immutable.{SeqMap, VectorMap}
 import scala.collection.mutable.{HashSet, LinkedHashMap}
 import scala.language.experimental.macros
-import chisel3.experimental.{BaseModule, BundleLiteralException, OpaqueType, VecLiteralException}
+import chisel3.experimental.{
+  BaseModule,
+  BundleAlias,
+  BundleLiteralException,
+  HasTypeAlias,
+  OpaqueType,
+  VecLiteralException
+}
 import chisel3.experimental.{SourceInfo, UnlocatableSourceInfo}
 import chisel3.internal._
 import chisel3.internal.Builder.pushCommand
 import chisel3.internal.firrtl._
 import chisel3.internal.sourceinfo.{SourceInfoTransform, VecTransform}
+import chisel3.reflect.DataMirror
+import _root_.firrtl.{ir => fir}
 
 import java.lang.Math.{floor, log10, pow}
 import scala.collection.mutable
@@ -183,6 +192,8 @@ sealed class Vec[T <: Data] private[chisel3] (gen: => T, val length: Int) extend
     */
   override def typeName = s"Vec${length}_${gen.typeName}"
 
+  override def isFlipped = sample_element.isFlipped
+
   private[chisel3] override def bind(target: Binding, parentDirection: SpecifiedDirection): Unit = {
     this.maybeAddToParentIds(target)
     binding = target
@@ -1018,6 +1029,12 @@ abstract class Record extends Aggregate {
     }
   }
 
+  /* Tracking variable for deciding Record flipped-ness. */
+  private[chisel3] var _isFlipped: Boolean = false
+
+  /* In the context of Records, isFlipped is assigned true if any of its children are flipped. */
+  override def isFlipped: Boolean = _isFlipped
+
   private[chisel3] override def bind(target: Binding, parentDirection: SpecifiedDirection): Unit = {
     this.maybeAddToParentIds(target)
     binding = target
@@ -1038,6 +1055,9 @@ abstract class Record extends Aggregate {
         )
       }
       child.bind(ChildBinding(this), resolvedDirection)
+
+      // Update the flipped tracker based on the flipped-ness of this specific child element
+      _isFlipped |= child.isFlipped
     }
 
     // Check that children obey the directionality rules.
@@ -1053,6 +1073,11 @@ abstract class Record extends Aggregate {
         }
     }
     setElementRefs()
+
+    this match {
+      case aliasedRecord: HasTypeAlias => Builder.setRecordAlias(aliasedRecord, resolvedDirection)
+      case _ =>
+    }
   }
 
   /** Creates a Bundle literal of this type with specified values. this must be a chisel type.
@@ -1463,4 +1488,5 @@ abstract class Bundle extends Record {
     *   the fields in the order they were defined
     */
   override def toPrintable: Printable = toPrintableHelper(_elements.toList.reverse)
+
 }

core/src/main/scala/chisel3/Data.scala

@@ -293,6 +293,9 @@ abstract class Data extends HasId with NamedComponent with SourceInfoDoc {
     }
   }
 
+  // Whether this node has a specified flipped direction, ignoring coercion via Input/Output
+  private[chisel3] def isFlipped: Boolean = false
+
   // Must clone a Data if any of the following are true:
   // * It has a binding
   // * Its id is older than prevId (not "freshly created")

core/src/main/scala/chisel3/Element.scala

@@ -67,4 +67,8 @@ abstract class Element extends Data {
     }
   }
 
+  override def isFlipped = specifiedDirection match {
+    case SpecifiedDirection.Flip | SpecifiedDirection.Input => true
+    case _                                                  => false
+  }
 }

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

@@ -0,0 +1,51 @@
+package chisel3.experimental
+
+import chisel3.Record
+
+/** Wrapper object for a Record alias name. Primarily intended to provide an invocation point for source line locators, but
+  * also contains pertinent information to generating FIRRTL alias statements.
+  *
+  * @param id The desired name to generate an alias statement
+  * @param strippedSuffix In the case of forced coersion by [[Input]] or [[Output]], the string to append to the end of the
+  *        alias name. Takes the default value of `"_stripped"`
+  */
+case class BundleAlias private[chisel3] (info: SourceInfo, id: String, strippedSuffix: String = "_stripped")
+
+object BundleAlias {
+  def apply(id: String)(implicit info:  SourceInfo): BundleAlias = BundleAlias(info, id)
+  def apply(id: String, strippedSuffix: String)(implicit info: SourceInfo): BundleAlias =
+    BundleAlias(info, id, strippedSuffix)
+}
+
+trait HasTypeAlias {
+  this: Record =>
+
+  /** An optional FIRRTL type alias name to give to this [[Record]]. If overrided with a `Some(...)`, for instance
+    * `Some(BundleAlias("UserBundle"))`, this causes emission of circuit-level FIRRTL statements that declare that name for
+    * this bundle type:
+    *
+    * @example
+    * {{{
+    * class MyBundle extends Bundle with HasTypeAlias {
+    *   override def aliasName = Some("UserBundle")
+    * }
+    * }}}
+    *
+    * {{{
+    * circuit Top :
+    *   type UserBundle = { ... }
+    *   module Top :
+    *     // ...
+    * }}}
+    *
+    * This is used as a strong hint for the generated type alias: steps like sanitization and disambiguation
+    * may change the resulting alias by necessity, so there is no certain guarantee that the desired name will show up in
+    * the generated FIRRTL.
+    */
+  def aliasName: Option[BundleAlias] = None
+
+  // The final sanitized and disambiguated alias for this bundle, generated when aliasName is a non-empty Option.
+  // This is important if sanitization and disambiguation results in a changed alias,
+  // as the sanitized name no longer matches the user-specified alias.
+  private[chisel3] var finalizedAlias: Option[String] = None
+}

core/src/main/scala/chisel3/internal/Builder.scala

@@ -15,6 +15,7 @@ import _root_.firrtl.annotations.AnnotationUtils.validComponentName
 import _root_.firrtl.AnnotationSeq
 import _root_.firrtl.renamemap.MutableRenameMap
 import _root_.firrtl.util.BackendCompilationUtilities._
+import _root_.firrtl.{ir => fir}
 import chisel3.experimental.dataview.{reify, reifySingleData}
 import chisel3.internal.Builder.Prefix
 import logger.LazyLogging
@@ -453,6 +454,13 @@ private[chisel3] class DynamicContext(
   val globalNamespace = Namespace.empty
   val globalIdentifierNamespace = Namespace.empty('$')
 
+  // A mapping from previously named bundles to their hashed structural/FIRRTL types, for
+  // disambiguation purposes when emitting type aliases
+  // Records are used as the key for this map to both represent their alias name and preserve
+  // the chisel Bundle structure when passing everything off to the Converter
+  private[chisel3] val aliasMap: mutable.LinkedHashMap[String, (fir.Type, SourceInfo)] =
+    mutable.LinkedHashMap.empty[String, (fir.Type, SourceInfo)]
+
   // Ensure imported Definitions emit as ExtModules with the correct name so
   // that instantiations will also use the correct name and prevent any name
   // conflicts with Modules/Definitions in this elaboration
@@ -536,8 +544,12 @@ private[chisel3] object Builder extends LazyLogging {
 
   def globalNamespace:           Namespace = dynamicContext.globalNamespace
   def globalIdentifierNamespace: Namespace = dynamicContext.globalIdentifierNamespace
-  def components:                ArrayBuffer[Component] = dynamicContext.components
-  def annotations:               ArrayBuffer[ChiselAnnotation] = dynamicContext.annotations
+
+  def aliasMap: mutable.LinkedHashMap[String, (fir.Type, SourceInfo)] =
+    dynamicContext.aliasMap
+
+  def components:  ArrayBuffer[Component] = dynamicContext.components
+  def annotations: ArrayBuffer[ChiselAnnotation] = dynamicContext.annotations
 
   def contextCache: BuilderContextCache = dynamicContext.contextCache
 
@@ -857,6 +869,57 @@ private[chisel3] object Builder extends LazyLogging {
     renames
   }
 
+  def setRecordAlias(record: Record with HasTypeAlias, parentDirection: SpecifiedDirection): Unit = {
+    val alias = record.aliasName.flatMap { candidateAlias =>
+      {
+        val sourceInfo = candidateAlias.info
+
+        // If the aliased bundle is coerced and it has flipped signals, then they must be stripped
+        val isCoerced = parentDirection match {
+          case SpecifiedDirection.Input | SpecifiedDirection.Output => true
+          case other                                                => false
+        }
+        val isStripped = isCoerced && record.isFlipped
+
+        // The true alias, after sanitization and (TODO) disambiguation
+        val alias = sanitize(s"${candidateAlias.id}${if (isStripped) candidateAlias.strippedSuffix else ""}")
+        // Filter out (TODO: disambiguate) FIRRTL keywords that cause parser errors if used
+        if (illegalTypeAliases.contains(alias)) {
+          Builder.error(
+            s"Attempted to use an illegal word '$alias' for a type alias. Chisel does not automatically disambiguate these aliases at this time."
+          )(sourceInfo)
+
+          None
+        } else {
+          val tpe = Converter.extractType(record, isCoerced, sourceInfo, true, true, aliasMap.keys.toSeq)
+          // If the name is already taken, check if there exists a *structurally equivalent* bundle with the same name, and
+          // simply error (TODO: disambiguate that name)
+          if (
+            Builder.aliasMap.contains(alias) &&
+            Builder.aliasMap.get(alias).exists(_._1 != tpe)
+          ) {
+            // Get full structural map value
+            val recordValue = Builder.aliasMap.get(alias).get
+            // Conflict found:
+            error(
+              s"Attempted to redeclare an existing type alias '$alias' with a new Record structure:\n'$tpe'.\n\nThe alias was previously defined as:\n'${recordValue._1}${recordValue._2
+                .makeMessage(" " + _)}"
+            )(sourceInfo)
+
+            None
+          } else {
+            if (!Builder.aliasMap.contains(alias)) {
+              Builder.aliasMap.put(alias, (tpe, sourceInfo))
+            }
+
+            Some(alias)
+          }
+        }
+      }
+    }
+    record.finalizedAlias = alias
+  }
+
   private[chisel3] def build[T <: BaseModule](
     f:              => T,
     dynamicContext: DynamicContext,
@@ -883,7 +946,23 @@ private[chisel3] object Builder extends LazyLogging {
       errors.checkpoint(logger)
       logger.info("Done elaborating.")
 
-      (Circuit(components.last.name, components.toSeq, annotations.toSeq, makeViewRenameMap, newAnnotations.toSeq), mod)
+      val typeAliases = aliasMap.flatMap {
+        // Discard the previously-computed FIRRTL type as the converter will now have alias information
+        case (name, (underlying: fir.Type, info: SourceInfo)) => Some(DefTypeAlias(info, underlying, name))
+        case _ => None
+      }.toSeq
+
+      (
+        Circuit(
+          components.last.name,
+          components.toSeq,
+          annotations.toSeq,
+          makeViewRenameMap,
+          newAnnotations.toSeq,
+          typeAliases
+        ),
+        mod
+      )
     }
   }
   initializeSingletons()