Promote ChiselEnum user APIs from experimental (backport #2929) (#2931)

* Promote ChiselEnum user APIs from experimental (#2929)

They are commonly used and if we were ever to change them, we will need
to go through a deprecation process anyway.

Note that the EnumAnnotations remain in chisel3.experimental because,
like all Chisel annotation support, they are slated to be deprecated and
removed.

(cherry picked from commit 424e9446f1675fe0168e22bdfbbe85db997376e6)

# Conflicts:
#	docs/src/cookbooks/verilog-vs-chisel.md
#	docs/src/explanations/chisel-enum.md

* Maintain binary compatbility, use aliases in chisel3 package

* Deprecate the actual classes in chisel3.experimental
* Also fix backport conflicts

Co-authored-by: Jack Koenig <koenig@sifive.com>

20 files changed, 41 insertions, 42 deletions

diff --git a/core/src/main/scala/chisel3/Aggregate.scala b/core/src/main/scala/chisel3/Aggregate.scala
index b6836ea7..dbf6969f 100644
--- a/core/src/main/scala/chisel3/Aggregate.scala
+++ b/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._
diff --git a/core/src/main/scala/chisel3/Data.scala b/core/src/main/scala/chisel3/Data.scala
index dddc0d5d..259e6545 100644
--- a/core/src/main/scala/chisel3/Data.scala
+++ b/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._
diff --git a/core/src/main/scala/chisel3/StrongEnum.scala b/core/src/main/scala/chisel3/experimental/ChiselEnum.scala
index c1967949..37c6fb58 100644
--- a/core/src/main/scala/chisel3/StrongEnum.scala
+++ b/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
@@ -277,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 {
@@ -433,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.
   * {{{
@@ -452,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
diff --git a/core/src/main/scala/chisel3/experimental/package.scala b/core/src/main/scala/chisel3/experimental/package.scala
index 42ec9666..2b493aab 100644
--- a/core/src/main/scala/chisel3/experimental/package.scala
+++ b/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
diff --git a/core/src/main/scala/chisel3/internal/Builder.scala b/core/src/main/scala/chisel3/internal/Builder.scala
index be2c4cfb..ab1435c5 100644
--- a/core/src/main/scala/chisel3/internal/Builder.scala
+++ b/core/src/main/scala/chisel3/internal/Builder.scala
@@ -509,7 +509,7 @@ private[chisel3] class DynamicContext(
   val newAnnotations = ArrayBuffer[ChiselMultiAnnotation]()
   var currentModule: Option[BaseModule] = None
 
-  // Enum annotations are added every time a StrongEnum is bound
+  // 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]()
 
diff --git a/core/src/main/scala/chisel3/internal/MonoConnect.scala b/core/src/main/scala/chisel3/internal/MonoConnect.scala
index 4e762a7c..a0cca4a6 100644
--- a/core/src/main/scala/chisel3/internal/MonoConnect.scala
+++ b/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}
diff --git a/core/src/main/scala/chisel3/package.scala b/core/src/main/scala/chisel3/package.scala
index 87024683..afffad1c 100644
--- a/core/src/main/scala/chisel3/package.scala
+++ b/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.
diff --git a/docs/src/cookbooks/cookbook.md b/docs/src/cookbooks/cookbook.md
index e7485e66..5b8239a7 100644
--- a/docs/src/cookbooks/cookbook.md
+++ b/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 {
diff --git a/docs/src/cookbooks/verilog-vs-chisel.md b/docs/src/cookbooks/verilog-vs-chisel.md
index 1adf609e..75cc0ec8 100644
--- a/docs/src/cookbooks/verilog-vs-chisel.md
+++ b/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}
 ```
 
diff --git a/docs/src/explanations/chisel-enum.md b/docs/src/explanations/chisel-enum.md
index 16b5570d..b76fd746 100644
--- a/docs/src/explanations/chisel-enum.md
+++ b/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
diff --git a/src/test/scala/chiselTests/AsTypeOfTester.scala b/src/test/scala/chiselTests/AsTypeOfTester.scala
index 2141cac2..a1668914 100644
--- a/src/test/scala/chiselTests/AsTypeOfTester.scala
+++ b/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 {
diff --git a/src/test/scala/chiselTests/BundleElementsSpec.scala b/src/test/scala/chiselTests/BundleElementsSpec.scala
index fab2e733..afca3d81 100644
--- a/src/test/scala/chiselTests/BundleElementsSpec.scala
+++ b/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
diff --git a/src/test/scala/chiselTests/BundleLiteralSpec.scala b/src/test/scala/chiselTests/BundleLiteralSpec.scala
index bc6522bb..f90e230d 100644
--- a/src/test/scala/chiselTests/BundleLiteralSpec.scala
+++ b/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 {
diff --git a/src/test/scala/chiselTests/StrongEnum.scala b/src/test/scala/chiselTests/ChiselEnum.scala
index e9f412fe..dbad273b 100644
--- a/src/test/scala/chiselTests/StrongEnum.scala
+++ b/src/test/scala/chiselTests/ChiselEnum.scala
@@ -3,9 +3,7 @@
 package chiselTests
 
 import chisel3._
-import chisel3.experimental.ChiselEnum
 import chisel3.experimental.AffectsChiselPrefix
-import chisel3.experimental.suppressEnumCastWarning
 import chisel3.internal.firrtl.UnknownWidth
 import chisel3.stage.{ChiselGeneratorAnnotation, ChiselStage}
 import chisel3.util._
@@ -119,7 +117,7 @@ class EnumOps(val xType: ChiselEnum, val yType: ChiselEnum) extends Module {
   io.ne := io.x =/= io.y
 }
 
-object StrongEnumFSM {
+object ChiselEnumFSM {
   object State extends ChiselEnum {
     val sNone, sOne1, sTwo1s = Value
 
@@ -127,9 +125,9 @@ object StrongEnumFSM {
   }
 }
 
-class StrongEnumFSM extends Module {
-  import StrongEnumFSM.State
-  import StrongEnumFSM.State._
+class ChiselEnumFSM extends Module {
+  import ChiselEnumFSM.State
+  import ChiselEnumFSM.State._
 
   // This FSM detects two 1's one after the other
   val io = IO(new Bundle {
@@ -304,10 +302,10 @@ class WidthTester extends BasicTester {
   stop()
 }
 
-class StrongEnumFSMTester extends BasicTester {
-  import StrongEnumFSM.State._
+class ChiselEnumFSMTester extends BasicTester {
+  import ChiselEnumFSM.State._
 
-  val dut = Module(new StrongEnumFSM)
+  val dut = Module(new ChiselEnumFSM)
 
   // Inputs and expected results
   val inputs: Vec[Bool] = VecInit(false.B, true.B, false.B, true.B, true.B, true.B, false.B, true.B, true.B, false.B)
@@ -362,10 +360,10 @@ class IsOneOfTester extends BasicTester {
   stop()
 }
 
-class StrongEnumSpec extends ChiselFlatSpec with Utils {
+class ChiselEnumSpec extends ChiselFlatSpec with Utils {
   import chisel3.internal.ChiselException
 
-  behavior.of("Strong enum tester")
+  behavior.of("ChiselEnum")
 
   it should "fail to instantiate non-literal enums with the Value function" in {
     an[ExceptionInInitializerError] should be thrownBy extractCause[ExceptionInInitializerError] {
@@ -470,8 +468,8 @@ class StrongEnumSpec extends ChiselFlatSpec with Utils {
     "object UnnamedEnum extends ChiselEnum { Value }" shouldNot compile
   }
 
-  "StrongEnum FSM" should "work" in {
-    assertTesterPasses(new StrongEnumFSMTester)
+  "ChiselEnum FSM" should "work" in {
+    assertTesterPasses(new ChiselEnumFSMTester)
   }
 
   "Casting a UInt to an Enum" should "warn if the UInt can express illegal states" in {
@@ -584,7 +582,7 @@ class StrongEnumSpec extends ChiselFlatSpec with Utils {
   }
 }
 
-class StrongEnumAnnotator extends Module {
+class ChiselEnumAnnotator extends Module {
   import EnumExample._
 
   object LocalEnum extends ChiselEnum {
@@ -643,7 +641,7 @@ class StrongEnumAnnotator extends Module {
   val indexed2 = vec_of_bundles(cycle)
 }
 
-class StrongEnumAnnotatorWithChiselName extends Module {
+class ChiselEnumAnnotatorWithChiselName extends Module {
   import EnumExample._
 
   object LocalEnum extends ChiselEnum with AffectsChiselPrefix {
@@ -702,7 +700,7 @@ class StrongEnumAnnotatorWithChiselName extends Module {
   val indexed2 = vec_of_bundles(cycle)
 }
 
-class StrongEnumAnnotationSpec extends AnyFreeSpec with Matchers {
+class ChiselEnumAnnotationSpec extends AnyFreeSpec with Matchers {
   import chisel3.experimental.EnumAnnotations._
   import firrtl.annotations.{Annotation, ComponentName}
 
@@ -820,7 +818,7 @@ class StrongEnumAnnotationSpec extends AnyFreeSpec with Matchers {
   }
 
   "Test that strong enums annotate themselves appropriately" in {
-    test(() => new StrongEnumAnnotator)
-    test(() => new StrongEnumAnnotatorWithChiselName)
+    test(() => new ChiselEnumAnnotator)
+    test(() => new ChiselEnumAnnotatorWithChiselName)
   }
 }
diff --git a/src/test/scala/chiselTests/DataEqualitySpec.scala b/src/test/scala/chiselTests/DataEqualitySpec.scala
index 4ac3292d..8fbbaf94 100644
--- a/src/test/scala/chiselTests/DataEqualitySpec.scala
+++ b/src/test/scala/chiselTests/DataEqualitySpec.scala
@@ -3,7 +3,7 @@ package chiselTests
 import chisel3._
 import chisel3.experimental.VecLiterals._
 import chisel3.experimental.BundleLiterals._
-import chisel3.experimental.{Analog, ChiselEnum, ChiselRange, FixedPoint, Interval}
+import chisel3.experimental.{Analog, ChiselRange, FixedPoint, Interval}
 import chisel3.stage.ChiselStage
 import chisel3.testers.BasicTester
 import chisel3.util.Valid
diff --git a/src/test/scala/chiselTests/DataPrint.scala b/src/test/scala/chiselTests/DataPrint.scala
index 091722b8..82fa1519 100644
--- a/src/test/scala/chiselTests/DataPrint.scala
+++ b/src/test/scala/chiselTests/DataPrint.scala
@@ -5,7 +5,7 @@ package chiselTests
 import org.scalatest._
 
 import chisel3._
-import chisel3.experimental.{ChiselEnum, FixedPoint}
+import chisel3.experimental.FixedPoint
 import chisel3.experimental.BundleLiterals._
 import chisel3.stage.ChiselStage
 import org.scalatest.matchers.should.Matchers
diff --git a/src/test/scala/chiselTests/VecLiteralSpec.scala b/src/test/scala/chiselTests/VecLiteralSpec.scala
index e2eb791d..dcc96b17 100644
--- a/src/test/scala/chiselTests/VecLiteralSpec.scala
+++ b/src/test/scala/chiselTests/VecLiteralSpec.scala
@@ -5,7 +5,7 @@ package chiselTests
 import chisel3._
 import chisel3.experimental.BundleLiterals.AddBundleLiteralConstructor
 import chisel3.experimental.VecLiterals._
-import chisel3.experimental.{ChiselEnum, FixedPoint, VecLiteralException}
+import chisel3.experimental.{FixedPoint, VecLiteralException}
 import chisel3.stage.ChiselStage
 import chisel3.testers.BasicTester
 import chisel3.util.Counter
diff --git a/src/test/scala/chiselTests/WarningSpec.scala b/src/test/scala/chiselTests/WarningSpec.scala
index 1cef1ffc..1bb9e6dc 100644
--- a/src/test/scala/chiselTests/WarningSpec.scala
+++ b/src/test/scala/chiselTests/WarningSpec.scala
@@ -5,8 +5,6 @@ package chiselTests
 import chisel3._
 import chisel3.util._
 import chisel3.stage.ChiselStage
-import chisel3.experimental.ChiselEnum
-import chisel3.experimental.EnumType
 
 class WarningSpec extends ChiselFlatSpec with Utils {
   behavior.of("Warnings")
diff --git a/src/test/scala/chiselTests/experimental/TraceSpec.scala b/src/test/scala/chiselTests/experimental/TraceSpec.scala
index 31ccdf9b..1d67ba0b 100644
--- a/src/test/scala/chiselTests/experimental/TraceSpec.scala
+++ b/src/test/scala/chiselTests/experimental/TraceSpec.scala
@@ -3,7 +3,6 @@
 package chiselTests
 
 import chisel3._
-import chisel3.experimental.ChiselEnum
 import chisel3.experimental.Trace._
 import chisel3.stage.{ChiselGeneratorAnnotation, ChiselStage, DesignAnnotation}
 import chisel3.util.experimental.InlineInstance
diff --git a/src/test/scala/cookbook/FSM.scala b/src/test/scala/cookbook/FSM.scala
index 66f3063f..40f8abc7 100644
--- a/src/test/scala/cookbook/FSM.scala
+++ b/src/test/scala/cookbook/FSM.scala
@@ -4,11 +4,10 @@ package cookbook
 
 import chisel3._
 import chisel3.util._
-import chisel3.experimental.ChiselEnum
 
 /* ### How do I create a finite state machine?
  *
- * Use Chisel StrongEnum to construct the states and switch & is to construct the FSM
+ * Use ChiselEnum to construct the states and switch & is to construct the FSM
  * control logic
  */