package experimental
- Alphabetic
- Public
- All
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
Flattens an instance of a module
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) }
Example: -
trait
InlineInstance extends AnyRef
Inlines an instance of a module
Inlines an instance of a module
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) }
Example: -
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 exmple where you want to connect a component in one module to a component in another. Module
Constant
has a wire tied to42
andExpect
will assert unless connected to42
: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
toy
using BoringUtils without modifiying the Chisel IO ofConstant
,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
Hierarchcical boring involves connecting one sink instance to another source instance in a parent module. Below, module
Top
contains an instance ofCosntant
andExpect
. Using BoringUtils.bore, we can connectconstant.x
toexpect.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
, andy
is described as a sink with the same name. This is equivalent to the hierarchical boring example above, but requires no modifications toTop
.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. Hierarhical 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
loadMemoryFromFile
loadMemoryFromFile is an annotation generator that helps with loading a memory from a text file.
loadMemoryFromFile is an annotation generator that helps with loading a memory from a text file. 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
LoadMemoryFromFileSpec.scala in the test suite for additional examples.
Chisel3 Wiki entry on "Loading Memories in Simulation"
This is the documentation for Chisel.
Package structure
The chisel3 package presents the public API of Chisel. It contains the concrete core types
UInt
,SInt
,Bool
,FixedPoint
,Clock
, andReg
, the abstract typesBits
,Aggregate
, andData
, and the aggregate typesBundle
andVec
.The Chisel package is a compatibility layer that attempts to provide chisel2 compatibility in chisel3.
Utility objects and methods are found in the
util
package.The
testers
package defines the basic interface for chisel testers.