Canonicalize construction of Decoupled with no payload (#785)

* Canonicalize construction of empty Decoupled

* Change signature after dev meeting discussion
* Make EmptyBundle private and final

* Add test case for Decoupled with no payload

* Apply suggestions from code review

Co-authored-by: Richard Lin <richard.lin@berkeley.edu>

Co-authored-by: Albert Magyar <albert.magyar@gmail.com>
Co-authored-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
Co-authored-by: Adam Izraelevitz <azidar@gmail.com>
Co-authored-by: Richard Lin <richard.lin@berkeley.edu>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

2 files changed, 28 insertions, 0 deletions

diff --git a/src/main/scala/chisel3/util/Decoupled.scala b/src/main/scala/chisel3/util/Decoupled.scala
index 6a3aad24..82511ee5 100644
--- a/src/main/scala/chisel3/util/Decoupled.scala
+++ b/src/main/scala/chisel3/util/Decoupled.scala
@@ -92,6 +92,15 @@ object Decoupled
   /** Wraps some Data with a DecoupledIO interface. */
   def apply[T <: Data](gen: T): DecoupledIO[T] = new DecoupledIO(gen)
 
+  // TODO: use a proper empty data type, this is a quick and dirty solution
+  private final class EmptyBundle extends Bundle
+
+  // Both of these methods return DecoupledIO parameterized by the most generic type: Data
+  /** Returns a [[DecoupledIO]] inteface with no payload */
+  def apply(): DecoupledIO[Data] = apply(new EmptyBundle)
+  /** Returns a [[DecoupledIO]] inteface with no payload */
+  def empty: DecoupledIO[Data] = Decoupled()
+
   /** Downconverts an IrrevocableIO output to a DecoupledIO, dropping guarantees of irrevocability.
     *
     * @note unsafe (and will error) on the producer (input) side of an IrrevocableIO
diff --git a/src/test/scala/chiselTests/DecoupledSpec.scala b/src/test/scala/chiselTests/DecoupledSpec.scala
new file mode 100644
index 00000000..c251df82
--- /dev/null
+++ b/src/test/scala/chiselTests/DecoupledSpec.scala
@@ -0,0 +1,19 @@
+// See LICENSE for license details.
+
+package chiselTests
+
+import chisel3._
+import chisel3.util.Decoupled
+
+class DecoupledSpec extends ChiselFlatSpec {
+  "Decoupled() and Decoupled.empty" should "give DecoupledIO with empty payloads" in {
+    elaborate(new Module {
+      val io = IO(new Bundle {
+        val in = Flipped(Decoupled())
+        val out = Decoupled.empty
+      })
+      io.out <> io.in
+      assert(io.asUInt.widthOption.get === 4)
+    })
+  }
+}