Merge branch 'master' into exceptionfix

7 files changed, 103 insertions, 20 deletions

diff --git a/src/main/scala/chisel3/Driver.scala b/src/main/scala/chisel3/Driver.scala
index ab51ad25..40c94b54 100644
--- a/src/main/scala/chisel3/Driver.scala
+++ b/src/main/scala/chisel3/Driver.scala
@@ -6,10 +6,13 @@ import chisel3.internal.firrtl.Emitter
 
 import scala.sys.process._
 import java.io._
+import net.jcazevedo.moultingyaml._
 
 import internal.firrtl._
 import firrtl._
 
+import _root_.firrtl.annotations.AnnotationYamlProtocol._
+
 /**
   * The Driver provides methods to invoke the chisel3 compiler and the firrtl compiler.
   * By default firrtl is automatically run after chisel.  an [[ExecutionOptionsManager]]
@@ -239,6 +242,23 @@ object Driver extends BackendCompilationUtilities {
     w.write(firrtlString)
     w.close()
 
+    val annotationFile = new File(optionsManager.getBuildFileName("anno"))
+    val af = new FileWriter(annotationFile)
+    af.write(circuit.annotations.toArray.toYaml.prettyPrint)
+    af.close()
+
+    /* create custom transforms by finding the set of transform classes associated with annotations
+     * then instantiate them into actual transforms
+     */
+    val transforms = circuit.annotations.map(_.transform).toSet.map { transformClass: Class[_ <: Transform] =>
+      transformClass.newInstance()
+    }
+    /* This passes the firrtl source and annotations directly to firrtl */
+    optionsManager.firrtlOptions = optionsManager.firrtlOptions.copy(
+      firrtlSource = Some(firrtlString),
+      annotations = circuit.annotations.toList,
+      customTransforms = transforms.toList)
+
     val firrtlExecutionResult = if(chiselOptions.runFirrtlCompiler) {
       Some(firrtl.Driver.execute(optionsManager))
     }
diff --git a/src/main/scala/chisel3/package.scala b/src/main/scala/chisel3/package.scala
index e4e64b89..25d3ec3a 100644
--- a/src/main/scala/chisel3/package.scala
+++ b/src/main/scala/chisel3/package.scala
@@ -32,6 +32,9 @@ package object chisel3 {    // scalastyle:ignore package.object.name
   type Element = chisel3.core.Element
   type Bits = chisel3.core.Bits
 
+  type ChiselAnnotation = chisel3.core.ChiselAnnotation
+  val ChiselAnnotation = chisel3.core.ChiselAnnotation
+
   // Some possible regex replacements for the literal specifier deprecation:
   // (note: these are not guaranteed to handle all edge cases! check all replacements!)
   // Bool\((true|false)\)
diff --git a/src/main/scala/chisel3/util/BitPat.scala b/src/main/scala/chisel3/util/BitPat.scala
index 9c9909cd..add40f79 100644
--- a/src/main/scala/chisel3/util/BitPat.scala
+++ b/src/main/scala/chisel3/util/BitPat.scala
@@ -35,7 +35,7 @@ object BitPat {
   }
 
   /** Creates a [[BitPat]] literal from a string.
-   *
+    *
     * @param n the literal value as a string, in binary, prefixed with 'b'
     * @note legal characters are '0', '1', and '?', as well as '_' and white
     * space (which are ignored)
@@ -45,7 +45,12 @@ object BitPat {
     new BitPat(bits, mask, width)
   }
 
-  /** Creates a [[BitPat]] of all don't cares of the specified bitwidth. */
+  /** Creates a [[BitPat]] of all don't cares of the specified bitwidth.
+    *
+    * @example {{{
+    * val myDontCare = BitPat.dontCare(4)  // equivalent to BitPat("b????")
+    * }}}
+    */
   def dontCare(width: Int): BitPat = BitPat("b" + ("?" * width))
 
   @deprecated("Use BitPat.dontCare", "chisel3")
@@ -73,10 +78,14 @@ object BitPat {
   }
 }
 
