Packages

p

chisel3

util

package util

The util package provides extensions to core chisel for common hardware components and utility functions

Source
util.scala
Linear Supertypes
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. util
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Type Members

  1. class Arbiter[T <: Data] extends Module

    Hardware module that is used to sequence n producers into 1 consumer.

    Hardware module that is used to sequence n producers into 1 consumer. Priority is given to lower producer.

    Example:
    1. val arb = Module(new Arbiter(UInt(), 2))
      arb.io.in(0) <> producer0.io.out
      arb.io.in(1) <> producer1.io.out
      consumer.io.in <> arb.io.out
  2. class ArbiterIO[T <: Data] extends Bundle

    IO bundle definition for an Arbiter, which takes some number of ready-valid inputs and outputs (selects) at most one.

  3. sealed class BitPat extends SourceInfoDoc

    Bit patterns are literals with masks, used to represent values with don't care bits.

    Bit patterns are literals with masks, used to represent values with don't care bits. Equality comparisons will ignore don't care bits.

    Example:
    1. "b10101".U === BitPat("b101??") // evaluates to true.B
      "b10111".U === BitPat("b101??") // evaluates to true.B
      "b10001".U === BitPat("b101??") // evaluates to false.B
  4. class Counter extends AnyRef

    Used to generate an inline (logic directly in the containing Module, no internal Module is created) hardware counter.

    Used to generate an inline (logic directly in the containing Module, no internal Module is created) hardware counter.

    Typically instantiated with apply methods in object Counter

    Does not create a new Chisel Module

    Example:
    1. val countOn = true.B // increment counter every clock cycle
      val (counterValue, counterWrap) = Counter(countOn, 4)
      when (counterValue === 3.U) {
        ...
      }
  5. class DecoupledIO[+T <: Data] extends ReadyValidIO[T]

    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.

    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.

  6. trait Enum extends AnyRef

    Defines a set of unique UInt constants

    Defines a set of unique UInt constants

    Unpack with a list to specify an enumeration. Usually used with switch to describe a finite state machine.

    Example:
    1. val state_on :: state_off :: Nil = Enum(2)
      val current_state = WireDefault(state_off)
      switch (current_state) {
        is (state_on) {
          ...
        }
        is (state_off) {
          ...
        }
      }
  7. trait HasBlackBoxInline extends BlackBox
  8. trait HasBlackBoxPath extends BlackBox
  9. trait HasBlackBoxResource extends BlackBox
  10. class IrrevocableIO[+T <: Data] extends ReadyValidIO[T]

    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.

    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.

  11. class LockingArbiter[T <: Data] extends LockingArbiterLike[T]
  12. abstract class LockingArbiterLike[T <: Data] extends Module
  13. class LockingRRArbiter[T <: Data] extends LockingArbiterLike[T]
  14. final class MixedVec[T <: Data] extends Record with IndexedSeq[T]

    A hardware array of elements that can hold values of different types/widths, unlike Vec which can only hold elements of the same type/width.

    A hardware array of elements that can hold values of different types/widths, unlike Vec which can only hold elements of the same type/width.

    Example:
    1. val v = Wire(MixedVec(Seq(UInt(8.W), UInt(16.W), UInt(32.W))))
      v(0) := 100.U(8.W)
      v(1) := 10000.U(16.W)
      v(2) := 101.U(32.W)
  15. class Pipe[T <: Data] extends Module

    Pipeline module generator parameterized by data type and latency.

    Pipeline module generator parameterized by data type and latency.

    This defines a module with one input, enq, and one output, deq. The input and output are Valid interfaces that wrap some Chisel type, e.g., a UInt or a Bundle. This generator will then chain together a number of pipeline stages that all advance when the input Valid enq fires. The output deq Valid will fire only when valid data has made it all the way through the pipeline.

    As an example, to construct a 4-stage pipe of 8-bit UInts and connect it to a producer and consumer, you can use the following:

    val foo = Module(new Pipe(UInt(8.W)), 4)
    pipe.io.enq := producer.io
    consumer.io := pipe.io.deq

    If you already have the Valid input or the components of a Valid interface, it may be simpler to use the Pipe factory companion object. This, which Pipe internally utilizes, will automatically connect the input for you.

    See also

    Pipe factory for an alternative API

    Valid interface

    Queue and the Queue factory for actual queues

    The ShiftRegister factory to generate a pipe without a Valid interface

  16. class Queue[T <: Data] extends Module

    A hardware module implementing a Queue

    A hardware module implementing a Queue

    Example:
    1. val q = Module(new Queue(UInt(), 16))
      q.io.enq <> producer.io.out
      consumer.io.in <> q.io.deq
  17. class QueueIO[T <: Data] extends Bundle

    An I/O Bundle for Queues

  18. class RRArbiter[T <: Data] extends LockingRRArbiter[T]

    Hardware module that is used to sequence n producers into 1 consumer.

    Hardware module that is used to sequence n producers into 1 consumer. Producers are chosen in round robin order.

    Example:
    1. val arb = Module(new RRArbiter(UInt(), 2))
      arb.io.in(0) <> producer0.io.out
      arb.io.in(1) <> producer1.io.out
      consumer.io.in <> arb.io.out
  19. abstract class ReadyValidIO[+T <: Data] extends Bundle

    An I/O Bundle containing 'valid' and 'ready' signals that handshake the transfer of data stored in the 'bits' subfield.

    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 producer uses the interface as-is (outputs bits) while the consumer uses the flipped interface (inputs bits). The actual semantics of ready/valid are enforced via the use of concrete subclasses.

  20. class SwitchContext[T <: Element] extends AnyRef

    Implementation details for switch.

    Implementation details for switch. See switch and is for the user-facing API.

    Note

    DO NOT USE. This API is subject to change without warning.

  21. class Valid[+T <: Data] extends Bundle

    A Bundle that adds a valid bit to some data.

    A Bundle that adds a valid bit to some data. This indicates that the user expects a "valid" interface between a producer and a consumer. Here, the producer asserts the valid bit when data on the bits line contains valid data. This differs from DecoupledIO or IrrevocableIO as there is no ready line that the consumer can use to put back pressure on the producer.

    In most scenarios, the Valid class will not be used directly. Instead, users will create Valid interfaces using the Valid factory.

    T

    the type of the data

    See also

    Valid factory for concrete examples

  22. type ValidIO[+T <: Data] = Valid[T]

    Synonyms, moved from main package object - maintain scope.

