Fixed comment punctuation and made it clearer that using an init() method for DeqIO and EnqIO initialization is likely to change.

2 files changed, 28 insertions, 3 deletions

diff --git a/src/main/scala/Chisel/util/Decoupled.scala b/src/main/scala/Chisel/util/Decoupled.scala
index e06e899a..ba33e6c7 100644
--- a/src/main/scala/Chisel/util/Decoupled.scala
+++ b/src/main/scala/Chisel/util/Decoupled.scala
@@ -23,11 +23,20 @@ object Decoupled {
 }
 
 /** An I/O bundle for enqueuing data with valid/ready handshaking
-  * initialization must be handled, if necessary, by the parent circuit
+  * Initialization must be handled, if necessary, by the parent circuit
   */
 class EnqIO[T <: Data](gen: T) extends DecoupledIO(gen)
 {
+  /** push dat onto the output bits of this interface to let the consumer know it has happened.
+    * @param dat the values to assign to bits.
+    * @return    dat.
+    */
   def enq(dat: T): T = { valid := Bool(true); bits := dat; dat }
+
+  /** Initialize this Bundle.  Valid is set to false, and all bits are set to zero.
+    * NOTE: This method of initialization is still being discussed and could change in the
+    * future.
+    */
   def init(): Unit = {
     valid := Bool(false)
     for (io <- bits.flatten)
@@ -36,12 +45,22 @@ class EnqIO[T <: Data](gen: T) extends DecoupledIO(gen)
   override def cloneType: this.type = { new EnqIO(gen).asInstanceOf[this.type]; }
 }
 
-/** An I/O bundle for dequeuing data with valid/ready handshaking
-  * initialization must be handled, if necessary, by the parent circuit
+/** An I/O bundle for dequeuing data with valid/ready handshaking.
+  * Initialization must be handled, if necessary, by the parent circuit
   */
 class DeqIO[T <: Data](gen: T) extends DecoupledIO(gen) with Flipped
 {
+  /** Assert ready on this port and return the associated data bits.
+    * This is typically used when valid has been asserted by the producer side.
+    * @param b ignored
+    * @return the data for this device,
+    */
   def deq(b: Boolean = false): T = { ready := Bool(true); bits }
+
+  /** Initialize this Bundle.
+    * NOTE: This method of initialization is still being discussed and could change in the
+    * future.
+    */
   def init(): Unit = {
     ready := Bool(false)
   }
diff --git a/src/test/scala/chiselTests/VectorPacketIO.scala b/src/test/scala/chiselTests/VectorPacketIO.scala
index 5fff6236..99ec66a6 100644
--- a/src/test/scala/chiselTests/VectorPacketIO.scala
+++ b/src/test/scala/chiselTests/VectorPacketIO.scala
@@ -11,8 +11,11 @@ import Chisel.testers.BasicTester
   * The symptom is creation of a firrtl file
   * with missing declarations, the problem is exposed by
   * the creation of the val outs in VectorPacketIO
+  *
   * NOTE: The problem does not exist now because the initialization
   * code has been removed from DeqIO and EnqIO
+  *
+  * IMPORTANT:  The canonical way to initialize a decoupled inteface is still being debated.
   */
 class Packet extends Bundle {
   val header = UInt(width = 1)
@@ -35,6 +38,9 @@ class VectorPacketIO(n: Int) extends Bundle {
 class BrokenVectorPacketModule extends Module {
   val n  = 4
   val io = new VectorPacketIO(n)
+
+  /* the following method of initializing the circuit may change in the future */
+  io.outs.foreach(_.init())
 }
 
 class VectorPacketIOUnitTester extends BasicTester {