chisel6.4.0 < Back


# Packages

-  package root
  Definition Classes
    root
-  package chisel3

  This package contains the main chisel3 API.

  This package contains the main chisel3 API.

  Definition Classes
    root
-  package util

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

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

  Definition Classes
    chisel3
-  package circt
  Definition Classes
    util
-  package experimental
  Definition Classes
    util
-  package decode
- BitSet
- BoringUtils
- BoringUtilsException
- FlattenInstance
- ForceNameAnnotation
- InlineInstance
- forceName
- getAnnotations
- loadMemoryFromFile
- loadMemoryFromFileInline
-  package random
  Definition Classes
    util

p

chisel3.util

# experimental

#### package experimental


Ordering

1. Alphabetic

Visibility

1. Public
2. Protected

### Package Members

1.  package decode

### Type Members

1.  sealed trait BitSet extends AnyRef

   A Set of `BitPat` represents a set of bit vector with mask.

2.  class BoringUtilsException extends Exception

   An exception related to BoringUtils

3.  trait FlattenInstance extends AnyRef

   Flattens an instance of a module

   Flattens an instance of a module

   Example:

   1.     trait Internals { this: Module =>
            val io = IO(new Bundle{ val a = Input(Bool()) })
          }
          class Foo extends Module with Internals with FlattenInstance
          class Bar extends Module with Internals {
            val baz = Module(new Baz)
            baz.io.a := io.a
          }
          class Baz extends Module with Internals
          /* The resulting instances will be:
               - Top
               - Top.x
               - Top.y
               - Top.z
               - Top.z.baz */
          class Top extends Module with Internals {
            val x = Module(new Foo)                      // x will be flattened
            val y = Module(new Bar with FlattenInstance) // y will also be flattened
            val z = Module(new Bar)                      // z will not be flattened
            Seq(x, y, z).map(_.io.a := io.a)
          }

4.  case class ForceNameAnnotation(target: IsMember, name: String) extends SingleTargetAnnotation[IsMember] with Product with Serializable

   Links the user-specified name to force to, with the signal/instance in the FIRRTL design

   Links the user-specified name to force to, with the signal/instance in the FIRRTL design

   target

     signal/instance to force the name

   name

     name to force it to be

5.  trait InlineInstance extends AnyRef

   Inlines an instance of a module

   Inlines an instance of a module

   Example:

   1.     trait Internals { this: Module =>
            val io = IO(new Bundle{ val a = Input(Bool()) })
          }
          class Sub extends Module with Internals
          trait HasSub { this: Module with Internals =>
            val sub = Module(new Sub)
            sub.io.a := io.a
          }
          /* InlineInstance is mixed directly into Foo's definition. Every instance
           * of this will be inlined. */
          class Foo extends Module with Internals with InlineInstance with HasSub
          /* Bar will, by default, not be inlined */
          class Bar extends Module with Internals with HasSub
          /* The resulting instances will be:
           - Top
           - Top.x$sub
           - Top.y$sub
           - Top.z
           - Top.z.sub */
          class Top extends Module with Internals {
            val x = Module(new Foo)                     // x will be inlined
            val y = Module(new Bar with InlineInstance) // y will also be inlined
            val z = Module(new Bar)                     // z will not be inlined
            Seq(x, y, z).map(_.io.a := io.a)
          }

### Value Members

1.  object BitSet
2.  object BoringUtils

   Utilities for generating synthesizable cross module references that "bore" through the hierarchy.

   Utilities for generating synthesizable cross module references that "bore" through the hierarchy. The underlying cross module connects are handled by FIRRTL's Wiring Transform.

   Consider the following example where you want to connect a component in one module to a component in another. Module `Constant` has a wire tied to `42` and `Expect` will assert unless connected to `42`:

       class Constant extends Module {
         val io = IO(new Bundle{})
         val x = Wire(UInt(6.W))
         x := 42.U
       }
       class Expect extends Module {
         val io = IO(new Bundle{})
         val y = Wire(UInt(6.W))
         y := 0.U
         // This assertion will fail unless we bore!
         chisel3.assert(y === 42.U, "y should be 42 in module Expect")
       }

   We can then connect `x` to `y` using BoringUtils without modifiying the Chisel IO of `Constant`, `Expect`, or modules that may instantiate them. There are two approaches to do this:

   1. Hierarchical boring using BoringUtils.bore

   2. Non-hierarchical boring using BoringUtils.addSink/BoringUtils.addSource

   ##### Hierarchical Boring

   Hierarchical boring involves connecting one sink instance to another source instance in a parent module. Below, module `Top` contains an instance of `Constant` and `Expect`. Using BoringUtils.bore, we can connect `constant.x` to `expect.y`.

       class Top extends Module {
         val io = IO(new Bundle{})
         val constant = Module(new Constant)
         val expect = Module(new Expect)
         BoringUtils.bore(constant.x, Seq(expect.y))
       }

   Bottom-up boring involves boring a sink in a child instance to the current module, where it can be assigned from. Using BoringUtils.bore, we can connect from `constant.x` to `mywire`.

       class Top extends Module {
         val io = IO(new Bundle { val foo = UInt(3.W) })
         val constant = Module(new Constant)
         io.foo := BoringUtils.bore(constant.x)
       }

   ##### Non-hierarchical Boring

   Non-hierarchical boring involves connections from sources to sinks that cannot see each other. Here, `x` is described as a source and given a name, `uniqueId`, and `y` is described as a sink with the same name. This is equivalent to the hierarchical boring example above, but requires no modifications to `Top`.

       class Constant extends Module {
         val io = IO(new Bundle{})
         val x = Wire(UInt(6.W))
         x := 42.U
         BoringUtils.addSource(x, "uniqueId")
       }
       class Expect extends Module {
         val io = IO(new Bundle{})
         val y = Wire(UInt(6.W))
         y := 0.U
         // This assertion will fail unless we bore!
         chisel3.assert(y === 42.U, "y should be 42 in module Expect")
         BoringUtils.addSink(y, "uniqueId")
       }
       class Top extends Module {
         val io = IO(new Bundle{})
         val constant = Module(new Constant)
         val expect = Module(new Expect)
       }

   #### Comments

   Both hierarchical and non-hierarchical boring emit FIRRTL annotations that describe sources and sinks. These are matched by a `name` key that indicates they should be wired together. Hierarchical boring safely generates this name automatically. Non-hierarchical boring unsafely relies on user input to generate this name. Use of non-hierarchical naming may result in naming conflicts that the user must handle.

   The automatic generation of hierarchical names relies on a global, mutable namespace. This is currently persistent across circuit elaborations.

