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>

10 files changed, 23 insertions, 29 deletions

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
  */