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>

7 files changed, 16 insertions, 7 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.