Move dontTouch, RawModule, and MultiIOModule out of experimental (#1162)

* Move dontTouch out of experimental package.

* Move RawModule, MultiIOModule out of experimental.

* Respond to comments - Move LagacyModule from experimental to internal.
*NOTE*: At some point, these module definitions (especially those in separate packages) should be moved to individual files at the appropriate location in the source tree. The current organization is purely to support comparison with prior versions.

* Fix up a few more imports.

14 files changed, 113 insertions, 107 deletions

diff --git a/chiselFrontend/src/main/scala/chisel3/Annotation.scala b/chiselFrontend/src/main/scala/chisel3/Annotation.scala
index ec000d93..e54b1bf9 100644
--- a/chiselFrontend/src/main/scala/chisel3/Annotation.scala
+++ b/chiselFrontend/src/main/scala/chisel3/Annotation.scala
@@ -3,7 +3,7 @@
 package chisel3.experimental
 
 import scala.language.existentials
-import chisel3.internal.{Builder, InstanceId}
+import chisel3.internal.{Builder, InstanceId, LegacyModule}
 import chisel3.{CompileOptions, Data}
 import firrtl.Transform
 import firrtl.annotations._
@@ -21,7 +21,7 @@ trait ChiselAnnotation {
 
 /** Mixin for [[ChiselAnnotation]] that instantiates an associated FIRRTL Transform when this Annotation is present
   * during a run of
-  * [[Driver$.execute(args:Array[String],dut:()=>chisel3\.experimental\.RawModule)* Driver.execute]].
+  * [[Driver$.execute(args:Array[String],dut:()=>chisel3\.RawModule)* Driver.execute]].
   * Automatic Transform instantiation is *not* supported when the Circuit and Annotations are serialized before invoking
   * FIRRTL.
   */
@@ -45,40 +45,6 @@ object annotate { // scalastyle:ignore object.name
   }
 }
 
-/** Marks that a signal should not be removed by Chisel and Firrtl optimization passes
-  *
-  * @example {{{
-  * class MyModule extends Module {
-  *   val io = IO(new Bundle {
-  *     val a = Input(UInt(32.W))
-  *     val b = Output(UInt(32.W))
-  *   })
-  *   io.b := io.a
-  *   val dead = io.a +% 1.U // normally dead would be pruned by DCE
-  *   dontTouch(dead) // Marking it as such will preserve it
-  * }
-  * }}}
-  *
-  * @note Calling this on [[Data]] creates an annotation that Chisel emits to a separate annotations
-  * file. This file must be passed to FIRRTL independently of the `.fir` file. The execute methods
-  * in [[chisel3.Driver]] will pass the annotations to FIRRTL automatically.
-  */
-object dontTouch { // scalastyle:ignore object.name
-  /** Marks a signal to be preserved in Chisel and Firrtl
-    *
-    * @note Requires the argument to be bound to hardware
-    * @param data The signal to be marked
-    * @return Unmodified signal `data`
-    */
-  def apply[T <: Data](data: T)(implicit compileOptions: CompileOptions): T = {
-    if (compileOptions.checkSynthesizable) {
-      requireIsHardware(data, "Data marked dontTouch")
-    }
-    annotate(new ChiselAnnotation { def toFirrtl = DontTouchAnnotation(data.toNamed) })
-    data
-  }
-}
-
 /** Marks that a module to be ignored in Dedup Transform in Firrtl pass
   *
   * @example {{{
@@ -119,7 +85,7 @@ object dontTouch { // scalastyle:ignore object.name
 object doNotDedup { // scalastyle:ignore object.name
   /** Marks a module to be ignored in Dedup Transform in Firrtl
     *
-    * @param data The module to be marked
+    * @param module The module to be marked
     * @return Unmodified signal `module`
     */
    def apply[T <: LegacyModule](module: T)(implicit compileOptions: CompileOptions): Unit = {
diff --git a/chiselFrontend/src/main/scala/chisel3/Attach.scala b/chiselFrontend/src/main/scala/chisel3/Attach.scala
index 1ceba7c2..25c83d9a 100644
--- a/chiselFrontend/src/main/scala/chisel3/Attach.scala
+++ b/chiselFrontend/src/main/scala/chisel3/Attach.scala
@@ -2,6 +2,7 @@
 
 package chisel3.experimental
 
+import chisel3.RawModule
 import chisel3.internal._
 import chisel3.internal.Builder.pushCommand
 import chisel3.internal.firrtl._
diff --git a/chiselFrontend/src/main/scala/chisel3/Module.scala b/chiselFrontend/src/main/scala/chisel3/Module.scala
index a6f682a8..cd6bbeb8 100644
--- a/chiselFrontend/src/main/scala/chisel3/Module.scala
+++ b/chiselFrontend/src/main/scala/chisel3/Module.scala
@@ -121,7 +121,7 @@ package experimental {
 }
 
 package internal {
-  import chisel3.experimental.{BaseModule, MultiIOModule}
+  import chisel3.experimental.BaseModule
 
   object BaseModule {
     private[chisel3] class ClonePorts (elts: Data*)(implicit compileOptions: CompileOptions) extends Record {
diff --git a/chiselFrontend/src/main/scala/chisel3/ModuleAspect.scala b/chiselFrontend/src/main/scala/chisel3/ModuleAspect.scala
index 3edf0a22..20793cd7 100644
--- a/chiselFrontend/src/main/scala/chisel3/ModuleAspect.scala
+++ b/chiselFrontend/src/main/scala/chisel3/ModuleAspect.scala
@@ -3,7 +3,6 @@
 package chisel3
 
 import chisel3.internal.Builder
-import chisel3.experimental.RawModule
 
 /** Used by Chisel Aspects to inject Chisel code into modules, after they have been elaborated.
   * This is an internal API - don't use!
diff --git a/chiselFrontend/src/main/scala/chisel3/RawModule.scala b/chiselFrontend/src/main/scala/chisel3/RawModule.scala
index 8f201ce6..4155ef4a 100644
--- a/chiselFrontend/src/main/scala/chisel3/RawModule.scala
+++ b/chiselFrontend/src/main/scala/chisel3/RawModule.scala
@@ -1,12 +1,12 @@
 // See LICENSE for license details.
 
-package chisel3.experimental
+package chisel3
 
 import scala.collection.mutable.{ArrayBuffer, HashMap}
 import scala.collection.JavaConversions._
 import scala.language.experimental.macros
 
-import chisel3._
+import chisel3.experimental.BaseModule
 import chisel3.internal._
 import chisel3.internal.Builder._
 import chisel3.internal.firrtl._
@@ -162,68 +162,71 @@ abstract class MultiIOModule(implicit moduleCompileOptions: CompileOptions)
   }
 }
 
-/** Legacy Module class that restricts IOs to just io, clock, and reset, and provides a constructor
-  * for threading through explicit clock and reset.
-  *
-  * While this class isn't planned to be removed anytime soon (there are benefits to restricting
-  * IO), the clock and reset constructors will be phased out. Recommendation is to wrap the module
-  * in a withClock/withReset/withClockAndReset block, or directly hook up clock or reset IO pins.
-  */
-abstract class LegacyModule(implicit moduleCompileOptions: CompileOptions)
+package internal {
+
+  /** Legacy Module class that restricts IOs to just io, clock, and reset, and provides a constructor
+    * for threading through explicit clock and reset.
+    *
+    * While this class isn't planned to be removed anytime soon (there are benefits to restricting
+    * IO), the clock and reset constructors will be phased out. Recommendation is to wrap the module
+    * in a withClock/withReset/withClockAndReset block, or directly hook up clock or reset IO pins.
+    */
+  abstract class LegacyModule(implicit moduleCompileOptions: CompileOptions)
     extends MultiIOModule {
-  // These are to be phased out
-  protected var override_clock: Option[Clock] = None
-  protected var override_reset: Option[Bool] = None
+    // These are to be phased out
+    protected var override_clock: Option[Clock] = None
+    protected var override_reset: Option[Bool] = None
 
-  // IO for this Module. At the Scala level (pre-FIRRTL transformations),
-  // connections in and out of a Module may only go through `io` elements.
-  def io: Record
+    // IO for this Module. At the Scala level (pre-FIRRTL transformations),
+    // connections in and out of a Module may only go through `io` elements.
+    def io: Record
 
-  // Allow access to bindings from the compatibility package
-  protected def _compatIoPortBound() = portsContains(io)// scalastyle:ignore method.name
+    // Allow access to bindings from the compatibility package
+    protected def _compatIoPortBound() = portsContains(io)// scalastyle:ignore method.name
 
-  protected override def nameIds(rootClass: Class[_]): HashMap[HasId, String] = {
-    val names = super.nameIds(rootClass)
+    protected override def nameIds(rootClass: Class[_]): HashMap[HasId, String] = {
+      val names = super.nameIds(rootClass)
 
-    // Allow IO naming without reflection
-    names.put(io, "io")
-    names.put(clock, "clock")
-    names.put(reset, "reset")
+      // Allow IO naming without reflection
+      names.put(io, "io")
+      names.put(clock, "clock")
+      names.put(reset, "reset")
 
-    names
-  }
+      names
+    }
 
-  private[chisel3] override def namePorts(names: HashMap[HasId, String]): Unit = {
-    for (port <- getModulePorts) {
-      // This should already have been caught
-      if (!names.contains(port)) throwException(s"Unable to name port $port in $this")
-      val name = names(port)
-      port.setRef(ModuleIO(this, _namespace.name(name)))
+    private[chisel3] override def namePorts(names: HashMap[HasId, String]): Unit = {
+      for (port <- getModulePorts) {
+        // This should already have been caught
+        if (!names.contains(port)) throwException(s"Unable to name port $port in $this")
+        val name = names(port)
+        port.setRef(ModuleIO(this, _namespace.name(name)))
+      }
     }
-  }
 
-  private[chisel3] override def generateComponent(): Component = {
-    _compatAutoWrapPorts()  // pre-IO(...) compatibility hack
+    private[chisel3] override def generateComponent(): Component = {
+      _compatAutoWrapPorts()  // pre-IO(...) compatibility hack
 
-    // Restrict IO to just io, clock, and reset
-    require(io != null, "Module must have io")
-    require(portsContains(io), "Module must have io wrapped in IO(...)")
-    require((portsContains(clock)) && (portsContains(reset)), "Internal error, module did not have clock or reset as IO") // scalastyle:ignore line.size.limit
-    require(portsSize == 3, "Module must only have io, clock, and reset as IO")
+      // Restrict IO to just io, clock, and reset
+      require(io != null, "Module must have io")
+      require(portsContains(io), "Module must have io wrapped in IO(...)")
+      require((portsContains(clock)) && (portsContains(reset)), "Internal error, module did not have clock or reset as IO") // scalastyle:ignore line.size.limit
+      require(portsSize == 3, "Module must only have io, clock, and reset as IO")
 
-    super.generateComponent()
-  }
+      super.generateComponent()
+    }
 
-  private[chisel3] override def initializeInParent(parentCompileOptions: CompileOptions): Unit = {
-    // Don't generate source info referencing parents inside a module, since this interferes with
-    // module de-duplication in FIRRTL emission.
-    implicit val sourceInfo = UnlocatableSourceInfo
+    private[chisel3] override def initializeInParent(parentCompileOptions: CompileOptions): Unit = {
+      // Don't generate source info referencing parents inside a module, since this interferes with
+      // module de-duplication in FIRRTL emission.
+      implicit val sourceInfo = UnlocatableSourceInfo
 
-    if (!parentCompileOptions.explicitInvalidate) {
-      pushCommand(DefInvalid(sourceInfo, io.ref))
-    }
+      if (!parentCompileOptions.explicitInvalidate) {
+        pushCommand(DefInvalid(sourceInfo, io.ref))
+      }
 
-    clock := override_clock.getOrElse(Builder.forcedClock)
-    reset := override_reset.getOrElse(Builder.forcedReset)
+      clock := override_clock.getOrElse(Builder.forcedClock)
+      reset := override_reset.getOrElse(Builder.forcedReset)
+    }
   }
 }
diff --git a/chiselFrontend/src/main/scala/chisel3/aop/Aspect.scala b/chiselFrontend/src/main/scala/chisel3/aop/Aspect.scala
index 86f5b347..9f10a0dd 100644
--- a/chiselFrontend/src/main/scala/chisel3/aop/Aspect.scala
+++ b/chiselFrontend/src/main/scala/chisel3/aop/Aspect.scala
@@ -2,7 +2,7 @@
 
 package chisel3.aop
 
-import chisel3.experimental.RawModule
+import chisel3.RawModule
 import firrtl.annotations.{Annotation, NoTargetAnnotation}
 import firrtl.options.Unserializable
 import firrtl.AnnotationSeq
diff --git a/chiselFrontend/src/main/scala/chisel3/core/package.scala b/chiselFrontend/src/main/scala/chisel3/core/package.scala
index 13a89971..2c60ce85 100644
--- a/chiselFrontend/src/main/scala/chisel3/core/package.scala
+++ b/chiselFrontend/src/main/scala/chisel3/core/package.scala
@@ -62,17 +62,17 @@ package object core {
 
   // These provide temporary compatibility for those who foolishly imported from chisel3.core
   @deprecated("Avoid importing from chisel3.core, these are not public APIs and may change at any time. " +
-    " Use chisel3.experimental.RawModule instead. This alias will be removed in 3.3.", "since the beginning of time")
-  type RawModule = chisel3.experimental.RawModule
+    " Use chisel3.RawModule instead. This alias will be removed in 3.3.", "since the beginning of time")
+  type RawModule = chisel3.RawModule
   @deprecated("Avoid importing from chisel3.core, these are not public APIs and may change at any time. " +
-    "Use chisel3.experimental.MultiIOModule instead. This alias will be removed in 3.3.", "since the beginning of time")
-  type MultiIOModule = chisel3.experimental.MultiIOModule
+    "Use chisel3.MultiIOModule instead. This alias will be removed in 3.3.", "since the beginning of time")
+  type MultiIOModule = chisel3.MultiIOModule
   @deprecated("Avoid importing from chisel3.core, these are not public APIs and may change at any time. " +
-    " Use chisel3.experimental.RawModule instead. This alias will be removed in 3.3.", "since the beginning of time")
-  type UserModule = chisel3.experimental.RawModule
+    " Use chisel3.RawModule instead. This alias will be removed in 3.3.", "since the beginning of time")
+  type UserModule = chisel3.RawModule
   @deprecated("Avoid importing from chisel3.core, these are not public APIs and may change at any time. " +
-    "Use chisel3.experimental.MultiIOModule instead. This alias will be removed in 3.3.", "since the beginning of time")
-  type ImplicitModule = chisel3.experimental.MultiIOModule
+    "Use chisel3.MultiIOModule instead. This alias will be removed in 3.3.", "since the beginning of time")
+  type ImplicitModule = chisel3.MultiIOModule
 
   @deprecated("Use the version in chisel3._", "3.2")
   val Bits = chisel3.Bits
@@ -213,8 +213,8 @@ package object core {
   @deprecated("Use the version in chisel3._", "3.2")
   val withReset = chisel3.withReset
 
-  @deprecated("Use the version in chisel3.experimental._", "3.2")
-  val dontTouch = chisel3.experimental.dontTouch
+  @deprecated("Use the version in chisel3._", "3.2")
+  val dontTouch = chisel3.dontTouch
 
   @deprecated("Use the version in chisel3.experimental._", "3.2")
   type BaseModule = chisel3.experimental.BaseModule
diff --git a/chiselFrontend/src/main/scala/chisel3/dontTouch.scala b/chiselFrontend/src/main/scala/chisel3/dontTouch.scala
new file mode 100644
index 00000000..5dfd9f19
--- /dev/null
+++ b/chiselFrontend/src/main/scala/chisel3/dontTouch.scala
@@ -0,0 +1,37 @@
+package chisel3
+
+import chisel3.experimental.{ChiselAnnotation, annotate, requireIsHardware}
+import firrtl.transforms.DontTouchAnnotation
+
+/** Marks that a signal should not be removed by Chisel and Firrtl optimization passes
+  *
+  * @example {{{
+  * class MyModule extends Module {
+  *   val io = IO(new Bundle {
+  *     val a = Input(UInt(32.W))
+  *     val b = Output(UInt(32.W))
+  *   })
+  *   io.b := io.a
+  *   val dead = io.a +% 1.U // normally dead would be pruned by DCE
+  *   dontTouch(dead) // Marking it as such will preserve it
+  * }
+  * }}}
+  * @note Calling this on [[Data]] creates an annotation that Chisel emits to a separate annotations
+  * file. This file must be passed to FIRRTL independently of the `.fir` file. The execute methods
+  * in [[chisel3.Driver]] will pass the annotations to FIRRTL automatically.
+  */
+object dontTouch { // scalastyle:ignore object.name
+  /** Marks a signal to be preserved in Chisel and Firrtl
+    *
+    * @note Requires the argument to be bound to hardware
+    * @param data The signal to be marked
+    * @return Unmodified signal `data`
+    */
+  def apply[T <: Data](data: T)(implicit compileOptions: CompileOptions): T = {
+    if (compileOptions.checkSynthesizable) {
+      requireIsHardware(data, "Data marked dontTouch")
+    }
+    annotate(new ChiselAnnotation { def toFirrtl = DontTouchAnnotation(data.toNamed) })
+    data
+  }
+}
diff --git a/chiselFrontend/src/main/scala/chisel3/experimental/Analog.scala b/chiselFrontend/src/main/scala/chisel3/experimental/Analog.scala
index 1f7150c8..2a4aa5f5 100644
--- a/chiselFrontend/src/main/scala/chisel3/experimental/Analog.scala
+++ b/chiselFrontend/src/main/scala/chisel3/experimental/Analog.scala
@@ -5,7 +5,7 @@ package chisel3.experimental
 import chisel3.internal.firrtl.Width
 import chisel3.internal.sourceinfo.SourceInfo
 import chisel3.internal._
-import chisel3.{ActualDirection, Bits, CompileOptions, Data, Element, PString, Printable, SpecifiedDirection, UInt}
+import chisel3.{ActualDirection, Bits, CompileOptions, Data, Element, PString, Printable, RawModule, SpecifiedDirection, UInt}
 
 import scala.collection.mutable
 
diff --git a/chiselFrontend/src/main/scala/chisel3/internal/BiConnect.scala b/chiselFrontend/src/main/scala/chisel3/internal/BiConnect.scala
index f49deff4..6b4c1070 100644
--- a/chiselFrontend/src/main/scala/chisel3/internal/BiConnect.scala
+++ b/chiselFrontend/src/main/scala/chisel3/internal/BiConnect.scala
@@ -3,7 +3,7 @@
 package chisel3.internal
 
 import chisel3._
-import chisel3.experimental.{Analog, BaseModule, RawModule, attach}
+import chisel3.experimental.{Analog, BaseModule, attach}
 import chisel3.internal.Builder.pushCommand
 import chisel3.internal.firrtl.{Connect, DefInvalid}
 import scala.language.experimental.macros
diff --git a/chiselFrontend/src/main/scala/chisel3/internal/Binding.scala b/chiselFrontend/src/main/scala/chisel3/internal/Binding.scala
index 23e35f5c..07c44f9f 100644
--- a/chiselFrontend/src/main/scala/chisel3/internal/Binding.scala
+++ b/chiselFrontend/src/main/scala/chisel3/internal/Binding.scala
@@ -3,7 +3,7 @@
 package chisel3.internal
 
 import chisel3._
-import chisel3.experimental.{BaseModule, RawModule}
+import chisel3.experimental.BaseModule
 import chisel3.internal.firrtl.LitArg
 
 /** Requires that a node is hardware ("bound")
diff --git a/chiselFrontend/src/main/scala/chisel3/internal/MonoConnect.scala b/chiselFrontend/src/main/scala/chisel3/internal/MonoConnect.scala
index ace7be20..1c001183 100644
--- a/chiselFrontend/src/main/scala/chisel3/internal/MonoConnect.scala
+++ b/chiselFrontend/src/main/scala/chisel3/internal/MonoConnect.scala
@@ -3,7 +3,7 @@
 package chisel3.internal
 
 import chisel3._
-import chisel3.experimental.{Analog, BaseModule, EnumType, FixedPoint, RawModule, UnsafeEnum}
+import chisel3.experimental.{Analog, BaseModule, EnumType, FixedPoint, UnsafeEnum}
 import chisel3.internal.Builder.pushCommand
 import chisel3.internal.firrtl.{Connect, DefInvalid}
 import scala.language.experimental.macros
diff --git a/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala b/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala
index e4b660dd..4643f66c 100644
--- a/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala
+++ b/chiselFrontend/src/main/scala/chisel3/internal/firrtl/IR.scala
@@ -5,7 +5,7 @@ package chisel3.internal.firrtl
 import chisel3._
 import chisel3.internal._
 import chisel3.internal.sourceinfo.SourceInfo
-import chisel3.experimental.{BaseModule, ChiselAnnotation, Param, RawModule}
+import chisel3.experimental.{BaseModule, ChiselAnnotation, Param}
 
 // scalastyle:off number.of.types
 
diff --git a/chiselFrontend/src/main/scala/chisel3/package.scala b/chiselFrontend/src/main/scala/chisel3/package.scala
index 4a240a8c..51bcf1fe 100644
--- a/chiselFrontend/src/main/scala/chisel3/package.scala
+++ b/chiselFrontend/src/main/scala/chisel3/package.scala
@@ -142,7 +142,7 @@ package object chisel3 {    // scalastyle:ignore package.object.name
 
   type InstanceId = internal.InstanceId
 
-  type Module = chisel3.experimental.LegacyModule
+  type Module = chisel3.internal.LegacyModule
 
   /** Implicit for custom Printable string interpolator */
   implicit class PrintableHelper(val sc: StringContext) extends AnyVal {