Merge branch 'master' into release

# Conflicts:
#	build.sbt

Author: ucbjrl

build.sbt

@@ -17,8 +17,8 @@ lazy val commonSettings = Seq (
   organization := "edu.berkeley.cs",
   version := "3.0-SNAPSHOT_2017-05-25",
   git.remoteRepo := "git@github.com:ucb-bar/chisel3.git",
-  scalaVersion := "2.11.7",
   autoAPIMappings := true,
+  scalaVersion := "2.11.11",
   resolvers ++= Seq(
     Resolver.sonatypeRepo("snapshots"),
     Resolver.sonatypeRepo("releases")
@@ -86,9 +86,9 @@ lazy val chiselSettings = Seq (
   dep: String => "edu.berkeley.cs" %% dep % sys.props.getOrElse(dep + "Version", defaultVersions(dep)) }),
 
   libraryDependencies ++= Seq(
-    "org.scalatest" %% "scalatest" % "2.2.5" % "test",
-    "org.scalacheck" %% "scalacheck" % "1.12.4" % "test",
-    "com.github.scopt" %% "scopt" % "3.4.0"
+    "org.scalatest" %% "scalatest" % "3.0.1" % "test",
+    "org.scalacheck" %% "scalacheck" % "1.13.4" % "test",
+    "com.github.scopt" %% "scopt" % "3.5.0"
   ),
 
   // Tests from other projects may still run concurrently.

project/build.properties

@@ -1 +1 @@
-sbt.version=0.13.12
+sbt.version=0.13.15

project/plugins.sbt

@@ -8,7 +8,7 @@ addSbtPlugin("com.typesafe.sbt" % "sbt-pgp" % "0.8.3")
 
 addSbtPlugin("org.scalastyle" %% "scalastyle-sbt-plugin" % "0.8.0")
 
-addSbtPlugin("org.scoverage" % "sbt-scoverage" % "1.3.5")
+addSbtPlugin("org.scoverage" % "sbt-scoverage" % "1.5.0")
 
 addSbtPlugin("com.typesafe.sbt" % "sbt-ghpages" % "0.5.4")
 

src/main/scala/chisel3/util/Decoupled.scala

@@ -10,9 +10,11 @@ import chisel3.internal.naming._  // can't use chisel3_ version because of compi
 
 /** An I/O Bundle containing 'valid' and 'ready' signals that handshake
   * the transfer of data stored in the 'bits' subfield.
-  * The base protocol implied by the directionality is that the consumer
-  * uses the flipped interface. Actual semantics of ready/valid are
-  * enforced via use of concrete subclasses.
+  * The base protocol implied by the directionality is that
+  * the producer uses the interface as-is (outputs bits)
+  * while the consumer uses the flipped interface (inputs bits).
+  * The actual semantics of ready/valid are enforced via the use of concrete subclasses.
+  * @param gen the type of data to be wrapped in Ready/Valid
   */
 abstract class ReadyValidIO[+T <: Data](gen: T) extends Bundle
 {
@@ -47,7 +49,6 @@ object ReadyValidIO {
 
     /** 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(): T = {
@@ -68,6 +69,7 @@ object ReadyValidIO {
   * put valid data in 'bits', and 'ready' indicates that the consumer is ready
   * to accept the data this cycle. No requirements are placed on the signaling
   * of ready or valid.
+  * @param gen the type of data to be wrapped in DecoupledIO
   */
 class DecoupledIO[+T <: Data](gen: T) extends ReadyValidIO[T](gen)
 {
@@ -102,6 +104,7 @@ object Decoupled
   * the value of 'bits' after a cycle where 'valid' is high and 'ready' is low.
   * Additionally, once 'valid' is raised it will never be lowered until after
   * 'ready' has also been raised.
+  * @param gen the type of data to be wrapped in IrrevocableIO
   */
 class IrrevocableIO[+T <: Data](gen: T) extends ReadyValidIO[T](gen)
 {
@@ -128,22 +131,33 @@ object Irrevocable
   }
 }
 
+/** Producer - drives (outputs) valid and bits, inputs ready.
+  * @param gen The type of data to enqueue
+  */
 object EnqIO {
   def apply[T<:Data](gen: T): DecoupledIO[T] = Decoupled(gen)
 }
+/** Consumer - drives (outputs) ready, inputs valid and bits.
+  * @param gen The type of data to dequeue
+  */
 object DeqIO {
   def apply[T<:Data](gen: T): DecoupledIO[T] = Flipped(Decoupled(gen))
 }
 
 /** An I/O Bundle for Queues
   * @param gen The type of data to queue
-  * @param entries The max number of entries in the queue */
+  * @param entries The max number of entries in the queue.
+  */
 class QueueIO[T <: Data](gen: T, entries: Int) extends Bundle
 {
-  /** I/O to enqueue data, is [[Chisel.DecoupledIO]] flipped */
-  val enq = DeqIO(gen)
-  /** I/O to enqueue data, is [[Chisel.DecoupledIO]]*/
-  val deq = EnqIO(gen)
+  /* These may look inverted, because the names (enq/deq) are from the perspective of the client,
+   *  but internally, the queue implementation itself sits on the other side
+   *  of the interface so uses the flipped instance.
+   */
+  /** I/O to enqueue data (client is producer, and Queue object is consumer), is [[Chisel.DecoupledIO]] flipped. */
+  val enq = Flipped(EnqIO(gen))
+  /** I/O to dequeue data (client is consumer and Queue object is producer), is [[Chisel.DecoupledIO]]*/
+  val deq = Flipped(DeqIO(gen))
   /** The current amount of data in the queue */
   val count = Output(UInt(log2Ceil(entries + 1).W))
 
@@ -159,7 +173,7 @@ class QueueIO[T <: Data](gen: T, entries: Int) extends Bundle
   * The ''valid'' signals are coupled.
   *
   * @example {{{
-  * val q = new Queue(UInt(), 16)
+  * val q = Module(new Queue(UInt(), 16))
   * q.io.enq <> producer.io.out
   * consumer.io.in <> q.io.deq
   * }}}

src/test/scala/chiselTests/ChiselSpec.scala

@@ -68,7 +68,7 @@ class ChiselPropSpec extends PropSpec with ChiselRunners with PropertyChecks wit
 
   // Constrain the default number of instances generated for every use of forAll.
   implicit override val generatorDrivenConfig =
-    PropertyCheckConfig(minSuccessful = 8, minSize = 1, maxSize = 4)
+    PropertyCheckConfiguration(minSuccessful = 8, minSize = 1, sizeRange = 3)
 
   // Generator for small positive integers.
   val smallPosInts = Gen.choose(1, 4)

src/test/scala/chiselTests/Direction.scala

@@ -4,6 +4,7 @@ package chiselTests
 
 import chisel3._
 import org.scalatest._
+import org.scalatest.matchers._
 import org.scalatest.prop._
 import chisel3.testers.BasicTester
 
@@ -22,7 +23,7 @@ class BadDirection extends DirectionHaver {
   io.in := 0.U
 }
 
-class DirectionSpec extends ChiselPropSpec with ShouldMatchers {
+class DirectionSpec extends ChiselPropSpec with Matchers {
 
   //TODO: In Chisel3 these are actually FIRRTL errors. Remove from tests?