firrtl
Container of all annotations for a Firrtl compiler.
This transforms "CHIRRTL", the chisel3 IR, to "Firrtl".
This transforms "CHIRRTL", the chisel3 IR, to "Firrtl". Note the resulting circuit has only IR nodes, not WIR.
Current form of the Firrtl Circuit
Current form of the Firrtl Circuit
Form is a measure of addition restrictions on the legality of a Firrtl circuit. There is a notion of "highness" and "lowness" implemented in the compiler by extending scala.math.Ordered. "Lower" forms add additional restrictions compared to "higher" forms. This means that "higher" forms are strictly supersets of the "lower" forms. Thus, that any transform that operates on HighForm can also operate on MidForm or LowForm
Current State of the Circuit
Current State of the Circuit
The current state of the Firrtl AST
The current form of the circuit
The current collection of Annotation
A map of Named things that have been renamed. Generally only a return value from Transforms
Most of the chisel toolchain components require a topName which defines a circuit or a device under test.
Most of the chisel toolchain components require a topName which defines a circuit or a device under test. Much of the work that is done takes place in a directory. It would be simplest to require topName to be defined but in practice it is preferred to defer this. For example, in chisel, by deferring this it is possible for the execute there to first elaborate the circuit and then set the topName from that if it has not already been set.
Use this trait to define an options class that can add its private command line options to a externally declared parser
Super class for Annotations containing emitted components
Super class for Annotations containing emitted components
These annotations cannot be serialized and deserialized to/from an annotation file
Defines old API for Emission.
Defines old API for Emission. Deprecated
The firrtl compilation failed.
The firrtl compilation failed.
Some kind of hint as to what went wrong.
The options that firrtl supports in callable component sense
The options that firrtl supports in callable component sense
default is targetDir/topName.fir
default is targetDir/topName.v the .v is based on the compilerName parameter
which compiler to use
annotations to pass to compiler
Indicates a successful execution of the firrtl compiler, returning the compiled result and the type of compile
Indicates a successful execution of the firrtl compiler, returning the compiled result and the type of compile
The name of the compiler used, currently "high", "middle", "low", or "verilog"
The emitted result of compilation
Emits input circuit Will replace Chirrtl constructs with Firrtl
Expands aggregate connects, removes dynamic accesses, and when statements.
Expands aggregate connects, removes dynamic accesses, and when statements. Checks for uninitialized values. Must accept a well-formed graph. Operates on working IR nodes.
Converts from the bare intermediate representation (ir.scala) to a working representation (WIR.scala)
Emits lowered input circuit
Runs a series of optimization passes on LowFirrtl
Runs a series of optimization passes on LowFirrtl
This is currently required for correct Verilog emission TODO Fix the above note
Emits middle Firrtl input circuit
Expands all aggregate types into many ground-typed components.
Expands all aggregate types into many ground-typed components. Must accept a well-formed graph of only middle Firrtl features. Operates on working IR nodes.
Maintains a one to many graph of each modules instantiated child module.
Maintains a one to many graph of each modules instantiated child module. This graph can be searched for a path from a child module back to one of it's parents. If one is found a recursive loop has happened The graph is a map between the name of a node to set of names of that nodes children
Firrtl output configuration specified by FirrtlExecutionOptions
Firrtl output configuration specified by FirrtlExecutionOptions
Derived from the fields of the execution options
Resolves types, kinds, and genders, and checks the circuit legality.
Resolves types, kinds, and genders, and checks the circuit legality. Operates on working IR nodes and high Firrtl.
For transformations that are simply a sequence of transforms
The basic unit of operating on a Firrtl AST
Emits Verilog
Chirrtl Form
Chirrtl Form
The form of the circuit emitted by Chisel. Not a true Firrtl form. Includes cmem, smem, and mport IR nodes which enable declaring memories separately form their ports. A "Higher" form than HighForm
See CDefMemory and CDefMPort
The driver provides methods to access the firrtl compiler.
The driver provides methods to access the firrtl compiler. Invoke the compiler with either a FirrtlExecutionOption
firrtl.Driver.execute(Array("--top-name Dummy --compiler verilog".split(" +"))
each approach has its own endearing aspects
val optionsManager = new ExecutionOptionsManager("firrtl") optionsManager.register( FirrtlExecutionOptionsKey -> new FirrtlExecutionOptions(topName = "Dummy", compilerName = "verilog")) firrtl.Driver.execute(optionsManager)
or a series of command line arguments
CompilerUtils.mergeTransforms to see how customTransformations are inserted
firrtlTests/DriverSpec.scala in the test directory for a lot more examples
High Form
High Form
As detailed in the Firrtl specification https://github.com/ucb-bar/firrtl/blob/master/spec/spec.pdf
Also see firrtl.ir
Low Form
Low Form
The "lowest" form. In addition to the restrictions in MidForm:
Middle Form
Middle Form
A "lower" form than HighForm with the following restrictions:
Definitions and Utility functions for ir.PrimOps
RenameMap maps old names to modified names.
RenameMap maps old names to modified names. Generated by transformations that modify names
annotations.GlobalCircuitAnnotation that contains the CommonOptions target directory
Unknown Form
Unknown Form
Often passes may modify a circuit (e.g. InferTypes), but return a circuit in the same form it was given.
For this use case, use UnknownForm. It cannot be compared against other forms.
TODO(azidar): Replace with PreviousForm, which more explicitly encodes this requirement.
Given an expression, return an expression consisting of all sub-expressions concatenated (or flattened).