Merge branch 'master' into tobits-deprecation

28 files changed, 2030 insertions, 0 deletions

diff --git a/src/main/scala/chisel3/Driver.scala b/src/main/scala/chisel3/Driver.scala
new file mode 100644
index 00000000..5e0a3a0f
--- /dev/null
+++ b/src/main/scala/chisel3/Driver.scala
@@ -0,0 +1,135 @@
+// See LICENSE for license details.
+
+package chisel3
+
+import scala.sys.process._
+import java.io._
+
+import internal._
+import internal.firrtl._
+
+trait BackendCompilationUtilities {
+  /** Create a temporary directory with the prefix name. Exists here because it doesn't in Java 6.
+    */
+  def createTempDirectory(prefix: String): File = {
+    val temp = File.createTempFile(prefix, "")
+    if (!temp.delete()) {
+      throw new IOException(s"Unable to delete temp file '$temp'")
+    }
+    if (!temp.mkdir()) {
+      throw new IOException(s"Unable to create temp directory '$temp'")
+    }
+    temp
+  }
+
+  def makeHarness(template: String => String, post: String)(f: File): File = {
+    val prefix = f.toString.split("/").last
+    val vf = new File(f.toString + post)
+    val w = new FileWriter(vf)
+    w.write(template(prefix))
+    w.close()
+    vf
+  }
+
+  def firrtlToVerilog(prefix: String, dir: File): ProcessBuilder = {
+    Process(
+      Seq("firrtl",
+          "-i", s"$prefix.fir",
+          "-o", s"$prefix.v",
+          "-X", "verilog"),
+      dir)
+  }
+
+  /** Generates a Verilator invocation to convert Verilog sources to C++
+    * simulation sources.
+    *
+    * The Verilator prefix will be V$dutFile, and running this will generate
+    * C++ sources and headers as well as a makefile to compile them.
+    *
+    * @param dutFile name of the DUT .v without the .v extension
+    * @param topModule of the top-level module in the design
+    * @param dir output directory
+    * @param vSources list of additional Verilog sources to compile
+    * @param cppHarness C++ testharness to compile/link against
+    */
+  def verilogToCpp(
+      dutFile: String,
+      topModule: String,
+      dir: File,
+      vSources: Seq[File],
+      cppHarness: File
+                  ): ProcessBuilder = {
+    val command = Seq("verilator",
+      "--cc", s"$dutFile.v") ++
+      vSources.map(file => Seq("-v", file.toString)).flatten ++
+      Seq("--assert",
+        "-Wno-fatal",
+        "-Wno-WIDTH",
+        "-Wno-STMTDLY",
+        "--trace",
+        "-O2",
+        "--top-module", topModule,
+        "+define+TOP_TYPE=V" + dutFile,
+        s"+define+PRINTF_COND=!$topModule.reset",
+        s"+define+STOP_COND=!$topModule.reset",
+        "-CFLAGS",
+        s"""-Wno-undefined-bool-conversion -O2 -DTOP_TYPE=V$dutFile -include V$dutFile.h""",
+        "-Mdir", dir.toString,
+        "--exe", cppHarness.toString)
+    System.out.println(s"${command.mkString(" ")}") // scalastyle:ignore regex
+    command
+  }
+
+  def cppToExe(prefix: String, dir: File): ProcessBuilder =
+    Seq("make", "-C", dir.toString, "-j", "-f", s"V${prefix}.mk", s"V${prefix}")
+
+  def executeExpectingFailure(
+      prefix: String,
+      dir: File,
+      assertionMsg: String = "Assertion failed"): Boolean = {
+    var triggered = false
+    val e = Process(s"./V${prefix}", dir) !
+      ProcessLogger(line => {
+        triggered = triggered || line.contains(assertionMsg)
+        System.out.println(line) // scalastyle:ignore regex
+      })
+    triggered
+  }
+
+  def executeExpectingSuccess(prefix: String, dir: File): Boolean = {
+    !executeExpectingFailure(prefix, dir)
+  }
+}
+
+object Driver extends BackendCompilationUtilities {
+
+  /** Elaborates the Module specified in the gen function into a Circuit
+    *
+    *  @param gen a function that creates a Module hierarchy
+    *  @return the resulting Chisel IR in the form of a Circuit (TODO: Should be FIRRTL IR)
+    */
+  def elaborate[T <: Module](gen: () => T): Circuit = Builder.build(Module(gen()))
+
+  def emit[T <: Module](gen: () => T): String = Emitter.emit(elaborate(gen))
+
+  def emit[T <: Module](ir: Circuit): String = Emitter.emit(ir)
+
+  def dumpFirrtl(ir: Circuit, optName: Option[File]): File = {
+    val f = optName.getOrElse(new File(ir.name + ".fir"))
+    val w = new FileWriter(f)
+    w.write(Emitter.emit(ir))
+    w.close()
+    f
+  }
+
+  private var target_dir: Option[String] = None
+  def parseArgs(args: Array[String]): Unit = {
+    for (i <- 0 until args.size) {
+      if (args(i) == "--targetDir") {
+        target_dir = Some(args(i + 1))
+      }
+    }
+  }
+
+  def targetDir(): String = { target_dir getOrElse new File(".").getCanonicalPath }
+}
diff --git a/src/main/scala/chisel3/compatibility.scala b/src/main/scala/chisel3/compatibility.scala
new file mode 100644
index 00000000..d13fcb06
--- /dev/null
+++ b/src/main/scala/chisel3/compatibility.scala
@@ -0,0 +1,211 @@
+// See LICENSE for license details.
+
+// Allows legacy users to continue using Chisel (capital C) package name while
+// moving to the more standard package naming convention chisel3 (lowercase c).
+
+package object Chisel {     // scalastyle:ignore package.object.name
+  implicit val defaultCompileOptions = chisel3.core.ExplicitCompileOptions.NotStrict
+  type Direction = chisel3.core.Direction
+  val INPUT = chisel3.core.Direction.Input
+  val OUTPUT = chisel3.core.Direction.Output
+  val NODIR = chisel3.core.Direction.Unspecified
+  object Flipped {
+    def apply[T<:Data](target: T): T = chisel3.core.Flipped[T](target)
+  }
+  // TODO: Possibly move the AddDirectionToData class here?
+  implicit class AddDirMethodToData[T<:Data](val target: T) extends AnyVal {
+    def dir: Direction = {
+      target match {
+        case e: Element => e.dir
+        case _ => chisel3.core.Direction.Unspecified
+      }
+    }
+  }
+
+  type ChiselException = chisel3.internal.ChiselException
+
+  type Data = chisel3.core.Data
+  val Wire = chisel3.core.Wire
+  val Clock = chisel3.core.Clock
+  type Clock = chisel3.core.Clock
+
+  type Aggregate = chisel3.core.Aggregate
+  val Vec = chisel3.core.Vec
+  type Vec[T <: Data] = chisel3.core.Vec[T]
+  type VecLike[T <: Data] = chisel3.core.VecLike[T]
+  type Bundle = chisel3.core.Bundle
+
+  val assert = chisel3.core.assert
+  val stop = chisel3.core.stop
+
+  type Element = chisel3.core.Element
+  type Bits = chisel3.core.Bits
+  val Bits = chisel3.core.Bits
+  type Num[T <: Data] = chisel3.core.Num[T]
+  type UInt = chisel3.core.UInt
+  val UInt = chisel3.core.UInt
+  type SInt = chisel3.core.SInt
+  val SInt = chisel3.core.SInt
+  type Bool = chisel3.core.Bool
+  val Bool = chisel3.core.Bool
+  val Mux = chisel3.core.Mux
+
+  type BlackBox = chisel3.core.BlackBox
+
+  val Mem = chisel3.core.Mem
+  type MemBase[T <: Data] = chisel3.core.MemBase[T]
+  type Mem[T <: Data] = chisel3.core.Mem[T]
+  val SeqMem = chisel3.core.SeqMem
+  type SeqMem[T <: Data] = chisel3.core.SeqMem[T]
+
+  val Module = chisel3.core.Module
+  type Module = chisel3.core.Module
+
+  val printf = chisel3.core.printf
+
+  val Reg = chisel3.core.Reg
+
+  val when = chisel3.core.when
+  type WhenContext = chisel3.core.WhenContext
+
+  import chisel3.internal.firrtl.Width
+  /**
+  * These implicit classes allow one to convert scala.Int|scala.BigInt to
+  * Chisel.UInt|Chisel.SInt by calling .asUInt|.asSInt on them, respectively.
+  * The versions .asUInt(width)|.asSInt(width) are also available to explicitly
+  * mark a width for the new literal.
+  *
+  * Also provides .asBool to scala.Boolean and .asUInt to String
+  *
+  * Note that, for stylistic reasons, one should avoid extracting immediately
+  * after this call using apply, ie. 0.asUInt(1)(0) due to potential for
+  * confusion (the 1 is a bit length and the 0 is a bit extraction position).
+  * Prefer storing the result and then extracting from it.
+  */
+  implicit class fromIntToLiteral(val x: Int) extends AnyVal {
+    def U: UInt = UInt(BigInt(x), Width())    // scalastyle:ignore method.name
+    def S: SInt = SInt(BigInt(x), Width())    // scalastyle:ignore method.name
+
+    def asUInt(): UInt = UInt(x, Width())
+    def asSInt(): SInt = SInt(x, Width())
+    def asUInt(width: Int): UInt = UInt(x, width)
+    def asSInt(width: Int): SInt = SInt(x, width)
+  }
+
+  implicit class fromBigIntToLiteral(val x: BigInt) extends AnyVal {
+    def U: UInt = UInt(x, Width())       // scalastyle:ignore method.name
+    def S: SInt = SInt(x, Width())       // scalastyle:ignore method.name
+
+    def asUInt(): UInt = UInt(x, Width())
+    def asSInt(): SInt = SInt(x, Width())
+    def asUInt(width: Int): UInt = UInt(x, width)
+    def asSInt(width: Int): SInt = SInt(x, width)
+  }
+  implicit class fromStringToLiteral(val x: String) extends AnyVal {
+    def U: UInt = UInt(x)       // scalastyle:ignore method.name
+  }
+  implicit class fromBooleanToLiteral(val x: Boolean) extends AnyVal {
+    def B: Bool = Bool(x)       // scalastyle:ignore method.name
+  }
+
+
+  type BackendCompilationUtilities = chisel3.BackendCompilationUtilities
+  val Driver = chisel3.Driver
+  val ImplicitConversions = chisel3.util.ImplicitConversions
+  val chiselMain = chisel3.compatibility.chiselMain
+  val throwException = chisel3.compatibility.throwException
+  val debug = chisel3.compatibility.debug
+
+  object testers {    // scalastyle:ignore object.name
+    type BasicTester = chisel3.testers.BasicTester
+    val TesterDriver = chisel3.testers.TesterDriver
+  }
+
+
+  val log2Up = chisel3.util.log2Up
+  val log2Ceil = chisel3.util.log2Ceil
+  val log2Down = chisel3.util.log2Down
+  val log2Floor = chisel3.util.log2Floor
+  val isPow2 = chisel3.util.isPow2
+
+  val BitPat = chisel3.util.BitPat
+  type BitPat = chisel3.util.BitPat
+
+  type ArbiterIO[T <: Data] = chisel3.util.ArbiterIO[T]
+  type LockingArbiterLike[T <: Data] = chisel3.util.LockingArbiterLike[T]
+  type LockingRRArbiter[T <: Data] = chisel3.util.LockingRRArbiter[T]
+  type LockingArbiter[T <: Data] = chisel3.util.LockingArbiter[T]
+  type RRArbiter[T <: Data] = chisel3.util.RRArbiter[T]
+  type Arbiter[T <: Data] = chisel3.util.Arbiter[T]
+
+  val FillInterleaved = chisel3.util.FillInterleaved
+  val PopCount = chisel3.util.PopCount
+  val Fill = chisel3.util.Fill
+  val Reverse = chisel3.util.Reverse
+
+  val Cat = chisel3.util.Cat
+
+  val Log2 = chisel3.util.Log2
+
+  val unless = chisel3.util.unless
+  type SwitchContext[T <: Bits] = chisel3.util.SwitchContext[T]
+  val is = chisel3.util.is
+  val switch = chisel3.util.switch
+
+  type Counter = chisel3.util.Counter
+  val Counter = chisel3.util.Counter
+
+  type DecoupledIO[+T <: Data] = chisel3.util.DecoupledIO[T]
+  val DecoupledIO = chisel3.util.Decoupled
+  val Decoupled = chisel3.util.Decoupled
+  class EnqIO[+T <: Data](gen: T) extends DecoupledIO(gen) {
+    def init(): Unit = {
+      this.noenq()
+    }
+    override def cloneType: this.type = EnqIO(gen).asInstanceOf[this.type]
+  }
+  class DeqIO[+T <: Data](gen: T) extends DecoupledIO(gen) {
+    chisel3.core.Binding.bind(this, chisel3.core.FlippedBinder, "Error: Cannot flip ")
+    def init(): Unit = {
+      this.nodeq()
+    }
+    override def cloneType: this.type = DeqIO(gen).asInstanceOf[this.type]
+  }
+  object EnqIO {
+    def apply[T<:Data](gen: T): DecoupledIO[T] = DecoupledIO(gen)
+  }
+  object DeqIO {
+    def apply[T<:Data](gen: T): DecoupledIO[T] = Flipped(DecoupledIO(gen))
+  }
+  type QueueIO[T <: Data] = chisel3.util.QueueIO[T]
+  type Queue[T <: Data] = chisel3.util.Queue[T]
+  val Queue = chisel3.util.Queue
+
+  val Enum = chisel3.util.Enum
+
+  val LFSR16 = chisel3.util.LFSR16
+
+  val ListLookup = chisel3.util.ListLookup
+  val Lookup = chisel3.util.Lookup
+
+  val Mux1H = chisel3.util.Mux1H
+  val PriorityMux = chisel3.util.PriorityMux
+  val MuxLookup = chisel3.util.MuxLookup
+  val MuxCase = chisel3.util.MuxCase
+
+  val OHToUInt = chisel3.util.OHToUInt
+  val PriorityEncoder = chisel3.util.PriorityEncoder
+  val UIntToOH = chisel3.util.UIntToOH
+  val PriorityEncoderOH = chisel3.util.PriorityEncoderOH
+
+  val RegNext = chisel3.util.RegNext
+  val RegInit = chisel3.util.RegInit
+  val RegEnable = chisel3.util.RegEnable
+  val ShiftRegister = chisel3.util.ShiftRegister
+
+  type ValidIO[+T <: Data] = chisel3.util.Valid[T]
+  val Valid = chisel3.util.Valid
+  val Pipe = chisel3.util.Pipe
+  type Pipe[T <: Data] = chisel3.util.Pipe[T]
+
+}
diff --git a/src/main/scala/chisel3/compatibility/Main.scala b/src/main/scala/chisel3/compatibility/Main.scala
new file mode 100644
index 00000000..a41599a3
--- /dev/null
+++ b/src/main/scala/chisel3/compatibility/Main.scala
@@ -0,0 +1,19 @@
+// See LICENSE for license details.
+
+package chisel3.compatibility
+
+import java.io.File
+
+import chisel3._
+
+@deprecated("chiselMain doesn't exist in Chisel3", "3.0") object chiselMain {
+  def apply[T <: Module](args: Array[String], gen: () => T): Unit =
+    Predef.assert(false, "No more chiselMain in Chisel3")
+
+  def run[T <: Module] (args: Array[String], gen: () => T): Unit = {
+    val circuit = Driver.elaborate(gen)
+    Driver.parseArgs(args)
+    val output_file = new File(Driver.targetDir + "/" + circuit.name + ".fir")
+    Driver.dumpFirrtl(circuit, Option(output_file))
+  }
+}
diff --git a/src/main/scala/chisel3/compatibility/debug.scala b/src/main/scala/chisel3/compatibility/debug.scala
new file mode 100644
index 00000000..d9f6e4b0
--- /dev/null
+++ b/src/main/scala/chisel3/compatibility/debug.scala
@@ -0,0 +1,10 @@
+// See LICENSE for license details.
+
+package chisel3.compatibility
+
+import chisel3.core._
+
+@deprecated("debug doesn't do anything in Chisel3 as no pruning happens in the frontend", "chisel3")
+object debug {  // scalastyle:ignore object.name
+  def apply (arg: Data): Data = arg
+}
diff --git a/src/main/scala/chisel3/compatibility/throwException.scala b/src/main/scala/chisel3/compatibility/throwException.scala
new file mode 100644
index 00000000..3e8b33e6
--- /dev/null
+++ b/src/main/scala/chisel3/compatibility/throwException.scala
@@ -0,0 +1,14 @@
+// See LICENSE for license details.
+
+package chisel3.compatibility
+
+import chisel3._
+
+@deprecated("throwException doesn't exist in Chisel3", "3.0.0")
+@throws(classOf[Exception])
+object throwException {
+  def apply(s: String, t: Throwable = null) = {
+    val xcpt = new Exception(s, t)
+    throw xcpt
+  }
+}
diff --git a/src/main/scala/chisel3/internal/firrtl/Emitter.scala b/src/main/scala/chisel3/internal/firrtl/Emitter.scala
new file mode 100644
index 00000000..f1908089
--- /dev/null
+++ b/src/main/scala/chisel3/internal/firrtl/Emitter.scala
@@ -0,0 +1,108 @@
+// See LICENSE for license details.
+
+package chisel3.internal.firrtl
+import chisel3._
+import chisel3.internal.sourceinfo.{NoSourceInfo, SourceLine}
+
+private[chisel3] object Emitter {
+  def emit(circuit: Circuit): String = new Emitter(circuit).toString
+}
+
+private class Emitter(circuit: Circuit) {
+  override def toString: String = res.toString
+
+  private def emitPort(e: Port): String =
+    s"${e.dir} ${e.id.getRef.name} : ${e.id.toType}"
+  private def emit(e: Command, ctx: Component): String = {
+    val firrtlLine = e match {
+      case e: DefPrim[_] => s"node ${e.name} = ${e.op.name}(${e.args.map(_.fullName(ctx)).mkString(", ")})"
+      case e: DefWire => s"wire ${e.name} : ${e.id.toType}"
+      case e: DefReg => s"reg ${e.name} : ${e.id.toType}, ${e.clock.fullName(ctx)}"
+      case e: DefRegInit => s"reg ${e.name} : ${e.id.toType}, ${e.clock.fullName(ctx)} with : (reset => (${e.reset.fullName(ctx)}, ${e.init.fullName(ctx)}))"
+      case e: DefMemory => s"cmem ${e.name} : ${e.t.toType}[${e.size}]"
+      case e: DefSeqMemory => s"smem ${e.name} : ${e.t.toType}[${e.size}]"
+      case e: DefMemPort[_] => s"${e.dir} mport ${e.name} = ${e.source.fullName(ctx)}[${e.index.fullName(ctx)}], ${e.clock.fullName(ctx)}"
+      case e: Connect => s"${e.loc.fullName(ctx)} <= ${e.exp.fullName(ctx)}"
+      case e: BulkConnect => s"${e.loc1.fullName(ctx)} <- ${e.loc2.fullName(ctx)}"
+      case e: Stop => s"stop(${e.clock.fullName(ctx)}, UInt<1>(1), ${e.ret})"
+      case e: Printf =>
+        val (fmt, args) = e.pable.unpack(ctx)
+        val printfArgs = Seq(e.clock.fullName(ctx), "UInt<1>(1)",
+          "\"" + printf.format(fmt) + "\"") ++ args
+        printfArgs mkString ("printf(", ", ", ")")
+      case e: DefInvalid => s"${e.arg.fullName(ctx)} is invalid"
+      case e: DefInstance => s"inst ${e.name} of ${e.id.modName}"
+      case w: WhenBegin =>
+        indent()
+        s"when ${w.pred.fullName(ctx)} :"
+      case _: WhenEnd =>
+        unindent()
+        s"skip"
+    }
+    e.sourceInfo match {
+      case SourceLine(filename, line, col) => s"${firrtlLine} @[${filename} ${line}:${col}] "
+      case _: NoSourceInfo => firrtlLine
+    }
+  }
+
+  // Map of Module FIRRTL definition to FIRRTL name, if it has been emitted already.
+  private val defnMap = collection.mutable.HashMap[(String, String), Component]()
+
+  /** Generates the FIRRTL module declaration.
+    */
+  private def moduleDecl(m: Component): String = m.id match {
+    case _: BlackBox => newline + s"extmodule ${m.name} : "
+    case _: Module => newline + s"module ${m.name} : "
+  }
+
+  /** Generates the FIRRTL module definition.
+    */
+  private def moduleDefn(m: Component): String = {
+    val body = new StringBuilder
+    withIndent {
+      for (p <- m.ports)
+        body ++= newline + emitPort(p)
+      body ++= newline
+
+      m.id match {
+        case _: BlackBox =>
+          // TODO: BlackBoxes should be empty, but funkiness in Module() means
+          // it's not for now. Eventually, this should assert out.
+        case _: Module => for (cmd <- m.commands) {
+          body ++= newline + emit(cmd, m)
+        }
+      }
+      body ++= newline
+    }
+    body.toString()
+  }
+
+  /** Returns the FIRRTL declaration and body of a module, or nothing if it's a
+    * duplicate of something already emitted (on the basis of simple string
+    * matching).
+    */
+  private def emit(m: Component): String = {
+    // Generate the body.
+    val defn = moduleDefn(m)
+
+    defnMap get (m.id.desiredName, defn) match {
+      case Some(duplicate) =>
+        m.id setModName duplicate.name
+        ""
+      case None =>
+        defnMap((m.id.desiredName, defn)) = m
+        m.id setModName m.name
+        moduleDecl(m) + defn
+    }
+  }
+
+  private var indentLevel = 0
+  private def newline = "\n" + ("  " * indentLevel)
+  private def indent(): Unit = indentLevel += 1
+  private def unindent() { require(indentLevel > 0); indentLevel -= 1 }
+  private def withIndent(f: => Unit) { indent(); f; unindent() }
+
+  private val res = new StringBuilder(s"circuit ${circuit.name} : ")
+  withIndent { circuit.components.foreach(c => res ++= emit(c)) }
+  res ++= newline
+}
diff --git a/src/main/scala/chisel3/package.scala b/src/main/scala/chisel3/package.scala
new file mode 100644
index 00000000..17ddd55a
--- /dev/null
+++ b/src/main/scala/chisel3/package.scala
@@ -0,0 +1,197 @@
+// See LICENSE for license details.
+
+package object chisel3 {    // scalastyle:ignore package.object.name
+  import scala.language.experimental.macros
+
+  import internal.firrtl.Width
+  import internal.sourceinfo.{SourceInfo, SourceInfoTransform}
+  import util.BitPat
+
+  import chisel3.core.{Binding, FlippedBinder}
+  import chisel3.util._
+  import chisel3.internal.firrtl.Port
+
+  type Direction = chisel3.core.Direction
+  val Input   = chisel3.core.Input
+  val Output  = chisel3.core.Output
+  val Flipped = chisel3.core.Flipped
+
+  type Data = chisel3.core.Data
+  val Wire = chisel3.core.Wire
+  val Clock = chisel3.core.Clock
+  type Clock = chisel3.core.Clock
+
+  type Aggregate = chisel3.core.Aggregate
+  val Vec = chisel3.core.Vec
+  type Vec[T <: Data] = chisel3.core.Vec[T]
+  type VecLike[T <: Data] = chisel3.core.VecLike[T]
+  type Bundle = chisel3.core.Bundle
+
+  val assert = chisel3.core.assert
+
+  type Element = chisel3.core.Element
+  type Bits = chisel3.core.Bits
+  val Bits = chisel3.core.Bits
+  type Num[T <: Data] = chisel3.core.Num[T]
+  type UInt = chisel3.core.UInt
+  val UInt = chisel3.core.UInt
+  type SInt = chisel3.core.SInt
+  val SInt = chisel3.core.SInt
+  type Bool = chisel3.core.Bool
+  val Bool = chisel3.core.Bool
+  val Mux = chisel3.core.Mux
+
+  type BlackBox = chisel3.core.BlackBox
+
+  val Mem = chisel3.core.Mem
+  type MemBase[T <: Data] = chisel3.core.MemBase[T]
+  type Mem[T <: Data] = chisel3.core.Mem[T]
+  val SeqMem = chisel3.core.SeqMem
+  type SeqMem[T <: Data] = chisel3.core.SeqMem[T]
+
+  val Module = chisel3.core.Module
+  type Module = chisel3.core.Module
+
+  val printf = chisel3.core.printf
+
+  val Reg = chisel3.core.Reg
+
+  val when = chisel3.core.when
+  type WhenContext = chisel3.core.WhenContext
+
+  type Printable = chisel3.core.Printable
+  val Printable = chisel3.core.Printable
+  type Printables = chisel3.core.Printables
+  val Printables = chisel3.core.Printables
+  type PString = chisel3.core.PString
+  val PString = chisel3.core.PString
+  type FirrtlFormat = chisel3.core.FirrtlFormat
+  val FirrtlFormat = chisel3.core.FirrtlFormat
+  type Decimal = chisel3.core.Decimal
+  val Decimal = chisel3.core.Decimal
+  type Hexadecimal = chisel3.core.Hexadecimal
+  val Hexadecimal = chisel3.core.Hexadecimal
+  type Binary = chisel3.core.Binary
+  val Binary = chisel3.core.Binary
+  type Character = chisel3.core.Character
+  val Character = chisel3.core.Character
+  type Name = chisel3.core.Name
+  val Name = chisel3.core.Name
+  type FullName = chisel3.core.FullName
+  val FullName = chisel3.core.FullName
+  val Percent = chisel3.core.Percent
+
+  /** Implicit for custom Printable string interpolator */
+  implicit class PrintableHelper(val sc: StringContext) extends AnyVal {
+    /** Custom string interpolator for generating Printables: p"..."
+      * Will call .toString on any non-Printable arguments (mimicking s"...")
+      */
+    def p(args: Any*): Printable = {
+      sc.checkLengths(args) // Enforce sc.parts.size == pargs.size + 1
+      val pargs: Seq[Option[Printable]] = args map {
+        case p: Printable => Some(p)
+        case d: Data => Some(d.toPrintable)
+        case any => for {
+          v <- Option(any) // Handle null inputs
+          str = v.toString
+          if !str.isEmpty // Handle empty Strings
+        } yield PString(str)
+      }
+      val parts = sc.parts map StringContext.treatEscapes
+      // Zip sc.parts and pargs together ito flat Seq
+      // eg. Seq(sc.parts(0), pargs(0), sc.parts(1), pargs(1), ...)
+      val seq = for { // append None because sc.parts.size == pargs.size + 1
+        (literal, arg) <- parts zip (pargs :+ None)
+        optPable <- Seq(Some(PString(literal)), arg)
+        pable <- optPable // Remove Option[_]
+      } yield pable
+      Printables(seq)
+    }
+  }
+
+  implicit def string2Printable(str: String): Printable = PString(str)
+
+  /**
+  * These implicit classes allow one to convert scala.Int|scala.BigInt to
+  * Chisel.UInt|Chisel.SInt by calling .asUInt|.asSInt on them, respectively.
+  * The versions .asUInt(width)|.asSInt(width) are also available to explicitly
+  * mark a width for the new literal.
+  *
+  * Also provides .asBool to scala.Boolean and .asUInt to String
+  *
+  * Note that, for stylistic reasons, one should avoid extracting immediately
+  * after this call using apply, ie. 0.asUInt(1)(0) due to potential for
+  * confusion (the 1 is a bit length and the 0 is a bit extraction position).
+  * Prefer storing the result and then extracting from it.
+  */
+  implicit class fromIntToLiteral(val x: Int) extends AnyVal {
+    def U: UInt = UInt(BigInt(x), Width())    // scalastyle:ignore method.name
+    def S: SInt = SInt(BigInt(x), Width())    // scalastyle:ignore method.name
+
+    def asUInt(): UInt = UInt(x, Width())
+    def asSInt(): SInt = SInt(x, Width())
+    def asUInt(width: Int): UInt = UInt(x, width)
+    def asSInt(width: Int): SInt = SInt(x, width)
+  }
+
+  implicit class fromBigIntToLiteral(val x: BigInt) extends AnyVal {
+    def U: UInt = UInt(x, Width())    // scalastyle:ignore method.name
+    def S: SInt = SInt(x, Width())    // scalastyle:ignore method.name
+
+    def asUInt(): UInt = UInt(x, Width())
+    def asSInt(): SInt = SInt(x, Width())
+    def asUInt(width: Int): UInt = UInt(x, width)
+    def asSInt(width: Int): SInt = SInt(x, width)
+  }
+  implicit class fromStringToLiteral(val x: String) extends AnyVal {
+    def U: UInt = UInt(x)    // scalastyle:ignore method.name
+  }
+  implicit class fromBooleanToLiteral(val x: Boolean) extends AnyVal {
+    def B: Bool = Bool(x)    // scalastyle:ignore method.name
+  }
+
+  implicit class fromUIntToBitPatComparable(val x: UInt) extends AnyVal {
+    final def === (that: BitPat): Bool = macro SourceInfoTransform.thatArg
+    final def != (that: BitPat): Bool = macro SourceInfoTransform.thatArg
+    final def =/= (that: BitPat): Bool = macro SourceInfoTransform.thatArg
+
+    def do_=== (that: BitPat)(implicit sourceInfo: SourceInfo): Bool = that === x    // scalastyle:ignore method.name
+    def do_!= (that: BitPat)(implicit sourceInfo: SourceInfo): Bool = that != x      // scalastyle:ignore method.name
+    def do_=/= (that: BitPat)(implicit sourceInfo: SourceInfo): Bool = that =/= x    // scalastyle:ignore method.name
+  }
+
+  // Compatibility with existing code.
+  val INPUT = chisel3.core.Direction.Input
+  val OUTPUT = chisel3.core.Direction.Output
+  val NODIR = chisel3.core.Direction.Unspecified
+  type ChiselException = chisel3.internal.ChiselException
+
+  class EnqIO[+T <: Data](gen: T) extends DecoupledIO(gen) {
+    def init(): Unit = {
+      this.noenq()
+    }
+    override def cloneType: this.type = EnqIO(gen).asInstanceOf[this.type]
+  }
+  class DeqIO[+T <: Data](gen: T) extends DecoupledIO(gen) {
+    val Data = chisel3.core.Data
+    Data.setFirrtlDirection(this, Data.getFirrtlDirection(this).flip)
+    Binding.bind(this, FlippedBinder, "Error: Cannot flip ")
+    def init(): Unit = {
+      this.nodeq()
+    }
+    override def cloneType: this.type = DeqIO(gen).asInstanceOf[this.type]
+  }
+  object EnqIO {
+    def apply[T<:Data](gen: T): EnqIO[T] = new EnqIO(gen)
+  }
+  object DeqIO {
+    def apply[T<:Data](gen: T): DeqIO[T] = new DeqIO(gen)
+  }
+
+  // Debugger/Tester access to internal Chisel data structures and methods.
+  def getDataElements(a: Aggregate): Seq[Element] = {
+    a.allElements
+  }
+  def getModulePorts(m: Module): Seq[Port] = m.getPorts
+  def getFirrtlDirection(d: Data): Direction = chisel3.core.Data.getFirrtlDirection(d)
+}
diff --git a/src/main/scala/chisel3/testers/BasicTester.scala b/src/main/scala/chisel3/testers/BasicTester.scala
new file mode 100644
index 00000000..bd7d4027
--- /dev/null
+++ b/src/main/scala/chisel3/testers/BasicTester.scala
@@ -0,0 +1,39 @@
+// See LICENSE for license details.
+
+package chisel3.testers
+import chisel3._
+
+import scala.language.experimental.macros
+
+import internal._
+import internal.Builder.pushCommand
+import internal.firrtl._
+import internal.sourceinfo.SourceInfo
+//import chisel3.core.ExplicitCompileOptions.NotStrict
+
+class BasicTester extends Module() {
+  // The testbench has no IOs, rather it should communicate using printf, assert, and stop.
+  val io = IO(new Bundle())
+
+  def popCount(n: Long): Int = n.toBinaryString.count(_=='1')
+
+  /** Ends the test reporting success.
+    *
+    * Does not fire when in reset (defined as the encapsulating Module's
+    * reset). If your definition of reset is not the encapsulating Module's
+    * reset, you will need to gate this externally.
+    */
+  def stop()(implicit sourceInfo: SourceInfo) {
+    // TODO: rewrite this using library-style SourceInfo passing.
+    when (!reset) {
+      pushCommand(Stop(sourceInfo, Node(clock), 0))
+    }
+  }
+
+  /** The finish method provides a hook that subclasses of BasicTester can use to
+    * alter a circuit after their constructor has been called.
+    * For example, a specialized tester subclassing BasicTester could override finish in order to
+    * add flow control logic for a decoupled io port of a device under test
+    */
+  def finish(): Unit = {}
+}
diff --git a/src/main/scala/chisel3/testers/TesterDriver.scala b/src/main/scala/chisel3/testers/TesterDriver.scala
new file mode 100644
index 00000000..586fa780
--- /dev/null
+++ b/src/main/scala/chisel3/testers/TesterDriver.scala
@@ -0,0 +1,69 @@
+// See LICENSE for license details.
+
+package chisel3.testers
+
+import chisel3._
+import scala.io.Source
+import scala.sys.process._
+import java.io._
+
+object TesterDriver extends BackendCompilationUtilities {
+  /** Copy the contents of a resource to a destination file.
+    */
+  def copyResourceToFile(name: String, file: File) {
+    val in = getClass().getResourceAsStream(name)
+    if (in == null) {
+      throw new FileNotFoundException(s"Resource '$name'")
+    }
+    val out = new FileOutputStream(file)
+    Iterator.continually(in.read).takeWhile(-1 !=).foreach(out.write)
+    out.close()
+  }
+
+  /** For use with modules that should successfully be elaborated by the
+    * frontend, and which can be turned into executables with assertions. */
+  def execute(t: () => BasicTester, additionalVResources: Seq[String] = Seq()): Boolean = {
+    // Invoke the chisel compiler to get the circuit's IR
+    val circuit = Driver.elaborate(finishWrapper(t))
+
+    // Set up a bunch of file handlers based on a random temp filename,
+    // plus the quirks of Verilator's naming conventions
+    val target = circuit.name
+
+    val path = createTempDirectory(target)
+    val fname = new File(path, target)
+
+    // For now, dump the IR out to a file
+    Driver.dumpFirrtl(circuit, Some(new File(fname.toString + ".fir")))
+
+    // Copy CPP harness and other Verilog sources from resources into files
+    val cppHarness =  new File(path, "top.cpp")
+    copyResourceToFile("/top.cpp", cppHarness)
+    val additionalVFiles = additionalVResources.map((name: String) => {
+      val mangledResourceName = name.replace("/", "_")
+      val out = new File(path, mangledResourceName)
+      copyResourceToFile(name, out)
+      out
+    })
+
+    // Use sys.Process to invoke a bunch of backend stuff, then run the resulting exe
+    if ((firrtlToVerilog(target, path) #&&
+        verilogToCpp(target, target, path, additionalVFiles, cppHarness) #&&
+        cppToExe(target, path)).! == 0) {
+      executeExpectingSuccess(target, path)
+    } else {
+      false
+    }
+  }
+  /**
+    * Calls the finish method of an BasicTester or a class that extends it.
+    * The finish method is a hook for code that augments the circuit built in the constructor.
+    */
+  def finishWrapper(test: () => BasicTester): () => BasicTester = {
+    () => {
+      val tester = test()
+      tester.finish()
+      tester
+    }
+  }
+}
diff --git a/src/main/scala/chisel3/util/Arbiter.scala b/src/main/scala/chisel3/util/Arbiter.scala
new file mode 100644
index 00000000..89bb644a
--- /dev/null
+++ b/src/main/scala/chisel3/util/Arbiter.scala
@@ -0,0 +1,128 @@
+// See LICENSE for license details.
+
+/** Arbiters in all shapes and sizes.
+  */
+
+package chisel3.util
+
+import chisel3._
+// TODO: remove this once we have CompileOptions threaded through the macro system.
+import chisel3.core.ExplicitCompileOptions.NotStrict
+
+/** IO bundle definition for an Arbiter, which takes some number of ready-valid inputs and outputs
+  * (selects) at most one.
+  *
+  * @param gen data type
+  * @param n number of inputs
+  */
+class ArbiterIO[T <: Data](gen: T, n: Int) extends Bundle {
+  val in  = Flipped(Vec(n, Decoupled(gen)))
+  val out = Decoupled(gen)
+  val chosen = Output(UInt.width(log2Up(n)))
+}
+
+/** Arbiter Control determining which producer has access
+  */
+private object ArbiterCtrl {
+  def apply(request: Seq[Bool]): Seq[Bool] = request.length match {
+    case 0 => Seq()
+    case 1 => Seq(Bool(true))
+    case _ => Bool(true) +: request.tail.init.scanLeft(request.head)(_ || _).map(!_)
+  }
+}
+
+abstract class LockingArbiterLike[T <: Data](gen: T, n: Int, count: Int, needsLock: Option[T => Bool]) extends Module {
+  def grant: Seq[Bool]
+  def choice: UInt
+  val io = IO(new ArbiterIO(gen, n))
+
+  io.chosen := choice
+  io.out.valid := io.in(io.chosen).valid
+  io.out.bits := io.in(io.chosen).bits
+
+  if (count > 1) {
+    val lockCount = Counter(count)
+    val lockIdx = Reg(UInt())
+    val locked = lockCount.value =/= UInt(0)
+    val wantsLock = needsLock.map(_(io.out.bits)).getOrElse(Bool(true))
+
+    when (io.out.fire() && wantsLock) {
+      lockIdx := io.chosen
+      lockCount.inc()
+    }
+
+    when (locked) { io.chosen := lockIdx }
+    for ((in, (g, i)) <- io.in zip grant.zipWithIndex)
+      in.ready := Mux(locked, lockIdx === UInt(i), g) && io.out.ready
+  } else {
+    for ((in, g) <- io.in zip grant)
+      in.ready := g && io.out.ready
+  }
+}
+
+class LockingRRArbiter[T <: Data](gen: T, n: Int, count: Int, needsLock: Option[T => Bool] = None)
+    extends LockingArbiterLike[T](gen, n, count, needsLock) {
+  lazy val lastGrant = RegEnable(io.chosen, io.out.fire())
+  lazy val grantMask = (0 until n).map(UInt(_) > lastGrant)
+  lazy val validMask = io.in zip grantMask map { case (in, g) => in.valid && g }
+
+  override def grant: Seq[Bool] = {
+    val ctrl = ArbiterCtrl((0 until n).map(i => validMask(i)) ++ io.in.map(_.valid))
+    (0 until n).map(i => ctrl(i) && grantMask(i) || ctrl(i + n))
+  }
+
+  override lazy val choice = Wire(init=UInt(n-1))
+  for (i <- n-2 to 0 by -1)
+    when (io.in(i).valid) { choice := UInt(i) }
+  for (i <- n-1 to 1 by -1)
+    when (validMask(i)) { choice := UInt(i) }
+}
+
+class LockingArbiter[T <: Data](gen: T, n: Int, count: Int, needsLock: Option[T => Bool] = None)
+    extends LockingArbiterLike[T](gen, n, count, needsLock) {
+  def grant: Seq[Bool] = ArbiterCtrl(io.in.map(_.valid))
+
+  override lazy val choice = Wire(init=UInt(n-1))
+  for (i <- n-2 to 0 by -1)
+    when (io.in(i).valid) { choice := UInt(i) }
+}
+
+/** Hardware module that is used to sequence n producers into 1 consumer.
+  * Producers are chosen in round robin order.
+  *
+  * @example {{{
+  * val arb = new RRArbiter(2, UInt())
+  * arb.io.in(0) <> producer0.io.out
+  * arb.io.in(1) <> producer1.io.out
+  * consumer.io.in <> arb.io.out
+  * }}}
+  */
+class RRArbiter[T <: Data](gen:T, n: Int) extends LockingRRArbiter[T](gen, n, 1)
+
+/** Hardware module that is used to sequence n producers into 1 consumer.
+  * Priority is given to lower producer.
+  *
+  * @example {{{
+  * val arb = Module(new Arbiter(2, UInt()))
+  * arb.io.in(0) <> producer0.io.out
+  * arb.io.in(1) <> producer1.io.out
+  * consumer.io.in <> arb.io.out
+  * }}}
+  */
+class Arbiter[T <: Data](gen: T, n: Int) extends Module {
+  val io = IO(new ArbiterIO(gen, n))
+
+  io.chosen := UInt(n-1)
+  io.out.bits := io.in(n-1).bits
+  for (i <- n-2 to 0 by -1) {
+    when (io.in(i).valid) {
+      io.chosen := UInt(i)
+      io.out.bits := io.in(i).bits
+    }
+  }
+
+  val grant = ArbiterCtrl(io.in.map(_.valid))
+  for ((in, g) <- io.in zip grant)
+    in.ready := g && io.out.ready
+  io.out.valid := !grant.last || io.in.last.valid
+}
diff --git a/src/main/scala/chisel3/util/BitPat.scala b/src/main/scala/chisel3/util/BitPat.scala
new file mode 100644
index 00000000..972010a6
--- /dev/null
+++ b/src/main/scala/chisel3/util/BitPat.scala
@@ -0,0 +1,90 @@
+// See LICENSE for license details.
+
+package chisel3.util
+
+import scala.language.experimental.macros
+
+import chisel3._
+import chisel3.internal.sourceinfo.{SourceInfo, SourceInfoTransform}
+
+object BitPat {
+  /** Parses a bit pattern string into (bits, mask, width).
+    *
+    * @return bits the literal value, with don't cares being 0
+    * @return mask the mask bits, with don't cares being 0 and cares being 1
+    * @return width the number of bits in the literal, including values and
+    * don't cares.
+    */
+  private def parse(x: String): (BigInt, BigInt, Int) = {
+    // Notes:
+    // While Verilog Xs also handle octal and hex cases, there isn't a
+    // compelling argument and no one has asked for it.
+    // 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'")
+    var bits = BigInt(0)
+    var mask = BigInt(0)
+    for (d <- x.tail) {
+      if (d != '_') {
+        require("01?".contains(d), "Literal: " + x + " contains illegal character: " + d)
+        mask = (mask << 1) + (if (d == '?') 0 else 1)
+        bits = (bits << 1) + (if (d == '1') 1 else 0)
+      }
+    }
+    (bits, mask, x.length - 1)
+  }
+
+  /** 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)
+    */
+  def apply(n: String): BitPat = {
+    val (bits, mask, width) = parse(n)
+    new BitPat(bits, mask, width)
+  }
+
+  /** Creates a [[BitPat]] of all don't cares of the specified bitwidth. */
+  def dontCare(width: Int): BitPat = BitPat("b" + ("?" * width))
+
+  @deprecated("Use BitPat.dontCare", "chisel3")
+  def DC(width: Int): BitPat = dontCare(width)  // scalastyle:ignore method.name
+
+  /** Allows BitPats to be used where a UInt is expected.
+    *
+    * @note the BitPat must not have don't care bits (will error out otherwise)
+    */
+  def bitPatToUInt(x: BitPat): UInt = {
+    require(x.mask == (BigInt(1) << x.getWidth) - 1)
+    UInt(x.value, x.getWidth)
+  }
+
+  /** Allows UInts to be used where a BitPat is expected, useful for when an
+    * interface is defined with BitPats but not all cases need the partial
+    * matching capability.
+    *
+    * @note the UInt must be a literal
+    */
+  def apply(x: UInt): BitPat = {
+    require(x.isLit)
+    val len = if (x.isWidthKnown) x.getWidth else 0
+    apply("b" + x.litValue.toString(2).reverse.padTo(len, "0").reverse.mkString)
+  }
+}
+
+// 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.
+  */
+sealed class BitPat(val value: BigInt, val mask: BigInt, width: Int) {
+  def getWidth: Int = width
+  def === (that: UInt): Bool = macro SourceInfoTransform.thatArg
+  def =/= (that: UInt): Bool = macro SourceInfoTransform.thatArg
+  def != (that: UInt): Bool = macro SourceInfoTransform.thatArg
+
+  def do_=== (that: UInt)(implicit sourceInfo: SourceInfo): Bool = value.asUInt === (that & mask.asUInt)    // scalastyle:ignore method.name
+  def do_=/= (that: UInt)(implicit sourceInfo: SourceInfo): Bool = !(this === that)    // scalastyle:ignore method.name
+  def do_!= (that: UInt)(implicit sourceInfo: SourceInfo): Bool = this =/= that        // scalastyle:ignore method.name
+}
diff --git a/src/main/scala/chisel3/util/Bitwise.scala b/src/main/scala/chisel3/util/Bitwise.scala
new file mode 100644
index 00000000..289d27b1
--- /dev/null
+++ b/src/main/scala/chisel3/util/Bitwise.scala
@@ -0,0 +1,79 @@
+// See LICENSE for license details.
+
+/** Miscellaneous circuit generators operating on bits.
+  */
+
+package chisel3.util
+
+import chisel3._
+import chisel3.core.SeqUtils
+
+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)
+
+  /** 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)
+    */
+  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.
+  */
+object PopCount
+{
+  def apply(in: Iterable[Bool]): UInt = SeqUtils.count(in.toSeq)
+  def apply(in: Bits): UInt = apply((0 until in.getWidth).map(in(_)))
+}
+
+object Fill {
+  /** Create n repetitions of x using a tree fanout topology.
+    *
+    * Output data-equivalent to x ## x ## ... ## x (n repetitions).
+    */
+  def apply(n: Int, x: UInt): UInt = {
+    n match {
+      case 0 => UInt.width(0)
+      case 1 => x
+      case _ if x.isWidthKnown && x.getWidth == 1 =>
+        Mux(x.toBool, UInt((BigInt(1) << n) - 1, n), UInt(0, n))
+      case _ if n > 1 =>
+        val p2 = Array.ofDim[UInt](log2Up(n + 1))
+        p2(0) = x
+        for (i <- 1 until p2.length)
+          p2(i) = Cat(p2(i-1), p2(i-1))
+        Cat((0 until log2Up(n + 1)).filter(i => (n & (1 << i)) != 0).map(p2(_)))
+      case _ => throw new IllegalArgumentException(s"n (=$n) must be nonnegative integer.")
+    }
+  }
+}
+
+object Reverse {
+  private def doit(in: UInt, length: Int): UInt = {
+    if (length == 1) {
+      in
+    } else if (isPow2(length) && length >= 8 && length <= 64) {
+      // This esoterica improves simulation performance
+      var res = in
+      var shift = length >> 1
+      var mask = UInt((BigInt(1) << length) - 1, length)
+      do {
+        mask = mask ^ (mask(length-shift-1,0) << shift)
+        res = ((res >> shift) & mask) | ((res(length-shift-1,0) << shift) & ~mask)
+        shift = shift >> 1
+      } while (shift > 0)
+      res
+    } else {
+      val half = (1 << log2Up(length))/2
+      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
new file mode 100644
index 00000000..ba12a7d4
--- /dev/null
+++ b/src/main/scala/chisel3/util/Cat.scala
@@ -0,0 +1,20 @@
+// See LICENSE for license details.
+
+package chisel3.util
+
+import chisel3._
+import chisel3.core.SeqUtils
+
+object Cat {
+  /** Concatenates the argument data elements, in argument order, together.
+    */
+  def apply[T <: Bits](a: T, r: T*): UInt = apply(a :: r.toList)
+
+  /** Concatenates the data elements of the input sequence, in reverse sequence order, together.
+    * The first element of the sequence forms the most significant bits, while the last element
+    * in the sequence forms the least significant bits.
+    *
+    * Equivalent to r(0) ## r(1) ## ... ## r(n-1).
+    */
+  def apply[T <: Bits](r: Seq[T]): UInt = SeqUtils.asUInt(r.reverse)
+}
diff --git a/src/main/scala/chisel3/util/CircuitMath.scala b/src/main/scala/chisel3/util/CircuitMath.scala
new file mode 100644
index 00000000..d478e10e
--- /dev/null
+++ b/src/main/scala/chisel3/util/CircuitMath.scala
@@ -0,0 +1,38 @@
+// See LICENSE for license details.
+
+/** Circuit-land math operations.
+  */
+
+package chisel3.util
+
+import chisel3._
+
+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(UInt(13)) === UInt(3)
+    */
+  def apply(x: Bits, width: Int): UInt = {
+    if (width < 2) {
+      UInt(0)
+    } else if (width == 2) {
+      x(1)
+    } else if (width <= divideAndConquerThreshold) {
+      Mux(x(width-1), UInt(width-1), apply(x, width-1))
+    } else {
+      val mid = 1 << (log2Ceil(width) - 1)
+      val hi = x(width-1, mid)
+      val lo = x(mid-1, 0)
+      val useHi = hi.orR
+      Cat(useHi, Mux(useHi, Log2(hi, width - mid), Log2(lo, mid)))
+    }
+  }
+
+  /** Returns the base-2 integer logarithm of an UInt.
+    *
+    * @note The result is truncated, so e.g. Log2(UInt(13)) === UInt(3)
+    */
+  def apply(x: Bits): UInt = apply(x, x.getWidth)
+
+  private def divideAndConquerThreshold = 4
+}
diff --git a/src/main/scala/chisel3/util/Conditional.scala b/src/main/scala/chisel3/util/Conditional.scala
new file mode 100644
index 00000000..5830e014
--- /dev/null
+++ b/src/main/scala/chisel3/util/Conditional.scala
@@ -0,0 +1,94 @@
+// See LICENSE for license details.
+
+/** Conditional blocks.
+  */
+
+package chisel3.util
+
+import scala.language.reflectiveCalls
+import scala.language.experimental.macros
+import scala.reflect.runtime.universe._
+import scala.reflect.macros.blackbox._
+
+import chisel3._
+
+object unless {  // scalastyle:ignore object.name
+  /** Does the same thing as [[when$ when]], but with the condition inverted.
+    */
+  def apply(c: Bool)(block: => Unit) {
+    when (!c) { block }
+  }
+}
+
+/** Implementation details for [[switch]]. See [[switch]] and [[chisel3.util.is is]] for the
+  * user-facing API.
+  */
+class SwitchContext[T <: Bits](cond: T) {
+  def is(v: Iterable[T])(block: => Unit) {
+    if (!v.isEmpty) {
+      when (v.map(_.asUInt === cond.asUInt).reduce(_||_)) {
+        block
+      }
+    }
+  }
+  def is(v: T)(block: => Unit) { is(Seq(v))(block) }
+  def is(v: T, vr: T*)(block: => Unit) { is(v :: vr.toList)(block) }
+}
+
+/** Use to specify cases in a [[switch]] block, equivalent to a [[when$ when]] block comparing to
+  * the condition variable.
+  *
+  * @note illegal outside a [[switch]] block
+  * @note multiple conditions may fire simultaneously
+  * @note dummy implementation, a macro inside [[switch]] transforms this into the actual
+  * implementation
+  */
+object is {   // scalastyle:ignore object.name
+  // TODO: Begin deprecation of non-type-parameterized is statements.
+  /** Executes `block` if the switch condition is equal to any of the values in `v`.
+    */
+  def apply(v: Iterable[Bits])(block: => Unit) {
+    require(false, "The 'is' keyword may not be used outside of a switch.")
+  }
+
+  /** Executes `block` if the switch condition is equal to `v`.
+    */
+  def apply(v: Bits)(block: => Unit) {
+    require(false, "The 'is' keyword may not be used outside of a switch.")
+  }
+
+  /** Executes `block` if the switch condition is equal to any of the values in the argument list.
+    */
+  def apply(v: Bits, vr: Bits*)(block: => Unit) {
+    require(false, "The 'is' keyword may not be used outside of a switch.")
+  }
+}
+
+/** Conditional logic to form a switch block. See [[is$ is]] for the case API.
+  *
+  * @example {{{
+  * switch (myState) {
+  *   is (state1) {
+  *     // some logic here that runs when myState === state1
+  *   }
+  *   is (state2) {
+  *     // some logic here that runs when myState === state2
+  *   }
+  * }
+  * }}}
+  */
+object switch {  // scalastyle:ignore object.name
+  def apply[T <: Bits](cond: T)(x: => Unit): Unit = macro impl
+  def impl(c: Context)(cond: c.Tree)(x: c.Tree): c.Tree = { import c.universe._
+    val sc = c.universe.internal.reificationSupport.freshTermName("sc")
+    def extractIsStatement(tree: Tree): List[c.universe.Tree] = tree match {
+      // TODO: remove when Chisel compatibility package is removed
+      case q"Chisel.`package`.is.apply( ..$params )( ..$body )" => List(q"$sc.is( ..$params )( ..$body )")
+      case q"chisel3.util.is.apply( ..$params )( ..$body )" => List(q"$sc.is( ..$params )( ..$body )")
+      case b => throw new Exception(s"Cannot include blocks that do not begin with is() in switch.")
+    }
+    val q"..$body" = x
+    val ises = body.flatMap(extractIsStatement(_))
+    q"""{ val $sc = new SwitchContext($cond); ..$ises }"""
+  }
+}
diff --git a/src/main/scala/chisel3/util/Counter.scala b/src/main/scala/chisel3/util/Counter.scala
new file mode 100644
index 00000000..ba66d667
--- /dev/null
+++ b/src/main/scala/chisel3/util/Counter.scala
@@ -0,0 +1,62 @@
+// See LICENSE for license details.
+
+package chisel3.util
+
+import chisel3._
+//import chisel3.core.ExplicitCompileOptions.Strict
+
+/** A counter module
+ *
+  * @param n number of counts before the counter resets (or one more than the
+  * maximum output value of the counter), need not be a power of two
+  */
+class Counter(val n: Int) {
+  require(n >= 0)
+  val value = if (n > 1) Reg(init=UInt(0, log2Up(n))) else UInt(0)
+
+  /** Increment the counter, returning whether the counter currently is at the
+    * maximum and will wrap. The incremented value is registered and will be
+    * visible on the next cycle.
+    */
+  def inc(): Bool = {
+    if (n > 1) {
+      val wrap = value === UInt(n-1)
+      value := value + UInt(1)
+      if (!isPow2(n)) {
+        when (wrap) { value := UInt(0) }
+      }
+      wrap
+    } else {
+      Bool(true)
+    }
+  }
+}
+
+object Counter
+{
+  /** Instantiate a [[Counter! counter]] with the specified number of counts.
+    */
+  def apply(n: Int): Counter = new Counter(n)
+
+  /** Instantiate a [[Counter! counter]] with the specified number of counts and a gate.
+   *
+    * @param cond condition that controls whether the counter increments this cycle
+    * @param n number of counts before the counter resets
+    * @return tuple of the counter value and whether the counter will wrap (the value is at
+    * maximum and the condition is true).
+    *
+    * @example {{{
+    * val countOn = Bool(true) // increment counter every clock cycle
+    * val (counterValue, counterWrap) = Counter(countOn, 4)
+    * when (counterValue === UInt(3)) {
+    *   ...
+    * }
+    * }}}
+    */
+  def apply(cond: Bool, n: Int): (UInt, Bool) = {
+    val c = new Counter(n)
+    var wrap: Bool = null
+    when (cond) { wrap = c.inc() }
+    (c.value, cond && wrap)
+  }
+}
diff --git a/src/main/scala/chisel3/util/Decoupled.scala b/src/main/scala/chisel3/util/Decoupled.scala
new file mode 100644
index 00000000..a0cbf4f7
--- /dev/null
+++ b/src/main/scala/chisel3/util/Decoupled.scala
@@ -0,0 +1,269 @@
+// See LICENSE for license details.
+
+/** Wrappers for ready-valid (Decoupled) interfaces and associated circuit generators using them.
+  */
+
+package chisel3.util
+
+import chisel3._
+// TODO: remove this once we have CompileOptions threaded through the macro system.
+import chisel3.core.ExplicitCompileOptions.NotStrict
+
+/** An I/O Bundle containing 'valid' and 'ready' signals that handshake
+  * the transfer of data stored in the 'bits' subfield.
+  * The base protocol implied by the directionality is that the consumer
+  * uses the flipped interface. Actual semantics of ready/valid are
+  * enforced via use of concrete subclasses.
+  */
+abstract class ReadyValidIO[+T <: Data](gen: T) extends Bundle
+{
+  val ready = Input(Bool())
+  val valid = Output(Bool())
+  val bits  = Output(gen.chiselCloneType)
+}
+
+object ReadyValidIO {
+
+  implicit class AddMethodsToReadyValid[T<:Data](val target: ReadyValidIO[T]) extends AnyVal {
+    def fire(): Bool = target.ready && target.valid
+
+    /** push dat onto the output bits of this interface to let the consumer know it has happened.
+      * @param dat the values to assign to bits.
+      * @return    dat.
+      */
+    def enq(dat: T): T = {
+      target.valid := Bool(true)
+      target.bits := dat
+      dat
+    }
+
+    /** Indicate no enqueue occurs.  Valid is set to false, and all bits are set to zero.
+      */
+    def noenq(): Unit = {
+      target.valid := Bool(false)
+      // We want the type from the following, not any existing binding.
+      target.bits := target.bits.cloneType.fromBits(0.asUInt)
+    }
+
+    /** Assert ready on this port and return the associated data bits.
+      * This is typically used when valid has been asserted by the producer side.
+      * @param b ignored
+      * @return the data for this device,
+      */
+    def deq(): T = {
+      target.ready := Bool(true)
+      target.bits
+    }
+
+    /** Indicate no dequeue occurs. Ready is set to false
+      */
+    def nodeq(): Unit = {
+      target.ready := Bool(false)
+    }
+  }
+}
+
+/** A concrete subclass of ReadyValidIO signaling that the user expects a
+  * "decoupled" interface: 'valid' indicates that the producer has
+  * put valid data in 'bits', and 'ready' indicates that the consumer is ready
+  * to accept the data this cycle. No requirements are placed on the signaling
+  * of ready or valid.
+  */
+class DecoupledIO[+T <: Data](gen: T) extends ReadyValidIO[T](gen)
+{
+  override def cloneType: this.type = new DecoupledIO(gen).asInstanceOf[this.type]
+}
+
+/** This factory adds a decoupled handshaking protocol to a data bundle. */
+object Decoupled
+{
+  /** Wraps some Data with a DecoupledIO interface. */
+  def apply[T <: Data](gen: T): DecoupledIO[T] = new DecoupledIO(gen)
+
+  /** Downconverts an IrrevocableIO output to a DecoupledIO, dropping guarantees of irrevocability.
+    *
+    * @note unsafe (and will error) on the producer (input) side of an IrrevocableIO
+    */
+  def apply[T <: Data](irr: IrrevocableIO[T]): DecoupledIO[T] = {
+    require(irr.bits.flatten forall (_.dir == OUTPUT), "Only safe to cast produced Irrevocable bits to Decoupled.")
+    val d = Wire(new DecoupledIO(irr.bits))
+    d.bits := irr.bits
+    d.valid := irr.valid
+    irr.ready := d.ready
+    d
+  }
+//  override def cloneType: this.type = {
+//    DeqIO(gen).asInstanceOf[this.type]
+//  }
+}
+
+/** A concrete subclass of ReadyValidIO that promises to not change
+  * the value of 'bits' after a cycle where 'valid' is high and 'ready' is low.
+  * Additionally, once 'valid' is raised it will never be lowered until after
+  * 'ready' has also been raised.
+  */
+class IrrevocableIO[+T <: Data](gen: T) extends ReadyValidIO[T](gen)
+{
+  override def cloneType: this.type = new IrrevocableIO(gen).asInstanceOf[this.type]
+}
+
+/** Factory adds an irrevocable handshaking protocol to a data bundle. */
+object Irrevocable
+{
+  def apply[T <: Data](gen: T): IrrevocableIO[T] = new IrrevocableIO(gen)
+
+  /** Upconverts a DecoupledIO input to an IrrevocableIO, allowing an IrrevocableIO to be used
+    * where a DecoupledIO is expected.
+    *
+    * @note unsafe (and will error) on the consumer (output) side of an DecoupledIO
+    */
+  def apply[T <: Data](dec: DecoupledIO[T]): IrrevocableIO[T] = {
+    require(dec.bits.flatten forall (_.dir == INPUT), "Only safe to cast consumed Decoupled bits to Irrevocable.")
+    val i = Wire(new IrrevocableIO(dec.bits))
+    dec.bits := i.bits
+    dec.valid := i.valid
+    i.ready := dec.ready
+    i
+  }
+}
+
+object EnqIO {
+  def apply[T<:Data](gen: T): DecoupledIO[T] = Decoupled(gen)
+}
+object DeqIO {
+  def apply[T<:Data](gen: T): DecoupledIO[T] = Flipped(Decoupled(gen))
+}
+
+/** An I/O Bundle for Queues
+  * @param gen The type of data to queue
+  * @param entries The max number of entries in the queue */
+class QueueIO[T <: Data](gen: T, entries: Int) extends Bundle
+{
+  /** I/O to enqueue data, is [[Chisel.DecoupledIO]] flipped */
+  val enq = DeqIO(gen)
+  /** I/O to enqueue data, is [[Chisel.DecoupledIO]]*/
+  val deq = EnqIO(gen)
+  /** The current amount of data in the queue */
+  val count = Output(UInt.width(log2Up(entries + 1)))
+}
+
+/** A hardware module implementing a Queue
+  * @param gen The type of data to queue
+  * @param entries The max number of entries in the queue
+  * @param pipe True if a single entry queue can run at full throughput (like a pipeline). The ''ready'' signals are
+  * 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.
+  *
+  * @example {{{
+  * val q = new Queue(UInt(), 16)
+  * q.io.enq <> producer.io.out
+  * consumer.io.in <> q.io.deq
+  * }}}
+  */
+class Queue[T <: Data](gen: T,
+                       val entries: Int,
+                       pipe: Boolean = false,
+                       flow: Boolean = false,
+                       override_reset: Option[Bool] = None)
+extends Module(override_reset=override_reset) {
+  def this(gen: T, entries: Int, pipe: Boolean, flow: Boolean, _reset: Bool) =
+    this(gen, entries, pipe, flow, Some(_reset))
+
+  val io = IO(new QueueIO(gen, entries))
+
+  val ram = Mem(entries, gen)
+  val enq_ptr = Counter(entries)
+  val deq_ptr = Counter(entries)
+  val maybe_full = Reg(init=Bool(false))
+
+  val ptr_match = enq_ptr.value === deq_ptr.value
+  val empty = ptr_match && !maybe_full
+  val full = ptr_match && maybe_full
+  val do_enq = Wire(init=io.enq.fire())
+  val do_deq = Wire(init=io.deq.fire())
+
+  when (do_enq) {
+    ram(enq_ptr.value) := io.enq.bits
+    enq_ptr.inc()
+  }
+  when (do_deq) {
+    deq_ptr.inc()
+  }
+  when (do_enq != do_deq) {
+    maybe_full := do_enq
+  }
+
+  io.deq.valid := !empty
+  io.enq.ready := !full
+  io.deq.bits := ram(deq_ptr.value)
+
+  if (flow) {
+    when (io.enq.valid) { io.deq.valid := Bool(true) }
+    when (empty) {
+      io.deq.bits := io.enq.bits
+      do_deq := Bool(false)
+      when (io.deq.ready) { do_enq := Bool(false) }
+    }
+  }
+
+  if (pipe) {
+    when (io.deq.ready) { io.enq.ready := Bool(true) }
+  }
+
+  val ptr_diff = enq_ptr.value - deq_ptr.value
+  if (isPow2(entries)) {
+    io.count := Cat(maybe_full && ptr_match, ptr_diff)
+  } else {
+    io.count := Mux(ptr_match,
+                    Mux(maybe_full,
+                      UInt(entries), UInt(0)),
+                    Mux(deq_ptr.value > enq_ptr.value,
+                      UInt(entries) + ptr_diff, ptr_diff))
+  }
+}
+
+/** Factory for a generic hardware queue.
+  *
+  * @param enq input (enqueue) interface to the queue, also determines width of queue elements
+  * @param entries depth (number of elements) of the queue
+  *
+  * @returns output (dequeue) interface from the queue
+  *
+  * @example {{{
+  * consumer.io.in <> Queue(producer.io.out, 16)
+  * }}}
+  */
+object Queue
+{
+  /** Create a queue and supply a DecoupledIO containing the product. */
+  def apply[T <: Data](
+      enq: ReadyValidIO[T],
+      entries: Int = 2,
+      pipe: Boolean = false,
+      flow: Boolean = false): DecoupledIO[T] = {
+    val q = Module(new Queue(enq.bits.cloneType, entries, pipe, flow))
+    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
+    TransitName(q.io.deq, q)
+  }
+
+  /** Create a queue and supply a IrrevocableIO containing the product.
+    * Casting from Decoupled is safe here because we know the Queue has
+    * Irrevocable semantics; we didn't want to change the return type of
+    * apply() for backwards compatibility reasons.
+    */
+  def irrevocable[T <: Data](
+      enq: ReadyValidIO[T],
+      entries: Int = 2,
+      pipe: Boolean = false,
+      flow: Boolean = false): IrrevocableIO[T] = {
+    val deq = apply(enq, entries, pipe, flow)
+    val irr = Wire(new IrrevocableIO(deq.bits))
+    irr.bits := deq.bits
+    irr.valid := deq.valid
+    deq.ready := irr.ready
+    irr
+  }
+}
diff --git a/src/main/scala/chisel3/util/Enum.scala b/src/main/scala/chisel3/util/Enum.scala
new file mode 100644
index 00000000..55b595ee
--- /dev/null
+++ b/src/main/scala/chisel3/util/Enum.scala
@@ -0,0 +1,53 @@
+// See LICENSE for license details.
+
+/** Enum generators, allowing circuit constants to have more meaningful names.
+  */
+
+package chisel3.util
+
+import chisel3._
+
+object Enum {
+  /** Returns a sequence of Bits subtypes with values from 0 until n. Helper method. */
+  private def createValues[T <: Bits](nodeType: T, n: Int): Seq[T] =
+    (0 until n).map(x => nodeType.fromInt(x, log2Up(n)))
+
+  /** Returns n unique values of the specified type. Can be used with unpacking to define enums.
+    *
+    * @example {{{
+    * val state_on :: state_off :: Nil = Enum(UInt(), 2)
+    * val current_state = UInt()
+    * switch (current_state) {
+    *   is (state_on) {
+    *      ...
+    *   }
+    *   if (state_off) {
+    *      ...
+    *   }
+    * }
+    * }}}
+    *
+    */
+  def apply[T <: Bits](nodeType: T, n: Int): List[T] = createValues(nodeType, n).toList
+
+  /** Returns a map of the input symbols to unique values of the specified type.
+    *
+    * @example {{{
+    * val states = Enum(UInt(), 'on, 'off)
+    * val current_state = UInt()
+    * switch (current_state) {
+    *   is (states('on)) {
+    *     ...
+    *   }
+    *   if (states('off)) {
+    *     ..
+    *   }
+    * }
+    * }}}
+    */
+  def apply[T <: Bits](nodeType: T, l: Symbol *): Map[Symbol, T] = (l zip createValues(nodeType, l.length)).toMap
+
+  /** Returns a map of the input symbols to unique values of the specified type.
+    */
+  def apply[T <: Bits](nodeType: T, l: List[Symbol]): Map[Symbol, T] = (l zip createValues(nodeType, l.length)).toMap
+}
diff --git a/src/main/scala/chisel3/util/ImplicitConversions.scala b/src/main/scala/chisel3/util/ImplicitConversions.scala
new file mode 100644
index 00000000..4d816a19
--- /dev/null
+++ b/src/main/scala/chisel3/util/ImplicitConversions.scala
@@ -0,0 +1,10 @@
+// See LICENSE for license details.
+
+package chisel3.util
+
+import chisel3._
+
+object ImplicitConversions {
+  implicit def intToUInt(x: Int): UInt = UInt(x)
+  implicit def booleanToBool(x: Boolean): Bool = Bool(x)
+}
diff --git a/src/main/scala/chisel3/util/LFSR.scala b/src/main/scala/chisel3/util/LFSR.scala
new file mode 100644
index 00000000..fedbf194
--- /dev/null
+++ b/src/main/scala/chisel3/util/LFSR.scala
@@ -0,0 +1,26 @@
+// See LICENSE for license details.
+
+/** LFSRs in all shapes and sizes.
+  */
+
+package chisel3.util
+
+import chisel3._
+//import chisel3.core.ExplicitCompileOptions.Strict
+
+// scalastyle:off magic.number
+object LFSR16 {
+  /** Generates a 16-bit linear feedback shift register, returning the register contents.
+    * May be useful for generating a pseudorandom sequence.
+    *
+    * @param increment optional control to gate when the LFSR updates.
+    */
+  def apply(increment: Bool = Bool(true)): UInt = {
+    val width = 16
+    val lfsr = Reg(init=UInt(1, width))
+    when (increment) { lfsr := Cat(lfsr(0)^lfsr(2)^lfsr(3)^lfsr(5), lfsr(width-1,1)) }
+    lfsr
+  }
+}
+// scalastyle:on magic.number
+
diff --git a/src/main/scala/chisel3/util/Lookup.scala b/src/main/scala/chisel3/util/Lookup.scala
new file mode 100644
index 00000000..9e909c0c
--- /dev/null
+++ b/src/main/scala/chisel3/util/Lookup.scala
@@ -0,0 +1,19 @@
+// See LICENSE for license details.
+
+package chisel3.util
+
+import chisel3._
+
+object ListLookup {
+  def apply[T <: Data](addr: UInt, default: List[T], mapping: Array[(BitPat, List[T])]): List[T] = {
+    val map = mapping.map(m => (m._1 === addr, m._2))
+    default.zipWithIndex map { case (d, i) =>
+      map.foldRight(d)((m, n) => Mux(m._1, m._2(i), n))
+    }
+  }
+}
+
+object Lookup {
+  def apply[T <: Bits](addr: UInt, default: T, mapping: Seq[(BitPat, T)]): T =
+    ListLookup(addr, List(default), mapping.map(m => (m._1, List(m._2))).toArray).head
+}
diff --git a/src/main/scala/chisel3/util/Math.scala b/src/main/scala/chisel3/util/Math.scala
new file mode 100644
index 00000000..73665f0f
--- /dev/null
+++ b/src/main/scala/chisel3/util/Math.scala
@@ -0,0 +1,44 @@
+// See LICENSE for license details.
+
+/** Scala-land math helper functions, like logs.
+  */
+
+package chisel3.util
+
+import chisel3._
+
+/** Compute the log2 rounded up with min value of 1 */
+object log2Up {
+  def apply(in: BigInt): Int = {
+    require(in >= 0)
+    1 max (in-1).bitLength
+  }
+  def apply(in: Int): Int = apply(BigInt(in))
+}
+
+/** Compute the log2 rounded up */
+object log2Ceil {
+  def apply(in: BigInt): Int = {
+    require(in > 0)
+    (in-1).bitLength
+  }
+  def apply(in: Int): Int = apply(BigInt(in))
+}
+
+/** Compute the log2 rounded down with min value of 1 */
+object log2Down {
+  def apply(in: BigInt): Int = log2Up(in) - (if (isPow2(in)) 0 else 1)
+  def apply(in: Int): Int = apply(BigInt(in))
+}
+
+/** Compute the log2 rounded down */
+object log2Floor {
+  def apply(in: BigInt): Int = log2Ceil(in) - (if (isPow2(in)) 0 else 1)
+  def apply(in: Int): Int = apply(BigInt(in))
+}
+
+/** Check if an Integer is a power of 2 */
+object isPow2 {
+  def apply(in: BigInt): Boolean = in > 0 && ((in & (in-1)) == 0)
+  def apply(in: Int): Boolean = apply(BigInt(in))
+}
diff --git a/src/main/scala/chisel3/util/Mux.scala b/src/main/scala/chisel3/util/Mux.scala
new file mode 100644
index 00000000..245de67e
--- /dev/null
+++ b/src/main/scala/chisel3/util/Mux.scala
@@ -0,0 +1,65 @@
+// See LICENSE for license details.
+
+/** Mux circuit generators.
+  */
+
+package chisel3.util
+
+import chisel3._
+import chisel3.core.SeqUtils
+
+/** Builds a Mux tree out of the input signal vector using a one hot encoded
+  * select signal. Returns the output of the Mux tree.
+  *
+  * @note results undefined if multiple select signals are simultaneously high
+  */
+object Mux1H {
+  def apply[T <: Data](sel: Seq[Bool], in: Seq[T]): T =
+    apply(sel zip in)
+  def apply[T <: Data](in: Iterable[(Bool, T)]): T = SeqUtils.oneHotMux(in)
+  def apply[T <: Data](sel: UInt, in: Seq[T]): T =
+    apply((0 until in.size).map(sel(_)), in)
+  def apply(sel: UInt, in: UInt): Bool = (sel & in).orR
+}
+
+/** Builds a Mux tree under the assumption that multiple select signals
+  * can be enabled. Priority is given to the first select signal.
+  *
+  * Returns the output of the Mux tree.
+  */
+object PriorityMux {
+  def apply[T <: Data](in: Seq[(Bool, T)]): T = SeqUtils.priorityMux(in)
+  def apply[T <: Data](sel: Seq[Bool], in: Seq[T]): T = apply(sel zip in)
+  def apply[T <: Data](sel: Bits, in: Seq[T]): T = apply((0 until in.size).map(sel(_)), in)
+}
+
+/** Creates a cascade of n Muxs to search for a key value. */
+object MuxLookup {
+  /** @param key a key to search for
+    * @param default a default value if nothing is found
+    * @param mapping a sequence to search of keys and values
+    * @return the value found or the default if not
+    */
+  def apply[S <: UInt, T <: Data] (key: S, default: T, mapping: Seq[(S, T)]): T = {
+    var res = default
+    for ((k, v) <- mapping.reverse)
+      res = Mux(k === key, v, res)
+    res
+  }
+}
+
+/** Given an association of values to enable signals, returns the first value with an associated
+  * high enable signal.
+  */
+object MuxCase {
+  /** @param default the default value if none are enabled
+    * @param mapping a set of data values with associated enables
+    * @return the first value in mapping that is enabled */
+  def apply[T <: Data] (default: T, mapping: Seq[(Bool, T)]): T = {
+    var res = default
+    for ((t, v) <- mapping.reverse){
+      res = Mux(t, v, res)
+    }
+    res
+  }
+}
diff --git a/src/main/scala/chisel3/util/OneHot.scala b/src/main/scala/chisel3/util/OneHot.scala
new file mode 100644
index 00000000..53ba8c3d
--- /dev/null
+++ b/src/main/scala/chisel3/util/OneHot.scala
@@ -0,0 +1,66 @@
+// See LICENSE for license details.
+
+/** Circuit generators for working with one-hot representations.
+  */
+
+package chisel3.util
+
+import chisel3._
+
+/** Returns the bit position of the sole high bit of the input bitvector.
+  *
+  * Inverse operation of [[UIntToOH]].
+  *
+  * @note assumes exactly one high bit, results undefined otherwise
+  */
+object OHToUInt {
+  def apply(in: Seq[Bool]): UInt = apply(Cat(in.reverse), in.size)
+  def apply(in: Vec[Bool]): UInt = apply(in.asUInt, in.size)
+  def apply(in: Bits): UInt = apply(in, in.getWidth)
+
+  def apply(in: Bits, width: Int): UInt = {
+    if (width <= 2) {
+      Log2(in, width)
+    } else {
+      val mid = 1 << (log2Up(width)-1)
+      val hi = in(width-1, mid)
+      val lo = in(mid-1, 0)
+      Cat(hi.orR, apply(hi | lo, mid))
+    }
+  }
+}
+
+/** Returns the bit position of the least-significant high bit of the input bitvector.
+  *
+  * Multiple bits may be high in the input.
+  */
+object PriorityEncoder {
+  def apply(in: Seq[Bool]): UInt = PriorityMux(in, (0 until in.size).map(UInt(_)))
+  def apply(in: Bits): UInt = apply(in.toBools)
+}
+
+/** Returns the one hot encoding of the input UInt.
+  */
+object UIntToOH {
+  def apply(in: UInt, width: Int = -1): UInt =
+    if (width == -1) {
+      UInt(1) << in
+    } else {
+      (UInt(1) << in(log2Up(width)-1,0))(width-1,0)
+    }
+}
+
+/** Returns a bit vector in which only the least-significant 1 bit in the input vector, if any,
+  * is set.
+  */
+object PriorityEncoderOH {
+  private def encode(in: Seq[Bool]): UInt = {
+    val outs = Seq.tabulate(in.size)(i => UInt(BigInt(1) << i, in.size))
+    PriorityMux(in :+ Bool(true), outs :+ UInt(0, in.size))
+  }
+  def apply(in: Seq[Bool]): Seq[Bool] = {
+    val enc = encode(in)
+    Seq.tabulate(in.size)(enc(_))
+  }
+  def apply(in: Bits): UInt = encode((0 until in.getWidth).map(i => in(i)))
+}
diff --git a/src/main/scala/chisel3/util/Reg.scala b/src/main/scala/chisel3/util/Reg.scala
new file mode 100644
index 00000000..713a3b2e
--- /dev/null
+++ b/src/main/scala/chisel3/util/Reg.scala
@@ -0,0 +1,66 @@
+// See LICENSE for license details.
+
+package chisel3.util
+
+import chisel3._
+// TODO: remove this once we have CompileOptions threaded through the macro system.
+import chisel3.core.ExplicitCompileOptions.NotStrict
+
+object RegNext {
+  /** Returns a register with the specified next and no reset initialization.
+    *
+    * Essentially a 1-cycle delayed version of the input signal.
+    */
+  def apply[T <: Data](next: T): T = Reg[T](null.asInstanceOf[T], next, null.asInstanceOf[T])
+
+  /** Returns a register with the specified next and reset initialization.
+    *
+    * Essentially a 1-cycle delayed version of the input signal.
+    */
+  def apply[T <: Data](next: T, init: T): T = Reg[T](null.asInstanceOf[T], next, init)
+}
+
+object RegInit {
+  /** Returns a register pre-initialized (on reset) to the specified value.
+    */
+  def apply[T <: Data](init: T): T = Reg[T](null.asInstanceOf[T], null.asInstanceOf[T], init)
+}
+
+object RegEnable {
+  /** Returns a register with the specified next, update enable gate, and no reset initialization.
+    */
+  def apply[T <: Data](updateData: T, enable: Bool): T = {
+    val clonedUpdateData = updateData.chiselCloneType
+    val r = Reg(clonedUpdateData)
+    when (enable) { r := updateData }
+    r
+  }
+
+  /** Returns a register with the specified next, update enable gate, and reset initialization.
+    */
+  def apply[T <: Data](updateData: T, resetData: T, enable: Bool): T = {
+    val r = RegInit(resetData)
+    when (enable) { r := updateData }
+    r
+  }
+}
+
+object ShiftRegister
+{
+  /** Returns the n-cycle delayed version of the input signal.
+    *
+    * @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 = Bool(true)): T = {
+    // The order of tests reflects the expected use cases.
+    if (n == 1) {
+      RegEnable(in, en)
+    } else if (n != 0) {
+      RegNext(apply(in, n-1, en))
+    } else {
+      in
+    }
+  }
+}
diff --git a/src/main/scala/chisel3/util/TransitName.scala b/src/main/scala/chisel3/util/TransitName.scala
new file mode 100644
index 00000000..a3220a13
--- /dev/null
+++ b/src/main/scala/chisel3/util/TransitName.scala
@@ -0,0 +1,26 @@
+// See LICENSE for license details.
+
+package chisel3.util
+
+import chisel3._
+import internal.HasId
+
+/**
+ * The purpose of TransitName is to allow a library to 'move' a name
+ * call to a more appropriate place.
+ * For example, a library factory function may create a module and return
+ * the io. The only user-exposed field is that given IO, which can't use
+ * any name supplied by the user. This can add a hook so that the supplied
+ * name then names the Module.
+ * See Queue companion object for working example
+ */
+object TransitName {
+  def apply[T<:HasId](from: T, to: HasId): T = {
+    from.addPostnameHook((given_name: String) => {to.suggestName(given_name)})
+    from
+  }
+  def withSuffix[T<:HasId](suffix: String)(from: T, to: HasId): T = {
+    from.addPostnameHook((given_name: String) => {to.suggestName(given_name + suffix)})
+    from
+  }
+}
diff --git a/src/main/scala/chisel3/util/Valid.scala b/src/main/scala/chisel3/util/Valid.scala
new file mode 100644
index 00000000..3d153a2a
--- /dev/null
+++ b/src/main/scala/chisel3/util/Valid.scala
@@ -0,0 +1,61 @@
+// See LICENSE for license details.
+
+/** Wrappers for valid interfaces and associated circuit generators using them.
+  */
+
+package chisel3.util
+
+import chisel3._
+// TODO: remove this once we have CompileOptions threaded through the macro system.
+import chisel3.core.ExplicitCompileOptions.NotStrict
+
+/** An Bundle containing data and a signal determining if it is valid */
+class Valid[+T <: Data](gen: T) extends Bundle
+{
+  val valid = Output(Bool())
+  val bits  = Output(gen.chiselCloneType)
+  def fire(dummy: Int = 0): Bool = valid
+  override def cloneType: this.type = Valid(gen).asInstanceOf[this.type]
+}
+
+/** Adds a valid protocol to any interface */
+object Valid {
+  def apply[T <: Data](gen: T): Valid[T] = new Valid(gen)
+}
+
+/** A hardware module that delays data coming down the pipeline
+  by the number of cycles set by the latency parameter. Functionality
+  is similar to ShiftRegister but this exposes a Pipe interface.
+
+  Example usage:
+    val pipe = new Pipe(UInt())
+    pipe.io.enq <> produce.io.out
+    consumer.io.in <> pipe.io.deq
+  */
+object Pipe
+{
+  def apply[T <: Data](enqValid: Bool, enqBits: T, latency: Int): Valid[T] = {
+    if (latency == 0) {
+      val out = Wire(Valid(enqBits))
+      out.valid <> enqValid
+      out.bits <> enqBits
+      out
+    } else {
+      val v = Reg(Bool(), next=enqValid, init=Bool(false))
+      val b = RegEnable(enqBits, enqValid)
+      apply(v, b, latency-1)
+    }
+  }
+  def apply[T <: Data](enqValid: Bool, enqBits: T): Valid[T] = apply(enqValid, enqBits, 1)
+  def apply[T <: Data](enq: Valid[T], latency: Int = 1): Valid[T] = apply(enq.valid, enq.bits, latency)
+}
+
+class Pipe[T <: Data](gen: T, latency: Int = 1) extends Module
+{
+  val io = IO(new Bundle {
+    val enq = Input(Valid(gen))
+    val deq = Output(Valid(gen))
+  })
+
+  io.deq <> Pipe(io.enq, latency)
+}
diff --git a/src/main/scala/chisel3/util/util.scala b/src/main/scala/chisel3/util/util.scala
new file mode 100644
index 00000000..812af21c
--- /dev/null
+++ b/src/main/scala/chisel3/util/util.scala
@@ -0,0 +1,12 @@
+// See LICENSE for license details.
+
+package chisel3
+
+package object util {
+
+  /** Synonyms, moved from main package object - maintain scope. */
+  type ValidIO[+T <: Data] = chisel3.util.Valid[T]
+  val ValidIO = chisel3.util.Valid
+  val DecoupledIO = chisel3.util.Decoupled
+
+}