Merge branch '3.5.x' into 3.5-release

Author: jackkoenig

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

@@ -8,7 +8,7 @@ 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, ChiselEnum, EnumType, OpaqueType, VecLiteralException}
+import chisel3.experimental.{BaseModule, BundleLiteralException, OpaqueType, VecLiteralException}
 import chisel3.internal._
 import chisel3.internal.Builder.pushCommand
 import chisel3.internal.firrtl._

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

@@ -5,7 +5,7 @@ package chisel3
 import chisel3.experimental.dataview.reify
 
 import scala.language.experimental.macros
-import chisel3.experimental.{Analog, BaseModule, DataMirror, EnumType, FixedPoint, Interval}
+import chisel3.experimental.{Analog, BaseModule, DataMirror, FixedPoint, Interval}
 import chisel3.internal.Builder.pushCommand
 import chisel3.internal._
 import chisel3.internal.firrtl._

core/src/main/scala/chisel3/StrongEnum.scala renamed to core/src/main/scala/chisel3/experimental/ChiselEnum.scala

@@ -69,9 +69,11 @@ object EnumAnnotations {
     override def toFirrtl: Annotation = EnumDefAnnotation(typeName, definition)
   }
 }
+
 import EnumAnnotations._
 
-abstract class EnumType(private[chisel3] val factory: EnumFactory, selfAnnotating: Boolean = true) extends Element {
+@deprecated("This type has moved to chisel3", "Chisel 3.5")
+abstract class EnumType(private[chisel3] val factory: ChiselEnum, selfAnnotating: Boolean = true) extends Element {
 
   // Use getSimpleName instead of enumTypeName because for debugging purposes
   //   the fully qualified name isn't necessary (compared to for the
@@ -240,11 +242,13 @@ abstract class EnumType(private[chisel3] val factory: EnumFactory, selfAnnotatin
       case None    => EnumComponentChiselAnnotation(this, enumTypeName)
     }
 
-    if (!Builder.annotations.contains(anno)) {
+    if (!Builder.enumAnnos.contains(anno)) {
+      Builder.enumAnnos += anno
       annotate(anno)
     }
 
-    if (!Builder.annotations.contains(factory.globalAnnotation)) {
+    if (!Builder.enumAnnos.contains(factory.globalAnnotation)) {
+      Builder.enumAnnos += factory.globalAnnotation
       annotate(factory.globalAnnotation)
     }
   }
@@ -275,6 +279,7 @@ abstract class EnumType(private[chisel3] val factory: EnumFactory, selfAnnotatin
   }
 }
 
+@deprecated("This type has been moved and renamed to chisel3.ChiselEnum", "Chisel 3.5")
 abstract class EnumFactory {
   class Type extends EnumType(this)
   object Type {
@@ -431,11 +436,11 @@ private[chisel3] object EnumMacros {
 private[chisel3] class UnsafeEnum(override val width: Width) extends EnumType(UnsafeEnum, selfAnnotating = false) {
   override def cloneType: this.type = new UnsafeEnum(width).asInstanceOf[this.type]
 }
-private object UnsafeEnum extends EnumFactory
+private object UnsafeEnum extends ChiselEnum
 
 /** Suppress enum cast warnings
   *
-  * Users should use [[EnumFactory.safe <EnumType>.safe]] when possible.
+  * Users should use [[ChiselEnum.safe <EnumType>.safe]] when possible.
   *
   * This is primarily used for casting from [[UInt]] to a Bundle type that contains an Enum.
   * {{{
@@ -450,6 +455,7 @@ private object UnsafeEnum extends EnumFactory
   * }
   * }}}
   */
+@deprecated("This type has moved to chisel3", "Chisel 3.5")
 object suppressEnumCastWarning {
   def apply[T](block: => T): T = {
     val parentWarn = Builder.suppressEnumCastWarning

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

@@ -22,6 +22,7 @@ package object experimental {
   implicit def fromDoubleToDoubleParam(x: Double): DoubleParam = DoubleParam(x)
   implicit def fromStringToStringParam(x: String): StringParam = StringParam(x)
 
+  @deprecated("This type has moved to chisel3", "Chisel 3.5")
   type ChiselEnum = EnumFactory
 
   // Rocket Chip-style clonemodule

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

@@ -299,25 +299,31 @@ private[chisel3] trait HasId extends InstanceId {
       // Builder.deprecated mechanism, we have to create our own one off ErrorLog and print the
       // warning right away.
       // It's especially bad because --warnings-as-errors does not work with these warnings
-      val nameGuess = _computeName(None) match {
-        case Some(name) => s": '$name'"
-        case None       => ""
-      }
-      val parentGuess = _parent match {
-        case Some(ViewParent) => s", in module '${reifyParent.pathName}'"
-        case Some(p)          => s", in module '${p.pathName}'"
-        case None             => ""
-      }
       val errors = new ErrorLog(false)
       val logger = new _root_.logger.Logger(this.getClass.getName)
       val msg =
-        "Accessing the .instanceName or .toTarget of non-hardware Data is deprecated" + nameGuess + parentGuess + ". " +
+        "Accessing the .instanceName or .toTarget of non-hardware Data is deprecated" + _errorContext + ". " +
           "This will become an error in Chisel 3.6."
       errors.deprecated(msg, None)
       errors.checkpoint(logger)
       _computeName(None).get
   }
 
+  private[chisel3] def _errorContext: String = {
+    val nameGuess: String = _computeName(None) match {
+      case Some(name) => s": '$name'"
+      case None       => ""
+    }
+
+    val parentGuess: String = _parent match {
+      case Some(ViewParent) => s", in module '${reifyParent.pathName}'"
+      case Some(p)          => s", in module '${p.pathName}'"
+      case None             => ""
+    }
+
+    nameGuess + parentGuess
+  }
+
   // Helper for reifying views if they map to a single Target
   private[chisel3] def reifyTarget: Option[Data] = this match {
     case d: Data => reifySingleData(d) // Only Data can be views
@@ -393,13 +399,16 @@ private[chisel3] trait NamedComponent extends HasId {
   /** Returns a FIRRTL ComponentName that references this object
     * @note Should not be called until circuit elaboration is complete
     */
-  final def toNamed: ComponentName =
+  final def toNamed: ComponentName = {
+    assertValidTarget()
     ComponentName(this.instanceName, ModuleName(this.parentModName, CircuitName(this.circuitName)))
+  }
 
   /** Returns a FIRRTL ReferenceTarget that references this object
     * @note Should not be called until circuit elaboration is complete
     */
   final def toTarget: ReferenceTarget = {
+    assertValidTarget()
     val name = this.instanceName
     if (!validComponentName(name)) throwException(s"Illegal component name: $name (note: literals are illegal)")
     import _root_.firrtl.annotations.{Target, TargetToken}
@@ -423,6 +432,21 @@ private[chisel3] trait NamedComponent extends HasId {
       case None             => localTarget
     }
   }
+
+  private def assertValidTarget(): Unit = {
+    val isVecSubaccess = getOptionRef.map {
+      case Index(_, _: ULit) => true // Vec literal indexing
+      case Index(_, _: Node) => true // Vec dynamic indexing
+      case _ => false
+    }.getOrElse(false)
+
+    if (isVecSubaccess) {
+      throwException(
+        s"You cannot target Vec subaccess" + _errorContext +
+          ". Instead, assign it to a temporary (for example, with WireInit) and target the temporary."
+      )
+    }
+  }
 }
 
 // Mutable global state for chisel that can appear outside a Builder context
@@ -485,6 +509,10 @@ private[chisel3] class DynamicContext(
   val newAnnotations = ArrayBuffer[ChiselMultiAnnotation]()
   var currentModule: Option[BaseModule] = None
 
+  // Enum annotations are added every time a ChiselEnum is bound
+  // To keep the number down, we keep them unique in the annotations
+  val enumAnnos = mutable.HashSet[ChiselAnnotation]()
+
   /** Contains a mapping from a elaborated module to their aspect
     * Set by [[ModuleAspect]]
     */
@@ -553,6 +581,8 @@ private[chisel3] object Builder extends LazyLogging {
   def components:      ArrayBuffer[Component] = dynamicContext.components
   def annotations:     ArrayBuffer[ChiselAnnotation] = dynamicContext.annotations
 
+  def enumAnnos: mutable.HashSet[ChiselAnnotation] = dynamicContext.enumAnnos
+
   // TODO : Unify this with annotations in the future - done this way for backward compatability
   def newAnnotations: ArrayBuffer[ChiselMultiAnnotation] = dynamicContext.newAnnotations
 

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

@@ -3,7 +3,7 @@
 package chisel3.internal
 
 import chisel3._
-import chisel3.experimental.{Analog, BaseModule, EnumType, FixedPoint, Interval, UnsafeEnum}
+import chisel3.experimental.{Analog, BaseModule, FixedPoint, Interval, UnsafeEnum}
 import chisel3.internal.Builder.pushCommand
 import chisel3.internal.firrtl.{Connect, Converter, DefInvalid}
 import chisel3.experimental.dataview.{isView, reify, reifyToAggregate}

core/src/main/scala/chisel3/package.scala

@@ -14,6 +14,10 @@ package object chisel3 {
 
   import scala.language.implicitConversions
 
+  type ChiselEnum = experimental.ChiselEnum
+  type EnumType = experimental.EnumType
+  val suppressEnumCastWarning = experimental.suppressEnumCastWarning
+
   /**
     * These implicit classes allow one to convert [[scala.Int]] or [[scala.BigInt]] to
     * Chisel.UInt|Chisel.SInt by calling .asUInt|.asSInt on them, respectively.

docs/src/cookbooks/cookbook.md

@@ -445,13 +445,12 @@ getVerilogString(new Top(new UsingCloneTypeBundle(UInt(8.W))))
 
 ### How do I create a finite state machine (FSM)?
 
-The advised way is to use [`ChiselEnum`](https://www.chisel-lang.org/api/latest/chisel3/experimental/index.html#ChiselEnum=chisel3.experimental.EnumFactory) to construct enumerated types representing the state of the FSM.
-State transitions are then handled with [`switch`](https://www.chisel-lang.org/api/latest/chisel3/util/switch$.html)/[`is`](https://www.chisel-lang.org/api/latest/chisel3/util/is$.html) and [`when`](https://www.chisel-lang.org/api/latest/chisel3/when$.html)/[`.elsewhen`](https://www.chisel-lang.org/api/latest/chisel3/WhenContext.html#elsewhen(elseCond:=%3Echisel3.Bool)(block:=%3EUnit)(implicitsourceInfo:chisel3.internal.sourceinfo.SourceInfo,implicitcompileOptions:chisel3.CompileOptions):chisel3.WhenContext)/[`.otherwise`](https://www.chisel-lang.org/api/latest/chisel3/WhenContext.html#otherwise(block:=%3EUnit)(implicitsourceInfo:chisel3.internal.sourceinfo.SourceInfo,implicitcompileOptions:chisel3.CompileOptions):Unit).
+The advised way is to use `ChiselEnum` to construct enumerated types representing the state of the FSM.
+State transitions are then handled with `switch`/`is` and `when`/`.elsewhen`/`.otherwise`.
 
 ```scala mdoc:silent:reset
 import chisel3._
 import chisel3.util.{switch, is}
-import chisel3.experimental.ChiselEnum
 
 object DetectTwoOnes {
   object State extends ChiselEnum {

docs/src/cookbooks/verilog-vs-chisel.md

@@ -15,7 +15,6 @@ This page serves as a quick introduction to Chisel for those familiar with Veril
 import chisel3._
 import chisel3.util.{switch, is}
 import chisel3.stage.ChiselStage
-import chisel3.experimental.ChiselEnum
 import chisel3.util.{Cat, Fill, DecoupledIO}
 ```
 

docs/src/explanations/chisel-enum.md

@@ -16,8 +16,6 @@ In contrast with `Chisel.util.Enum`, `ChiselEnum` are subclasses of `Data`, whic
 import chisel3._
 import chisel3.util._
 import chisel3.stage.ChiselStage
-import chisel3.experimental.ChiselEnum
-import chisel3.experimental.suppressEnumCastWarning
 ```
 
 ```scala mdoc:invisible

src/main/scala/chisel3/util/experimental/decode/TruthTable.scala

@@ -3,29 +3,35 @@
 package chisel3.util.experimental.decode
 
 import chisel3.util.BitPat
+import scala.util.hashing.MurmurHash3
 import scala.collection.mutable
 
-sealed class TruthTable private (val table: Seq[(BitPat, BitPat)], val default: BitPat, val sort: Boolean) {
+sealed class TruthTable private (val table: Seq[(BitPat, BitPat)], val default: BitPat, _sort: Boolean) {
   def inputWidth = table.head._1.getWidth
 
   def outputWidth = table.head._2.getWidth
 
+  @deprecated("This field is unused and will be removed.", "Chisel 3.5")
+  def sort: Boolean = _sort
+
   override def toString: String = {
     def writeRow(map: (BitPat, BitPat)): String =
       s"${map._1.rawString}->${map._2.rawString}"
 
     (table.map(writeRow) ++ Seq(s"${" " * (inputWidth + 2)}${default.rawString}")).mkString("\n")
   }
 
-  def copy(table: Seq[(BitPat, BitPat)] = this.table, default: BitPat = this.default, sort: Boolean = this.sort) =
-    TruthTable(table, default, sort)
+  def copy(table: Seq[(BitPat, BitPat)] = this.table, default: BitPat = this.default, sort: Boolean = _sort) =
+    TruthTable(table, default)
 
   override def equals(y: Any): Boolean = {
     y match {
-      case y: TruthTable => toString == y.toString
+      case that: TruthTable => this.table == that.table && this.default == that.default
       case _ => false
     }
   }
+
+  override lazy val hashCode: Int = MurmurHash3.productHash((table, default))
 }
 
 object TruthTable {

src/test/scala/chiselTests/AsTypeOfTester.scala

@@ -3,7 +3,7 @@
 package chiselTests
 
 import chisel3._
-import chisel3.experimental.{ChiselEnum, DataMirror, FixedPoint}
+import chisel3.experimental.{DataMirror, FixedPoint}
 import chisel3.testers.BasicTester
 
 class AsTypeOfBundleTester extends BasicTester {

src/test/scala/chiselTests/BundleElementsSpec.scala

@@ -3,7 +3,7 @@
 package chiselTests
 
 import chisel3._
-import chisel3.experimental.{ChiselEnum, FixedPoint}
+import chisel3.experimental.FixedPoint
 import chisel3.stage.ChiselStage
 import chisel3.util.Decoupled
 import org.scalatest.exceptions.TestFailedException

src/test/scala/chiselTests/BundleLiteralSpec.scala

@@ -7,7 +7,7 @@ import chisel3.stage.ChiselStage
 import chisel3.testers.BasicTester
 import chisel3.experimental.BundleLiterals._
 import chisel3.experimental.VecLiterals.AddVecLiteralConstructor
-import chisel3.experimental.{BundleLiteralException, ChiselEnum, ChiselRange, FixedPoint, Interval}
+import chisel3.experimental.{BundleLiteralException, ChiselRange, FixedPoint, Interval}
 
 class BundleLiteralSpec extends ChiselFlatSpec with Utils {
   object MyEnum extends ChiselEnum {