Promote FlatIO to package chisel3 (#3727)

Also change to an object (from a def) so that it shows up in ScalaDoc
search.

Author: jackkoenig

core/src/main/scala/chisel3/IO.scala

@@ -2,8 +2,9 @@ package chisel3
 
 import chisel3.internal.requireIsChiselType // Fix ambiguous import
 import chisel3.internal.{throwException, Builder}
-import chisel3.experimental.SourceInfo
+import chisel3.experimental.{noPrefix, SourceInfo}
 import chisel3.properties.{Class, Property}
+import chisel3.reflect.DataMirror.internal.chiselTypeClone
 
 object IO {
 
@@ -62,3 +63,55 @@ object IO {
     iodefClone
   }
 }
+
+/** The same as [[IO]] except there is no prefix when given a [[Record]] or
+  * [[Bundle]].  For [[Element]] ([[UInt]], etc.) or [[Vec]] types, this is
+  * the same as [[IO]].
+  *
+  * @example {{{
+  * class MyBundle extends Bundle {
+  *   val foo = Input(UInt(8.W))
+  *   val bar = Output(UInt(8.W))
+  * }
+  * class MyModule extends Module {
+  *   val io = FlatIO(new MyBundle)
+  *   // input  [7:0] foo,
+  *   // output [7:0] bar
+  * }
+  * }}}
+  */
+object FlatIO {
+  def apply[T <: Data](gen: => T)(implicit sourceInfo: SourceInfo): T = noPrefix {
+    import chisel3.experimental.dataview._
+    def coerceDirection(d: Data) = {
+      import chisel3.{SpecifiedDirection => SD}
+      chisel3.reflect.DataMirror.specifiedDirectionOf(gen) match {
+        case SD.Flip   => Flipped(d)
+        case SD.Input  => Input(d)
+        case SD.Output => Output(d)
+        case _         => d
+      }
+    }
+
+    type R = T with Record
+    gen match {
+      case _:      Element => IO(gen)
+      case _:      Vec[_] => IO(gen)
+      case record: R =>
+        val ports: Seq[Data] =
+          record._elements.toSeq.reverse.map {
+            case (name, data) =>
+              val p = chisel3.IO(coerceDirection(chiselTypeClone(data).asInstanceOf[Data]))
+              p.suggestName(name)
+              p
+
+          }
+
+        implicit val dv: DataView[Seq[Data], R] = DataView.mapping(
+          _ => chiselTypeClone(gen).asInstanceOf[R],
+          (seq, rec) => seq.zip(rec._elements.toSeq.reverse).map { case (port, (_, field)) => port -> field }
+        )
+        ports.viewAs[R]
+    }
+  }
+}

core/src/main/scala/chisel3/experimental/package.scala

@@ -81,43 +81,8 @@ package object experimental {
   type Direction = ActualDirection
   val Direction = ActualDirection
 
-  /** The same as [[IO]] except there is no prefix when given a [[Record]] or
-    * [[Bundle]].  For [[Element]] ([[UInt]], etc.) or [[Vec]] types, this is
-    * the same as [[IO]].
-    */
-  def FlatIO[T <: Data](gen: => T)(implicit sourceInfo: SourceInfo): T = noPrefix {
-    import dataview._
-    def coerceDirection(d: Data) = {
-      import chisel3.{SpecifiedDirection => SD}
-      chisel3.reflect.DataMirror.specifiedDirectionOf(gen) match {
-        case SD.Flip   => Flipped(d)
-        case SD.Input  => Input(d)
-        case SD.Output => Output(d)
-        case _         => d
-      }
-    }
-
-    type R = T with Record
-    gen match {
-      case _:      Element => IO(gen)
-      case _:      Vec[_] => IO(gen)
-      case record: R =>
-        val ports: Seq[Data] =
-          record._elements.toSeq.reverse.map {
-            case (name, data) =>
-              val p = chisel3.IO(coerceDirection(chiselTypeClone(data).asInstanceOf[Data]))
-              p.suggestName(name)
-              p
-
-          }
-
-        implicit val dv: DataView[Seq[Data], R] = DataView.mapping(
-          _ => chiselTypeClone(gen).asInstanceOf[R],
-          (seq, rec) => seq.zip(rec._elements.toSeq.reverse).map { case (port, (_, field)) => port -> field }
-        )
-        ports.viewAs[R]
-    }
-  }
+  @deprecated("FlatIO has moved to package chisel3", "Chisel 6.0")
+  val FlatIO = chisel3.FlatIO
 
   class dump extends chisel3.internal.naming.dump
   class treedump extends chisel3.internal.naming.treedump

docs/src/cookbooks/cookbook.md

@@ -727,7 +727,6 @@ normal `val` prefix, you can use `FlatIO`:
 
 ```scala mdoc:silent:reset
 import chisel3._
-import chisel3.experimental.FlatIO
 
 class MyBundle extends Bundle {
   val foo = Input(UInt(8.W))

src/main/scala/chisel3/FixedIOModule.scala

@@ -2,7 +2,7 @@
 
 package chisel3
 
-import chisel3.experimental.{BaseModule, ExtModule, FlatIO, Param}
+import chisel3.experimental.{BaseModule, ExtModule, Param}
 
 /** A module or external module whose IO is generated from a specific generator.
   * This module may have no additional IO created other than what is specified

src/main/scala/chisel3/interface/Interface.scala

@@ -2,7 +2,7 @@
 package chisel3.interface
 
 import chisel3.{BlackBox => _, Module => _, _}
-import chisel3.experimental.{BaseModule, FlatIO}
+import chisel3.experimental.BaseModule
 import chisel3.experimental.dataview._
 import chisel3.probe.define
 import chisel3.reflect.DataMirror

src/main/scala/chisel3/util/circt/PlusArgsValue.scala

@@ -5,7 +5,7 @@ package chisel3.util.circt
 import scala.language.reflectiveCalls
 
 import chisel3._
-import chisel3.experimental.{FlatIO, IntrinsicModule}
+import chisel3.experimental.IntrinsicModule
 import chisel3.internal.Builder
 
 import circt.Intrinsic

src/test/scala/chiselTests/ExtModule.scala

@@ -3,7 +3,7 @@
 package chiselTests
 
 import chisel3._
-import chisel3.experimental._
+import chisel3.experimental.ExtModule
 import circt.stage.ChiselStage
 import chisel3.testers.{BasicTester, TesterDriver}
 import chisel3.reflect.DataMirror
@@ -12,8 +12,6 @@ import chisel3.reflect.DataMirror
 // in their own scope.
 package extmoduletests {
 
-  import chisel3.experimental.ExtModule
-
   class BlackBoxInverter extends ExtModule {
     val in = IO(Input(Bool()))
     val out = IO(Output(Bool()))

src/test/scala/chiselTests/experimental/FlatIOSpec.scala

@@ -5,7 +5,7 @@ package chiselTests.experimental
 import chisel3._
 import chisel3.util.Valid
 import circt.stage.ChiselStage.emitCHIRRTL
-import chisel3.experimental.{Analog, FlatIO}
+import chisel3.experimental.Analog
 import chiselTests.ChiselFlatSpec
 
 class FlatIOSpec extends ChiselFlatSpec {

src/test/scala/chiselTests/properties/PropertySpec.scala

@@ -3,7 +3,6 @@
 package chiselTests.properties
 
 import chisel3._
-import chisel3.experimental.FlatIO
 import chisel3.properties.{Class, Path, Property, PropertyType}
 import chiselTests.{ChiselFlatSpec, MatchesAndOmits}
 import circt.stage.ChiselStage