3.  object forceName
4.  object getAnnotations
5.  object loadMemoryFromFile

   loadMemoryFromFile is an annotation generator that helps with loading a memory from a text file as a bind module.

   loadMemoryFromFile is an annotation generator that helps with loading a memory from a text file as a bind module. This relies on Verilator and Verilog's `$readmemh` or `$readmemb`.

   This annotation, when a FIRRTL compiler runs will add Verilog directives to enable the specified memories to be initialized from files.

   #### Example module

   Consider a simple Module containing a memory:

       import chisel3._
       class UsesMem(memoryDepth: Int, memoryType: Data) extends Module {
         val io = IO(new Bundle {
           val address = Input(UInt(memoryType.getWidth.W))
           val value   = Output(memoryType)
         })
         val memory = Mem(memoryDepth, memoryType)
         io.value := memory(io.address)
       }

   #### Above module with annotation

   To load this memory from the file `/workspace/workdir/mem1.hex.txt` just add an import and annotate the memory:

       import chisel3._
       import chisel3.util.experimental.loadMemoryFromFile   // <<-- new import here
       class UsesMem(memoryDepth: Int, memoryType: Data) extends Module {
         val io = IO(new Bundle {
           val address = Input(UInt(memoryType.getWidth.W))
           val value   = Output(memoryType)
         })
         val memory = Mem(memoryDepth, memoryType)
         io.value := memory(io.address)
         loadMemoryFromFile(memory, "/workspace/workdir/mem1.hex.txt")  // <<-- Note the annotation here
       }

   #### Example file format

   A memory file should consist of ASCII text in either hex or binary format. The following example shows such a file formatted to use hex:

        0
        7
        d
       15

   A binary file can be similarly constructed.

   See also

     LoadMemoryFromFileSpec.scala in the test suite for additional examples.

     Chisel3 Wiki entry on "Loading Memories in Simulation"

6.  object loadMemoryFromFileInline

   loadMemoryFromFileInline is an annotation generator that helps with loading a memory from a text file inlined in the Verilog module.

   loadMemoryFromFileInline is an annotation generator that helps with loading a memory from a text file inlined in the Verilog module. This relies on Verilator and Verilog's `$readmemh` or `$readmemb`.

   This annotation, when the FIRRTL compiler runs, triggers the `MemoryFileInlineAnnotation` that will add Verilog directives inlined to the module enabling the specified memories to be initialized from files. The module supports both `hex` and `bin` files by passing the appropriate `MemoryLoadFileType.FileType` `argument with `MemoryLoadFileType.Hex` or` MemoryLoadFileType.Binary`. Hex is the default.`

   #### Example module

   Consider a simple Module containing a memory:

       import chisel3._
       class UsesMem(memoryDepth: Int, memoryType: Data) extends Module {
         val io = IO(new Bundle {
           val address = Input(UInt(memoryType.getWidth.W))
           val value   = Output(memoryType)
         })
         val memory = Mem(memoryDepth, memoryType)
         io.value := memory(io.address)
       }

   #### Above module with annotation

   To load this memory from the file `/workspace/workdir/mem1.hex.txt` just add an import and annotate the memory:

       import chisel3._
       import chisel3.util.experimental.loadMemoryFromFileInline   // <<-- new import here
       class UsesMem(memoryDepth: Int, memoryType: Data) extends Module {
         val io = IO(new Bundle {
           val address = Input(UInt(memoryType.getWidth.W))
           val value   = Output(memoryType)
         })
         val memory = Mem(memoryDepth, memoryType)
         io.value := memory(io.address)
         loadMemoryFromFileInline(memory, "/workspace/workdir/mem1.hex.txt")  // <<-- Note the annotation here
       }

   #### Example file format

   A memory file should consist of ASCII text in either hex or binary format. The following example shows such a file formatted to use hex:

        0
        7
        d
       15

   A binary file can be similarly constructed. Chisel does not validate the file format or existence. It is supposed to be in a path accessible by the synthesis tool together with the generated Verilog.

   See also

     Chisel3 Wiki entry on "Loading Memories in Simulation"

### Ungrouped