diff options
Diffstat (limited to 'src/main')
21 files changed, 530 insertions, 278 deletions
diff --git a/src/main/scala/chisel3/Driver.scala b/src/main/scala/chisel3/Driver.scala index 5aeeef99..190b36bf 100644 --- a/src/main/scala/chisel3/Driver.scala +++ b/src/main/scala/chisel3/Driver.scala @@ -47,7 +47,7 @@ trait BackendCompilationUtilities { * C++ sources and headers as well as a makefile to compile them. * * @param dutFile name of the DUT .v without the .v extension - * @param name of the top-level module in the design + * @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 @@ -86,14 +86,17 @@ trait BackendCompilationUtilities { def executeExpectingFailure( prefix: String, dir: File, - assertionMsg: String = "Assertion failed"): Boolean = { + assertionMsg: String = ""): Boolean = { var triggered = false + val assertionMessageSupplied = assertionMsg != "" val e = Process(s"./V${prefix}", dir) ! ProcessLogger(line => { - triggered = triggered || line.contains(assertionMsg) + triggered = triggered || (assertionMessageSupplied && line.contains(assertionMsg)) System.out.println(line) // scalastyle:ignore regex }) - triggered + // Fail if a line contained an assertion or if we get a non-zero exit code + // or, we get a SIGABRT (assertion failure) and we didn't provide a specific assertion message + triggered || (e != 0 && (e != 134 || !assertionMessageSupplied)) } def executeExpectingSuccess(prefix: String, dir: File): Boolean = { diff --git a/src/main/scala/chisel3/compatibility.scala b/src/main/scala/chisel3/compatibility.scala index 56c92d24..d13fcb06 100644 --- a/src/main/scala/chisel3/compatibility.scala +++ b/src/main/scala/chisel3/compatibility.scala @@ -3,13 +3,27 @@ // 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 { +package object Chisel { // scalastyle:ignore package.object.name + implicit val defaultCompileOptions = chisel3.core.ExplicitCompileOptions.NotStrict type Direction = chisel3.core.Direction - val INPUT = chisel3.core.INPUT - val OUTPUT = chisel3.core.OUTPUT - val NO_DIR = chisel3.core.NO_DIR + 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 Flipped = chisel3.core.Flipped type Data = chisel3.core.Data val Wire = chisel3.core.Wire val Clock = chisel3.core.Clock @@ -54,6 +68,46 @@ package object Chisel { 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 @@ -62,7 +116,7 @@ package object Chisel { val throwException = chisel3.compatibility.throwException val debug = chisel3.compatibility.debug - object testers { + object testers { // scalastyle:ignore object.name type BasicTester = chisel3.testers.BasicTester val TesterDriver = chisel3.testers.TesterDriver } @@ -102,10 +156,27 @@ package object Chisel { val Counter = chisel3.util.Counter type DecoupledIO[+T <: Data] = chisel3.util.DecoupledIO[T] + val DecoupledIO = chisel3.util.Decoupled val Decoupled = chisel3.util.Decoupled - type EnqIO[T <: Data] = chisel3.util.EnqIO[T] - type DeqIO[T <: Data] = chisel3.util.DeqIO[T] - type DecoupledIOC[+T <: Data] = chisel3.util.DecoupledIOC[T] + 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 @@ -132,19 +203,9 @@ package object Chisel { val RegEnable = chisel3.util.RegEnable val ShiftRegister = chisel3.util.ShiftRegister - type ValidIO[+T <: Data] = chisel3.util.ValidIO[T] + 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] - - import chisel3.internal.firrtl.Width - implicit def fromBigIntToLiteral(x: BigInt): chisel3.fromBigIntToLiteral = - new chisel3.fromBigIntToLiteral(x) - implicit def fromIntToLiteral(x: Int): chisel3.fromIntToLiteral= - new chisel3.fromIntToLiteral(x) - implicit def fromStringToLiteral(x: String): chisel3.fromStringToLiteral= - new chisel3.fromStringToLiteral(x) - implicit def fromBooleanToLiteral(x: Boolean): chisel3.fromBooleanToLiteral= - new chisel3.fromBooleanToLiteral(x) } diff --git a/src/main/scala/chisel3/compatibility/debug.scala b/src/main/scala/chisel3/compatibility/debug.scala index c3966dae..d9f6e4b0 100644 --- a/src/main/scala/chisel3/compatibility/debug.scala +++ b/src/main/scala/chisel3/compatibility/debug.scala @@ -1,3 +1,5 @@ +// See LICENSE for license details. + package chisel3.compatibility import chisel3.core._ diff --git a/src/main/scala/chisel3/package.scala b/src/main/scala/chisel3/package.scala index 30e2b5c3..17ddd55a 100644 --- a/src/main/scala/chisel3/package.scala +++ b/src/main/scala/chisel3/package.scala @@ -1,16 +1,21 @@ -package object chisel3 { +// 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 NO_DIR = chisel3.core.NO_DIR - type Flipped = chisel3.core.Flipped + 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 @@ -76,31 +81,6 @@ package object chisel3 { val FullName = chisel3.core.FullName val Percent = chisel3.core.Percent - 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) - } - - 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 - def do_!= (that: BitPat)(implicit sourceInfo: SourceInfo): Bool = that != x - def do_=/= (that: BitPat)(implicit sourceInfo: SourceInfo): Bool = that =/= x - } - /** Implicit for custom Printable string interpolator */ implicit class PrintableHelper(val sc: StringContext) extends AnyVal { /** Custom string interpolator for generating Printables: p"..." @@ -130,4 +110,88 @@ package object chisel3 { } 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 index f91536d5..bd7d4027 100644 --- a/src/main/scala/chisel3/testers/BasicTester.scala +++ b/src/main/scala/chisel3/testers/BasicTester.scala @@ -9,10 +9,11 @@ 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') diff --git a/src/main/scala/chisel3/util/Arbiter.scala b/src/main/scala/chisel3/util/Arbiter.scala index eb541977..89bb644a 100644 --- a/src/main/scala/chisel3/util/Arbiter.scala +++ b/src/main/scala/chisel3/util/Arbiter.scala @@ -6,17 +6,24 @@ package chisel3.util import chisel3._ - -/** An I/O bundle for the Arbiter */ +// 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)) @@ -27,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 @@ -81,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 index 26106080..972010a6 100644 --- a/src/main/scala/chisel3/util/BitPat.scala +++ b/src/main/scala/chisel3/util/BitPat.scala @@ -37,7 +37,7 @@ object BitPat { /** Creates a [[BitPat]] literal from a string. * * @param n the literal value as a string, in binary, prefixed with 'b' - * @note legal characters are '0', '1', and '?', as well as '_' as white + * @note legal characters are '0', '1', and '?', as well as '_' and white * space (which are ignored) */ def apply(n: String): BitPat = { @@ -76,7 +76,7 @@ object BitPat { // TODO: Break out of Core? (this doesn't involve FIRRTL generation) /** Bit patterns are literals with masks, used to represent values with don't * cares. Equality comparisons will ignore don't care bits (for example, - * BitPat(0b10?1) === UInt(0b1001) and UInt(0b1011)). + * BitPat(0b10?1) === 0b1001.asUInt and 0b1011.asUInt. */ sealed class BitPat(val value: BigInt, val mask: BigInt, width: Int) { def getWidth: Int = width @@ -84,7 +84,7 @@ sealed class BitPat(val value: BigInt, val mask: BigInt, width: Int) { def =/= (that: UInt): Bool = macro SourceInfoTransform.thatArg def != (that: UInt): Bool = macro SourceInfoTransform.thatArg - def do_=== (that: UInt)(implicit sourceInfo: SourceInfo): Bool = UInt(value, width) === (that & UInt(mask)) - def do_=/= (that: UInt)(implicit sourceInfo: SourceInfo): Bool = !(this === that) - def do_!= (that: UInt)(implicit sourceInfo: SourceInfo): Bool = this =/= that + 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 index 6451ab14..289d27b1 100644 --- a/src/main/scala/chisel3/util/Bitwise.scala +++ b/src/main/scala/chisel3/util/Bitwise.scala @@ -8,9 +8,18 @@ package chisel3.util import chisel3._ import chisel3.core.SeqUtils -object FillInterleaved -{ +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) } @@ -22,12 +31,14 @@ 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 _ if x.isWidthKnown && x.getWidth == 1 => Mux(x.toBool, UInt((BigInt(1) << n) - 1, n), UInt(0, n)) @@ -42,10 +53,7 @@ object Fill { } } -/** 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 @@ -65,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 index 469bf9ab..ba12a7d4 100644 --- a/src/main/scala/chisel3/util/Cat.scala +++ b/src/main/scala/chisel3/util/Cat.scala @@ -6,16 +6,15 @@ import chisel3._ import chisel3.core.SeqUtils 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 + /** Concatenates the argument data elements, in argument order, 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 + /** 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 index a64447d9..d478e10e 100644 --- a/src/main/scala/chisel3/util/CircuitMath.scala +++ b/src/main/scala/chisel3/util/CircuitMath.scala @@ -7,13 +7,11 @@ package chisel3.util import chisel3._ -/** Compute the base-2 integer logarithm of a UInt - * @example - * {{{ data_out := Log2(data_in) }}} - * @note The result is truncated, so e.g. Log2(UInt(13)) = 3 - */ object Log2 { - /** Compute the Log2 on the least significant n bits of x */ + /** 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) @@ -30,6 +28,10 @@ object Log2 { } } + /** 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 index 6218feb0..5830e014 100644 --- a/src/main/scala/chisel3/util/Conditional.scala +++ b/src/main/scala/chisel3/util/Conditional.scala @@ -12,50 +12,71 @@ import scala.reflect.macros.blackbox._ import chisel3._ -/** This is identical to [[Chisel.when when]] with the condition inverted */ 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 } + 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 */ +/** 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 - // Begin deprecation of non-type-parameterized is statements. + // 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 - * @example - * {{{ ... // default values here - * switch ( myState ) { - * is( state1 ) { - * ... // some logic here +/** 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 + * 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._ diff --git a/src/main/scala/chisel3/util/Counter.scala b/src/main/scala/chisel3/util/Counter.scala index 1c95190b..ba66d667 100644 --- a/src/main/scala/chisel3/util/Counter.scala +++ b/src/main/scala/chisel3/util/Counter.scala @@ -3,14 +3,17 @@ 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. @@ -29,14 +32,27 @@ class Counter(val n: Int) { } } -/** Counter Object - * Example Usage: - * {{{ val countOn = Bool(true) // increment counter every clock cycle - * val (myCounterValue, myCounterWrap) = Counter(countOn, n) - * when ( myCounterValue === 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 index 77990777..a0cbf4f7 100644 --- a/src/main/scala/chisel3/util/Decoupled.scala +++ b/src/main/scala/chisel3/util/Decoupled.scala @@ -6,6 +6,8 @@ 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. @@ -15,16 +17,56 @@ import chisel3._ */ abstract class ReadyValidIO[+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 + val ready = Input(Bool()) + val valid = Output(Bool()) + val bits = Output(gen.chiselCloneType) } -/** A concrete subclass of ReadyValidIO signalling that the user expects a +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 signalling + * 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) @@ -35,21 +77,24 @@ class DecoupledIO[+T <: Data](gen: T) extends ReadyValidIO[T](gen) /** This factory adds a decoupled handshaking protocol to a data bundle. */ object Decoupled { - /** Take any Data and wrap it in a DecoupledIO interface */ + /** Wraps some Data with a DecoupledIO interface. */ def apply[T <: Data](gen: T): DecoupledIO[T] = new DecoupledIO(gen) - /** Take an IrrevocableIO and cast it to a DecoupledIO. - * This cast is only safe to do in cases where the IrrevocableIO - * is being produced as an output. + /** 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.dir == OUTPUT, "Only safe to cast produced Irrevocable bits to Decoupled.") + 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 @@ -67,12 +112,13 @@ object Irrevocable { def apply[T <: Data](gen: T): IrrevocableIO[T] = new IrrevocableIO(gen) - /** Take a DecoupledIO and cast it to an IrrevocableIO. - * This cast is only safe to do in cases where the IrrevocableIO - * is being consumed as an input. + /** 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.dir == INPUT, "Only safe to cast consumed Decoupled bits to Irrevocable.") + 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 @@ -81,58 +127,11 @@ object Irrevocable } } - -/** 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]; } +object EnqIO { + def apply[T<:Data](gen: T): DecoupledIO[T] = Decoupled(gen) } - -/** 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 +object DeqIO { + def apply[T<:Data](gen: T): DecoupledIO[T] = Flipped(Decoupled(gen)) } /** An I/O Bundle for Queues @@ -141,11 +140,11 @@ class DecoupledIOC[+T <: Data](gen: T) extends Bundle 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() + val enq = DeqIO(gen) /** I/O to enqueue data, is [[Chisel.DecoupledIO]]*/ - val deq = Decoupled(gen.cloneType) + val deq = EnqIO(gen) /** The current amount of data in the queue */ - val count = UInt(OUTPUT, log2Up(entries + 1)) + val count = Output(UInt.width(log2Up(entries + 1))) } /** A hardware module implementing a Queue @@ -156,10 +155,11 @@ class QueueIO[T <: Data](gen: T, entries: Int) extends Bundle * @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 }}} + * @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, @@ -170,7 +170,7 @@ 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 io = IO(new QueueIO(gen, entries)) val ram = Mem(entries, gen) val enq_ptr = Counter(entries) @@ -223,12 +223,16 @@ extends Module(override_reset=override_reset) { } } -/** Factory for a generic hardware queue. Required parameter 'entries' controls - * the depth of the queues. The width of the queue is determined - * from the input 'enq'. +/** 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 usage: - * {{{ consumer.io.in <> Queue(producer.io.out, 16) }}} + * @example {{{ + * consumer.io.in <> Queue(producer.io.out, 16) + * }}} */ object Queue { diff --git a/src/main/scala/chisel3/util/Enum.scala b/src/main/scala/chisel3/util/Enum.scala index 4ecc243b..55b595ee 100644 --- a/src/main/scala/chisel3/util/Enum.scala +++ b/src/main/scala/chisel3/util/Enum.scala @@ -12,12 +12,42 @@ object Enum { 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 */ + /** 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 - /** create enum values of given type and names */ + /** 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 - /** create enum values of given type and names */ + /** 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/LFSR.scala b/src/main/scala/chisel3/util/LFSR.scala index a30c276f..fedbf194 100644 --- a/src/main/scala/chisel3/util/LFSR.scala +++ b/src/main/scala/chisel3/util/LFSR.scala @@ -6,14 +6,16 @@ package chisel3.util import chisel3._ +//import chisel3.core.ExplicitCompileOptions.Strict // scalastyle:off magic.number -/** linear feedback shift register - */ -object LFSR16 -{ - def apply(increment: Bool = Bool(true)): UInt = - { +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)) } diff --git a/src/main/scala/chisel3/util/Mux.scala b/src/main/scala/chisel3/util/Mux.scala index 9956a7e3..245de67e 100644 --- a/src/main/scala/chisel3/util/Mux.scala +++ b/src/main/scala/chisel3/util/Mux.scala @@ -9,10 +9,11 @@ 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) @@ -22,18 +23,17 @@ 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 -{ +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 @@ -46,10 +46,11 @@ object MuxLookup { 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 diff --git a/src/main/scala/chisel3/util/OneHot.scala b/src/main/scala/chisel3/util/OneHot.scala index 7e04a8d7..53ba8c3d 100644 --- a/src/main/scala/chisel3/util/OneHot.scala +++ b/src/main/scala/chisel3/util/OneHot.scala @@ -7,8 +7,12 @@ package chisel3.util import chisel3._ -/** Converts from One Hot Encoding to a UInt indicating which bit is active - * This is the inverse of [[Chisel.UIntToOH UIntToOH]]*/ +/** 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) @@ -26,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(_))) @@ -37,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 @@ -47,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 index 81de4754..713a3b2e 100644 --- a/src/main/scala/chisel3/util/Reg.scala +++ b/src/main/scala/chisel3/util/Reg.scala @@ -1,34 +1,43 @@ // See LICENSE for license details. -/** Variations and helpers for registers. - */ - 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) - } -/** A register with an Enable signal */ -object RegEnable -{ +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 r = Reg(updateData) + 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 } @@ -36,15 +45,15 @@ object RegEnable } } -/** Returns the n-cycle delayed version of the input signal. - */ object ShiftRegister { - /** @param in input to delay + /** 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 = - { + * @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) diff --git a/src/main/scala/chisel3/util/TransitName.scala b/src/main/scala/chisel3/util/TransitName.scala index f36f926f..a3220a13 100644 --- a/src/main/scala/chisel3/util/TransitName.scala +++ b/src/main/scala/chisel3/util/TransitName.scala @@ -1,22 +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 { - // The purpose of this 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 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.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 index 78187ff6..3d153a2a 100644 --- a/src/main/scala/chisel3/util/Valid.scala +++ b/src/main/scala/chisel3/util/Valid.scala @@ -6,21 +6,21 @@ 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 data and a signal determining if it is valid */ -class ValidIO[+T <: Data](gen2: T) extends Bundle +/** 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 @@ -34,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 @@ -46,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 + +} |