-// TODO: Break out of Core? (this doesn't involve FIRRTL generation)
 /** Bit patterns are literals with masks, used to represent values with don't
-  * cares. Equality comparisons will ignore don't care bits (for example,
-  * BitPat(0b10?1) === 0b1001.asUInt and 0b1011.asUInt.
+  * care bits. Equality comparisons will ignore don't care bits.
+  *
+  * @example {{{
+  * "b10101".U === BitPat("b101??") // evaluates to true.B
+  * "b10111".U === BitPat("b101??") // evaluates to true.B
+  * "b10001".U === BitPat("b101??") // evaluates to false.B
+  * }}}
   */
 sealed class BitPat(val value: BigInt, val mask: BigInt, width: Int) {
   def getWidth: Int = width
diff --git a/src/main/scala/chisel3/util/Bitwise.scala b/src/main/scala/chisel3/util/Bitwise.scala
index 22326972..950fa65f 100644
--- a/src/main/scala/chisel3/util/Bitwise.scala
+++ b/src/main/scala/chisel3/util/Bitwise.scala
@@ -8,11 +8,21 @@ package chisel3.util
 import chisel3._
 import chisel3.core.SeqUtils
 
+/** Creates repetitions of each bit of the input in order.
+  *
+  * @example {{{
+  * FillInterleaved(2, "b1 0 0 0".U)  // equivalent to "b11 00 00 00".U
+  * FillInterleaved(2, "b1 0 0 1".U)  // equivalent to "b11 00 00 11".U
+  * FillInterleaved(2, myUIntWire)  // dynamic interleaved fill
+  *
+  * FillInterleaved(2, Seq(true.B, false.B, false.B, false.B))  // equivalent to "b11 00 00 00".U
+  * FillInterleaved(2, Seq(true.B, false.B, false.B, true.B))  // equivalent to "b11 00 00 11".U
+  * }}}
+  */
 object FillInterleaved {
   /** Creates n repetitions of each bit of x in order.
     *
     * Output data-equivalent to in(size(in)-1) (n times) ## ... ## in(1) (n times) ## in(0) (n times)
-    * For example, FillInterleaved(2, "b1000") === UInt("b11 00 00 00")
     */
   def apply(n: Int, in: UInt): UInt = apply(n, in.toBools)
 
@@ -23,14 +33,31 @@ object FillInterleaved {
   def apply(n: Int, in: Seq[Bool]): UInt = Cat(in.map(Fill(n, _)).reverse)
 }
 
-/** Returns the number of bits set (i.e value is 1) in the input signal.
+/** Returns the number of bits set (value is 1 or true) in the input signal.
+  *
+  * @example {{{
+  * PopCount(Seq(true.B, false.B, true.B, true.B))  // evaluates to 3.U
+  * PopCount(Seq(false.B, false.B, true.B, false.B))  // evaluates to 1.U
+  *
+  * PopCount("b1011".U)  // evaluates to 3.U
+  * PopCount("b0010".U)  // evaluates to 1.U
+  * PopCount(myUIntWire)  // dynamic count
+  * }}}
   */
-object PopCount
-{
+object PopCount {
   def apply(in: Iterable[Bool]): UInt = SeqUtils.count(in.toSeq)
+
   def apply(in: Bits): UInt = apply((0 until in.getWidth).map(in(_)))
 }
 
+/** Create repetitions of the input using a tree fanout topology.
+  *
+  * @example {{{
+  * Fill(2, "b1000".U)  // equivalent to "b1000 1000".U
+  * Fill(2, "b1001".U)  // equivalent to "b1001 1001".U
+  * Fill(2, myUIntWire)  // dynamic fill
+  * }}}
+  */
 object Fill {
   /** Create n repetitions of x using a tree fanout topology.
     *
@@ -53,6 +80,14 @@ object Fill {
   }
 }
 
+/** Returns the input in bit-reversed order. Useful for little/big-endian conversion.
+  *
+  * @example {{{
+  * Reverse("b1101".U)  // equivalent to "b1011".U
+  * Reverse("b1101".U(8.W))  // equivalent to "b10110000".U
+  * Reverse(myUIntWire)  // dynamic reverse
+  * }}}
+  */
 object Reverse {
   private def doit(in: UInt, length: Int): UInt = {
     if (length == 1) {
@@ -73,7 +108,6 @@ object Reverse {
       Cat(doit(in(half-1,0), half), doit(in(length-1,half), length-half))
     }
   }
-  /** Returns the input in bit-reversed order. Useful for little/big-endian conversion.
-    */
+
   def apply(in: UInt): UInt = doit(in, in.getWidth)
 }
diff --git a/src/main/scala/chisel3/util/Cat.scala b/src/main/scala/chisel3/util/Cat.scala
index ba12a7d4..78801541 100644
--- a/src/main/scala/chisel3/util/Cat.scala
+++ b/src/main/scala/chisel3/util/Cat.scala
@@ -5,8 +5,19 @@ package chisel3.util
 import chisel3._
 import chisel3.core.SeqUtils
 
+/** Concatenates elements of the input, in order, together.
+  *
+  * @example {{{
+  * Cat("b101".U, "b11".U)  // equivalent to "b101 11".U
+  * Cat(myUIntWire0, myUIntWire1)
+  *
+  * Cat(Seq("b101".U, "b11".U))  // equivalent to "b101 11".U
+  * Cat(mySeqOfBits)
+  * }}}
+  */
 object Cat {
-  /** Concatenates the argument data elements, in argument order, together.
+  /** Concatenates the argument data elements, in argument order, together. The first argument
+    * forms the most significant bits, while the last argument forms the least significant bits.
     */
   def apply[T <: Bits](a: T, r: T*): UInt = apply(a :: r.toList)
 
diff --git a/src/main/scala/chisel3/util/CircuitMath.scala b/src/main/scala/chisel3/util/CircuitMath.scala
index a422b5fe..b5f491ef 100644
--- a/src/main/scala/chisel3/util/CircuitMath.scala
+++ b/src/main/scala/chisel3/util/CircuitMath.scala
@@ -7,10 +7,19 @@ package chisel3.util
 
 import chisel3._
 
+/** Returns the base-2 integer logarithm of an UInt.
+  *
+  * @note The result is truncated, so e.g. Log2(13.U) === 3.U
+  *
+  * @example {{{
+  * Log2(8.U)  // evaluates to 3.U
+  * Log2(13.U)  // evaluates to 3.U (truncation)
+  * Log2(myUIntWire)
+  * }}}
+  *
+  */
 object Log2 {
   /** Returns the base-2 integer logarithm of the least-significant `width` bits of an UInt.
-    *
-    * @note The result is truncated, so e.g. Log2(13.U) === 3.U
     */
   def apply(x: Bits, width: Int): UInt = {
     if (width < 2) {
@@ -28,10 +37,6 @@ object Log2 {
     }
   }
 
-  /** Returns the base-2 integer logarithm of an UInt.
-    *
-    * @note The result is truncated, so e.g. Log2(13.U) === 3.U
-    */
   def apply(x: Bits): UInt = apply(x, x.getWidth)
 
   private def divideAndConquerThreshold = 4
diff --git a/src/main/scala/chisel3/util/Decoupled.scala b/src/main/scala/chisel3/util/Decoupled.scala
index fcda6943..4a97724a 100644
--- a/src/main/scala/chisel3/util/Decoupled.scala
+++ b/src/main/scala/chisel3/util/Decoupled.scala
@@ -37,12 +37,13 @@ object ReadyValidIO {
       dat
     }
 
-    /** Indicate no enqueue occurs.  Valid is set to false, and all bits are set to zero.
+    /** Indicate no enqueue occurs. Valid is set to false, and bits are
+      * connected to an uninitialized wire
       */
     def noenq(): Unit = {
       target.valid := false.B
       // We want the type from the following, not any existing binding.
-      target.bits := target.bits.cloneType.fromBits(0.asUInt)
+      target.bits := Wire(target.bits.cloneType)
     }
 
     /** Assert ready on this port and return the associated data bits.