Merge branch '3.0.1' into 3.0.x

Author: ucbjrl

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,30 @@
+**Note: for support questions, you are strongly advised to use [Stack Overflow](https://stackoverflow.com/questions/tagged/chisel)**.
+
+This repository's issues are reserved for feature requests and bug reports.
+
+* **Type of issue**
+  - [ ] Bug report
+  - [ ] Feature request
+  - [ ] Other enhancement
+
+* **If the current behavior is a bug, please provide the steps to reproduce the problem:**
+  * **What is the current behavior?**
+  * **What is the expected behavior?**
+  * **Please tell us about your environment:**
+    (examples)
+    - version: `3.0-SNAPSHOT`
+    - OS: `Linux knight 4.4.0-92-generic #115-Ubuntu SMP Thu Aug 10 09:04:33 UTC 2017 x86_64 x86_64 x86_64 GNU/Linux`
+
+* **What is the use case for changing the behavior?**
+
+* **Impact**
+  - [ ] no functional change
+  - [ ] API addition (no impact on existing code)
+  - [ ] API modification
+  - [ ] unknown
+
+* **Development Phase**
+  - [ ] request
+  - [ ] proposal
+
+* **Other information** (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. Stack Overflow, gitter, etc)

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,19 @@
+* **Related issue** (if applicable)
+
+* **Type of change**
+  - [ ] Bug report
+  - [ ] Feature request
+  - [ ] Other enhancement
+
+* **Impact**
+  - [ ] no functional change
+  - [ ] API addition (no impact on existing code)
+  - [ ] API modification
+
+* **Development Phase**
+  - [ ] proposal
+  - [ ] implementation
+
+* **Release Notes**
+
+Text from here to the end of the body will be considered for inclusion in the release notes for the version containing this pull request.

.gitignore

@@ -4,3 +4,5 @@ generated/
 .idea
 target/
 *.iml
+*.swp
+test_run_dir

build.sbt

@@ -32,7 +32,7 @@ def javacOptionsVersion(scalaVersion: String): Seq[String] = {
 
 lazy val commonSettings = Seq (
   organization := "edu.berkeley.cs",
-  version := "3.0.0",
+  version := "3.0.1",
   git.remoteRepo := "git@github.com:freechipsproject/chisel3.git",
   autoAPIMappings := true,
   scalaVersion := "2.11.11",
@@ -92,7 +92,7 @@ lazy val publishSettings = Seq (
   }
 )
 
-val defaultVersions = Map("firrtl" -> "1.0.0")
+val defaultVersions = Map("firrtl" -> "1.0.+")
 
 lazy val chiselSettings = Seq (
   name := "chisel3",

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

@@ -118,11 +118,13 @@ object Vec extends VecFactory
 /** A vector (array) of [[Data]] elements. Provides hardware versions of various
   * collection transformation functions found in software array implementations.
   *
-  * Careful consideration should be given over the use of [[Vec]] vs [[Seq]] or some other scala collection. In
-  * general [[Vec]] only needs to be used when there is a need to express the hardware collection in a [[Reg]]
-  * or IO [[Bundle]] or when access to elements of the array is indexed via a hardware signal.
+  * Careful consideration should be given over the use of [[Vec]] vs
+  * [[scala.collection.immutable.Seq Seq]] or some other Scala collection. In general [[Vec]] only
+  * needs to be used when there is a need to express the hardware collection in a [[Reg]] or IO
+  * [[Bundle]] or when access to elements of the array is indexed via a hardware signal.
   *
-  * Example of indexing into a [[Vec]] using a hardware address and where the [[Vec]] is defined in an IO [[Bundle]]
+  * Example of indexing into a [[Vec]] using a hardware address and where the [[Vec]] is defined in
+  * an IO [[Bundle]]
   *
   *  {{{
   *    val io = IO(new Bundle {
@@ -174,7 +176,9 @@ sealed class Vec[T <: Data] private[core] (gen: => T, val length: Int)
     * @note the length of this Vec must match the length of the input Seq
     */
   def <> (that: Seq[T])(implicit sourceInfo: SourceInfo, moduleCompileOptions: CompileOptions): Unit = {
-    require(this.length == that.length)
+    if (this.length != that.length) {
+      Builder.error("Vec and Seq being bulk connected have different lengths!")
+    }
     for ((a, b) <- this zip that)
       a <> b
   }
@@ -468,7 +472,7 @@ abstract class Record(private[chisel3] implicit val compileOptions: CompileOptio
   }
   /** Default "pretty-print" implementation
     * Analogous to printing a Map
-    * Results in "$className(elt0.name -> elt0.value, ...)"
+    * Results in "`\$className(elt0.name -> elt0.value, ...)`"
     */
   def toPrintable: Printable = toPrintableHelper(elements.toList)
 }
@@ -581,7 +585,7 @@ class Bundle(implicit compileOptions: CompileOptions) extends Record {
 
   /** Default "pretty-print" implementation
     * Analogous to printing a Map
-    * Results in "Bundle(elt0.name -> elt0.value, ...)"
+    * Results in "`Bundle(elt0.name -> elt0.value, ...)`"
     * @note The order is reversed from the order of elements in order to print
     *   the fields in the order they were defined
     */

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

@@ -308,6 +308,12 @@ sealed abstract class Bits(width: Width, override val litArg: Option[LitArg])
 
   /** Default print as [[Decimal]] */
   final def toPrintable: Printable = Decimal(this)
+
+  protected final def validateShiftAmount(x: Int): Int = {
+    if (x < 0)
+      Builder.error(s"Negative shift amounts are illegal (got $x)")
+    x
+  }
 }
 
 // REVIEW TODO: Further discussion needed on what Num actually is.
@@ -494,13 +500,13 @@ sealed class UInt private[core] (width: Width, lit: Option[ULit] = None)
   def do_unary_! (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions) : Bool = this === 0.U(1.W)
 
   override def do_<< (that: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
-    binop(sourceInfo, UInt(this.width + that), ShiftLeftOp, that)
+    binop(sourceInfo, UInt(this.width + that), ShiftLeftOp, validateShiftAmount(that))
   override def do_<< (that: BigInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     this << that.toInt
   override def do_<< (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     binop(sourceInfo, UInt(this.width.dynamicShiftLeft(that.width)), DynamicShiftLeftOp, that)
   override def do_>> (that: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
-    binop(sourceInfo, UInt(this.width.shiftRight(that)), ShiftRightOp, that)
+    binop(sourceInfo, UInt(this.width.shiftRight(that)), ShiftRightOp, validateShiftAmount(that))
   override def do_>> (that: BigInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
     this >> that.toInt
   override def do_>> (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): UInt =
@@ -662,13 +668,13 @@ sealed class SInt private[core] (width: Width, lit: Option[SLit] = None)
   }
 
   override def do_<< (that: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
-    binop(sourceInfo, SInt(this.width + that), ShiftLeftOp, that)
+    binop(sourceInfo, SInt(this.width + that), ShiftLeftOp, validateShiftAmount(that))
   override def do_<< (that: BigInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     this << that.toInt
   override def do_<< (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     binop(sourceInfo, SInt(this.width.dynamicShiftLeft(that.width)), DynamicShiftLeftOp, that)
   override def do_>> (that: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
-    binop(sourceInfo, SInt(this.width.shiftRight(that)), ShiftRightOp, that)
+    binop(sourceInfo, SInt(this.width.shiftRight(that)), ShiftRightOp, validateShiftAmount(that))
   override def do_>> (that: BigInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
     this >> that.toInt
   override def do_>> (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): SInt =
@@ -924,13 +930,13 @@ sealed class FixedPoint private (width: Width, val binaryPoint: BinaryPoint, lit
   }
 
   override def do_<< (that: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint =
-    binop(sourceInfo, FixedPoint(this.width + that, this.binaryPoint), ShiftLeftOp, that)
+    binop(sourceInfo, FixedPoint(this.width + that, this.binaryPoint), ShiftLeftOp, validateShiftAmount(that))
   override def do_<< (that: BigInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint =
     (this << that.toInt).asFixedPoint(this.binaryPoint)
   override def do_<< (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint =
     binop(sourceInfo, FixedPoint(this.width.dynamicShiftLeft(that.width), this.binaryPoint), DynamicShiftLeftOp, that)
   override def do_>> (that: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint =
-    binop(sourceInfo, FixedPoint(this.width.shiftRight(that), this.binaryPoint), ShiftRightOp, that)
+    binop(sourceInfo, FixedPoint(this.width.shiftRight(that), this.binaryPoint), ShiftRightOp, validateShiftAmount(that))
   override def do_>> (that: BigInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint =
     (this >> that.toInt).asFixedPoint(this.binaryPoint)
   override def do_>> (that: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): FixedPoint =

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

@@ -80,7 +80,7 @@ abstract class ExtModule(val params: Map[String, Param] = Map.empty[String, Para
     component
   }
 
-  private[core] def initializeInParent() {
+  private[core] def initializeInParent(parentCompileOptions: CompileOptions): Unit = {
     implicit val sourceInfo = UnlocatableSourceInfo
 
     for (x <- getModulePorts) {
@@ -165,7 +165,7 @@ abstract class BlackBox(val params: Map[String, Param] = Map.empty[String, Param
     component
   }
 
-  private[core] def initializeInParent() {
+  private[core] def initializeInParent(parentCompileOptions: CompileOptions): Unit = {
     for ((_, port) <- io.elements) {
       pushCommand(DefInvalid(UnlocatableSourceInfo, port.ref))
     }

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

@@ -45,9 +45,9 @@ case class ChiselAnnotation(component: InstanceId, transformClass: Class[_ <: Tr
   * }
   * }}}
   *
-  * @note Calling this on Data creates an annotation that Chisel emits to a separate annotations
-  * file. This file must be passed to Firrtl independently of the .fir file.
-  * [[chisel3.Driver.execute]] will do this automatically.
+  * @note Calling this on [[Data]] creates an annotation that Chisel emits to a separate annotations
+  * file. This file must be passed to FIRRTL independently of the `.fir` file. The execute methods
+  * in [[chisel3.Driver]] will pass the annotations to FIRRTL automatically.
   */
 object dontTouch { // scalastyle:ignore object.name
   /** Marks a signal to be preserved in Chisel and Firrtl

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

@@ -451,13 +451,20 @@ object WireInit {
     apply(model, init)
   }
 
-  def apply[T <: Data](t: T, init: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
+  private def applyImpl[T <: Data](t: T, init: Data)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
     implicit val noSourceInfo = UnlocatableSourceInfo
     val x = Wire(t)
     requireIsHardware(init, "wire initializer")
     x := init
     x
   }
+
+  def apply[T <: Data](t: T, init: T)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
+    applyImpl(t, init)
+  }
+  def apply[T <: Data](t: T, init: DontCare.type)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
+    applyImpl(t, init)
+  }
 }
 
 /** RHS (source) for Invalidate API.

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

@@ -46,12 +46,18 @@ sealed abstract class MemBase[T <: Data](t: T, val length: Int) extends HasId {
   /** Creates a read/write accessor into the memory with dynamic addressing.
     * See the class documentation of the memory for more detailed information.
     */
-  def apply(idx: UInt)(implicit compileOptions: CompileOptions): T = makePort(UnlocatableSourceInfo, idx, MemPortDirection.INFER)
+  def apply(x: UInt): T = macro SourceInfoTransform.xArg
+
+  def do_apply(idx: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T =
+    makePort(sourceInfo, idx, MemPortDirection.INFER)
 
   /** Creates a read accessor into the memory with dynamic addressing. See the
     * class documentation of the memory for more detailed information.
     */
-  def read(idx: UInt)(implicit compileOptions: CompileOptions): T = makePort(UnlocatableSourceInfo, idx, MemPortDirection.READ)
+  def read(x: UInt): T = macro SourceInfoTransform.xArg
+
+  def do_read(idx: UInt)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T =
+    makePort(sourceInfo, idx, MemPortDirection.READ)
 
   /** Creates a write accessor into the memory.
     *
@@ -144,7 +150,9 @@ object SyncReadMem {
   * result is undefined (unlike Vec, where the last assignment wins)
   */
 sealed class SyncReadMem[T <: Data](t: T, n: Int) extends MemBase[T](t, n) {
-  def read(addr: UInt, enable: Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
+  def read(x: UInt, en: Bool): T = macro SourceInfoTransform.xEnArg
+
+  def do_read(addr: UInt, enable: Bool)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): T = {
     val a = Wire(UInt())
     var port: Option[T] = None
     when (enable) {

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

@@ -23,7 +23,9 @@ object Module {
     */
   def apply[T <: BaseModule](bc: => T): T = macro InstTransform.apply[T]
 
-  def do_apply[T <: BaseModule](bc: => T)(implicit sourceInfo: SourceInfo): T = {
+  def do_apply[T <: BaseModule](bc: => T)
+                               (implicit sourceInfo: SourceInfo,
+                                         compileOptions: CompileOptions): T = {
     if (Builder.readyForModuleConstr) {
       throwException("Error: Called Module() twice without instantiating a Module." +
                      sourceInfo.makeMessage(" See " + _))
@@ -62,7 +64,7 @@ object Module {
     // Handle connections at enclosing scope
     if(!Builder.currentModule.isEmpty) {
       pushCommand(DefInstance(sourceInfo, module, component.ports))
-      module.initializeInParent()
+      module.initializeInParent(compileOptions)
     }
     module
   }
@@ -124,7 +126,7 @@ abstract class BaseModule extends HasId {
 
   /** Sets up this module in the parent context
     */
-  private[core] def initializeInParent()
+  private[core] def initializeInParent(parentCompileOptions: CompileOptions): Unit
 
   //
   // Chisel Internals

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

@@ -14,12 +14,39 @@ import java.util.{
 
 /** Superclass of things that can be printed in the resulting circuit
   *
-  * Usually created using the custom string interpolator p"..."
-  * TODO Add support for names of Modules
-  *   Currently impossible because unpack is called before the name is selected
-  *   Could be implemented by adding a new format specifier to Firrtl (eg. %m)
-  * TODO Should we provide more functions like map and mkPrintable?
+  * Usually created using the custom string interpolator `p"..."`. Printable string interpolation is
+  * similar to [[https://docs.scala-lang.org/overviews/core/string-interpolation.html String
+  * interpolation in Scala]] For example:
+  * {{{
+  *   printf(p"The value of wire = \$wire\n")
+  * }}}
+  * This is equivalent to writing:
+  * {{{
+  *   printf(p"The value of wire = %d\n", wire)
+  * }}}
+  * All Chisel data types have a method `.toPrintable` that gives a default pretty print that can be
+  * accessed via `p"..."`. This works even for aggregate types, for example:
+  * {{{
+  *   val myVec = VecInit(5.U, 10.U, 13.U)
+  *   printf(p"myVec = \$myVec\n")
+  *   // myVec = Vec(5, 10, 13)
+  *
+  *   val myBundle = Wire(new Bundle {
+  *     val foo = UInt()
+  *     val bar = UInt()
+  *   })
+  *   myBundle.foo := 3.U
+  *   myBundle.bar := 11.U
+  *   printf(p"myBundle = \$myBundle\n")
+  *   // myBundle = Bundle(a -> 3, b -> 11)
+  * }}}
+  * Users can override the default behavior of `.toPrintable` in custom [[Bundle]] and [[Record]]
+  * types.
   */
+// TODO Add support for names of Modules
+//   Currently impossible because unpack is called before the name is selected
+//   Could be implemented by adding a new format specifier to Firrtl (eg. %m)
+// TODO Should we provide more functions like map and mkPrintable?
 sealed abstract class Printable {
   /** Unpack into format String and a List of String arguments (identifiers)
     * @note This must be called after elaboration when Chisel nodes actually