Merge branch 'master' into 3.5-release

17 files changed, 1011 insertions, 71 deletions

diff --git a/src/main/scala/chisel3/util/BitPat.scala b/src/main/scala/chisel3/util/BitPat.scala
index 40563e23..0dcb2466 100644
--- a/src/main/scala/chisel3/util/BitPat.scala
+++ b/src/main/scala/chisel3/util/BitPat.scala
@@ -23,6 +23,7 @@ object BitPat {
     // If ? parsing is to be exposed, the return API needs further scrutiny
     // (especially with things like mask polarity).
     require(x.head == 'b', "BitPats must be in binary and be prefixed with 'b'")
+    require(x.length > 1, "BitPat width cannot be 0.")
     var bits = BigInt(0)
     var mask = BigInt(0)
     var count = 0
@@ -57,6 +58,22 @@ object BitPat {
     */
   def dontCare(width: Int): BitPat = BitPat("b" + ("?" * width))
 
+  /** Creates a [[BitPat]] of all 1 of the specified bitwidth.
+    *
+    * @example {{{
+    * val myY = BitPat.Y(4)  // equivalent to BitPat("b1111")
+    * }}}
+    */
+  def Y(width: Int = 1): BitPat = BitPat("b" + ("1" * width))
+
+  /** Creates a [[BitPat]] of all 0 of the specified bitwidth.
+    *
+    * @example {{{
+    * val myN = BitPat.N(4)  // equivalent to BitPat("b0000")
+    * }}}
+    */
+  def N(width: Int = 1): BitPat = BitPat("b" + ("0" * width))
+
   /** Allows BitPats to be used where a UInt is expected.
     *
     * @note the BitPat must not have don't care bits (will error out otherwise)
@@ -91,12 +108,6 @@ object BitPat {
     /** @group SourceInfoTransformMacro */
     def do_=/= (that: BitPat)
                (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = that =/= x
-
-    final def != (that: BitPat): Bool = macro SourceInfoTransform.thatArg
-    @chiselRuntimeDeprecated
-    @deprecated("Use '=/=', which avoids potential precedence problems", "3.0")
-    def do_!= (that: BitPat)
-              (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = that != x
   }
 }
 
@@ -111,8 +122,29 @@ object BitPat {
   */
 sealed class BitPat(val value: BigInt, val mask: BigInt, width: Int) extends SourceInfoDoc {
   def getWidth: Int = width
+  def apply(x: Int): BitPat = macro SourceInfoTransform.xArg
+  def apply(x: Int, y: Int): BitPat = macro SourceInfoTransform.xyArg
   def === (that: UInt): Bool = macro SourceInfoTransform.thatArg
   def =/= (that: UInt): Bool = macro SourceInfoTransform.thatArg
+  def ## (that: BitPat): BitPat = macro SourceInfoTransform.thatArg
+  override def equals(obj: Any): Boolean = {
+    obj match {
+      case y: BitPat => value == y.value && mask == y.mask && getWidth == y.getWidth
+      case _ => false
+    }
+  }
+
+  /** @group SourceInfoTransformMacro */
+  def do_apply(x: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): BitPat = {
+    do_apply(x, x)
+  }
+
+  /** @group SourceInfoTransformMacro */
+  def do_apply(x: Int, y: Int)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): BitPat = {
+    require(width > x && y >= 0, s"Invalid bit range ($x, $y), index should be bounded by (${width - 1}, 0)")
+    require(x >= y, s"Invalid bit range ($x, $y), x should be greater or equal to y.")
+    BitPat(s"b${rawString.slice(width - x - 1, width - y)}")
+  }
 
   /** @group SourceInfoTransformMacro */
   def do_=== (that: UInt)
@@ -124,12 +156,19 @@ sealed class BitPat(val value: BigInt, val mask: BigInt, width: Int) extends Sou
       (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = {
     !(this === that)
   }
-
-  def != (that: UInt): Bool = macro SourceInfoTransform.thatArg
-  @chiselRuntimeDeprecated
-  @deprecated("Use '=/=', which avoids potential precedence problems", "3.0")
-  def do_!= (that: UInt)
-      (implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): Bool = {
-    this =/= that
+  /** @group SourceInfoTransformMacro */
+  def do_##(that: BitPat)(implicit sourceInfo: SourceInfo, compileOptions: CompileOptions): BitPat = {
+    new BitPat((value << that.getWidth) + that.value, (mask << that.getWidth) + that.mask, this.width + that.getWidth)
   }
+
+  /** Generate raw string of a BitPat. */
+  def rawString: String = Seq.tabulate(width) { i =>
+      (value.testBit(width - i - 1), mask.testBit(width - i - 1)) match {
+      case (true, true) => "1"
+      case (false, true) => "0"
+      case (_, false) => "?"
+    }
+  }.mkString
+
+  override def toString = s"BitPat($rawString)"
 }
diff --git a/src/main/scala/chisel3/util/BlackBoxUtils.scala b/src/main/scala/chisel3/util/BlackBoxUtils.scala
index 21bd4dfa..443d7f3e 100644
--- a/src/main/scala/chisel3/util/BlackBoxUtils.scala
+++ b/src/main/scala/chisel3/util/BlackBoxUtils.scala
@@ -4,15 +4,39 @@ package chisel3.util
 
 import chisel3._
 import chisel3.experimental.{ChiselAnnotation, RunFirrtlTransform}
-import firrtl.transforms.{BlackBoxPathAnno, BlackBoxResourceAnno, BlackBoxInlineAnno, BlackBoxSourceHelper}
+import firrtl.transforms.{BlackBoxPathAnno, BlackBoxResourceAnno, BlackBoxInlineAnno, BlackBoxSourceHelper,
+  BlackBoxNotFoundException}
+import firrtl.annotations.ModuleName
+import logger.LazyLogging
+
+private[util] object BlackBoxHelpers {
+
+  implicit class BlackBoxInlineAnnoHelpers(anno: BlackBoxInlineAnno.type) extends LazyLogging {
+    /** Generate a BlackBoxInlineAnno from a Java Resource and a module name. */
+    def fromResource(resourceName: String, moduleName: ModuleName) = try {
+      val blackBoxFile = os.resource / os.RelPath(resourceName.dropWhile(_ == '/'))
+      val contents = os.read(blackBoxFile)
+      if (contents.size > BigInt(2).pow(20)) {
+        val message =
+          s"Black box resource $resourceName, which will be converted to an inline annotation, is greater than 1 MiB." +
+            "This may affect compiler performance. Consider including this resource via a black box path."
+        logger.warn(message)
+      }
+      BlackBoxInlineAnno(moduleName, blackBoxFile.last, contents)
+    } catch {
+      case e: os.ResourceNotFoundException =>
+        throw new BlackBoxNotFoundException(resourceName, e.getMessage)
+    }
+  }
+}
+
+import BlackBoxHelpers._
 
 trait HasBlackBoxResource extends BlackBox {
   self: BlackBox =>
 
-  @deprecated("Use addResource instead", "3.2")
-  def setResource(blackBoxResource: String): Unit = addResource(blackBoxResource)
-
-  /** Copies a resource file to the target directory
+  /** Copies a Java resource containing some text into the output directory. This is typically used to copy a Verilog file
+    * to the final output directory, but may be used to copy any Java resource (e.g., a C++ testbench).
     *
     * Resource files are located in project_root/src/main/resources/.
     * Example of adding the resource file project_root/src/main/resources/blackbox.v:
@@ -22,7 +46,7 @@ trait HasBlackBoxResource extends BlackBox {
     */
   def addResource(blackBoxResource: String): Unit = {
     val anno = new ChiselAnnotation with RunFirrtlTransform {
-      def toFirrtl = BlackBoxResourceAnno(self.toNamed, blackBoxResource)
+      def toFirrtl = BlackBoxInlineAnno.fromResource(blackBoxResource, self.toNamed)
       def transformClass = classOf[BlackBoxSourceHelper]
     }
     chisel3.experimental.annotate(anno)
diff --git a/src/main/scala/chisel3/util/Conditional.scala b/src/main/scala/chisel3/util/Conditional.scala
index b934f27f..1ac94bfe 100644
--- a/src/main/scala/chisel3/util/Conditional.scala
+++ b/src/main/scala/chisel3/util/Conditional.scala
@@ -12,15 +12,6 @@ import scala.reflect.macros.blackbox._
 import chisel3._
 import chisel3.internal.sourceinfo.SourceInfo
 
-@deprecated("The unless conditional is deprecated, use when(!condition){...} instead", "3.2")
-object unless {
-  /** Does the same thing as [[when$ when]], but with the condition inverted.
-    */
-  def apply(c: Bool)(block: => Any) {
-    when (!c) { block }
-  }
-}
-
 /** Implementation details for [[switch]]. See [[switch]] and [[chisel3.util.is is]] for the
   * user-facing API.
   * @note DO NOT USE. This API is subject to change without warning.
diff --git a/src/main/scala/chisel3/util/Decoupled.scala b/src/main/scala/chisel3/util/Decoupled.scala
index 032d731d..8909ffe3 100644
--- a/src/main/scala/chisel3/util/Decoupled.scala
+++ b/src/main/scala/chisel3/util/Decoupled.scala
@@ -108,7 +108,7 @@ object Decoupled
   @chiselName
   def apply[T <: Data](irr: IrrevocableIO[T]): DecoupledIO[T] = {
     require(DataMirror.directionOf(irr.bits) == Direction.Output, "Only safe to cast produced Irrevocable bits to Decoupled.")
-    val d = Wire(new DecoupledIO(irr.bits))
+    val d = Wire(new DecoupledIO(chiselTypeOf(irr.bits)))
     d.bits := irr.bits
     d.valid := irr.valid
     irr.ready := d.ready
@@ -139,7 +139,7 @@ object Irrevocable
     */
   def apply[T <: Data](dec: DecoupledIO[T]): IrrevocableIO[T] = {
     require(DataMirror.directionOf(dec.bits) == Direction.Input, "Only safe to cast consumed Decoupled bits to Irrevocable.")
-    val i = Wire(new IrrevocableIO(dec.bits))
+    val i = Wire(new IrrevocableIO(chiselTypeOf(dec.bits)))
     dec.bits := i.bits
     dec.valid := i.valid
     i.ready := dec.ready
@@ -163,8 +163,9 @@ object DeqIO {
 /** 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 hasFlush A boolean for whether the generated Queue is flushable
   */
-class QueueIO[T <: Data](private val gen: T, val entries: Int) extends Bundle
+class QueueIO[T <: Data](private val gen: T, val entries: Int, val hasFlush: Boolean = false) extends Bundle
 { // See github.com/freechipsproject/chisel3/issues/765 for why gen is a private val and proposed replacement APIs.
 
   /* These may look inverted, because the names (enq/deq) are from the perspective of the client,
@@ -177,6 +178,9 @@ class QueueIO[T <: Data](private val gen: T, val entries: Int) extends Bundle
   val deq = Flipped(DeqIO(gen))
   /** The current amount of data in the queue */
   val count = Output(UInt(log2Ceil(entries + 1).W))
+  /** When asserted, reset the enqueue and dequeue pointers, effectively flushing the queue (Optional IO for a flushable Queue)*/ 
+  val flush = if (hasFlush) Some(Input(Bool())) else None
+
 }
 
 /** A hardware module implementing a Queue
@@ -186,7 +190,8 @@ class QueueIO[T <: Data](private val gen: T, val entries: Int) extends Bundle
   * combinationally coupled.
   * @param flow True if the inputs can be consumed on the same cycle (the inputs "flow" through the queue immediately).
   * The ''valid'' signals are coupled.
-  *
+  * @param useSyncReadMem True uses SyncReadMem instead of Mem as an internal memory element.
+  * @param hasFlush True if generated queue requires a flush feature
   * @example {{{
   * val q = Module(new Queue(UInt(), 16))
   * q.io.enq <> producer.io.out
@@ -197,7 +202,9 @@ class QueueIO[T <: Data](private val gen: T, val entries: Int) extends Bundle
 class Queue[T <: Data](val gen: T,
                        val entries: Int,
                        val pipe: Boolean = false,
-                       val flow: Boolean = false)
+                       val flow: Boolean = false,
+                       val useSyncReadMem: Boolean = false, 
+                       val hasFlush: Boolean = false)
                       (implicit compileOptions: chisel3.CompileOptions)
     extends Module() {
   require(entries > -1, "Queue must have non-negative number of entries")
@@ -213,19 +220,20 @@ class Queue[T <: Data](val gen: T,
     }
   }
 
-  val io = IO(new QueueIO(genType, entries))
-
-  val ram = Mem(entries, genType)
+  val io = IO(new QueueIO(genType, entries, hasFlush))
+  val ram = if (useSyncReadMem) SyncReadMem(entries, genType, SyncReadMem.WriteFirst) else Mem(entries, genType)
   val enq_ptr = Counter(entries)
   val deq_ptr = Counter(entries)
   val maybe_full = RegInit(false.B)
-
   val ptr_match = enq_ptr.value === deq_ptr.value
   val empty = ptr_match && !maybe_full
   val full = ptr_match && maybe_full
   val do_enq = WireDefault(io.enq.fire())
   val do_deq = WireDefault(io.deq.fire())
+  val flush = io.flush.getOrElse(false.B) 
 
+  // when flush is high, empty the queue
+  // Semantically, any enqueues happen before the flush.
   when (do_enq) {
     ram(enq_ptr.value) := io.enq.bits
     enq_ptr.inc()
@@ -236,10 +244,23 @@ class Queue[T <: Data](val gen: T,
   when (do_enq =/= do_deq) {
     maybe_full := do_enq
   }
+  when(flush) {
+    enq_ptr.reset()
+    deq_ptr.reset()
+    maybe_full := false.B
+  }  
 
   io.deq.valid := !empty
   io.enq.ready := !full
-  io.deq.bits := ram(deq_ptr.value)
+
+  if (useSyncReadMem) {
+    val deq_ptr_next = Mux(deq_ptr.value === (entries.U - 1.U), 0.U, deq_ptr.value + 1.U)
+    val r_addr = WireDefault(Mux(do_deq, deq_ptr_next, deq_ptr.value))
+    io.deq.bits := ram.read(r_addr)
+  }
+  else {
+    io.deq.bits := ram(deq_ptr.value)
+  }
 
   if (flow) {
     when (io.enq.valid) { io.deq.valid := true.B }
@@ -255,6 +276,7 @@ class Queue[T <: Data](val gen: T,
   }
 
   val ptr_diff = enq_ptr.value - deq_ptr.value
+
   if (isPow2(entries)) {
     io.count := Mux(maybe_full && ptr_match, entries.U, 0.U) | ptr_diff
   } else {
@@ -285,7 +307,9 @@ object Queue
       enq: ReadyValidIO[T],
       entries: Int = 2,
       pipe: Boolean = false,
-      flow: Boolean = false): DecoupledIO[T] = {
+      flow: Boolean = false,
+      useSyncReadMem: Boolean = false,
+      hasFlush: Boolean = false): DecoupledIO[T] = {
     if (entries == 0) {
       val deq = Wire(new DecoupledIO(chiselTypeOf(enq.bits)))
       deq.valid := enq.valid
@@ -293,7 +317,7 @@ object Queue
       enq.ready := deq.ready
       deq
     } else {
-      val q = Module(new Queue(chiselTypeOf(enq.bits), entries, pipe, flow))
+      val q = Module(new Queue(chiselTypeOf(enq.bits), entries, pipe, flow, useSyncReadMem, hasFlush))
       q.io.enq.valid := enq.valid // not using <> so that override is allowed
       q.io.enq.bits := enq.bits
       enq.ready := q.io.enq.ready
@@ -311,8 +335,9 @@ object Queue
       enq: ReadyValidIO[T],
       entries: Int = 2,
       pipe: Boolean = false,
-      flow: Boolean = false): IrrevocableIO[T] = {    
-    val deq = apply(enq, entries, pipe, flow)
+      flow: Boolean = false,
+      useSyncReadMem: Boolean = false): IrrevocableIO[T] = {
+    val deq = apply(enq, entries, pipe, flow, useSyncReadMem)
     require(entries > 0, "Zero-entry queues don't guarantee Irrevocability")
     val irr = Wire(new IrrevocableIO(chiselTypeOf(deq.bits)))
     irr.bits := deq.bits
diff --git a/src/main/scala/chisel3/util/ExtModuleUtils.scala b/src/main/scala/chisel3/util/ExtModuleUtils.scala
index 831639be..62f384bc 100644
--- a/src/main/scala/chisel3/util/ExtModuleUtils.scala
+++ b/src/main/scala/chisel3/util/ExtModuleUtils.scala
@@ -3,7 +3,10 @@
 package chisel3.util
 
 import chisel3.experimental.{ChiselAnnotation, ExtModule, RunFirrtlTransform}
-import firrtl.transforms.{BlackBoxPathAnno, BlackBoxResourceAnno, BlackBoxInlineAnno, BlackBoxSourceHelper}
+import firrtl.transforms.{BlackBoxPathAnno, BlackBoxResourceAnno, BlackBoxInlineAnno, BlackBoxSourceHelper,
+  BlackBoxNotFoundException}
+
+import BlackBoxHelpers._
 
 trait HasExtModuleResource extends ExtModule {
   self: ExtModule =>
@@ -18,7 +21,7 @@ trait HasExtModuleResource extends ExtModule {
     */
   def addResource(blackBoxResource: String): Unit = {
     val anno = new ChiselAnnotation with RunFirrtlTransform {
-      def toFirrtl = BlackBoxResourceAnno(self.toNamed, blackBoxResource)
+      def toFirrtl = BlackBoxInlineAnno.fromResource(blackBoxResource, self.toNamed)
       def transformClass = classOf[BlackBoxSourceHelper]
     }
     chisel3.experimental.annotate(anno)
diff --git a/src/main/scala/chisel3/util/MixedVec.scala b/src/main/scala/chisel3/util/MixedVec.scala
index a632ec3a..14d6be38 100644
--- a/src/main/scala/chisel3/util/MixedVec.scala
+++ b/src/main/scala/chisel3/util/MixedVec.scala
@@ -91,6 +91,10 @@ final class MixedVec[T <: Data](private val eltsIn: Seq[T]) extends Record with
     eltsIn.foreach(e => requireIsChiselType(e))
   }
 
+  // In Scala 2.13, this is protected in IndexedSeq, must override as public because it's public in
+  // Record
+  override def className: String = "MixedVec"
+
   // Clone the inputs so that we have our own references.
   private val elts: IndexedSeq[T] = eltsIn.map(_.cloneTypeFull).toIndexedSeq
 
diff --git a/src/main/scala/chisel3/util/Reg.scala b/src/main/scala/chisel3/util/Reg.scala
index 982d80d0..e2b5d172 100644
--- a/src/main/scala/chisel3/util/Reg.scala
+++ b/src/main/scala/chisel3/util/Reg.scala
@@ -42,14 +42,7 @@ object ShiftRegister
     * val regDelayTwo = ShiftRegister(nextVal, 2, ena)
     * }}}
     */
-  def apply[T <: Data](in: T, n: Int, en: Bool = true.B): T = {
-    // The order of tests reflects the expected use cases.
-    if (n != 0) {
-      RegEnable(apply(in, n-1, en), en)
-    } else {
-      in
-    }
-  }
+  def apply[T <: Data](in: T, n: Int, en: Bool = true.B): T = ShiftRegisters(in, n, en).lastOption.getOrElse(in)
 
   /** Returns the n-cycle delayed version of the input signal with reset initialization.
     *
@@ -62,12 +55,30 @@ object ShiftRegister
     * val regDelayTwoReset = ShiftRegister(nextVal, 2, 0.U, ena)
     * }}}
     */
-  def apply[T <: Data](in: T, n: Int, resetData: T, en: Bool): T = {
-    // The order of tests reflects the expected use cases.
-    if (n != 0) {
-      RegEnable(apply(in, n-1, resetData, en), resetData, en)
-    } else {
-      in
-    }
-  }
+  def apply[T <: Data](in: T, n: Int, resetData: T, en: Bool): T = ShiftRegisters(in, n, resetData, en).lastOption.getOrElse(in)
+}
+
+
+object ShiftRegisters
+{
+  /** Returns a sequence of delayed input signal registers from 1 to n.
+    *
+    * @param in input to delay
+    * @param n  number of cycles to delay
+    * @param en enable the shift
+    *
+    */
+  def apply[T <: Data](in: T, n: Int, en: Bool = true.B): Seq[T] =
+    Seq.iterate(in, n + 1)(util.RegEnable(_, en)).drop(1)
+
+  /** Returns delayed input signal registers with reset initialization from 1 to n.
+    *
+    * @param in        input to delay
+    * @param n         number of cycles to delay
+    * @param resetData reset value for each register in the shift
+    * @param en        enable the shift
+    *
+    */
+  def apply[T <: Data](in: T, n: Int, resetData: T, en: Bool): Seq[T] =
+    Seq.iterate(in, n + 1)(util.RegEnable(_, resetData, en)).drop(1)
 }
diff --git a/src/main/scala/chisel3/util/experimental/BoringUtils.scala b/src/main/scala/chisel3/util/experimental/BoringUtils.scala
index 18551da8..f2a3e757 100644
--- a/src/main/scala/chisel3/util/experimental/BoringUtils.scala
+++ b/src/main/scala/chisel3/util/experimental/BoringUtils.scala
@@ -19,7 +19,7 @@ class BoringUtilsException(message: String) extends Exception(message)
 /** Utilities for generating synthesizable cross module references that "bore" through the hierarchy. The underlying
   * cross module connects are handled by FIRRTL's Wiring Transform.
   *
-  * Consider the following exmple where you want to connect a component in one module to a component in another. Module
+  * Consider the following example where you want to connect a component in one module to a component in another. Module
   * `Constant` has a wire tied to `42` and `Expect` will assert unless connected to `42`:
   * {{{
   * class Constant extends Module {
@@ -45,8 +45,8 @@ class BoringUtilsException(message: String) extends Exception(message)
   *
   * ===Hierarchical Boring===
   *
-  * Hierarchcical boring involves connecting one sink instance to another source instance in a parent module. Below,
-  * module `Top` contains an instance of `Cosntant` and `Expect`. Using [[BoringUtils.bore]], we can connect
+  * Hierarchical boring involves connecting one sink instance to another source instance in a parent module. Below,
+  * module `Top` contains an instance of `Constant` and `Expect`. Using [[BoringUtils.bore]], we can connect
   * `constant.x` to `expect.y`.
   *
   * {{{
@@ -89,7 +89,7 @@ class BoringUtilsException(message: String) extends Exception(message)
   * ==Comments==
   *
   * Both hierarchical and non-hierarchical boring emit FIRRTL annotations that describe sources and sinks. These are
-  * matched by a `name` key that indicates they should be wired together. Hierarhical boring safely generates this name
+  * matched by a `name` key that indicates they should be wired together. Hierarchical boring safely generates this name
   * automatically. Non-hierarchical boring unsafely relies on user input to generate this name. Use of non-hierarchical
   * naming may result in naming conflicts that the user must handle.
   *
@@ -115,7 +115,7 @@ object BoringUtils {
   /** Add a named source cross module reference
     * @param component source circuit component
     * @param name unique identifier for this source
-    * @param disableDedup disable dedupblication of this source component (this should be true if you are trying to wire
+    * @param disableDedup disable deduplication of this source component (this should be true if you are trying to wire
     * from specific identical sources differently)
     * @param uniqueName if true, this will use a non-conflicting name from the global namespace
     * @return the name used
@@ -137,7 +137,7 @@ object BoringUtils {
             def transformClass = classOf[WiringTransform] },
           new ChiselAnnotation { def toFirrtl = DontTouchAnnotation(component.toNamed) } ) ++ maybeDedup
 
-    annotations.map(annotate(_))
+    annotations.foreach(annotate(_))
     id
   }
 
@@ -146,8 +146,8 @@ object BoringUtils {
     * @param name unique identifier for this sink that must resolve to
     * @param disableDedup disable deduplication of this sink component (this should be true if you are trying to wire
     * specific, identical sinks differently)
-    * @param forceExists if true, require that the provided `name` paramater already exists in the global namespace
-    * @throws BoringUtilsException if name is expected to exist and itdoesn't
+    * @param forceExists if true, require that the provided `name` parameter already exists in the global namespace
+    * @throws BoringUtilsException if name is expected to exist and it doesn't
     */
   def addSink(
     component: InstanceId,
@@ -169,7 +169,7 @@ object BoringUtils {
       Seq(new ChiselAnnotation with RunFirrtlTransform {
             def toFirrtl = SinkAnnotation(component.toNamed, name)
             def transformClass = classOf[WiringTransform] }) ++ maybeDedup
-    annotations.map(annotate(_))
+    annotations.foreach(annotate(_))
   }
 
   /** Connect a source to one or more sinks
@@ -187,7 +187,7 @@ object BoringUtils {
       case _: Exception => "bore"
     }
     val genName = addSource(source, boringName, true, true)
-    sinks.map(addSink(_, genName, true, true))
+    sinks.foreach(addSink(_, genName, true, true))
     genName
   }
 
diff --git a/src/main/scala/chisel3/util/experimental/LoadMemoryTransform.scala b/src/main/scala/chisel3/util/experimental/LoadMemoryTransform.scala
index d91d97b7..93981485 100644
--- a/src/main/scala/chisel3/util/experimental/LoadMemoryTransform.scala
+++ b/src/main/scala/chisel3/util/experimental/LoadMemoryTransform.scala
@@ -40,7 +40,7 @@ case class ChiselLoadMemoryAnnotation[T <: Data](
 }
 
 
-/** [[loadMemoryFromFile]] is an annotation generator that helps with loading a memory from a text file. This relies on
+/** [[loadMemoryFromFile]] is an annotation generator that helps with loading a memory from a text file as a bind module. This relies on
   * Verilator and Verilog's `\$readmemh` or `\$readmemb`. The [[https://github.com/freechipsproject/treadle Treadle
   * backend]] can also recognize this annotation and load memory at run-time.
   *
@@ -116,6 +116,86 @@ object loadMemoryFromFile {
   }
 }
 
+
+/** [[loadMemoryFromFileInline]] is an annotation generator that helps with loading a memory from a text file inlined in
+  * the Verilog module. This relies on Verilator and Verilog's `\$readmemh` or `\$readmemb`.
+  * The [[https://github.com/freechipsproject/treadle Treadlebackend]] can also recognize this annotation and load memory at run-time.
+  *
+  * This annotation, when the FIRRTL compiler runs, triggers the [[MemoryFileInlineAnnotation]] that will add Verilog
+  * directives inlined to the module enabling the specified memories to be initialized from files.
+  * The module supports both `hex` and `bin` files by passing the appropriate [[MemoryLoadFileType.FileType]] argument with
+  * [[MemoryLoadFileType.Hex]] or [[MemoryLoadFileType.Binary]]. Hex is the default.
+  *
+  * ==Example module==
+  *
+  * Consider a simple Module containing a memory:
+  * {{{
+  * import chisel3._
+  * class UsesMem(memoryDepth: Int, memoryType: Data) extends Module {
+  *   val io = IO(new Bundle {
+  *     val address = Input(UInt(memoryType.getWidth.W))
+  *     val value   = Output(memoryType)
+  *   })
+  *   val memory = Mem(memoryDepth, memoryType)
+  *   io.value := memory(io.address)
+  * }
+  * }}}
+  *
+  * ==Above module with annotation==
+  *
+  * To load this memory from the file `/workspace/workdir/mem1.hex.txt` just add an import and annotate the memory:
+  * {{{
+  * import chisel3._
+  * import chisel3.util.experimental.loadMemoryFromFileInline   // <<-- new import here
+  * class UsesMem(memoryDepth: Int, memoryType: Data) extends Module {
+  *   val io = IO(new Bundle {
+  *     val address = Input(UInt(memoryType.getWidth.W))
+  *     val value   = Output(memoryType)
+  *   })
+  *   val memory = Mem(memoryDepth, memoryType)
+  *   io.value := memory(io.address)
+  *   loadMemoryFromFileInline(memory, "/workspace/workdir/mem1.hex.txt")  // <<-- Note the annotation here
+  * }
+  * }}}
+  *
+  * ==Example file format==
+  *
+  * A memory file should consist of ASCII text in either hex or binary format. The following example shows such a
+  * file formatted to use hex:
+  * {{{
+  *   0
+  *   7
+  *   d
+  *  15
+  * }}}
+  *
+  * A binary file can be similarly constructed.
+  * Chisel does not validate the file format or existence. It is supposed to be in a path accessible by the synthesis
+  * tool together with the generated Verilog.
+  *
+  * @see Chisel3 Wiki entry on
+  * [[https://github.com/freechipsproject/chisel3/wiki/Chisel-Memories#loading-memories-in-simulation "Loading Memories
+  * in Simulation"]]
+  */
+object loadMemoryFromFileInline {
+
+
+  /** Annotate a memory such that it can be initialized inline using a file
+    * @param memory the memory
+    * @param fileName the file used for initialization
+    * @param hexOrBinary whether the file uses a hex or binary number representation
+    */
+  def apply[T <: Data](
+    memory: MemBase[T],
+    fileName: String,
+    hexOrBinary: MemoryLoadFileType.FileType = MemoryLoadFileType.Hex
+  ): Unit = {
+    annotate(new ChiselAnnotation {
+      override def toFirrtl = MemoryFileInlineAnnotation(memory.toTarget, fileName, hexOrBinary)
+    })
+  }
+}
+
 /** This transform only is activated if Verilog is being generated (determined by presence of the proper emit
   * annotation) when activated it creates additional Verilog files that contain modules bound to the modules that
   * contain an initializable memory
diff --git a/src/main/scala/chisel3/util/experimental/decode/DecodeTableAnnotation.scala b/src/main/scala/chisel3/util/experimental/decode/DecodeTableAnnotation.scala
new file mode 100644
index 00000000..2b50ef90
--- /dev/null
+++ b/src/main/scala/chisel3/util/experimental/decode/DecodeTableAnnotation.scala
@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.util.experimental.decode
+
+import firrtl.annotations.{Annotation, ReferenceTarget, SingleTargetAnnotation}
+
+/** DecodeTableAnnotation used to store a decode result for a specific [[TruthTable]].
+  * This is useful for saving large [[TruthTable]] during a elaboration time.
+  *
+  * @note user should manage the correctness of [[minimizedTable]].
+  *
+  * @param target output wire of a decoder.
+  * @param truthTable input [[TruthTable]] encoded in a serialized [[TruthTable]].
+  * @param minimizedTable minimized [[truthTable]] encoded in a serialized [[TruthTable]].
+  */
+case class DecodeTableAnnotation(
+  target:         ReferenceTarget,
+  truthTable:     String,
+  minimizedTable: String)
+    extends SingleTargetAnnotation[ReferenceTarget] {
+  override def duplicate(n: ReferenceTarget): Annotation = this.copy(target = n)
+}
diff --git a/src/main/scala/chisel3/util/experimental/decode/EspressoMinimizer.scala b/src/main/scala/chisel3/util/experimental/decode/EspressoMinimizer.scala
new file mode 100644
index 00000000..1d725875
--- /dev/null
+++ b/src/main/scala/chisel3/util/experimental/decode/EspressoMinimizer.scala
@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.util.experimental.decode
+
+import chisel3.util.BitPat
+import logger.LazyLogging
+
+case object EspressoNotFoundException extends Exception
+
+object EspressoMinimizer extends Minimizer with LazyLogging {
+  def minimize(table: TruthTable): TruthTable =
+    TruthTable.merge(TruthTable.split(table).map{case (table, indexes) => (espresso(table), indexes)})
+
+  def espresso(table: TruthTable): TruthTable = {
+    def writeTable(table: TruthTable): String = {
+      def invert(string: String) = string
+        .replace('0', 't')
+        .replace('1', '0')
+        .replace('t', '1')
+      val defaultType: Char = {
+        val t = table.default.rawString.toCharArray.distinct
+        require(t.length == 1, "Internal Error: espresso only accept unified default type.")
+        t.head
+      }
+      val tableType: String = defaultType match {
+        case '?' => "fr"
+        case _ => "fd"
+      }
+      val rawTable = table
+        .toString
+        .split("\n")
+        .filter(_.contains("->"))
+        .mkString("\n")
+        .replace("->", " ")
+        .replace('?', '-')
+      // invert all output, since espresso cannot handle default is on.
+      val invertRawTable = rawTable
+        .split("\n")
+        .map(_.split(" "))
+        .map(row => s"${row(0)} ${invert(row(1))}")
+        .mkString("\n")
+      s""".i ${table.inputWidth}
+         |.o ${table.outputWidth}
+         |.type ${tableType}
+         |""".stripMargin ++ (if (defaultType == '1') invertRawTable else rawTable)
+    }
+
+    def readTable(espressoTable: String): Map[BitPat, BitPat] = {
+      def bitPat(espresso: String): BitPat = BitPat("b" + espresso.replace('-', '?'))
+
+      espressoTable
+        .split("\n")
+        .filterNot(_.startsWith("."))
+        .map(_.split(' '))
+        .map(row => bitPat(row(0)) -> bitPat(row(1)))
+        .toMap
+    }
+
+    val input = writeTable(table)
+    logger.trace(s"""espresso input table:
+                    |$input
+                    |""".stripMargin)
+    val output = try {
+      os.proc("espresso").call(stdin = input).out.chunks.mkString
+    } catch {
+      case e: java.io.IOException if e.getMessage.contains("error=2, No such file or directory") => throw EspressoNotFoundException
+    }
+    logger.trace(s"""espresso output table:
+                    |$output
+                    |""".stripMargin)
+    TruthTable(readTable(output), table.default)
+  }
+}
diff --git a/src/main/scala/chisel3/util/experimental/decode/Minimizer.scala b/src/main/scala/chisel3/util/experimental/decode/Minimizer.scala
new file mode 100644
index 00000000..86847710
--- /dev/null
+++ b/src/main/scala/chisel3/util/experimental/decode/Minimizer.scala
@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.util.experimental.decode
+
+abstract class Minimizer {
+  /** Minimize a multi-input multi-output logic function given by the truth table `table`, with function output values
+    * on unspecified inputs treated as `default`, and return a minimized PLA-like representation of the function.
+    *
+    * Each bit of `table[]._1` encodes one 1-bit input variable of the logic function, and each bit of `default` and
+    * `table[]._2` represents one 1-bit output value of the function.
+    *
+    * @param table    Truth table, can have don't cares in both inputs and outputs, specified as [(inputs, outputs), ...]
+    * @return         Minimized truth table, [(inputs, outputs), ...]
+    *
+    * @example {{{
+    *          minimize(BitPat("b?"), Seq(
+    *              (BitPat("b000"), BitPat("b0")),
+    *              // (BitPat("b001"), BitPat("b?")),  // same as default, can be omitted
+    *              // (BitPat("b010"), BitPat("b?")),  // same as default, can be omitted
+    *              (BitPat("b011"), BitPat("b0")),
+    *              (BitPat("b100"), BitPat("b1")),
+    *              (BitPat("b101"), BitPat("b1")),
+    *              (BitPat("b110"), BitPat("b0")),
+    *              (BitPat("b111"), BitPat("b1")),
+    *          ))
+    * }}}
+    */
+  def minimize(table: TruthTable): TruthTable
+}
\ No newline at end of file
diff --git a/src/main/scala/chisel3/util/experimental/decode/QMCMinimizer.scala b/src/main/scala/chisel3/util/experimental/decode/QMCMinimizer.scala
new file mode 100644
index 00000000..c1533f44
--- /dev/null
+++ b/src/main/scala/chisel3/util/experimental/decode/QMCMinimizer.scala
@@ -0,0 +1,298 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.util.experimental.decode
+
+import chisel3.util.BitPat
+
+import scala.annotation.tailrec
+import scala.math.Ordered.orderingToOrdered
+import scala.language.implicitConversions
+
+object QMCMinimizer extends Minimizer {
+  private implicit def toImplicant(x: BitPat): Implicant = new Implicant(x)
+
+  private class Implicant(val bp: BitPat) {
+    var isPrime: Boolean = true
+
+    def width = bp.getWidth
+
+    override def equals(that: Any): Boolean = that match {
+      case x: Implicant => bp.value == x.bp.value && bp.mask == x.bp.mask
+      case _ => false
+    }
+
+    override def hashCode = bp.value.toInt
+
+    /** Check whether two implicants have the same value on all of the cared bits (intersection).
+      *
+      * {{{
+      * value ^^ x.value                                       // bits that are different
+      * (bits that are different) & x.mask                     // bits that are different and `this` care
+      * (bits that are different and `this` care) & y.mask     // bits that are different and `both` care
+      * (bits that are different and both care) == 0           // no (bits that are different and we both care) exists
+      * no (bits that are different and we both care) exists   // all cared bits are the same, two terms intersect
+      * }}}
+      *
+      * @param y Implicant to be checked with
+      * @return Whether two implicants intersect
+      */
+    def intersects(y: Implicant): Boolean = ((bp.value ^ y.bp.value) & bp.mask & y.bp.mask) == 0
+
+    /** Check whether two implicants are similar.
+      * Two implicants are "similar" when they satisfy all the following rules:
+      *   1. have the same mask ('?'s are at the same positions)
+      *   1. values only differ by one bit
+      *   1. the bit at the differed position of this term is '1' (that of the other term is '0')
+      *
+      * @example this = 11?0, x = 10?0 -> similar
+      * @example this = 11??, x = 10?0 -> not similar, violated rule 1
+      * @example this = 11?1, x = 10?0 -> not similar, violated rule 2
+      * @example this = 10?0, x = 11?0 -> not similar, violated rule 3
+      * @param y Implicant to be checked with
+      * @return Whether this term is similar to the other
+      */
+    def similar(y: Implicant): Boolean = {
+      val diff = bp.value - y.bp.value
+      bp.mask == y.bp.mask && bp.value > y.bp.value && (diff & diff - 1) == 0
+    }
+
+    /** Merge two similar implicants
+      * Rule of merging: '0' and '1' merge to '?'
+      *
+      * @param y Term to be merged with
+      * @return A new term representing the merge result
+      */
+    def merge(y: Implicant): Implicant = {
+      require(similar(y), s"merge is only reasonable when $this is similar to $y")
+
+      // if two term can be merged, then they both are not prime implicants.
+      isPrime = false
+      y.isPrime = false
+      val bit = bp.value - y.bp.value
+      new BitPat(bp.value &~ bit, bp.mask &~ bit, width)
+    }
+
+    /** Check all bits in `x` cover the correspond position in `y`.
+      *
+      * Rule to define coverage relationship among `0`, `1` and `?`:
+      *   1. '?' covers '0' and '1', '0' covers '0', '1' covers '1'
+      *   1. '1' doesn't cover '?', '1' doesn't cover '0'
+      *   1. '0' doesn't cover '?', '0' doesn't cover '1'
+      *
+      * For all bits that `x` don't care, `y` can be `0`, `1`, `?`
+      * For all bits that `x` care, `y` must be the same value and not masked.
+      * {{{
+      *    (~x.mask & -1) | ((x.mask) & ((x.value xnor y.value) & y.mask)) = -1
+      * -> ~x.mask | ((x.mask) & ((x.value xnor y.value) & y.mask)) = -1
+      * -> ~x.mask | ((x.value xnor y.value) & y.mask) = -1
+      * -> x.mask & ~((x.value xnor y.value) & y.mask) = 0
+      * -> x.mask & (~(x.value xnor y.value) | ~y.mask) = 0
+      * -> x.mask & ((x.value ^ y.value) | ~y.mask) = 0
+      * -> ((x.value ^ y.value) & x.mask | ~y.mask & x.mask) = 0
+      * }}}
+      *
+      * @param y to check is covered by `x` or not.
+      * @return Whether `x` covers `y`
+      */
+    def covers(y: Implicant): Boolean = ((bp.value ^ y.bp.value) & bp.mask | ~y.bp.mask & bp.mask) == 0
+
+    override def toString = (if (!isPrime) "Non" else "") + "Prime" + bp.toString.replace("BitPat", "Implicant")
+  }
+
+  /**
+    * If two terms have different value, then their order is determined by the value, or by the mask.
+    */
+  private implicit def ordering: Ordering[Implicant] = new Ordering[Implicant] {
+    override def compare(x: Implicant, y: Implicant): Int =
+      if (x.bp.value < y.bp.value || x.bp.value == y.bp.value && x.bp.mask > y.bp.mask) -1 else 1
+  }
+
+  /** Calculate essential prime implicants based on previously calculated prime implicants and all implicants.
+    *
+    * @param primes    Prime implicants
+    * @param minterms All implicants
+    * @return (a, b, c)
+    *         a: essential prime implicants
+    *         b: nonessential prime implicants
+    *         c: implicants that are not cover by any of the essential prime implicants
+    */
+  private def getEssentialPrimeImplicants(primes: Seq[Implicant], minterms: Seq[Implicant]): (Seq[Implicant], Seq[Implicant], Seq[Implicant]) = {
+    // primeCovers(i): implicants that `prime(i)` covers
+    val primeCovers = primes.map(p => minterms.filter(p.covers))
+    // eliminate prime implicants that can be covered by other prime implicants
+    for (((icover, pi), i) <- (primeCovers zip primes).zipWithIndex) {
+      for (((jcover, pj), _) <- (primeCovers zip primes).zipWithIndex.drop(i + 1)) {
+        // we prefer prime implicants with wider implicants coverage
+        if (icover.size > jcover.size && jcover.forall(pi.covers)) {
+          // calculate essential prime implicants with `pj` eliminated from prime implicants table
+          return getEssentialPrimeImplicants(primes.filter(_ != pj), minterms)
+        }
+      }
+    }
+
+    // implicants that only one prime implicant covers
+    val essentiallyCovered = minterms.filter(t => primes.count(_.covers(t)) == 1)
+    // essential prime implicants, prime implicants that covers only one implicant
+    val essential = primes.filter(p => essentiallyCovered.exists(p.covers))
+    // {nonessential} = {prime implicants} - {essential prime implicants}
+    val nonessential = primes.filterNot(essential contains _)
+    // implicants that no essential prime implicants covers
+    val uncovered = minterms.filterNot(t => essential.exists(_.covers(t)))
+    if (essential.isEmpty || uncovered.isEmpty)
+      (essential, nonessential, uncovered)
+    else {
+      // now there are implicants (`uncovered`) that are covered by multiple nonessential prime implicants (`nonessential`)
+      // need to reduce prime implicants
+      val (a, b, c) = getEssentialPrimeImplicants(nonessential, uncovered)
+      (essential ++ a, b, c)
+    }
+  }
+
+  /** Use [[https://en.wikipedia.org/wiki/Petrick%27s_method]] to select a [[Seq]] of nonessential prime implicants
+    * that covers all implicants that are not covered by essential prime implicants.
+    *
+    * @param implicants Nonessential prime implicants
+    * @param minterms   Implicants that are not covered by essential prime implicants
+    * @return Selected nonessential prime implicants
+    */
+  private def getCover(implicants: Seq[Implicant], minterms: Seq[Implicant]): Seq[Implicant] = {
+    /** Calculate the implementation cost (using comparators) of a list of implicants, more don't cares is cheaper
+      *
+      * @param cover Implicant list
+      * @return How many comparators need to implement this list of implicants
+      */
+    def getCost(cover: Seq[Implicant]): Int = cover.map(_.bp.mask.bitCount).sum
+
+    /** Determine if one combination of prime implicants is cheaper when implementing as comparators.
+      * Shorter term list is cheaper, term list with more don't cares is cheaper (less comparators)
+      *
+      * @param a    Operand a
+      * @param b    Operand b
+      * @return `a` < `b`
+      */
+    def cheaper(a: Seq[Implicant], b: Seq[Implicant]): Boolean = {
+      val ca = getCost(a)
+      val cb = getCost(b)
+
+      /** If `a` < `b`
+        *
+        * Like comparing the dictionary order of two strings.
+        * Define `a` < `b` if both `a` and `b` are empty.
+        *
+        * @param a Operand a
+        * @param b Operand b
+        * @return `a` < `b`
+        */
+      @tailrec
+      def listLess(a: Seq[Implicant], b: Seq[Implicant]): Boolean = b.nonEmpty && (a.isEmpty || a.head < b.head || a.head == b.head && listLess(a.tail, b.tail))
+
+      ca < cb || ca == cb && listLess(a.sortWith(_ < _), b.sortWith(_ < _))
+    }
+
+    // if there are no implicant that is not covered by essential prime implicants, which means all implicants are
+    // covered by essential prime implicants, there is no need to apply Petrick's method
+    if (minterms.nonEmpty) {
+      // cover(i): nonessential prime implicants that covers `minterms(i)`
+      val cover = minterms.map(m => implicants.filter(_.covers(m)))
+      // all subsets of `cover`, NP algorithm, O(2 ^ len(cover))
+      val all = cover.tail.foldLeft(cover.head.map(Set(_)))((c0, c1) => c0.flatMap(a => c1.map(a + _)))
+      all.map(_.toList).reduceLeft((a, b) => if (cheaper(a, b)) a else b)
+    } else
+      Seq[Implicant]()
+  }
+
+  def minimize(table: TruthTable): TruthTable = {
+    require(table.table.nonEmpty, "Truth table must not be empty")
+
+    // extract decode table to inputs and outputs
+    val (inputs, outputs) = table.table.unzip
+
+    require(outputs.map(_.getWidth == table.default.getWidth).reduce(_ && _), "All output BitPats and default BitPat must have the same length")
+    require(if (inputs.toSeq.length > 1) inputs.tail.map(_.width == inputs.head.width).reduce(_ && _) else true, "All input BitPats must have the same length")
+
+    // make sure no two inputs specified in the truth table intersect
+    for (t <- inputs.tails; if t.nonEmpty)
+      for (u <- t.tail)
+        require(!t.head.intersects(u), "truth table entries " + t.head + " and " + u + " overlap")
+
+    // number of inputs
+    val n = inputs.head.width
+    // number of outputs
+    val m = outputs.head.getWidth
+
+    // for all outputs
+    val minimized = (0 until m).flatMap(i => {
+      val outputBp = BitPat("b" + "?" * (m - i - 1) + "1" + "?" * i)
+
+      // Minterms, implicants that makes the output to be 1
+      val mint: Seq[Implicant] = table.table.filter { case (_, t) => t.mask.testBit(i) && t.value.testBit(i) }.keys.map(toImplicant).toSeq
+      // Maxterms, implicants that makes the output to be 0
+      val maxt: Seq[Implicant] = table.table.filter { case (_, t) => t.mask.testBit(i) && !t.value.testBit(i) }.keys.map(toImplicant).toSeq
+      // Don't cares, implicants that can produce either 0 or 1 as output
+      val dc: Seq[Implicant] = table.table.filter { case (_, t) => !t.mask.testBit(i) }.keys.map(toImplicant).toSeq
+
+      val (implicants, defaultToDc) = table.default match {
+        case x if x.mask.testBit(i) && !x.value.testBit(i) => // default to 0
+          (mint ++ dc, false)
+        case x if x.mask.testBit(i) && x.value.testBit(i) => // default to 1
+          (maxt ++ dc, false)
+        case x if !x.mask.testBit(i) => // default to ?
+          (mint, true)
+      }
+
+      implicants.foreach(_.isPrime = true)
+      val cols = (0 to n).reverse.map(b => implicants.filter(b == _.bp.mask.bitCount))
+      val mergeTable = cols.map(
+        c => (0 to n).map(
+          b => collection.mutable.Set(c.filter(b == _.bp.value.bitCount):_*)
+        )
+      )
+
+      // O(n ^ 3)
+      for (i <- 0 to n) {
+        for (j <- 0 until n - i) {
+          mergeTable(i)(j).foreach(a => mergeTable(i + 1)(j) ++= mergeTable(i)(j + 1).filter(_ similar a).map(_ merge a))
+        }
+        if (defaultToDc) {
+          for (j <- 0 until n - i) {
+            for (a <- mergeTable(i)(j).filter(_.isPrime)) {
+              if (a.bp.mask.testBit(i) && !a.bp.value.testBit(i)) {
+                // this bit is `0`
+                val t = new BitPat(a.bp.value.setBit(i), a.bp.mask, a.width)
+                if (!maxt.exists(_.intersects(t))) mergeTable(i + 1)(j) += t merge a
+              }
+            }
+            for (a <- mergeTable(i)(j + 1).filter(_.isPrime)) {
+              if (a.bp.mask.testBit(i) && a.bp.value.testBit(i)) {
+                // this bit is `1`
+                val t = new BitPat(a.bp.value.clearBit(i), a.bp.mask, a.width)
+                if (!maxt.exists(_.intersects(t))) mergeTable(i + 1)(j) += a merge t
+              }
+            }
+          }
+        }
+      }
+
+      val primeImplicants = mergeTable.flatten.flatten.filter(_.isPrime).sortWith(_ < _)
+
+      // O(len(primeImplicants) ^ 4)
+      val (essentialPrimeImplicants, nonessentialPrimeImplicants, uncoveredImplicants) =
+        getEssentialPrimeImplicants(primeImplicants, implicants)
+
+      (essentialPrimeImplicants ++ getCover(nonessentialPrimeImplicants, uncoveredImplicants)).map(a => (a.bp, outputBp))
+    })
+
+    minimized.tail.foldLeft(table.copy(table = Map(minimized.head))) { case (tb, t) =>
+      if (tb.table.exists(x => x._1 == t._1)) {
+        tb.copy(table = tb.table.map { case (k, v) =>
+          if (k == t._1) {
+            def ones(bitPat: BitPat) = bitPat.rawString.zipWithIndex.collect{case ('1', x) => x}
+            (k, BitPat("b" + (0 until v.getWidth).map(i => if ((ones(v) ++ ones(t._2)).contains(i)) "1" else "?").mkString))
+          } else (k, v)
+        })
+      } else {
+        tb.copy(table = tb.table + t)
+      }
+    }
+  }
+}
\ No newline at end of file
diff --git a/src/main/scala/chisel3/util/experimental/decode/TruthTable.scala b/src/main/scala/chisel3/util/experimental/decode/TruthTable.scala
new file mode 100644
index 00000000..683de16b
--- /dev/null
+++ b/src/main/scala/chisel3/util/experimental/decode/TruthTable.scala
@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.util.experimental.decode
+
+import chisel3.util.BitPat
+
+final class TruthTable(val table: Map[BitPat, BitPat], val default: BitPat) {
+
+  def inputWidth = table.head._1.getWidth
+
+  def outputWidth = table.head._2.getWidth
+
+  override def toString: String = {
+    def writeRow(map: (BitPat, BitPat)): String =
+      s"${map._1.rawString}->${map._2.rawString}"
+
+    (table.map(writeRow) ++ Seq(s"${" "*(inputWidth + 2)}${default.rawString}")).toSeq.sorted.mkString("\n")
+  }
+
+  def copy(table: Map[BitPat, BitPat] = this.table, default: BitPat = this.default) = new TruthTable(table, default)
+
+  override def equals(y: Any): Boolean = {
+    y match {
+      case y: TruthTable => toString == y.toString
+      case _ => false
+    }
+  }
+}
+
+object TruthTable {
+  /** Parse TruthTable from its string representation. */
+  def apply(tableString: String): TruthTable = {
+    TruthTable(
+      tableString
+        .split("\n")
+        .filter(_.contains("->"))
+        .map(_.split("->").map(str => BitPat(s"b$str")))
+        .map(bps => bps(0) -> bps(1))
+        .toSeq,
+      BitPat(s"b${tableString.split("\n").filterNot(_.contains("->")).head.replace(" ", "")}")
+    )
+  }
+
+  /** Convert a table and default output into a [[TruthTable]]. */
+  def apply(table: Iterable[(BitPat, BitPat)], default: BitPat): TruthTable = {
+    require(table.map(_._1.getWidth).toSet.size == 1, "input width not equal.")
+    require(table.map(_._2.getWidth).toSet.size == 1, "output width not equal.")
+    val outputWidth = table.map(_._2.getWidth).head
+    new TruthTable(table.toSeq.groupBy(_._1.toString).map { case (key, values) =>
+      // merge same input inputs.
+      values.head._1 -> BitPat(s"b${
+        Seq.tabulate(outputWidth) { i =>
+          val outputSet = values.map(_._2)
+            .map(_.rawString)
+            .map(_ (i))
+            .toSet
+            .filterNot(_ == '?')
+          require(outputSet.size != 2, s"TruthTable conflict in :\n${values.map { case (i, o) => s"${i.rawString}->${o.rawString}" }.mkString("\n")}")
+          outputSet.headOption.getOrElse('?')
+        }.mkString
+      }")
+    }, default)
+  }
+
+
+  /** consume 1 table, split it into up to 3 tables with the same default bits.
+    *
+    * @return table and its indexes from original bits.
+    * @note
+    * Since most of minimizer(like espresso) cannot handle a multiple default table.
+    * It is useful to split a table into 3 tables based on the default type.
+    */
+  private[decode] def split(
+    table: TruthTable
+  ): Seq[(TruthTable, Seq[Int])] = {
+    def bpFilter(bitPat: BitPat, indexes: Seq[Int]): BitPat =
+      BitPat(s"b${bitPat.rawString.zipWithIndex.filter(b => indexes.contains(b._2)).map(_._1).mkString}")
+
+    def tableFilter(indexes: Seq[Int]): Option[(TruthTable, Seq[Int])] = {
+      if(indexes.nonEmpty) Some((TruthTable(
+        table.table.map { case (in, out) => in -> bpFilter(out, indexes) },
+        bpFilter(table.default, indexes)
+      ), indexes)) else None
+    }
+
+    def index(bitPat: BitPat, bpType: Char): Seq[Int] =
+      bitPat.rawString.zipWithIndex.filter(_._1 == bpType).map(_._2)
+
+    Seq('1', '0', '?').flatMap(t => tableFilter(index(table.default, t)))
+  }
+
+  /** consume tables, merge it into single table with different default bits.
+    *
+    * @note
+    * Since most of minimizer(like espresso) cannot handle a multiple default table.
+    * It is useful to split a table into 3 tables based on the default type.
+    */
+  private[decode] def merge(
+    tables: Seq[(TruthTable, Seq[Int])]
+  ): TruthTable = {
+    def reIndex(bitPat: BitPat, table: TruthTable, indexes: Seq[Int]): Seq[(Char, Int)] =
+      (table.table.map(a => a._1.toString -> a._2).getOrElse(bitPat.toString, BitPat.dontCare(indexes.size))).rawString.zip(indexes)
+    def bitPat(indexedChar: Seq[(Char, Int)]) = BitPat(s"b${indexedChar
+      .sortBy(_._2)
+      .map(_._1)
+      .mkString}")
+    TruthTable(
+      tables
+        .flatMap(_._1.table.keys)
+        .map { key =>
+          key -> bitPat(tables.flatMap { case (table, indexes) => reIndex(key, table, indexes) })
+        }
+        .toMap,
+      bitPat(tables.flatMap { case (table, indexes) => table.default.rawString.zip(indexes) })
+    )
+  }
+}
diff --git a/src/main/scala/chisel3/util/experimental/decode/decoder.scala b/src/main/scala/chisel3/util/experimental/decode/decoder.scala
new file mode 100644
index 00000000..42e374d1
--- /dev/null
+++ b/src/main/scala/chisel3/util/experimental/decode/decoder.scala
@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.util.experimental.decode
+
+import chisel3._
+import chisel3.experimental.{ChiselAnnotation, annotate}
+import chisel3.util.{BitPat, pla}
+import chisel3.util.experimental.getAnnotations
+import firrtl.annotations.Annotation
+import logger.LazyLogging
+
+object decoder extends LazyLogging {
+  /** Use a specific [[Minimizer]] to generated decoded signals.
+    *
+    * @param minimizer  specific [[Minimizer]], can be [[QMCMinimizer]] or [[EspressoMinimizer]].
+    * @param input      input signal that contains decode table input
+    * @param truthTable [[TruthTable]] to decode user input.
+    * @return decode table output.
+    */
+  def apply(minimizer: Minimizer, input: UInt, truthTable: TruthTable): UInt = {
+    val minimizedTable = getAnnotations().collect {
+      case DecodeTableAnnotation(_, in, out) => TruthTable(in) -> TruthTable(out)
+    }.toMap.getOrElse(truthTable, minimizer.minimize(truthTable))
+    if (minimizedTable.table.isEmpty) {
+      val outputs = Wire(UInt(minimizedTable.default.getWidth.W))
+      outputs := minimizedTable.default.value.U(minimizedTable.default.getWidth.W)
+      outputs
+    } else {
+      val (plaInput, plaOutput) =
+        pla(minimizedTable.table.toSeq, BitPat(minimizedTable.default.value.U(minimizedTable.default.getWidth.W)))
+
+      annotate(new ChiselAnnotation {
+        override def toFirrtl: Annotation =
+          DecodeTableAnnotation(plaOutput.toTarget, truthTable.toString, minimizedTable.toString)
+      })
+
+      plaInput := input
+      plaOutput
+    }
+  }
+
+  /** Use [[EspressoMinimizer]] to generated decoded signals.
+    *
+    * @param input      input signal that contains decode table input
+    * @param truthTable [[TruthTable]] to decode user input.
+    * @return decode table output.
+    */
+  def espresso(input: UInt, truthTable: TruthTable): UInt = apply(EspressoMinimizer, input, truthTable)
+
+  /** Use [[QMCMinimizer]] to generated decoded signals.
+    *
+    * @param input      input signal that contains decode table input
+    * @param truthTable [[TruthTable]] to decode user input.
+    * @return decode table output.
+    */
+  def qmc(input: UInt, truthTable: TruthTable): UInt = apply(QMCMinimizer, input, truthTable)
+
+  /** try to use [[EspressoMinimizer]] to decode `input` by `truthTable`
+    * if `espresso` not exist in your PATH environment it will fall back to [[QMCMinimizer]], and print a warning.
+    *
+    * @param input      input signal that contains decode table input
+    * @param truthTable [[TruthTable]] to decode user input.
+    * @return decode table output.
+    */
+  def apply(input: UInt, truthTable: TruthTable): UInt = {
+    def qmcFallBack(input: UInt, truthTable: TruthTable) = {
+      """fall back to QMC.
+        |Quine-McCluskey is a NP complete algorithm, may run forever or run out of memory in large decode tables.
+        |To get rid of this warning, please use `decoder.qmc` directly, or add espresso to your PATH.
+        |""".stripMargin
+      qmc(input, truthTable)
+    }
+
+    try espresso(input, truthTable) catch {
+      case EspressoNotFoundException =>
+        logger.error(s"espresso is not found in your PATH:\n${sys.env("PATH").split(":").mkString("\n")}".stripMargin)
+        qmcFallBack(input, truthTable)
+      case e: java.io.IOException =>
+        logger.error(s"espresso failed to run with ${e.getMessage}")
+        qmcFallBack(input, truthTable)
+    }
+  }
+}
diff --git a/src/main/scala/chisel3/util/experimental/getAnnotations.scala b/src/main/scala/chisel3/util/experimental/getAnnotations.scala
new file mode 100644
index 00000000..dc9b75ee
--- /dev/null
+++ b/src/main/scala/chisel3/util/experimental/getAnnotations.scala
@@ -0,0 +1,9 @@
+package chisel3.util.experimental
+
+import chisel3.internal.Builder
+import firrtl.AnnotationSeq
+
+object getAnnotations {
+  /** Returns the global Annotations */
+  def apply(): AnnotationSeq = Builder.annotationSeq
+}
diff --git a/src/main/scala/chisel3/util/pla.scala b/src/main/scala/chisel3/util/pla.scala
new file mode 100644
index 00000000..c57ca962
--- /dev/null
+++ b/src/main/scala/chisel3/util/pla.scala
@@ -0,0 +1,132 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package chisel3.util
+
+import chisel3._
+
+object pla {
+
+  /** Construct a [[https://en.wikipedia.org/wiki/Programmable_logic_array]] from specified table.
+    *
+    * Each position in the input matrix corresponds to an input variable where
+    * `0` implies the corresponding input literal appears complemented in the product term.
+    * `1` implies the input literal appears uncomplemented in the product term
+    * `?` implies the input literal does not appear in the product term.
+    *
+    * For each output
+    * a `1` means this product term makes the function value to `1`
+    * and a `0` or `?` means this product term make the function value to `0`
+    *
+    * @note There is one special case which we call it `? -> 1`. In this scenario, for some of the output functions (bits),
+    * all input terms that make this function value to `1` is purely composed by `?`. In a real pla, this will result in
+    * no connection to the gates in the AND Plane (verilog `z` on gate inputs), which in turn makes the outputs of the
+    * AND Plane undetermined (verilog `x` on outputs). This is not desired behavior in most cases, for example the
+    * minimization result of following truth table:
+    * 0 -> 1
+    * 1 -> 1
+    * which is:
+    * ? -> 1
+    * actually means something other than a verilog `x`. To ease the generation of minimized truth tables, this pla
+    * generation api will hard wire outputs to a `1` on this special case.
+    * This behavior is formally described as: if product terms that make one function value to `1` is solely consisted
+    * of don't-cares (`?`s), then this function is implemented as a constant `1`.
+    *
+    * @param table A [[Seq]] of inputs -> outputs mapping
+    * @param invert A [[BitPat]] specify which bit of the output should be inverted. `1` means the correspond position
+    *               of the output should be inverted in the PLA, a `0` or a `?` means direct output from the OR matrix.
+    * @return the (input, output) [[Wire]] of [[UInt]] of the constructed pla.
+    * {{{
+    *   // A 1-of-8 decoder (like the 74xx138) can be constructed as follow
+    *   val (inputs, outputs) = pla(Seq(
+    *     (BitPat("b000"), BitPat("b00000001")),
+    *     (BitPat("b001"), BitPat("b00000010")),
+    *     (BitPat("b010"), BitPat("b00000100")),
+    *     (BitPat("b011"), BitPat("b00001000")),
+    *     (BitPat("b100"), BitPat("b00010000")),
+    *     (BitPat("b101"), BitPat("b00100000")),
+    *     (BitPat("b110"), BitPat("b01000000")),
+    *     (BitPat("b111"), BitPat("b10000000")),
+    *   ))
+    * }}}
+    */
+  def apply(table: Seq[(BitPat, BitPat)], invert: BitPat = BitPat("b0")): (UInt, UInt) = {
+    require(table.nonEmpty, "pla table must not be empty")
+
+    val (inputTerms, outputTerms) = table.unzip
+    require(
+      inputTerms.map(_.getWidth).distinct.size == 1,
+      "all `BitPat`s in the input part of specified PLA table must have the same width"
+    )
+    require(
+      outputTerms.map(_.getWidth).distinct.size == 1,
+      "all `BitPat`s in the output part of specified PLA table must have the same width"
+    )
+
+    // now all inputs / outputs have the same width
+    val numberOfInputs = inputTerms.head.getWidth
+    val numberOfOutputs = outputTerms.head.getWidth
+
+    val inverterMask = invert.value & invert.mask
+    if (inverterMask.bitCount != 0)
+      require(invert.getWidth == numberOfOutputs,
+        "non-zero inverter mask must have the same width as the output part of specified PLA table"
+      )
+
+    // input wires of the generated PLA
+    val inputs = Wire(UInt(numberOfInputs.W))
+    val invInputs = ~inputs
+
+    // output wires of the generated PLA
+    val outputs = Wire(UInt(numberOfOutputs.W))
+
+    // the AND matrix
+    // use `term -> AND line` map to reuse AND matrix output lines
+    val andMatrixOutputs: Map[String, Bool] = inputTerms.map { t =>
+      val andMatrixInput = Seq
+        .tabulate(numberOfInputs) { i =>
+          if (t.mask.testBit(i)) {
+            Some(
+              if (t.value.testBit(i)) inputs(i)
+              else invInputs(i)
+            )
+          } else {
+            None
+          }
+        }
+        .flatten
+      if (andMatrixInput.nonEmpty) t.toString -> Cat(andMatrixInput).andR() else t.toString -> true.B
+    }.toMap
+
+    // the OR matrix
+    val orMatrixOutputs: UInt = Cat(
+        Seq
+          .tabulate(numberOfOutputs) { i =>
+            val andMatrixLines = table
+              // OR matrix composed by input terms which makes this output bit a `1`
+              .filter {
+                case (_, or) => or.mask.testBit(i) && or.value.testBit(i)
+              }.map {
+                case (inputTerm, _) =>
+                  andMatrixOutputs(inputTerm.toString)
+              }
+            if (andMatrixLines.isEmpty) false.B
+            else Cat(andMatrixLines).orR()
+          }
+          .reverse
+      )
+
+    // the INV matrix, useful for decoders
+    val invMatrixOutputs: UInt = Cat(
+      Seq
+        .tabulate(numberOfOutputs) { i =>
+          if (inverterMask.testBit(i)) ~orMatrixOutputs(i)
+          else                          orMatrixOutputs(i)
+        }
+        .reverse
+    )
+
+    outputs := invMatrixOutputs
+
+    (inputs, outputs)
+  }
+}