Programmatic Port Creation (#833)

Add chisel3.experimental.IO for programmatic port creation in Raw and
MultiIOModules. suggestName is required to name ports that cannot be
named by reflection. Two ports cannot be given the same name.

2 files changed, 77 insertions, 4 deletions

diff --git a/src/test/scala/chiselTests/NamingAnnotationTest.scala b/src/test/scala/chiselTests/NamingAnnotationTest.scala
index a7b9b75c..07962aaf 100644
--- a/src/test/scala/chiselTests/NamingAnnotationTest.scala
+++ b/src/test/scala/chiselTests/NamingAnnotationTest.scala
@@ -4,16 +4,14 @@ package chiselTests
 
 import chisel3._
 import chisel3.internal.InstanceId
-import chisel3.experimental.{chiselName, dump}
+import chisel3.experimental.{chiselName, dump, MultiIOModule}
 import org.scalatest._
 import org.scalatest.prop._
 import chisel3.testers.BasicTester
 
 import scala.collection.mutable.ListBuffer
 
-trait NamedModuleTester extends Module {
-  val io = IO(new Bundle() {})  // Named module testers don't need IO
-
+trait NamedModuleTester extends MultiIOModule {
   val expectedNameMap = ListBuffer[(InstanceId, String)]()
   val expectedModuleNameMap = ListBuffer[(Module, String)]()
 
diff --git a/src/test/scala/chiselTests/experimental/ProgrammaticPortsSpec.scala b/src/test/scala/chiselTests/experimental/ProgrammaticPortsSpec.scala
new file mode 100644
index 00000000..d17bfd32
--- /dev/null
+++ b/src/test/scala/chiselTests/experimental/ProgrammaticPortsSpec.scala
@@ -0,0 +1,75 @@
+// See LICENSE for license details.
+
+package chiselTests
+package experimental
+
+import chisel3._
+import chisel3.experimental.MultiIOModule
+
+// NOTE This is currently an experimental API and subject to change
+// Example using a private port
+class PrivatePort extends NamedModuleTester {
+  private val port = expectName(IO(Input(UInt(8.W))), "foo")
+  port.suggestName("foo")
+}
+
+// Example of using composition to add ports to a Module
+class CompositionalPort(module: NamedModuleTester, name: String) {
+  import chisel3.experimental.IO
+  val foo = module.expectName(IO(Output(Bool())), name)
+  foo.suggestName(name)
+  foo := true.B
+}
+
+class CompositionalPortTester extends NamedModuleTester {
+  val a = new CompositionalPort(this, "cheese")
+  val b = new CompositionalPort(this, "tart")
+}
+
+class PortsWinTester extends NamedModuleTester {
+  val wire = expectName(Wire(UInt()), "wire_1")
+  val foo = expectName(Wire(UInt()).suggestName("wire"), "wire_2")
+  val output = expectName(IO(Output(UInt())).suggestName("wire"), "wire")
+}
+
+class ProgrammaticPortsSpec extends ChiselFlatSpec {
+
+  private def doTest(testMod: => NamedModuleTester): Unit = {
+    var module: NamedModuleTester = null
+    elaborate { module = testMod; module }
+    assert(module.getNameFailures() == Nil)
+  }
+
+  "Programmatic port creation" should "be supported" in {
+    doTest(new PrivatePort)
+  }
+
+  "Calling IO outside of a Module definition" should "be supported" in {
+    doTest(new CompositionalPortTester)
+  }
+
+  "Ports" should "always win over internal components in naming" in {
+    doTest(new PortsWinTester)
+  }
+
+  "LegacyModule" should "ignore suggestName on ports" in {
+    doTest(new Module with NamedModuleTester {
+      val io = IO(new Bundle {
+        val foo = Output(UInt(8.W))
+      })
+      expectName(io.suggestName("cheese"), "io")
+      expectName(clock.suggestName("tart"), "clock")
+      expectName(reset.suggestName("teser"), "reset")
+    })
+  }
+
+  "SuggestName collisions on ports" should "be illegal" in {
+    a [ChiselException] should be thrownBy {
+      elaborate(new MultiIOModule {
+        val foo = IO(UInt(8.W)).suggestName("apple")
+        val bar = IO(UInt(8.W)).suggestName("apple")
+      })
+    }
+  }
+}
+