Merge tag 'v3.1.3' into 3.1.x

master 4cccd87

# Conflicts:
#	build.sbt

.gitignore

@@ -1,8 +1,13 @@
 generated/
 /lib/firrtl.jar
 /bin/
+.classpath
 .idea
+.project
 target/
 *.iml
 *.swp
 test_run_dir
+*~
+\#*\#
+.\#*

README.md

@@ -1,20 +1,20 @@
-# Chisel3
+# Chisel 3
 
 [![Join the chat at https://gitter.im/freechipsproject/chisel3](https://badges.gitter.im/freechipsproject/chisel3.svg)](https://gitter.im/freechipsproject/chisel3?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
 
 Chisel is a new hardware construction language to support advanced hardware design and circuit generation.
-The latest version of [Chisel](https://chisel.eecs.berkeley.edu/) is Chisel3,
+The latest iteration of [Chisel](https://chisel.eecs.berkeley.edu/) is Chisel3,
 which uses Firrtl as an intermediate hardware representation language.
 
-Chisel3 releases are available as jars on Sonatype/Nexus/Maven and as tagged branches in the [Chisel3 repository](https://github.com/freechipsproject/chisel3/releases).
-The current Chisel3 release is 3.0.1
+Chisel3 releases are available as jars on Sonatype/Nexus/Maven and as tagged branches on the [releases tab](https://github.com/freechipsproject/chisel3/releases) of this repository.
+The latest release is 3.1.3.
 
-Please visit the [Wiki](https://github.com/ucb-bar/chisel3/wiki) for a more detailed description of Chisel3.
+Please visit the [Wiki](https://github.com/ucb-bar/chisel3/wiki) for documentation!
 
-The ScalaDoc for Chisel3 is available at the [API tab on the Chisel web site.](https://chisel.eecs.berkeley.edu/api/)
+The ScalaDoc for Chisel3 is available at the [API tab on the Chisel web site.](https://chisel.eecs.berkeley.edu/api/latest/index.html)
 
 ## Overview
-Chisel3 is much more modular than Chisel2, and the compilation pipeline looks like:
+The standard Chisel3 compilation pipeline looks like:
 - Chisel3 (Scala) to Firrtl (this is your "Chisel RTL").
 - [Firrtl](https://github.com/ucb-bar/firrtl) to Verilog (which can then be passed into FPGA or ASIC tools).
 - Verilog to C++ for simulation and testing using [Verilator](http://www.veripool.org/wiki/verilator).
@@ -23,8 +23,8 @@ Chisel3 is much more modular than Chisel2, and the compilation pipeline looks li
 This will walk you through installing Chisel and its dependencies:
 - [sbt](http://www.scala-sbt.org/), which is the preferred Scala build system and what Chisel uses.
 - [Firrtl](https://github.com/ucb-bar/firrtl), which compiles Chisel's IR down to Verilog.
-  If you're building from a release branch of chisel3, separate installation of Firrtl is no longer required: the required jar will be automatically downloaded by sbt.
-  If you're building chisel3 from the master branch, you'll need to follow the directions on the [firrtl project](https://github.com/ucb-bar/firrtl) to publish a local copy of the required jar.
+  If you're building from a release branch of Chisel3, separate installation of Firrtl is no longer required: the required jar will be automatically downloaded by sbt.
+  If you're building chisel3 from the master branch, you'll need to follow the directions on the [Firrtl repository](https://github.com/ucb-bar/firrtl) to publish a local copy of the required jar.
 - [Verilator](http://www.veripool.org/wiki/verilator), which compiles Verilog down to C++ for simulation.
   The included unit testing infrastructure uses this.
 
@@ -43,7 +43,7 @@ This will walk you through installing Chisel and its dependencies:
     sudo apt-get install sbt
     ```
 1. Install Verilator.
-    We currently recommend Verilator version 3.904.
+    We currently recommend Verilator version 3.922.
     Follow these instructions to compile it from source.
     
     1. Install prerequisites (if not installed already):
@@ -59,7 +59,7 @@ This will walk you through installing Chisel and its dependencies:
     3. In the Verilator repository directory, check out a known good version:
         ```
         git pull
-        git checkout verilator_3_904
+        git checkout verilator_3_922
         ```
 
     4. In the Verilator repository directory, build and install:
@@ -150,7 +150,7 @@ where `MyTestModule` is your top-level test circuit that extends
 ## For Chisel Developers
 This section describes how to get started developing Chisel itself, including
 how to test your version locally against other projects that pull in Chisel
-using [sbt's managed dependencies](http://www.scala-sbt.org/0.13/tutorial/Library-Dependencies.html).
+using [sbt's managed dependencies](https://www.scala-sbt.org/1.x/docs/Library-Dependencies.html).
 
 ### Compiling and Testing Chisel
 In the Chisel repository directory, run:
@@ -166,23 +166,23 @@ sbt test
 ### Running Projects Against Local Chisel
 Chisel3 is still undergoing rapid development and we haven't pusblished a
 stable version to the Nexus repository.
-You will need to build from source and `publish-local`.
+You will need to build from source and `publishLocal`.
 The repo version can be found in the build.sbt file.
 At last check it was:
 
-    version := "3.1-SNAPSHOT",
+    version := "3.2-SNAPSHOT",
 
 To publish your version of Chisel to the local Ivy (sbt's dependency manager)
 repository, run:
 ```
-sbt publish-local
+sbt publishLocal
 ```
 
 *PROTIP*: sbt can automatically run commands on a source change if you prefix
 the command with `~`. For example, the above command to publish Chisel locally
-becomes `sbt ~publish-local`.
+becomes `sbt ~publishLocal`.
 
-[sbt's manual](http://www.scala-sbt.org/0.13/docs/Publishing.html#Publishing+Locally)
+[sbt's manual](https://www.scala-sbt.org/1.x/docs/Publishing.html#Publishing+Locally)
 recommends that you use a `SNAPSHOT` version suffix to ensure that the local
 repository is checked for updates. Since the current default is a `SNAPSHOT`,
 and the version number is already incremented compared to the currently
@@ -194,7 +194,7 @@ subfolder to un-publish your local copy of Chisel.
 In order to have your projects use this version of Chisel, you should update
 the libraryDependencies setting in your project's build.sbt file to:
 ```
-libraryDependencies += "edu.berkeley.cs" %% "chisel3" % "3.1-SNAPSHOT"
+libraryDependencies += "edu.berkeley.cs" %% "chisel3" % "3.2-SNAPSHOT"
 ```
 
 The version specifier in libraryDependencies in the project's build.sbt should
@@ -206,22 +206,22 @@ match the version string in your local copy of Chisel's build.sbt.
 
 The Chisel3 compiler consists of these main parts:
 
-- **The frontend**, `chisel.*`, which is the publicly visible "API" of Chisel
+- **The frontend**, `chisel3.*`, which is the publicly visible "API" of Chisel
   and what is used in Chisel RTL. These just add data to the...
-- **The Builder**, `chisel.internal.Builder`, which maintains global state
+- **The Builder**, `chisel3.internal.Builder`, which maintains global state
   (like the currently open Module) and contains commands, generating...
-- **The intermediate data structures**, `chisel.firrtl.*`, which are
+- **The intermediate data structures**, `chisel3.firrtl.*`, which are
   syntactically very similar to Firrtl. Once the entire circuit has been
   elaborated, the top-level object (a `Circuit`) is then passed to...
-- **The Firrtl emitter**, `chisel.firrtl.Emitter`, which turns the
+- **The Firrtl emitter**, `chisel3.firrtl.Emitter`, which turns the
   intermediate data structures into a string that can be written out into a
   Firrtl file for further processing.
 
 Also included is:
-- **The standard library** of circuit generators, `chisel.util.*`. These
+- **The standard library** of circuit generators, `chisel3.util.*`. These
   contain commonly used interfaces and constructors (like `Decoupled`, which
   wraps a signal with a ready-valid pair) as well as fully parameterizable
   circuit generators (like arbiters and muxes).
-- **Driver utilities**, `chisel.Driver`, which contains compilation and test
+- **Driver utilities**, `chisel3.Driver`, which contains compilation and test
   functions that are invoked in the standard Verilog generation and simulation
   testing infrastructure. These can also be used as part of custom flows.

chiselFrontend/src/main/scala/chisel3/core/Aggregate.scala

@@ -277,7 +277,7 @@ object VecInit {
     require(!elts.isEmpty)
     elts.foreach(requireIsHardware(_, "vec element"))
 
-    val vec = Wire(new Vec(cloneSupertype(elts, "Vec"), elts.length))
+    val vec = Wire(Vec(elts.length, cloneSupertype(elts, "Vec")))
 
     // TODO: try to remove the logic for this mess
     elts.head.direction match {
@@ -473,6 +473,21 @@ abstract class Record(private[chisel3] implicit val compileOptions: CompileOptio
   def toPrintable: Printable = toPrintableHelper(elements.toList)
 }
 
+/**
+  * Mix-in for Bundles that have arbitrary Seqs of Chisel types that aren't
+  * involved in hardware construction.
+  *
+  * Used to avoid raising an error/exception when a Seq is a public member of the
+  * bundle.
+  * This is useful if we those public Seq fields in the Bundle are unrelated to
+  * hardware construction.
+  */
+trait IgnoreSeqInBundle {
+  this: Bundle =>
+
+  override def ignoreSeq: Boolean = true
+}
+
 class AutoClonetypeException(message: String) extends ChiselException(message, null)
 
 /** Base class for data types defined as a bundle of other data types.
@@ -533,18 +548,39 @@ abstract class Bundle(implicit compileOptions: CompileOptions) extends Record {
     val nameMap = LinkedHashMap[String, Data]()
     val seen = HashSet[Data]()
     for (m <- getPublicFields(classOf[Bundle])) {
-      getBundleField(m) foreach { d =>
-        if (nameMap contains m.getName) {
-          require(nameMap(m.getName) eq d)
-        } else if (!seen(d)) {
-          nameMap(m.getName) = d
-          seen += d
-        }
+      getBundleField(m) match {
+        case Some(d: Data) =>
+          if (nameMap contains m.getName) {
+            require(nameMap(m.getName) eq d)
+          } else if (!seen(d)) {
+            nameMap(m.getName) = d
+            seen += d
+          }
+        case None =>
+          if (!ignoreSeq) {
+            m.invoke(this) match {
+              case s: scala.collection.Seq[Any] if s.nonEmpty => s.head match {
+                // Ignore empty Seq()
+                case d: Data => throwException("Public Seq members cannot be used to define Bundle elements " +
+                  s"(found public Seq member '${m.getName}'). " +
+                  "Either use a Vec if all elements are of the same type, or MixedVec if the elements " +
+                  "are of different types. If this Seq member is not intended to construct RTL, mix in the trait " +
+                  "IgnoreSeqInBundle.")
+                case _ => // don't care about non-Data Seq
+              }
+              case _ => // not a Seq
+            }
+          }
       }
     }
     ListMap(nameMap.toSeq sortWith { case ((an, a), (bn, b)) => (a._id > b._id) || ((a eq b) && (an > bn)) }: _*)
   }
 
+  /**
+    * Overridden by [[IgnoreSeqInBundle]] to allow arbitrary Seqs of Chisel elements.
+    */
+  def ignoreSeq: Boolean = false
+
   /** Returns a field's contained user-defined Bundle element if it appears to
     * be one, otherwise returns None.
     */

chiselFrontend/src/main/scala/chisel3/core/Binding.scala

@@ -28,7 +28,8 @@ object requireIsHardware {
     }
     if (!node.hasBinding) {
       val prefix = if (msg.nonEmpty) s"$msg " else ""
-      throw Binding.ExpectedHardwareException(s"$prefix'$node' must be hardware, not a bare Chisel type")
+      throw Binding.ExpectedHardwareException(s"$prefix'$node' must be hardware, " +
+        "not a bare Chisel type. Perhaps you forgot to wrap it in Wire(_) or IO(_)?")
     }
   }
 }

chiselFrontend/src/main/scala/chisel3/core/Bits.scala

@@ -190,8 +190,10 @@ sealed abstract class Bits(width: Width, override val litArg: Option[LitArg])
     */
   final def pad(that: Int): this.type = macro SourceInfoTransform.thatArg
 
-  def do_pad(that: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): this.type =
-    binop(sourceInfo, cloneTypeWidth(this.width max Width(that)), PadOp, that)
+  def do_pad(that: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): this.type = this.width match {
+    case KnownWidth(w) if w >= that => this
+    case _ => binop(sourceInfo, cloneTypeWidth(this.width max Width(that)), PadOp, that)
+  }
 
   /** Returns this wire bitwise-inverted. */
   final def unary_~ (): Bits = macro SourceInfoWhiteboxTransform.noArg

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

@@ -108,7 +108,7 @@ private[core] object cloneSupertype {
                                                           compileOptions: CompileOptions): T = {
     require(!elts.isEmpty, s"can't create $createdType with no inputs")
 
-    if (elts forall {_.isInstanceOf[Bits]}) {
+    if (elts.head.isInstanceOf[Bits]) {
       val model: T = elts reduce { (elt1: T, elt2: T) => ((elt1, elt2) match {
         case (elt1: Bool, elt2: Bool) => elt1
         case (elt1: Bool, elt2: UInt) => elt2  // TODO: what happens with zero width UInts?
@@ -130,7 +130,7 @@ private[core] object cloneSupertype {
         }
         case (elt1, elt2) =>
           throw new AssertionError(
-            s"can't create $createdType with heterogeneous Bits types ${elt1.getClass} and ${elt2.getClass}")
+            s"can't create $createdType with heterogeneous types ${elt1.getClass} and ${elt2.getClass}")
       }).asInstanceOf[T] }
       model.cloneTypeFull
     }

chiselFrontend/src/main/scala/chisel3/core/Mem.scala

@@ -116,7 +116,7 @@ sealed abstract class MemBase[T <: Data](t: T, val length: Int) extends HasId wi
   * @note when multiple conflicting writes are performed on a Mem element, the
   * result is undefined (unlike Vec, where the last assignment wins)
   */
-sealed class Mem[T <: Data](t: T, length: Int) extends MemBase(t, length)
+sealed class Mem[T <: Data] private (t: T, length: Int) extends MemBase(t, length)
 
 object SyncReadMem {
   @chiselRuntimeDeprecated
@@ -151,7 +151,7 @@ object SyncReadMem {
   * @note when multiple conflicting writes are performed on a Mem element, the
   * result is undefined (unlike Vec, where the last assignment wins)
   */
-sealed class SyncReadMem[T <: Data](t: T, n: Int) extends MemBase[T](t, n) {
+sealed class SyncReadMem[T <: Data] private (t: T, n: Int) extends MemBase[T](t, n) {
   def read(x: UInt, en: Bool): T = macro SourceInfoTransform.xEnArg
 
   def do_read(addr: UInt, enable: Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {

chiselFrontend/src/main/scala/chisel3/core/Module.scala

@@ -49,7 +49,7 @@ object Module {
     val module: T = bc  // bc is actually evaluated here
 
     if (Builder.whenDepth != 0) {
-      throwException("Internal Error! When depth is != 0, this should not be possible")
+      throwException("Internal Error! when() scope depth is != 0, this should have been caught!")
     }
     if (Builder.readyForModuleConstr) {
       throwException("Error: attempted to instantiate a Module, but nothing happened. " +
@@ -75,6 +75,8 @@ object Module {
   def clock: Clock = Builder.forcedClock
   /** Returns the implicit Reset */
   def reset: Reset = Builder.forcedReset
+  /** Returns the current Module */
+  def currentModule: Option[BaseModule] = Builder.currentModule
 }
 
 /** Abstract base class for Modules, an instantiable organizational unit for RTL.

chiselFrontend/src/main/scala/chisel3/core/When.scala

@@ -71,7 +71,14 @@ final class WhenContext(sourceInfo: SourceInfo, cond: Option[() => Bool], block:
   if (firrtlDepth > 0) { pushCommand(AltBegin(sourceInfo)) }
   cond.foreach( c => pushCommand(WhenBegin(sourceInfo, c().ref)) )
   Builder.whenDepth += 1
-  block
+  try {
+    block
+  } catch {
+    case ret: scala.runtime.NonLocalReturnControl[_] =>
+      throwException("Cannot exit from a when() block with a \"return\"!" +
+        " Perhaps you meant to use Mux or a Wire as a return value?"
+      )
+  }
   Builder.whenDepth -= 1
   cond.foreach( c => pushCommand(WhenEnd(sourceInfo,firrtlDepth)) )
   if (cond.isEmpty) { pushCommand(OtherwiseEnd(sourceInfo,firrtlDepth)) }

chiselFrontend/src/main/scala/chisel3/core/package.scala

@@ -23,7 +23,7 @@ package chisel3 {
     * interpreting calls that have a non-Width parameter as a chained apply, otherwise things like
     * `0.asUInt(16)` (instead of `16.W`) compile without error and produce undesired results.
     */
-    implicit class fromBigIntToLiteral(val bigint: BigInt) {
+    implicit class fromBigIntToLiteral(bigint: BigInt) {
       /** Int to UInt conversion, recommended style for constants.
         */
       def U: UInt = UInt.Lit(bigint, Width())  // scalastyle:ignore method.name
@@ -51,10 +51,10 @@ package chisel3 {
       def asSInt(width: Width): SInt = SInt.Lit(bigint, width)
     }
 
-    implicit class fromIntToLiteral(val int: Int) extends fromBigIntToLiteral(int)
-    implicit class fromLongToLiteral(val long: Long) extends fromBigIntToLiteral(long)
+    implicit class fromIntToLiteral(int: Int) extends fromBigIntToLiteral(int)
+    implicit class fromLongToLiteral(long: Long) extends fromBigIntToLiteral(long)
 
-    implicit class fromStringToLiteral(val str: String) {
+    implicit class fromStringToLiteral(str: String) {
       /** String to UInt parse, recommended style for constants.
         */
       def U: UInt = str.asUInt() // scalastyle:ignore method.name
@@ -85,7 +85,7 @@ package chisel3 {
       }
     }
 
-    implicit class fromBooleanToLiteral(val boolean: Boolean) {
+    implicit class fromBooleanToLiteral(boolean: Boolean) {
       /** Boolean to Bool conversion, recommended style for constants.
         */
       def B: Bool = Bool.Lit(boolean)  // scalastyle:ignore method.name
@@ -96,7 +96,7 @@ package chisel3 {
     }
 
     //scalastyle:off method.name
-    implicit class fromDoubleToLiteral(val double: Double) {
+    implicit class fromDoubleToLiteral(double: Double) {
       @deprecated("Use notation <double>.F(<binary_point>.BP) instead", "chisel3")
       def F(binaryPoint: Int): FixedPoint = FixedPoint.fromDouble(double, binaryPoint = binaryPoint)
       def F(binaryPoint: BinaryPoint): FixedPoint = {
@@ -107,11 +107,11 @@ package chisel3 {
       }
     }
 
-    implicit class fromIntToWidth(val int: Int) {
+    implicit class fromIntToWidth(int: Int) {
       def W: Width = Width(int)  // scalastyle:ignore method.name
     }
 
-    implicit class fromIntToBinaryPoint(val int: Int) {
+    implicit class fromIntToBinaryPoint(int: Int) {
       def BP: BinaryPoint = BinaryPoint(int)  // scalastyle:ignore method.name
     }
   }

chiselFrontend/src/main/scala/chisel3/internal/Error.scala

@@ -53,8 +53,8 @@ private[chisel3] class ErrorLog {
 
     if (!deprecations.isEmpty) {
       println(s"$warnTag ${Console.YELLOW}There were ${deprecations.size} deprecated function(s) used." +
-          s" These may stop compiling in a future release, you are encouraged to fix these issues.${Console.RESET}")
-      println(s"$warnTag Line numbers for deprecations reported by Chisel may be inaccurate, enable scalac compiler deprecation warnings by either:")
+          s" These may stop compiling in a future release - you are encouraged to fix these issues.${Console.RESET}")
+      println(s"$warnTag Line numbers for deprecations reported by Chisel may be inaccurate; enable scalac compiler deprecation warnings via either of the following methods:")
       println(s"$warnTag   In the sbt interactive console, enter:")
       println(s"""$warnTag     set scalacOptions in ThisBuild ++= Seq("-unchecked", "-deprecation")""")
       println(s"$warnTag   or, in your build.sbt, add the line:")