Value Members

  1. val DecoupledIO: Decoupled.type
  2. val ValidIO: Valid.type
  3. object BitPat
  4. object Cat

    Concatenates elements of the input, in order, together.

    Concatenates elements of the input, in order, together.

    Example:
    1. Cat("b101".U, "b11".U)  // equivalent to "b101 11".U
      Cat(myUIntWire0, myUIntWire1)
      
      Cat(Seq("b101".U, "b11".U))  // equivalent to "b101 11".U
      Cat(mySeqOfBits)
  5. object Counter
  6. object Decoupled

    This factory adds a decoupled handshaking protocol to a data bundle.

  7. object DeqIO

    Consumer - drives (outputs) ready, inputs valid and bits.

  8. object EnqIO

    Producer - drives (outputs) valid and bits, inputs ready.

  9. object Enum extends Enum
  10. object Fill

    Create repetitions of the input using a tree fanout topology.

    Create repetitions of the input using a tree fanout topology.

    Example:
    1. Fill(2, "b1000".U)  // equivalent to "b1000 1000".U
      Fill(2, "b1001".U)  // equivalent to "b1001 1001".U
      Fill(2, myUIntWire)  // dynamic fill
  11. object FillInterleaved

    Creates repetitions of each bit of the input in order.

    Creates repetitions of each bit of the input in order.

    Example:
    1. FillInterleaved(2, "b1 0 0 0".U)  // equivalent to "b11 00 00 00".U
      FillInterleaved(2, "b1 0 0 1".U)  // equivalent to "b11 00 00 11".U
      FillInterleaved(2, myUIntWire)  // dynamic interleaved fill
      
      FillInterleaved(2, Seq(true.B, false.B, false.B, false.B))  // equivalent to "b11 00 00 00".U
      FillInterleaved(2, Seq(true.B, false.B, false.B, true.B))  // equivalent to "b11 00 00 11".U
  12. object ImplicitConversions

    Implicit conversions to automatically convert scala.Boolean and scala.Int to Bool and UInt respectively

  13. object Irrevocable

    Factory adds an irrevocable handshaking protocol to a data bundle.

  14. object ListLookup

    For each element in a list, muxes (looks up) between cases (one per list element) based on a common address.

    For each element in a list, muxes (looks up) between cases (one per list element) based on a common address.

    Example:
    1. ListLookup(2.U,  // address for comparison
                               List(10.U, 11.U, 12.U),   // default "row" if none of the following cases match
          Array(BitPat(2.U) -> List(20.U, 21.U, 22.U),  // this "row" hardware-selected based off address 2.U
                BitPat(3.U) -> List(30.U, 31.U, 32.U))
      ) // hardware-evaluates to List(20.U, 21.U, 22.U)
      // Note: if given address 0.U, the above would hardware evaluate to List(10.U, 11.U, 12.U)
    Note

    This appears to be an odd, specialized operator that we haven't seen used much, and seems to be a holdover from chisel2. This may be deprecated and removed, usage is not recommended.

  15. object Log2

    Returns the base-2 integer logarithm of an UInt.

    Returns the base-2 integer logarithm of an UInt.

    Example:
    1. Log2(8.U)  // evaluates to 3.U
      Log2(13.U)  // evaluates to 3.U (truncation)
      Log2(myUIntWire)
    Note

    The result is truncated, so e.g. Log2(13.U) === 3.U

  16. object Lookup

    Muxes between cases based on whether an address matches any pattern for a case.

    Muxes between cases based on whether an address matches any pattern for a case. Similar to MuxLookup, but uses BitPat for address comparison.

    Note

    This appears to be an odd, specialized operator that we haven't seen used much, and seems to be a holdover from chisel2. This may be deprecated and removed, usage is not recommended.

  17. object MixedVec

    Create a MixedVec type, given element types.

    Create a MixedVec type, given element types. Inputs must be Chisel types which have no value (not hardware types).

    returns

    MixedVec with the given types.

  18. object MixedVecInit

    Create a MixedVec wire with default values as specified, and type of each element inferred from those default values.

    Create a MixedVec wire with default values as specified, and type of each element inferred from those default values.

    This is analogous to VecInit.

    returns

    MixedVec with given values assigned

    Example:
    1. MixedVecInit(Seq(100.U(8.W), 10000.U(16.W), 101.U(32.W)))
  19. object Mux1H

    Builds a Mux tree out of the input signal vector using a one hot encoded select signal.

    Builds a Mux tree out of the input signal vector using a one hot encoded select signal. Returns the output of the Mux tree.

    Example:
    1. val hotValue = chisel3.util.Mux1H(Seq(
       io.selector(0) -> 2.U,
       io.selector(1) -> 4.U,
       io.selector(2) -> 8.U,
       io.selector(4) -> 11.U,
      ))
    Note

    results undefined if multiple select signals are simultaneously high

  20. object MuxCase

    Given an association of values to enable signals, returns the first value with an associated high enable signal.

    Given an association of values to enable signals, returns the first value with an associated high enable signal.

    Example:
    1. MuxCase(default, Array(c1 -> a, c2 -> b))
  21. object 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.

    Example:
    1. MuxLookup(idx, default,
          Array(0.U -> a, 1.U -> b))
  22. object OHToUInt

    Returns the bit position of the sole high bit of the input bitvector.

    Returns the bit position of the sole high bit of the input bitvector.

    Inverse operation of UIntToOH.

    Example:
    1. OHToUInt("b0100".U) // results in 2.U
    Note

    assumes exactly one high bit, results undefined otherwise

  23. object Pipe

    A factory to generate a hardware pipe.

    A factory to generate a hardware pipe. This can be used to delay Valid data by a design-time configurable number of cycles.

    Here, we construct three different pipes using the different provided apply methods and hook them up together. The types are explicitly specified to show that these all communicate using Valid interfaces:

    val in: Valid[UInt]  = Wire(Valid(UInt(2.W)))
    
    /* A zero latency (combinational) pipe is connected to 'in' */
    val foo: Valid[UInt] = Pipe(in.valid, in.bits, 0)
    
    /* A one-cycle pipe is connected to the output of 'foo' */
    val bar: Valid[UInt] = Pipe(foo.valid, foo.bits)
    
    /* A two-cycle pipe is connected to the output of 'bar' */
    val baz: Valid[UInt] = Pipe(bar, 2)
    See also

    Pipe class for an alternative API

    Valid interface

    Queue and the Queue factory for actual queues

    The ShiftRegister factory to generate a pipe without a Valid interface

  24. object PopCount

    Returns the number of bits set (value is 1 or true) in the input signal.

    Returns the number of bits set (value is 1 or true) in the input signal.

    Example:
    1. PopCount(Seq(true.B, false.B, true.B, true.B))  // evaluates to 3.U
      PopCount(Seq(false.B, false.B, true.B, false.B))  // evaluates to 1.U
      
      PopCount("b1011".U)  // evaluates to 3.U
      PopCount("b0010".U)  // evaluates to 1.U
      PopCount(myUIntWire)  // dynamic count
  25. object PriorityEncoder

    Returns the bit position of the least-significant high bit of the input bitvector.

    Returns the bit position of the least-significant high bit of the input bitvector.

    Example:
    1. PriorityEncoder("b0110".U) // results in 1.U

      Multiple bits may be high in the input.

  26. object PriorityEncoderOH

    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.

    Example:
    1. PriorityEncoderOH((false.B, true.B, true.B, false.B)) // results in (false.B, false.B, true.B, false.B)
  27. object PriorityMux

    Builds a Mux tree under the assumption that multiple select signals can be enabled.

    Builds a Mux tree under the assumption that multiple select signals can be enabled. Priority is given to the first select signal.

    Example:
    1. val hotValue = chisel3.util.PriorityMux(Seq(
       io.selector(0) -> 2.U,
       io.selector(1) -> 4.U,
       io.selector(2) -> 8.U,
       io.selector(4) -> 11.U,
      ))

      Returns the output of the Mux tree.

  28. object Queue

    Factory for a generic hardware queue.

    Factory for a generic hardware queue.

    returns

    output (dequeue) interface from the queue

    Example:
    1. consumer.io.in <> Queue(producer.io.out, 16)
  29. object ReadyValidIO
  30. object RegEnable
  31. object Reverse

    Returns the input in bit-reversed order.

    Returns the input in bit-reversed order. Useful for little/big-endian conversion.

    Example:
    1. Reverse("b1101".U)  // equivalent to "b1011".U
      Reverse("b1101".U(8.W))  // equivalent to "b10110000".U
      Reverse(myUIntWire)  // dynamic reverse
  32. object ShiftRegister
  33. object TransitName

    The purpose of TransitName is to improve the naming of some object created in a different scope by "transiting" the name from the outer scope to the inner scope.

    The purpose of TransitName is to improve the naming of some object created in a different scope by "transiting" the name from the outer scope to the inner scope.

    Consider the example below. This shows three ways of instantiating MyModule and returning the IO. Normally, the instance will be named MyModule. However, it would be better if the instance was named using the name of the val that user provides for the returned IO. TransitName can then be used to "transit" the name from the IO to the module:

    /* Assign the IO of a new MyModule instance to value "foo". The instance will be named "MyModule". */
    val foo = Module(new MyModule).io
    
    /* Assign the IO of a new MyModule instance to value "bar". The instance will be named "bar". */
    val bar = {
      val x = Module(new MyModule)
      TransitName(x.io, x) // TransitName returns the first argument
    }
    
    /* Assign the IO of a new MyModule instance to value "baz". The instance will be named "baz_generated". */
    val baz = {
      val x = Module(new MyModule)
      TransitName.withSuffix("_generated")(x.io, x) // TransitName returns the first argument
    }

    TransitName helps library writers following the Factory Method Pattern where modules may be instantiated inside an enclosing scope. For an example of this, see how the Queue factory uses TransitName in Decoupled.scala factory.

  34. object UIntToOH

    Returns the one hot encoding of the input UInt.

    Returns the one hot encoding of the input UInt.

    Example:
    1. UIntToOH(2.U) // results in "b0100".U
  35. object Valid

    Factory for generating "valid" interfaces.

    Factory for generating "valid" interfaces. A "valid" interface is a data-communicating interface between a producer and a consumer where the producer does not wait for the consumer. Concretely, this means that one additional bit is added to the data indicating its validity.

    As an example, consider the following Bundle, MyBundle:

    class MyBundle extends Bundle {
      val foo = Output(UInt(8.W))
    }

    To convert this to a "valid" interface, you wrap it with a call to the Valid companion object's apply method:

    val bar = Valid(new MyBundle)

    The resulting interface is structurally equivalent to the following:

    class MyValidBundle extends Bundle {
      val valid = Output(Bool())
      val bits = Output(new MyBundle)
    }

    In addition to adding the valid bit, a Valid.fire method is also added that returns the valid bit. This provides a similarly named interface to DecoupledIO's fire.

    See also

    DecoupledIO Factory

    IrrevocableIO Factory

  36. object is

    Use to specify cases in a switch block, equivalent to a when block comparing to the condition variable.

    Use to specify cases in a switch block, equivalent to a when block comparing to the condition variable.

    Note

    illegal outside a switch block

    ,

    must be a literal

    ,

    each is must be mutually exclusive

    ,

    dummy implementation, a macro inside switch transforms this into the actual implementation

  37. object isPow2

    Returns whether a Scala integer is a power of two.

    Returns whether a Scala integer is a power of two.

    Example:
    1. isPow2(1)  // returns true
      isPow2(2)  // returns true
      isPow2(3)  // returns false
      isPow2(4)  // returns true
  38. object log2Ceil

    Compute the log2 of a Scala integer, rounded up.

    Compute the log2 of a Scala integer, rounded up. Useful for getting the number of bits needed to represent some number of states (in - 1). To get the number of bits needed to represent some number n, use log2Ceil(n + 1).

    Note: can return zero, and should not be used in cases where it may generate unsupported zero-width wires.

    Example:
    1. log2Ceil(1)  // returns 0
      log2Ceil(2)  // returns 1
      log2Ceil(3)  // returns 2
      log2Ceil(4)  // returns 2
  39. object log2Down

    Compute the log2 of a Scala integer, rounded down, with min value of 1.

    Compute the log2 of a Scala integer, rounded down, with min value of 1.

    Example:
    1. log2Down(1)  // returns 1
      log2Down(2)  // returns 1
      log2Down(3)  // returns 1
      log2Down(4)  // returns 2
  40. object log2Floor

    Compute the log2 of a Scala integer, rounded down.

    Compute the log2 of a Scala integer, rounded down.

    Can be useful in computing the next-smallest power of two.

    Example:
    1. log2Floor(1)  // returns 0
      log2Floor(2)  // returns 1
      log2Floor(3)  // returns 1
      log2Floor(4)  // returns 2
  41. object log2Up

    Compute the log2 of a Scala integer, rounded up, with min value of 1.

    Compute the log2 of a Scala integer, rounded up, with min value of 1. Useful for getting the number of bits needed to represent some number of states (in - 1), To get the number of bits needed to represent some number n, use log2Up(n + 1). with the minimum value preventing the creation of currently-unsupported zero-width wires.

    Note: prefer to use log2Ceil when in is known to be > 1 (where log2Ceil(in) > 0). This will be deprecated when zero-width wires is supported.

    Example:
    1. log2Up(1)  // returns 1
      log2Up(2)  // returns 1
      log2Up(3)  // returns 2
      log2Up(4)  // returns 2
  42. object signedBitLength
  43. object switch

    Conditional logic to form a switch block.

    Conditional logic to form a switch block. See is for the case API.

    Example:
    1. switch (myState) {
        is (state1) {
          // some logic here that runs when myState === state1
        }
        is (state2) {
          // some logic here that runs when myState === state2
        }
      }
  44. object unsignedBitLength

Deprecated Value Members

  1. object LFSR16

    LFSR16 generates a 16-bit linear feedback shift register, returning the register contents.

    LFSR16 generates a 16-bit linear feedback shift register, returning the register contents. This is useful for generating a pseudo-random sequence.

    The example below, taken from the unit tests, creates two 4-sided dice using LFSR16 primitives:

    Annotations
    @deprecated
    Deprecated

    (Since version 3.2) LFSR16 is deprecated in favor of the parameterized chisel3.util.random.LFSR

    Example:
    1. val bins = Reg(Vec(8, UInt(32.W)))
      
      // Create two 4 sided dice and roll them each cycle.
      // Use tap points on each LFSR so values are more independent
      val die0 = Cat(Seq.tabulate(2) { i => LFSR16()(i) })
      val die1 = Cat(Seq.tabulate(2) { i => LFSR16()(i + 2) })
      
      val rollValue = die0 +& die1  // Note +& is critical because sum will need an extra bit.
      
      bins(rollValue) := bins(rollValue) + 1.U
  2. object unless
    Annotations
    @deprecated
    Deprecated

    (Since version 3.2) The unless conditional is deprecated, use when(!condition){...} instead

Inherited from AnyRef

Inherited from Any

Ungrouped