firrtl
Wraps modules or statements with their respective described nodes.
Wraps modules or statements with their respective described nodes. Descriptions come from DescriptionAnnotation.
Describing a module or any of its ports will turn it into a DescribedMod. Describing a Statement will turn it into
a (private) DescribedStmt.
should only be used by VerilogEmitter, described nodes will break other transforms.
Container of all annotations for a Firrtl compiler
A Verilog-style attribute.
A Verilog-style attribute.
the attribute
An Verilog-style attribute.
An Verilog-style attribute.
the object being given an attribute
the attribute
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
Emission customization options for connect
Wraps exceptions from CustomTransforms so they can be reported appropriately
This trait helps ease migration from old CircuitForm specification of dependencies to Dependency API specification of dependencies.
This trait helps ease migration from old CircuitForm specification of dependencies to
Dependency API specification of dependencies. This trait implements deprecated, abstract Transform methods
(inputForm and outputForm) for you and sets default values for dependencies:
prerequisites are emptyoptionalPrerequisites are emptyoptionalPrerequisiteOf are emptyFor more information, see: https://bit.ly/2Voppre
Base trait for a description that gives some information about a FirrtlNode.
Base trait for a description that gives some information about a FirrtlNode.
Usually, we would like to emit these descriptions in some way.
A base trait for Annotations that describe a FirrtlNode.
A base trait for Annotations that describe a FirrtlNode.
Usually, we would like to emit these descriptions in some way.
A docstring description (a comment)
A docstring description (a comment)
a comment
A docstring description (a comment).
A docstring description (a comment).
the object being described
the docstring describing the object
Base type for emission customization options NOTE: all the following traits must be mixed with SingleTargetAnnotation[T <: Named] in order to be taken into account in the Emitter
Traits for Annotations containing emitted components
Defines old API for Emission.
Defines old API for Emission. Deprecated
Exception indicating user error
Exception indicating user error
These exceptions indicate a problem due to bad input and thus do not include a stack trace. This can be extended by custom transform writers.
Emission customization options for memories
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
Emission customization options for nodes
Firrtl output configuration specified by FirrtlExecutionOptions
Firrtl output configuration specified by FirrtlExecutionOptions
Derived from the fields of the execution options
Emission customization options for IO ports
Emission customization options for registers
Map old names to new names
Map old names to new names
Transforms that modify names should return a RenameMap with the CircuitState These are mutable datastructures for convenience
Extend for transforms that require resolved targets in their annotations Ensures all targets in annotations of a class in annotationClasses are resolved before the execute method
For transformations that are simply a sequence of transforms
The basic unit of operating on a Firrtl AST
Emission customization options for wires
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.
(Since version FIRRTL 1.3) Use 'new TransformManager(Forms.MinimalHighForm, Forms.ChirrtlForm)'. This will be removed in 1.4.
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
(Since version FIRRTL 1.3) Mix-in the DependencyAPIMigration trait into your Transform and specify its Dependency API dependencies. See: https://bit.ly/2Voppre
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.
(Since version 1.2) Use a FirrtlOptionsView, LoggerOptionsView, or construct your own view of an AnnotationSeq
(Since version FIRRTL 1.3) Migrate to firrtl.stage.transforms.Compiler. This will be removed in 1.4.
Use this trait to define an options class that can add its private command line options to a externally declared parser.
Use this trait to define an options class that can add its private command line options to a externally declared parser. NOTE In all derived trait/classes, if you intend on maintaining backwards compatibility, be sure to add new options at the end of the current ones and don't remove any existing ones.
(Since version 1.2) Use firrtl.options.HasScoptOptions and/or library/transform registration
(Since version FIRRTL 1.2) Use a TransformManager or some other Stage/Phase class. Will be removed in 1.4.
(Since version 1.2) Use new FirrtlStage infrastructure
(Since version 1.2) External users should use either FirrtlUserException or their own hierarchy
The firrtl compilation failed.
The firrtl compilation failed.
Some kind of hint as to what went wrong.
(Since version 1.2) Use FirrtlStage and examine the output AnnotationSeq directly
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
(Since version 1.2) Use a FirrtlOptionsView or construct your own view of an AnnotationSeq
(Since version 1.2) Use FirrtlStage and examine the output AnnotationSeq directly
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
(Since version 1.2) Use FirrtlStage and examine the output AnnotationSeq directly
(Since version 1.2) Specify command line arguments in an Annotation mixing in HasScoptOptions
(Since version 1.2) Specify command line arguments in an Annotation mixing in HasScoptOptions
(Since version 1.2) Use firrtl.options.{ExecutionOptionsManager, TerminateOnExit, DuplicateHandling}
Emits input circuit Will replace Chirrtl constructs with Firrtl
Emits input circuit Will replace Chirrtl constructs with Firrtl
(Since version FIRRTL 1.3) Use stage.{FirrtlStage, FirrtlMain} stage.transforms.Compiler(Seq(Dependency[HighFirrtlEmitter]))
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.
(Since version FIRRTL 1.3) Use 'new TransformManager(Forms.MidForm, Forms.Deduped)'. This will be removed in 1.4.
Converts from the bare intermediate representation (ir.scala) to a working representation (WIR.scala)
Converts from the bare intermediate representation (ir.scala) to a working representation (WIR.scala)
(Since version FIRRTL 1.3) Use 'new TransformManager(Forms.WorkingIR, Forms.MinimalHighForm)'. This will be removed in 1.4.
Emits lowered input circuit
Emits lowered input circuit
(Since version FIRRTL 1.3) Use stage.{FirrtlStage, FirrtlMain} stage.transforms.Compiler(Dependency[LowFirrtlEmitter])
Runs a series of optimization passes on LowFirrtl
Runs a series of optimization passes on LowFirrtl
(Since version FIRRTL 1.3) Use 'new TransformManager(Forms.LowFormOptimized, Forms.LowForm)'. This will be removed in 1.4.
This is currently required for correct Verilog emission TODO Fix the above note
Emits middle Firrtl input circuit
Emits middle Firrtl input circuit
(Since version FIRRTL 1.3) Use stage.{FirrtlStage, FirrtlMain} stage.transforms.Compiler(Dependency[MiddleFirrtlEmitter])
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.
(Since version FIRRTL 1.3) Use 'new TransformManager(Forms.LowForm, Forms.MidForm)'. This will be removed in 1.4.
Runs runs only the optimization passes needed for Verilog emission
Runs runs only the optimization passes needed for Verilog emission
(Since version FIRRTL 1.3) Use 'new TransformManager(Forms.LowFormMinimumOptimized, Forms.LowForm)'. This will be removed in 1.4.
Emits Verilog without optimizations
Emits Verilog without optimizations
(Since version FIRRTL 1.3) Use stage.{FirrtlStage, FirrtlMain} stage.transforms.Compiler(Dependency[MinimumVerilogEmitter])
Emits input circuit with no changes
Emits input circuit with no changes
Primarily useful for changing between .fir and .pb serialized formats
(Since version FIRRTL 1.3) Use stage.{FirrtlStage, FirrtlMain} or stage.transforms.Compiler(Seq(Dependency[ChirrtlEmitter]))
Resolves types, kinds, and flows, and checks the circuit legality.
Resolves types, kinds, and flows, and checks the circuit legality. Operates on working IR nodes and high Firrtl.
(Since version FIRRTL 1.3) Use 'new TransformManager(Forms.Resolved, Forms.WorkingIR)'. This will be removed in 1.4.
Currently just an alias for the VerilogCompiler
Currently just an alias for the VerilogCompiler
(Since version FIRRTL 1.3) Use stage.{FirrtlStage, FirrtlMain} stage.transforms.Compiler(Dependency[SystemVerilogEmitter])
(Since version 1.2) Use firrtl.stage.TargetDirAnnotation
Emits Verilog
Emits Verilog
(Since version FIRRTL 1.3) Use stage.{FirrtlStage, FirrtlMain} stage.transforms.Compiler(Dependency[VerilogEmitter])
This object was generated by sbt-buildinfo.
default Emitter behavior for connect
default Emitter behavior for memories
default Emitter behavior for nodes
default Emitter behavior for IO ports
Definitions and Utility functions for ir.PrimOps
default Emitter behavior for registers
default Emitter behavior for wires
The stage package provides an implementation of the FIRRTL compiler using the firrtl.options package.
The stage package provides an implementation of the FIRRTL compiler using the firrtl.options package. This primarily consists of:
Given an expression, return an expression consisting of all sub-expressions concatenated (or flattened).
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
(Since version FIRRTL 1.3) Mix-in the DependencyAPIMigration trait into your Transform and specify its Dependency API dependencies. See: https://bit.ly/2Voppre
(Since version FIRRTL 1.3) This will be removed in 1.4
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
(Since version 1.2) Use firrtl.stage.FirrtlStage
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
(Since version 1.2) External users should use either FirrtlUserException or their own hierarchy
(Since version 1.2) Use FirrtlStage and examine the output AnnotationSeq directly
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
(Since version FIRRTL 1.3) Mix-in the DependencyAPIMigration trait into your Transform and specify its Dependency API dependencies. See: https://bit.ly/2Voppre
Low Form
Low Form
The "lowest" form. In addition to the restrictions in MidForm:
(Since version FIRRTL 1.3) Mix-in the DependencyAPIMigration trait into your Transform and specify its Dependency API dependencies. See: https://bit.ly/2Voppre
Middle Form
Middle Form
A "lower" form than HighForm with the following restrictions:
(Since version FIRRTL 1.3) Mix-in the DependencyAPIMigration trait into your Transform and specify its Dependency API dependencies. See: https://bit.ly/2Voppre
(Since version 1.2) Use firrtl.stage.TargetDirAnnotation
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.
(Since version FIRRTL 1.3) Mix-in the DependencyAPIMigration trait into your Transform and specify its Dependency API dependencies. See: https://bit.ly/2Voppre