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.

Author: ucbjrl

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 = {

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._

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 {

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!

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)
+    }
   }
 }

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

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

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
+  }
+}

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
 

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

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")

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

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
 

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 {

src/main/scala/chisel3/Driver.scala

@@ -3,7 +3,6 @@
 package chisel3
 
 import chisel3.internal.ErrorLog
-import chisel3.experimental.RawModule
 import internal.firrtl._
 import firrtl._
 import firrtl.options.{Phase, PhaseManager, StageError}

src/main/scala/chisel3/aop/injecting/InjectingAspect.scala

@@ -2,9 +2,8 @@
 
 package chisel3.aop.injecting
 
-import chisel3.{Module, ModuleAspect, experimental, withClockAndReset}
+import chisel3.{Module, ModuleAspect, experimental, withClockAndReset, RawModule, MultiIOModule}
 import chisel3.aop._
-import chisel3.experimental.RawModule
 import chisel3.internal.Builder
 import chisel3.internal.firrtl.DefModule
 import chisel3.stage.DesignAnnotation
@@ -36,7 +35,7 @@ case class InjectingAspect[T <: RawModule,
     RunFirrtlTransformAnnotation(new InjectingTransform) +: modules.map { module =>
       val (chiselIR, _) = Builder.build(Module(new ModuleAspect(module) {
         module match {
-          case x: experimental.MultiIOModule => withClockAndReset(x.clock, x.reset) { injection(module) }
+          case x: MultiIOModule => withClockAndReset(x.clock, x.reset) { injection(module) }
           case x: RawModule => injection(module)
         }
       }))