Added Incoming/Outgoing, and clarified scaladoc on Input/Output

Author: azidar

core/src/main/scala/chisel3/Data.scala

@@ -46,6 +46,18 @@ object SpecifiedDirection {
     case Input       => Output
   }
 
+  /** Returns true if specified direction manifests as a flipped field
+    *
+    * @param dir provided specified direction
+    * @return
+    */
+  private[chisel3] def isFlipped(dir: SpecifiedDirection): Boolean  = dir match {
+    case Unspecified => false
+    case Flip        => true
+    case Output      => false
+    case Input       => true
+  }
+
   /** Returns the effective SpecifiedDirection of this node given the parent's effective SpecifiedDirection
     * and the user-specified SpecifiedDirection of this node.
     */
@@ -251,8 +263,17 @@ object chiselTypeOf {
   }
 }
 
-/**
-  * Input, Output, and Flipped are used to define the directions of Module IOs.
+/** Creates a field of a parent [[Aggregate]] which is
+  *  - flipped relative to that parent
+  *  - coerced all members of the field to be aligned
+  *
+  * E.g. The following will create a field `i` of `b` where all recursive sub-elements of `i` are aligned, and where `i` flipped relative to `b`
+  *
+  * ```scala
+  * val b = new Bundle {
+  *   val i = Input(new Decoupled(UInt(32.W))
+  * }
+  * ```
   *
   * Note that they currently clone their source argument, including its bindings.
   *
@@ -263,12 +284,44 @@ object Input {
     SpecifiedDirection.specifiedDirection(source)(_ => SpecifiedDirection.Input)
   }
 }
+
+/** Creates a field of a parent [[Aggregate]] which is
+  *  - aligned relative to that parent
+  *  - coerced all members of the field to be aligned
+  *
+  * E.g. The following will create a field `i` of `b` where all recursive sub-elements of `i` are aligned, and where `i` is also aligned relative to `b`
+  *
+  * ```scala
+  * val b = new Bundle {
+  *   val i = Output(new Decoupled(UInt(32.W))
+  * }
+  * ```
+  *
+  * Note that they currently clone their source argument, including its bindings.
+  *
+  * Thus, an error will be thrown if these are used on bound Data
+  */
 object Output {
   def apply[T <: Data](source: => T): T = {
     SpecifiedDirection.specifiedDirection(source)(_ => SpecifiedDirection.Output)
   }
 }
 
+/** Creates a field of a parent [[Aggregate]] which is
+  *  - flipped relative to that parent
+  * 
+  * E.g. The following will create a field `i` of `b` where `i` is flipped relative to `b`
+  * 
+  * ```scala
+  * val b = new Bundle {
+  *   val i = Flipped(new Decoupled(UInt(32.W))
+  * }
+  * ```
+  *
+  * Note that they currently clone their source argument, including its bindings.
+  *
+  * Thus, an error will be thrown if these are used on bound Data
+  */
 object Flipped {
   def apply[T <: Data](source: => T): T = {
     SpecifiedDirection.specifiedDirection(source)(x => SpecifiedDirection.flip(x.specifiedDirection))

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

@@ -9,11 +9,7 @@ object IO {
 
   /** Constructs a port for the current Module
     *
-    * This must wrap the datatype used to set the io field of any Module.
-    * i.e. All concrete modules must have defined io in this form:
-    * [lazy] val io[: io type] = IO(...[: io type])
-    *
-    * Items in [] are optional.
+    * This must wrap the datatype used to create an io port of any Module.
     *
     * The granted iodef must be a chisel type and not be bound to hardware.
     *
@@ -62,3 +58,55 @@ object IO {
     iodefClone
   }
 }
+
+object Incoming {
+
+  /** Constructs an incoming port of the provided `iodef` chisel type for the current Module
+    *
+    * The following example creates a input (and mixed-alignment) aggregate port in the current module
+    *
+    * ```scala
+    *   val i = Incoming(new Decoupled(UInt(32.W)))
+    * ```
+    * In this example, the sub-elements of `i` are ports of the following direction:
+    *  * `i.bits` is an input port
+    *  * `i.valid` is an input port
+    *  * `i.ready` is an output port
+    *
+    * Note that `Incoming(foo)` is equivalent to `IO(Flipped(foo))`
+    *
+    * This must wrap the datatype used to create an io port of any Module.
+    *
+    * The granted iodef must be a non-flipped chisel type and not be bound to hardware.
+    */
+  def apply[T <: Data](iodef: => T)(implicit sourceInfo: SourceInfo): T = {
+    if (SpecifiedDirection.isFlipped(iodef.specifiedDirection)) Builder.error("Incoming(..) cannot accept a chisel typed which is flipped")
+    IO(Flipped(iodef))
+  }
+}
+
+object Outgoing {
+
+  /** Constructs an outgoing port of the provided `iodef` chisel type for the current Module
+    *
+    * The following example creates a output (and mixed-alignment) aggregate port in the current module
+    *
+    * ```scala
+    *   val i = Outgoing(new Decoupled(UInt(32.W)))
+    * ```
+    * In this example, the sub-elements of `i` are ports of the following direction:
+    *  * `i.bits` is an output port
+    *  * `i.valid` is an output port
+    *  * `i.ready` is an input port
+    *
+    * Note that `Outgoing(foo)` is equivalent to `IO(foo)`
+    *
+    * This must wrap the datatype used to create an io port of any Module.
+    *
+    * The granted iodef must be a non-flipped chisel type and not be bound to hardware.
+    */
+  def apply[T <: Data](iodef: => T)(implicit sourceInfo: SourceInfo): T = {
+    if (SpecifiedDirection.isFlipped(iodef.specifiedDirection)) Builder.error("Outgoing(..) cannot accept a chisel typed which is flipped")
+    IO(iodef)
+  }
+}