diff options
Diffstat (limited to 'src/main/scala')
37 files changed, 1382 insertions, 541 deletions
diff --git a/src/main/scala/Chisel/FileSystemUtilities.scala b/src/main/scala/Chisel/FileSystemUtilities.scala deleted file mode 100644 index 575ae138..00000000 --- a/src/main/scala/Chisel/FileSystemUtilities.scala +++ /dev/null @@ -1,10 +0,0 @@ -// See LICENSE for license details. - -package Chisel - -@deprecated("FileSystemUtilities doesn't exist in chisel3", "3.0.0") -trait FileSystemUtilities { - def createOutputFile(name: String): java.io.FileWriter = { - new java.io.FileWriter(Driver.targetDir + "/" + name) - } -} diff --git a/src/main/scala/Chisel/package.scala b/src/main/scala/Chisel/package.scala deleted file mode 100644 index 61fb6904..00000000 --- a/src/main/scala/Chisel/package.scala +++ /dev/null @@ -1,17 +0,0 @@ -package object Chisel { - import internal.firrtl.Width - implicit class fromBigIntToLiteral(val x: BigInt) extends AnyVal { - def U: UInt = UInt(x, Width()) - def S: SInt = SInt(x, Width()) - } - implicit class fromIntToLiteral(val x: Int) extends AnyVal { - def U: UInt = UInt(BigInt(x), Width()) - def S: SInt = SInt(BigInt(x), Width()) - } - implicit class fromStringToLiteral(val x: String) extends AnyVal { - def U: UInt = UInt(x) - } - implicit class fromBooleanToLiteral(val x: Boolean) extends AnyVal { - def B: Bool = Bool(x) - } -} diff --git a/src/main/scala/Chisel/util/Cat.scala b/src/main/scala/Chisel/util/Cat.scala deleted file mode 100644 index dd706e62..00000000 --- a/src/main/scala/Chisel/util/Cat.scala +++ /dev/null @@ -1,18 +0,0 @@ -// See LICENSE for license details. - -package Chisel - -object Cat { - /** Combine data elements together - * @param a Data to combine with - * @param r any number of other Data elements to be combined in order - * @return A UInt which is all of the bits combined together - */ - def apply[T <: Bits](a: T, r: T*): UInt = apply(a :: r.toList) - - /** Combine data elements together - * @param r any number of other Data elements to be combined in order - * @return A UInt which is all of the bits combined together - */ - def apply[T <: Bits](r: Seq[T]): UInt = SeqUtils.asUInt(r.reverse) -} diff --git a/src/main/scala/Chisel/util/CircuitMath.scala b/src/main/scala/Chisel/util/CircuitMath.scala deleted file mode 100644 index 06cab903..00000000 --- a/src/main/scala/Chisel/util/CircuitMath.scala +++ /dev/null @@ -1,26 +0,0 @@ -// See LICENSE for license details. - -/** Circuit-land math operations. - */ - -package Chisel - -/** Compute Log2 with truncation of a UInt in hardware using a Mux Tree - * An alternative interpretation is it computes the minimum number of bits needed to represent x - * @example - * {{{ data_out := Log2(data_in) }}} - * @note Truncation is used so Log2(UInt(12412)) = 13*/ -object Log2 { - /** Compute the Log2 on the least significant n bits of x */ - def apply(x: Bits, width: Int): UInt = { - if (width < 2) { - UInt(0) - } else if (width == 2) { - x(1) - } else { - Mux(x(width-1), UInt(width-1), apply(x, width-1)) - } - } - - def apply(x: Bits): UInt = apply(x, x.getWidth) -} diff --git a/src/main/scala/Chisel/util/Conditional.scala b/src/main/scala/Chisel/util/Conditional.scala deleted file mode 100644 index 9cab25ef..00000000 --- a/src/main/scala/Chisel/util/Conditional.scala +++ /dev/null @@ -1,69 +0,0 @@ -// See LICENSE for license details. - -/** Conditional blocks. - */ - -package Chisel - -import scala.language.reflectiveCalls -import scala.language.experimental.macros -import scala.reflect.runtime.universe._ -import scala.reflect.macros.blackbox._ - -/** This is identical to [[Chisel.when when]] with the condition inverted */ -object unless { // scalastyle:ignore object.name - def apply(c: Bool)(block: => Unit) { - when (!c) { block } - } -} - -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) } -} - -/** An object for separate cases in [[Chisel.switch switch]] - * It is equivalent to a [[Chisel.when$ when]] block comparing to the condition - * Use outside of a switch statement is illegal */ -object is { // scalastyle:ignore object.name - // Begin deprecation of non-type-parameterized is statements. - def apply(v: Iterable[Bits])(block: => Unit) { - require(false, "The 'is' keyword may not be used outside of a switch.") - } - - def apply(v: Bits)(block: => Unit) { - require(false, "The 'is' keyword may not be used outside of a switch.") - } - - 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 - * @example - * {{{ ... // default values here - * switch ( myState ) { - * is( state1 ) { - * ... // some logic here - * } - * is( state2 ) { - * ... // some logic here - * } - * } }}}*/ -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 { - case q"Chisel.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/Chisel/util/Decoupled.scala b/src/main/scala/Chisel/util/Decoupled.scala deleted file mode 100644 index 8e045855..00000000 --- a/src/main/scala/Chisel/util/Decoupled.scala +++ /dev/null @@ -1,183 +0,0 @@ -// See LICENSE for license details. - -/** Wrappers for ready-valid (Decoupled) interfaces and associated circuit generators using them. - */ - -package Chisel - -/** An I/O Bundle with simple handshaking using valid and ready signals for data 'bits'*/ -class DecoupledIO[+T <: Data](gen: T) extends Bundle -{ - val ready = Bool(INPUT) - val valid = Bool(OUTPUT) - val bits = gen.cloneType.asOutput - def fire(dummy: Int = 0): Bool = ready && valid - override def cloneType: this.type = new DecoupledIO(gen).asInstanceOf[this.type] -} - -/** Adds a ready-valid handshaking protocol to any interface. - * The standard used is that the consumer uses the flipped interface. - */ -object Decoupled { - def apply[T <: Data](gen: T): DecoupledIO[T] = new DecoupledIO(gen) -} - -/** An I/O bundle for enqueuing data with valid/ready handshaking - * Initialization must be handled, if necessary, by the parent circuit - */ -class EnqIO[T <: Data](gen: T) extends DecoupledIO(gen) -{ - /** 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 = { valid := Bool(true); bits := dat; dat } - - /** Initialize this Bundle. Valid is set to false, and all bits are set to zero. - * NOTE: This method of initialization is still being discussed and could change in the - * future. - */ - def init(): Unit = { - valid := Bool(false) - for (io <- bits.flatten) - io := UInt(0) - } - override def cloneType: this.type = { new EnqIO(gen).asInstanceOf[this.type]; } -} - -/** An I/O bundle for dequeuing data with valid/ready handshaking. - * Initialization must be handled, if necessary, by the parent circuit - */ -class DeqIO[T <: Data](gen: T) extends DecoupledIO(gen) with Flipped -{ - /** 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(b: Boolean = false): T = { ready := Bool(true); bits } - - /** Initialize this Bundle. - * NOTE: This method of initialization is still being discussed and could change in the - * future. - */ - def init(): Unit = { - ready := Bool(false) - } - override def cloneType: this.type = { new DeqIO(gen).asInstanceOf[this.type]; } -} - -/** An I/O bundle for dequeuing data with valid/ready handshaking */ -class DecoupledIOC[+T <: Data](gen: T) extends Bundle -{ - val ready = Bool(INPUT) - val valid = Bool(OUTPUT) - val bits = gen.cloneType.asOutput -} - -/** 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 = Decoupled(gen.cloneType).flip() - /** I/O to enqueue data, is [[Chisel.DecoupledIO]]*/ - val deq = Decoupled(gen.cloneType) - /** The current amount of data in the queue */ - val count = UInt(OUTPUT, 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 usage: - * {{{ 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 = 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)) - } -} - -/** Generic hardware queue. Required parameter entries controls - the depth of the queues. The width of the queue is determined - from the inputs. - - Example usage: - {{{ val q = Queue(Decoupled(UInt()), 16) - q.io.enq <> producer.io.out - consumer.io.in <> q.io.deq }}} - */ -object Queue -{ - def apply[T <: Data](enq: DecoupledIO[T], entries: Int = 2, pipe: Boolean = false): DecoupledIO[T] = { - val q = Module(new Queue(enq.bits.cloneType, entries, pipe)) - 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) - } -} diff --git a/src/main/scala/Chisel/util/Enum.scala b/src/main/scala/Chisel/util/Enum.scala deleted file mode 100644 index 20057197..00000000 --- a/src/main/scala/Chisel/util/Enum.scala +++ /dev/null @@ -1,21 +0,0 @@ -// See LICENSE for license details. - -/** Enum generators, allowing circuit constants to have more meaningful names. - */ - -package Chisel - -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))) - - /** create n enum values of given type */ - def apply[T <: Bits](nodeType: T, n: Int): List[T] = createValues(nodeType, n).toList - - /** create enum values of given type and names */ - def apply[T <: Bits](nodeType: T, l: Symbol *): Map[Symbol, T] = (l zip createValues(nodeType, l.length)).toMap - - /** create enum values of given type and names */ - 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/Chisel/util/LFSR.scala b/src/main/scala/Chisel/util/LFSR.scala deleted file mode 100644 index 839b1d1f..00000000 --- a/src/main/scala/Chisel/util/LFSR.scala +++ /dev/null @@ -1,22 +0,0 @@ -// See LICENSE for license details. - -/** LFSRs in all shapes and sizes. - */ - -package Chisel - -// scalastyle:off magic.number -/** linear feedback shift register - */ -object LFSR16 -{ - 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/Chisel/util/Reg.scala b/src/main/scala/Chisel/util/Reg.scala deleted file mode 100644 index 6584a4bf..00000000 --- a/src/main/scala/Chisel/util/Reg.scala +++ /dev/null @@ -1,55 +0,0 @@ -// See LICENSE for license details. - -/** Variations and helpers for registers. - */ - -package Chisel - -object RegNext { - - def apply[T <: Data](next: T): T = Reg[T](null.asInstanceOf[T], next, null.asInstanceOf[T]) - - def apply[T <: Data](next: T, init: T): T = Reg[T](null.asInstanceOf[T], next, init) - -} - -object RegInit { - - def apply[T <: Data](init: T): T = Reg[T](null.asInstanceOf[T], null.asInstanceOf[T], init) - -} - -/** A register with an Enable signal */ -object RegEnable -{ - def apply[T <: Data](updateData: T, enable: Bool): T = { - val r = Reg(updateData) - when (enable) { r := updateData } - r - } - def apply[T <: Data](updateData: T, resetData: T, enable: Bool): T = { - val r = RegInit(resetData) - when (enable) { r := updateData } - r - } -} - -/** Returns the n-cycle delayed version of the input signal. - */ -object ShiftRegister -{ - /** @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/Chisel/Driver.scala b/src/main/scala/chisel3/Driver.scala index d5952834..5e0a3a0f 100644 --- a/src/main/scala/Chisel/Driver.scala +++ b/src/main/scala/chisel3/Driver.scala @@ -1,6 +1,6 @@ // See LICENSE for license details. -package Chisel +package chisel3 import scala.sys.process._ import java.io._ @@ -46,17 +46,15 @@ trait BackendCompilationUtilities { * The Verilator prefix will be V$dutFile, and running this will generate * C++ sources and headers as well as a makefile to compile them. * - * Verilator will automatically locate the top-level module as the one among - * all the files which are not included elsewhere. If multiple ones exist, - * the compilation will fail. - * * @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 @@ -70,8 +68,10 @@ trait BackendCompilationUtilities { "-Wno-STMTDLY", "--trace", "-O2", + "--top-module", topModule, "+define+TOP_TYPE=V" + dutFile, - s"+define+PRINTF_COND=!$dutFile.reset", + 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, @@ -112,6 +112,8 @@ object Driver extends BackendCompilationUtilities { 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) 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/Chisel/Main.scala b/src/main/scala/chisel3/compatibility/Main.scala index a72debc3..a41599a3 100644 --- a/src/main/scala/Chisel/Main.scala +++ b/src/main/scala/chisel3/compatibility/Main.scala @@ -1,9 +1,11 @@ // See LICENSE for license details. -package Chisel +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") 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/Chisel/throwException.scala b/src/main/scala/chisel3/compatibility/throwException.scala index 702884aa..3e8b33e6 100644 --- a/src/main/scala/Chisel/throwException.scala +++ b/src/main/scala/chisel3/compatibility/throwException.scala @@ -1,6 +1,8 @@ // See LICENSE for license details. -package Chisel +package chisel3.compatibility + +import chisel3._ @deprecated("throwException doesn't exist in Chisel3", "3.0.0") @throws(classOf[Exception]) 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/Chisel/testers/BasicTester.scala b/src/main/scala/chisel3/testers/BasicTester.scala index d3e9e7c8..bd7d4027 100644 --- a/src/main/scala/Chisel/testers/BasicTester.scala +++ b/src/main/scala/chisel3/testers/BasicTester.scala @@ -1,15 +1,19 @@ // See LICENSE for license details. -package Chisel.testers -import Chisel._ +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 { +class BasicTester extends Module() { // The testbench has no IOs, rather it should communicate using printf, assert, and stop. - val io = new Bundle() + val io = IO(new Bundle()) def popCount(n: Long): Int = n.toBinaryString.count(_=='1') @@ -19,9 +23,10 @@ class BasicTester extends Module { * reset). If your definition of reset is not the encapsulating Module's * reset, you will need to gate this externally. */ - def stop() { + def stop()(implicit sourceInfo: SourceInfo) { + // TODO: rewrite this using library-style SourceInfo passing. when (!reset) { - pushCommand(Stop(Node(clock), 0)) + pushCommand(Stop(sourceInfo, Node(clock), 0)) } } diff --git a/src/main/scala/Chisel/testers/TesterDriver.scala b/src/main/scala/chisel3/testers/TesterDriver.scala index c0cdfb3f..586fa780 100644 --- a/src/main/scala/Chisel/testers/TesterDriver.scala +++ b/src/main/scala/chisel3/testers/TesterDriver.scala @@ -1,7 +1,8 @@ // See LICENSE for license details. -package Chisel.testers -import Chisel._ +package chisel3.testers + +import chisel3._ import scala.io.Source import scala.sys.process._ import java.io._ @@ -47,7 +48,7 @@ object TesterDriver extends BackendCompilationUtilities { // Use sys.Process to invoke a bunch of backend stuff, then run the resulting exe if ((firrtlToVerilog(target, path) #&& - verilogToCpp(target, path, additionalVFiles, cppHarness) #&& + verilogToCpp(target, target, path, additionalVFiles, cppHarness) #&& cppToExe(target, path)).! == 0) { executeExpectingSuccess(target, path) } else { diff --git a/src/main/scala/Chisel/util/Arbiter.scala b/src/main/scala/chisel3/util/Arbiter.scala index 16ae9be5..89bb644a 100644 --- a/src/main/scala/Chisel/util/Arbiter.scala +++ b/src/main/scala/chisel3/util/Arbiter.scala @@ -3,18 +3,27 @@ /** Arbiters in all shapes and sizes. */ -package Chisel +package chisel3.util -/** An I/O bundle for the Arbiter */ +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 = Vec(n, Decoupled(gen)).flip + val in = Flipped(Vec(n, Decoupled(gen))) val out = Decoupled(gen) - val chosen = UInt(OUTPUT, log2Up(n)) + val chosen = Output(UInt.width(log2Up(n))) } -/** Arbiter Control determining which producer has access */ -private object ArbiterCtrl -{ +/** 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)) @@ -25,7 +34,7 @@ private object ArbiterCtrl 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 = new ArbiterIO(gen, n) + val io = IO(new ArbiterIO(gen, n)) io.chosen := choice io.out.valid := io.in(io.chosen).valid @@ -79,27 +88,29 @@ class LockingArbiter[T <: Data](gen: T, n: Int, count: Int, needsLock: Option[T } /** Hardware module that is used to sequence n producers into 1 consumer. - Producers are chosen in round robin order. - - Example usage: - 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 + * 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 usage: - 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 - */ + * 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 = new ArbiterIO(gen, n) + val io = IO(new ArbiterIO(gen, n)) io.chosen := UInt(n-1) io.out.bits := io.in(n-1).bits 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/Chisel/util/Bitwise.scala b/src/main/scala/chisel3/util/Bitwise.scala index 239a295e..289d27b1 100644 --- a/src/main/scala/Chisel/util/Bitwise.scala +++ b/src/main/scala/chisel3/util/Bitwise.scala @@ -3,12 +3,24 @@ /** Miscellaneous circuit generators operating on bits. */ -package Chisel +package chisel3.util -object FillInterleaved -{ +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) - def apply(n: Int, in: Seq[Bool]): UInt = Vec(in.map(Fill(n, _))).toBits + + /** 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. @@ -19,35 +31,29 @@ object PopCount def apply(in: Bits): UInt = apply((0 until in.getWidth).map(in(_))) } -/** Fill fans out a UInt to multiple copies */ object Fill { - /** Fan out x n times */ + /** 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 0 => UInt.width(0) case 1 => x - case y if n > 1 => + 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(y + 1)).filter(i => (y & (1 << i)) != 0).map(p2(_))) + 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.") } } - /** Fan out x n times */ - def apply(n: Int, x: Bool): UInt = - if (n > 1) { - UInt(0,n) - x - } else { - apply(n, x: UInt) - } } -/** Litte/big bit endian convertion: reverse the order of the bits in a UInt. -*/ -object Reverse -{ +object Reverse { private def doit(in: UInt, length: Int): UInt = { if (length == 1) { in @@ -67,5 +73,7 @@ object Reverse Cat(doit(in(half-1,0), half), doit(in(length-1,half), length-half)) } } + /** Returns the input in bit-reversed order. Useful for little/big-endian conversion. + */ def apply(in: UInt): UInt = doit(in, in.getWidth) } diff --git a/src/main/scala/chisel3/util/Cat.scala b/src/main/scala/chisel3/util/Cat.scala 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/Chisel/util/Counter.scala b/src/main/scala/chisel3/util/Counter.scala index 872e830a..ba66d667 100644 --- a/src/main/scala/Chisel/util/Counter.scala +++ b/src/main/scala/chisel3/util/Counter.scala @@ -1,14 +1,19 @@ // See LICENSE for license details. -package Chisel +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. @@ -27,14 +32,27 @@ class Counter(val n: Int) { } } -/** Counter Object - * Example Usage: - * {{{ val countOn = Bool(true) // increment counter every clock cycle - * val myCounter = Counter(countOn, n) - * when ( myCounter.value === UInt(3) ) { ... } }}}*/ 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 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/Chisel/ImplicitConversions.scala b/src/main/scala/chisel3/util/ImplicitConversions.scala index 6a230022..4d816a19 100644 --- a/src/main/scala/Chisel/ImplicitConversions.scala +++ b/src/main/scala/chisel3/util/ImplicitConversions.scala @@ -1,6 +1,8 @@ // See LICENSE for license details. -package Chisel +package chisel3.util + +import chisel3._ object ImplicitConversions { implicit def intToUInt(x: Int): UInt = UInt(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/Chisel/util/Lookup.scala b/src/main/scala/chisel3/util/Lookup.scala index 54922fc4..9e909c0c 100644 --- a/src/main/scala/Chisel/util/Lookup.scala +++ b/src/main/scala/chisel3/util/Lookup.scala @@ -1,6 +1,8 @@ // See LICENSE for license details. -package Chisel +package chisel3.util + +import chisel3._ object ListLookup { def apply[T <: Data](addr: UInt, default: List[T], mapping: Array[(BitPat, List[T])]): List[T] = { diff --git a/src/main/scala/Chisel/util/Math.scala b/src/main/scala/chisel3/util/Math.scala index 5f8212d8..73665f0f 100644 --- a/src/main/scala/Chisel/util/Math.scala +++ b/src/main/scala/chisel3/util/Math.scala @@ -3,7 +3,9 @@ /** Scala-land math helper functions, like logs. */ -package Chisel +package chisel3.util + +import chisel3._ /** Compute the log2 rounded up with min value of 1 */ object log2Up { diff --git a/src/main/scala/Chisel/util/Mux.scala b/src/main/scala/chisel3/util/Mux.scala index a7d835f6..245de67e 100644 --- a/src/main/scala/Chisel/util/Mux.scala +++ b/src/main/scala/chisel3/util/Mux.scala @@ -3,13 +3,17 @@ /** Mux circuit generators. */ -package Chisel +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. + * select signal. Returns the output of the Mux tree. + * + * @note results undefined if multiple select signals are simultaneously high */ -object Mux1H -{ +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) @@ -19,39 +23,39 @@ object Mux1H } /** 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. + * can be enabled. Priority is given to the first select signal. + * + * Returns the output of the Mux tree. */ -object PriorityMux -{ - def apply[T <: Bits](in: Seq[(Bool, T)]): T = SeqUtils.priorityMux(in) - def apply[T <: Bits](sel: Seq[Bool], in: Seq[T]): T = apply(sel zip in) - def apply[T <: Bits](sel: Bits, in: Seq[T]): T = apply((0 until in.size).map(sel(_)), in) +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) } -/** MuxLookup creates a cascade of n Muxs to search for a key value */ +/** 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 <: Bits] (key: S, default: T, mapping: Seq[(S, T)]): T = { + 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 } - } -/** MuxCase returns the first value that is enabled in a map of values */ +/** 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 <: Bits] (default: T, mapping: Seq[(Bool, T)]): T = { + def apply[T <: Data] (default: T, mapping: Seq[(Bool, T)]): T = { var res = default for ((t, v) <- mapping.reverse){ res = Mux(t, v, res) diff --git a/src/main/scala/Chisel/util/OneHot.scala b/src/main/scala/chisel3/util/OneHot.scala index 73f27403..53ba8c3d 100644 --- a/src/main/scala/Chisel/util/OneHot.scala +++ b/src/main/scala/chisel3/util/OneHot.scala @@ -3,13 +3,19 @@ /** Circuit generators for working with one-hot representations. */ -package Chisel +package chisel3.util -/** Converts from One Hot Encoding to a UInt indicating which bit is active - * This is the inverse of [[Chisel.UIntToOH UIntToOH]]*/ +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(Vec(in)) - def apply(in: Vec[Bool]): UInt = apply(in.toBits, in.size) + 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 = { @@ -24,9 +30,9 @@ object OHToUInt { } } -/** @return the bit position of the trailing 1 in the input vector - * with the assumption that multiple bits of the input bit vector can be set - * @example {{{ data_out := PriorityEncoder(data_in) }}} +/** 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(_))) @@ -35,8 +41,7 @@ object PriorityEncoder { /** Returns the one hot encoding of the input UInt. */ -object UIntToOH -{ +object UIntToOH { def apply(in: UInt, width: Int = -1): UInt = if (width == -1) { UInt(1) << in @@ -45,11 +50,10 @@ object UIntToOH } } -/** Returns a bit vector in which only the least-significant 1 bit in - the input vector, if any, is set. +/** Returns a bit vector in which only the least-significant 1 bit in the input vector, if any, + * is set. */ -object PriorityEncoderOH -{ +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)) 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/Chisel/util/TransitName.scala b/src/main/scala/chisel3/util/TransitName.scala index ec5a11cc..ce6cb60f 100644 --- a/src/main/scala/Chisel/util/TransitName.scala +++ b/src/main/scala/chisel3/util/TransitName.scala @@ -1,5 +1,8 @@ -package Chisel +// See LICENSE for license details. +package chisel3.util + +import chisel3._ import internal.HasId object TransitName { @@ -15,7 +18,7 @@ object TransitName { from } def withSuffix[T<:HasId](suffix: String)(from: T, to: HasId): T = { - from.addPostnameHook((given_name: String) => {to.suggestName(given_name+suffix)}) + from.addPostnameHook((given_name: String) => {to.suggestName(given_name + suffix)}) from } } diff --git a/src/main/scala/Chisel/util/Valid.scala b/src/main/scala/chisel3/util/Valid.scala index 9e2202bb..3d153a2a 100644 --- a/src/main/scala/Chisel/util/Valid.scala +++ b/src/main/scala/chisel3/util/Valid.scala @@ -3,22 +3,24 @@ /** Wrappers for valid interfaces and associated circuit generators using them. */ -package Chisel +package chisel3.util -/** An I/O Bundle containing data and a signal determining if it is valid */ -class ValidIO[+T <: Data](gen2: T) extends Bundle +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 = Bool(OUTPUT) - val bits = gen2.cloneType.asOutput + val valid = Output(Bool()) + val bits = Output(gen.chiselCloneType) def fire(dummy: Int = 0): Bool = valid - override def cloneType: this.type = new ValidIO(gen2).asInstanceOf[this.type] + override def cloneType: this.type = Valid(gen).asInstanceOf[this.type] } -/** Adds a valid protocol to any interface. The standard used is - that the consumer uses the flipped interface. -*/ +/** Adds a valid protocol to any interface */ object Valid { - def apply[T <: Data](gen: T): ValidIO[T] = new ValidIO(gen) + def apply[T <: Data](gen: T): Valid[T] = new Valid(gen) } /** A hardware module that delays data coming down the pipeline @@ -32,7 +34,7 @@ object Valid { */ object Pipe { - def apply[T <: Data](enqValid: Bool, enqBits: T, latency: Int): ValidIO[T] = { + def apply[T <: Data](enqValid: Bool, enqBits: T, latency: Int): Valid[T] = { if (latency == 0) { val out = Wire(Valid(enqBits)) out.valid <> enqValid @@ -44,16 +46,16 @@ object Pipe apply(v, b, latency-1) } } - def apply[T <: Data](enqValid: Bool, enqBits: T): ValidIO[T] = apply(enqValid, enqBits, 1) - def apply[T <: Data](enq: ValidIO[T], latency: Int = 1): ValidIO[T] = apply(enq.valid, enq.bits, latency) + 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 = new Bundle { - val enq = Valid(gen).flip - val deq = Valid(gen) - } + 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 + +} |