experimental

Type Members

class BoringUtilsException extends Exception

An exception related to BoringUtils
case class ChiselLoadMemoryAnnotation[T <: Data](target: MemBase[T], fileName: String, hexOrBinary: FileType = MemoryLoadFileType.Hex) extends ChiselAnnotation with RunFirrtlTransform with Product with Serializable

This is the annotation created when using loadMemoryFromFile, it records the memory, the load file and the format of the file.
This is the annotation created when using loadMemoryFromFile, it records the memory, the load file and the format of the file.
target
memory to load
fileName
name of input file
hexOrBinary
use $readmemh or $readmemb, i.e. hex or binary text input, default is hex

trait FlattenInstance extends AnyRef

Flattens an instance of a module

Example:

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)
}

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

Exceptions thrown
CustomTransformException when the signal is renamed to >1 target
class ForceNamesTransform extends Transform with DependencyAPIMigration

Forces the name of marked signals to a certain name
Forces the name of marked signals to a certain name
- If there is a conflict in the enclosing module's namespace, throws an exception
- Renames signals of ground types only. If you rename an intermediate module, it will throw an error
- Renames instances as well (as well as port names) Common usages:
- Use to avoid prefixing behavior on specific instances whose enclosing modules are inlined

trait InlineInstance extends AnyRef

Inlines an instance of a module

Example:

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)
}

class LoadMemoryTransform extends Transform

This transform only is activated if Verilog is being generated (determined by presence of the proper emit annotation) when activated it creates additional Verilog files that contain modules bound to the modules that contain an initializable memory
This transform only is activated if Verilog is being generated (determined by presence of the proper emit annotation) when activated it creates additional Verilog files that contain modules bound to the modules that contain an initializable memory
Currently the only non-Verilog based simulation that can support loading memory from a file is treadle but it does not need this transform to do that.

Value Members

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))
}
```
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.
object forceName
object group

Marks that a module to be ignored in Dedup Transform in Firrtl pass
Marks that a module to be ignored in Dedup Transform in Firrtl pass
Example:
1. class MyModule extends Module { val io = IO(new Bundle{ val a = Input(Bool()) val b = Output(Bool()) }) val reg1 = RegInit(0.U) reg1 := io.a val reg2 = RegNext(reg1) io.b := reg2 group(Seq(reg1, reg2), "DosRegisters", "doubleReg") }
Note
Intermediate wires will get pulled into the new instance, but intermediate registers will not because they are also connected to their module's clock port. This means that if you want a register to be included in a group, it must be explicitly referred to in the input list.
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. The Treadle backend can also recognize this annotation and load memory at run-time.
This annotation, when the FIRRTL compiler runs, triggers the LoadMemoryTransform. That 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
Chisel3 Wiki entry on "Loading Memories in Simulation"
LoadMemoryFromFileSpec.scala in the test suite for additional examples.
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. The Treadlebackend can also recognize this annotation and load memory at run-time.
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"

package experimental

Type Members

class BoringUtilsException extends Exception

case class ChiselLoadMemoryAnnotation[T <: Data](target: MemBase[T], fileName: String, hexOrBinary: FileType = MemoryLoadFileType.Hex) extends ChiselAnnotation with RunFirrtlTransform with Product with Serializable

trait FlattenInstance extends AnyRef

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

class ForceNamesTransform extends Transform with DependencyAPIMigration

trait InlineInstance extends AnyRef

class LoadMemoryTransform extends Transform

Value Members

object BoringUtils

Hierarchical Boring

Non-hierarchical Boring

Comments

object forceName

object group

object loadMemoryFromFile

Example module

Above module with annotation

Example file format

object loadMemoryFromFileInline

Example module

Above module with annotation

Example file format

Ungrouped