Add Rocket Chip-style clonemodule as CloneModuleAsRecord to experimental (#943)

2 files changed, 113 insertions, 0 deletions

diff --git a/src/main/scala/chisel3/package.scala b/src/main/scala/chisel3/package.scala
index 3b1275f6..ddabf62c 100644
--- a/src/main/scala/chisel3/package.scala
+++ b/src/main/scala/chisel3/package.scala
@@ -436,6 +436,28 @@ package object chisel3 {    // scalastyle:ignore package.object.name
 
     val IO = chisel3.core.IO
 
+    // Rocket Chip-style clonemodule
+
+    /** A record containing the results of CloneModuleAsRecord
+      * The apply method is retrieves the element with the supplied name.
+      */
+    type ClonePorts = chisel3.core.BaseModule.ClonePorts
+
+    object CloneModuleAsRecord {
+      /** Clones an existing module and returns a record of all its top-level ports.
+        * Each element of the record is named with a string matching the
+        * corresponding port's name and shares the port's type.
+        * @example {{{
+        * val q1 = Module(new Queue(UInt(32.W), 2))
+        * val q2_io = CloneModuleAsRecord(q1)("io").asInstanceOf[q1.io.type]
+        * q2_io.enq <> q1.io.deq
+        * }}}
+        */
+      def apply(proto: BaseModule)(implicit sourceInfo: chisel3.internal.sourceinfo.SourceInfo, compileOptions: chisel3.core.CompileOptions): ClonePorts = {
+        chisel3.core.BaseModule.cloneIORecord(proto)
+      }
+    }
+
     // Implicit conversions for BlackBox Parameters
     implicit def fromIntToIntParam(x: Int): IntParam = IntParam(BigInt(x))
     implicit def fromLongToIntParam(x: Long): IntParam = IntParam(BigInt(x))
diff --git a/src/test/scala/chiselTests/CloneModuleSpec.scala b/src/test/scala/chiselTests/CloneModuleSpec.scala
new file mode 100644
index 00000000..9a637df9
--- /dev/null
+++ b/src/test/scala/chiselTests/CloneModuleSpec.scala
@@ -0,0 +1,91 @@
+// See LICENSE for license details.
+
+package chiselTests
+
+import chisel3._
+import chisel3.util.{Queue, EnqIO, DeqIO, QueueIO, log2Ceil}
+import chisel3.experimental.{CloneModuleAsRecord, MultiIOModule, withClockAndReset}
+import chisel3.testers.BasicTester
+import org.scalatest._
+import org.scalatest.prop._
+
+class MultiIOQueue[T <: Data](gen: T, val entries: Int) extends MultiIOModule {
+  val clk = IO(Input(Clock()))
+  val rst = IO(Input(Bool()))
+  val enq = IO(Flipped(EnqIO(gen)))
+  val deq = IO(Flipped(DeqIO(gen)))
+  val count = IO(Output(UInt(log2Ceil(entries + 1).W)))
+  val impl = withClockAndReset(clk, rst) { Module(new Queue(gen, entries)) }
+  impl.io.enq <> enq
+  deq <> impl.io.deq
+  count := impl.io.count
+}
+
+class QueueClone(multiIO: Boolean = false) extends Module {
+  val io = IO(new QueueIO(UInt(32.W), 4))
+  if (multiIO) {
+    val q1 = Module(new MultiIOQueue(UInt(32.W), 2))
+    val q2_io = CloneModuleAsRecord(q1)
+    q1.clk := clock
+    q1.rst := reset
+    q1.enq <> io.enq
+    q2_io("clk").asInstanceOf[Clock] := clock
+    q2_io("rst").asInstanceOf[Bool] := reset
+    q2_io("enq").asInstanceOf[q1.enq.type] <> q1.deq
+    io.deq <> q2_io("deq").asInstanceOf[q1.deq.type]
+    io.count := q1.count + q2_io("count").asInstanceOf[q1.count.type]
+  } else {
+    val q1 = Module(new Queue(UInt(32.W), 2))
+    val q2_io = CloneModuleAsRecord(q1)
+    q1.io.enq <> io.enq
+    val q2_io_bundle = q2_io("io").asInstanceOf[q1.io.type]
+    q2_io_bundle.enq <> q1.io.deq
+    io.deq <> q2_io_bundle.deq
+    io.count := q1.io.count + q2_io_bundle.count
+  }
+}
+
+class QueueCloneTester(x: Int, multiIO: Boolean = false) extends BasicTester {
+  val dut = Module(new QueueClone(multiIO))
+  val start = RegNext(dut.io.enq.fire, true.B)
+  val accept = RegNext(dut.io.deq.valid, false.B)
+  dut.io.enq.bits := x.U
+  dut.io.enq.valid := start
+  dut.io.deq.ready := accept
+  when (dut.io.deq.fire) {
+    assert(dut.io.deq.bits === x.U)
+    stop()
+  }
+}
+
+class CloneModuleSpec extends ChiselPropSpec {
+
+  val xVals = Table(
+    ("x"),  // First tuple defines column names
+    (42),   // Subsequent tuples define the data
+    (63),
+    (99))
+
+  property("QueueCloneTester should return the correct result") {
+    forAll (xVals) { (x: Int) =>
+      assertTesterPasses{ new QueueCloneTester(x) }
+    }
+  }
+
+  property("QueueClone's cloned queues should share the same module") {
+    val c = Driver.toFirrtl(Driver.elaborate(() => new QueueClone))
+    assert(c.modules.length == 2)
+  }
+
+  property("Clone of MultiIOModule should simulate correctly") {
+    forAll (xVals) { (x: Int) =>
+      assertTesterPasses{ new QueueCloneTester(x, multiIO=true) }
+    }
+  }
+
+  property("Clones of MultiIOModules should share the same module") {
+    val c = Driver.toFirrtl(Driver.elaborate(() => new QueueClone(multiIO=true)))
+    assert(c.modules.length == 3)
+  }
+
+}