diff options
Diffstat (limited to 'src/main')
| -rw-r--r-- | src/main/scala/chisel3/compatibility.scala | 1 | ||||
| -rw-r--r-- | src/main/scala/chisel3/util/Arbiter.scala | 13 | ||||
| -rw-r--r-- | src/main/scala/chisel3/util/Decoupled.scala | 95 | ||||
| -rw-r--r-- | src/main/scala/chisel3/util/Valid.scala | 18 | ||||
| -rw-r--r-- | src/main/scala/chisel3/util/random/PRNG.scala | 13 |
5 files changed, 108 insertions, 32 deletions
diff --git a/src/main/scala/chisel3/compatibility.scala b/src/main/scala/chisel3/compatibility.scala index ffbb7e27..d1e7b4f1 100644 --- a/src/main/scala/chisel3/compatibility.scala +++ b/src/main/scala/chisel3/compatibility.scala @@ -637,6 +637,7 @@ package object Chisel { final def toUInt(implicit compileOptions: CompileOptions): UInt = a.do_asUInt(DeprecatedSourceInfo, compileOptions) + final def toBools(implicit compileOptions: CompileOptions): Seq[Bool] = a.do_asBools(DeprecatedSourceInfo, compileOptions) } } diff --git a/src/main/scala/chisel3/util/Arbiter.scala b/src/main/scala/chisel3/util/Arbiter.scala index 135700fa..b68acae1 100644 --- a/src/main/scala/chisel3/util/Arbiter.scala +++ b/src/main/scala/chisel3/util/Arbiter.scala @@ -10,6 +10,7 @@ import chisel3.internal.naming.chiselName // can't use chisel3_ version because /** IO bundle definition for an Arbiter, which takes some number of ready-valid inputs and outputs * (selects) at most one. + * @groupdesc Signals The actual hardware fields of the Bundle * * @param gen data type * @param n number of inputs @@ -17,8 +18,20 @@ import chisel3.internal.naming.chiselName // can't use chisel3_ version because class ArbiterIO[T <: Data](private val gen: T, val n: Int) extends Bundle { // See github.com/freechipsproject/chisel3/issues/765 for why gen is a private val and proposed replacement APIs. +/** Input data, one per potential sender + * + * @group Signals + */ val in = Flipped(Vec(n, Decoupled(gen))) +/** Output data after arbitration + * + * @group Signals + */ val out = Decoupled(gen) +/** One-Hot vector indicating which output was chosen + * + * @group Signals + */ val chosen = Output(UInt(log2Ceil(n).W)) } diff --git a/src/main/scala/chisel3/util/Decoupled.scala b/src/main/scala/chisel3/util/Decoupled.scala index 060a684c..4b8b3eeb 100644 --- a/src/main/scala/chisel3/util/Decoupled.scala +++ b/src/main/scala/chisel3/util/Decoupled.scala @@ -16,6 +16,7 @@ import chisel3.internal.naming._ // can't use chisel3_ version because of compi * while the consumer uses the flipped interface (inputs bits). * The actual semantics of ready/valid are enforced via the use of concrete subclasses. * @param gen the type of data to be wrapped in Ready/Valid + * @groupdesc Signals The actual hardware fields of the Bundle */ abstract class ReadyValidIO[+T <: Data](gen: T) extends Bundle { @@ -26,8 +27,19 @@ abstract class ReadyValidIO[+T <: Data](gen: T) extends Bundle case _ => gen } +/** Indicates that the consumer is ready to accept the data this cycle + * @group Signals + */ val ready = Input(Bool()) + +/** Indicates that the producer has put valid data in 'bits' + * @group Signals + */ val valid = Output(Bool()) + +/** The data to be transferred when ready and valid are asserted at the same cycle + * @group Signals + */ val bits = Output(genType) } @@ -121,6 +133,7 @@ object Decoupled * Additionally, once 'valid' is raised it will never be lowered until after * 'ready' has also been raised. * @param gen the type of data to be wrapped in IrrevocableIO + * @groupdesc Signals The actual hardware fields of the Bundle */ class IrrevocableIO[+T <: Data](gen: T) extends ReadyValidIO[T](gen) @@ -161,6 +174,7 @@ object DeqIO { * @param gen The type of data to queue * @param entries The max number of entries in the queue. * @param hasFlush A boolean for whether the generated Queue is flushable + * @groupdesc Signals The hardware fields of the Bundle */ class QueueIO[T <: Data](private val gen: T, val entries: Int, val hasFlush: Boolean = false) extends Bundle { // See github.com/freechipsproject/chisel3/issues/765 for why gen is a private val and proposed replacement APIs. @@ -169,13 +183,21 @@ class QueueIO[T <: Data](private val gen: T, val entries: Int, val hasFlush: Boo * but internally, the queue implementation itself sits on the other side * of the interface so uses the flipped instance. */ - /** I/O to enqueue data (client is producer, and Queue object is consumer), is [[Chisel.DecoupledIO]] flipped. */ + /** I/O to enqueue data (client is producer, and Queue object is consumer), is [[Chisel.DecoupledIO]] flipped. + * @group Signals + */ val enq = Flipped(EnqIO(gen)) - /** I/O to dequeue data (client is consumer and Queue object is producer), is [[Chisel.DecoupledIO]]*/ + /** I/O to dequeue data (client is consumer and Queue object is producer), is [[Chisel.DecoupledIO]] + * @group Signals + */ val deq = Flipped(DeqIO(gen)) - /** The current amount of data in the queue */ + /** The current amount of data in the queue + * @group Signals + */ val count = Output(UInt(log2Ceil(entries + 1).W)) - /** When asserted, reset the enqueue and dequeue pointers, effectively flushing the queue (Optional IO for a flushable Queue)*/ + /** When asserted, reset the enqueue and dequeue pointers, effectively flushing the queue (Optional IO for a flushable Queue) + * @group Signals + */ val flush = if (hasFlush) Some(Input(Bool())) else None } @@ -227,7 +249,7 @@ class Queue[T <: Data](val gen: T, val full = ptr_match && maybe_full val do_enq = WireDefault(io.enq.fire) val do_deq = WireDefault(io.deq.fire) - val flush = io.flush.getOrElse(false.B) + val flush = io.flush.getOrElse(false.B) // when flush is high, empty the queue // Semantically, any enqueues happen before the flush. @@ -285,20 +307,26 @@ class Queue[T <: Data](val gen: T, } } -/** 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 - * - * @return output (dequeue) interface from the queue - * - * @example {{{ - * consumer.io.in <> Queue(producer.io.out, 16) - * }}} - */ +/** Factory for a generic hardware queue. */ object Queue { - /** Create a queue and supply a DecoupledIO containing the product. */ + /** Create a [[Queue]] and supply a [[DecoupledIO]] containing the product. + * + * @param enq input (enqueue) interface to the queue, also determines type of queue elements. + * @param entries depth (number of elements) of 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. + * @param useSyncReadMem True uses SyncReadMem instead of Mem as an internal memory element. + * @param flush Optional [[Bool]] signal, if defined, the [[Queue.hasFlush]] will be true, and connect correspond + * signal to [[Queue]] instance. + * @return output (dequeue) interface from the queue. + * + * @example {{{ + * consumer.io.in <> Queue(producer.io.out, 16) + * }}} + */ @chiselName def apply[T <: Data]( enq: ReadyValidIO[T], @@ -306,7 +334,7 @@ object Queue pipe: Boolean = false, flow: Boolean = false, useSyncReadMem: Boolean = false, - hasFlush: Boolean = false): DecoupledIO[T] = { + flush: Option[Bool] = None): DecoupledIO[T] = { if (entries == 0) { val deq = Wire(new DecoupledIO(chiselTypeOf(enq.bits))) deq.valid := enq.valid @@ -314,7 +342,8 @@ object Queue enq.ready := deq.ready deq } else { - val q = Module(new Queue(chiselTypeOf(enq.bits), entries, pipe, flow, useSyncReadMem, hasFlush)) + val q = Module(new Queue(chiselTypeOf(enq.bits), entries, pipe, flow, useSyncReadMem, flush.isDefined)) + q.io.flush.zip(flush).foreach(f => f._1 := f._2) 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 @@ -322,10 +351,25 @@ object Queue } } - /** 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. + /** Create a queue and supply a [[IrrevocableIO]] containing the product. + * Casting from [[DecoupledIO]] 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. + * + * @param enq [[DecoupledIO]] signal to enqueue. + * @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. + * @param useSyncReadMem True uses SyncReadMem instead of Mem as an internal memory element. + * @param flush Optional [[Bool]] signal, if defined, the [[Queue.hasFlush]] will be true, and connect correspond + * signal to [[Queue]] instance. + * @return a [[DecoupledIO]] signal which should connect to the dequeue signal. + * + * @example {{{ + * consumer.io.in <> Queue(producer.io.out, 16) + * }}} */ @chiselName def irrevocable[T <: Data]( @@ -333,8 +377,9 @@ object Queue entries: Int = 2, pipe: Boolean = false, flow: Boolean = false, - useSyncReadMem: Boolean = false): IrrevocableIO[T] = { - val deq = apply(enq, entries, pipe, flow, useSyncReadMem) + useSyncReadMem: Boolean = false, + flush: Option[Bool] = None): IrrevocableIO[T] = { + val deq = apply(enq, entries, pipe, flow, useSyncReadMem, flush) require(entries > 0, "Zero-entry queues don't guarantee Irrevocability") val irr = Wire(new IrrevocableIO(chiselTypeOf(deq.bits))) irr.bits := deq.bits diff --git a/src/main/scala/chisel3/util/Valid.scala b/src/main/scala/chisel3/util/Valid.scala index 4d348014..5d80502a 100644 --- a/src/main/scala/chisel3/util/Valid.scala +++ b/src/main/scala/chisel3/util/Valid.scala @@ -17,12 +17,17 @@ import chisel3._ * @tparam T the type of the data * @param gen some data * @see [[Valid$ Valid factory]] for concrete examples + * @groupdesc Signals The actual hardware fields of the Bundle */ class Valid[+T <: Data](gen: T) extends Bundle { - /** A bit that will be asserted when `bits` is valid */ + /** A bit that will be asserted when `bits` is valid + * @group Signals + */ val valid = Output(Bool()) - /** Some data */ + /** The data to be transferred, qualified by `valid` + * @group Signals + */ val bits = Output(gen) /** True when `valid` is asserted @@ -173,13 +178,18 @@ class Pipe[T <: Data](val gen: T, val latency: Int = 1)(implicit compileOptions: /** Interface for [[Pipe]]s composed of a [[Valid]] input and [[Valid]] output * @define notAQueue + * @groupdesc Signals Hardware fields of the Bundle */ class PipeIO extends Bundle { - /** [[Valid]] input */ + /** [[Valid]] input + * @group Signals + */ val enq = Input(Valid(gen)) - /** [[Valid]] output. Data will appear here `latency` cycles after being valid at `enq`. */ + /** [[Valid]] output. Data will appear here `latency` cycles after being valid at `enq`. + * @group Signals + */ val deq = Output(Valid(gen)) } diff --git a/src/main/scala/chisel3/util/random/PRNG.scala b/src/main/scala/chisel3/util/random/PRNG.scala index 9b42acf1..3a44385a 100644 --- a/src/main/scala/chisel3/util/random/PRNG.scala +++ b/src/main/scala/chisel3/util/random/PRNG.scala @@ -7,16 +7,23 @@ import chisel3.util.Valid /** Pseudo Random Number Generators (PRNG) interface * @param n the width of the LFSR + * @groupdesc Signals The actual hardware fields of the Bundle */ class PRNGIO(val n: Int) extends Bundle { - /** A [[chisel3.util.Valid Valid]] interface that can be used to set the seed (internal PRNG state) */ + /** A [[chisel3.util.Valid Valid]] interface that can be used to set the seed (internal PRNG state) + * @group Signals + */ val seed: Valid[Vec[Bool]] = Input(Valid(Vec(n, Bool()))) - /** When asserted, the PRNG will increment by one */ + /** When asserted, the PRNG will increment by one + * @group Signals + */ val increment: Bool = Input(Bool()) - /** The current state of the PRNG */ + /** The current state of the PRNG + * @group Signals + */ val out: Vec[Bool] = Output(Vec(n, Bool())) } |