package transforms
- Alphabetic
- By Inheritance
- transforms
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
Type Members
- sealed trait BlackBoxHelperAnno extends Annotation
- case class BlackBoxInlineAnno(target: ModuleName, name: String, text: String) extends BlackBoxHelperAnno with SingleTargetAnnotation[ModuleName] with Product with Serializable
-
class
BlackBoxNotFoundException extends FirrtlUserException
Exception indicating that a blackbox wasn't found
- case class BlackBoxPathAnno(target: ModuleName, path: String) extends BlackBoxHelperAnno with SingleTargetAnnotation[ModuleName] with Product with Serializable
- case class BlackBoxResourceFileNameAnno(resourceFileName: String) extends BlackBoxHelperAnno with NoTargetAnnotation with Product with Serializable
-
class
BlackBoxSourceHelper extends Transform with DependencyAPIMigration
Handle source for Verilog ExtModules (BlackBoxes)
Handle source for Verilog ExtModules (BlackBoxes)
This transform handles the moving of Verilog source for black boxes into the target directory so that it can be accessed by verilator or other backend compilers While parsing it's annotations it looks for a BlackBoxTargetDir annotation that will set the directory where the Verilog will be written. This annotation is typically be set by the execution harness, or directly in the tests
- case class BlackBoxTargetDirAnno(targetDir: String) extends BlackBoxHelperAnno with NoTargetAnnotation with Product with Serializable
-
class
CheckCombLoops extends Transform with RegisteredTransform with DependencyAPIMigration
Finds and detects combinational logic loops in a circuit, if any exist.
Finds and detects combinational logic loops in a circuit, if any exist. Returns the input circuit with no modifications.
- Exceptions thrown
firrtl.transforms.CheckCombLoops.CombLoopException
if a loop is found- Note
Input form: Low FIRRTL
,Output form: Low FIRRTL (identity transform)
,The pass looks for loops through combinational-read memories
,The pass relies on ExtModulePathAnnotations to find loops through ExtModules
,The pass will throw exceptions on "false paths"
- case class CombinationalPath(sink: ReferenceTarget, sources: Seq[ReferenceTarget]) extends Annotation with Product with Serializable
-
class
CombineCats extends Transform with DependencyAPIMigration
Combine Cat DoPrims
Combine Cat DoPrims
Expands the arguments of any Cat DoPrims if they are references to other Cat DoPrims. Operates only on Cat DoPrims that are node values.
Use MaxCatLenAnnotation to limit the number of elements that can be concatenated. The default maximum number of elements is 10.
- class ConstantPropagation extends Transform with RegisteredTransform with DependencyAPIMigration
-
case class
CustomRadixApplyAnnotation(target: ReferenceTarget, name: String) extends SingleTargetAnnotation[ReferenceTarget] with Product with Serializable
A annotation making a ReferenceTarget to be a specific CustomRadixDefAnnotation.
A annotation making a ReferenceTarget to be a specific CustomRadixDefAnnotation.
- target
the ReferenceTarget which the alias applied to
- name
the identifier for the alias
-
case class
CustomRadixConfigFileAnnotation(signals: Seq[(String, Seq[String])], filters: Seq[CustomRadixDefAnnotation]) extends NoTargetAnnotation with CustomFileEmission with Product with Serializable
Dumps a JSON config file for custom radix.
Dumps a JSON config file for custom radix. Users can generate script using the emitted file.
- signals
which alias contains which signals, the signals should be converted from ReferenceTarget to String
- filters
sequence of CustomRadixDefAnnotation, the name should match signals.map(_._1)
-
case class
CustomRadixDefAnnotation(name: String, filters: Seq[(BigInt, String)], width: Int) extends NoTargetAnnotation with Product with Serializable
Contains a static map from signal value(BigInt) to signal name(String) This is useful for enumeration(finite state machine, bus transaction name, etc)
Contains a static map from signal value(BigInt) to signal name(String) This is useful for enumeration(finite state machine, bus transaction name, etc)
- name
identifier for this alias
- filters
a sequence of translation filter
- width
width of this alias
-
class
DeadCodeElimination extends Transform with RegisteredTransform with DependencyAPIMigration
Dead Code Elimination (DCE)
Dead Code Elimination (DCE)
Performs DCE by constructing a global dependency graph starting with top-level outputs, external module ports, and simulation constructs as circuit sinks. External modules can optionally be eligible for DCE via the OptimizableExtModuleAnnotation.
Dead code is eliminated across module boundaries. Wires, ports, registers, and memories are all eligible for removal. Components marked with a DontTouchAnnotation will be treated as a circuit sink and thus anything that drives such a marked component will NOT be removed.
This transform preserves deduplication. All instances of a given firrtl.ir.DefModule are treated as the same individual module. Thus, while certain instances may have dead code due to the circumstances of their instantiation in their parent module, they will still not be removed. To remove such modules, use the NoDedupAnnotation to prevent deduplication.
-
class
DedupAnnotationsTransform extends Transform with DependencyAPIMigration
Deduplicates memory annotations
-
class
DedupModules extends Transform with DependencyAPIMigration
Only use on legal Firrtl.
Only use on legal Firrtl.
Specifically, the restriction of instance loops must have been checked, or else this pass can infinitely recurse.
Deduped modules are renamed using a chain of 3 RenameMaps. The first RenameMap renames the original annotations.ModuleTargets and relative annotations.InstanceTargets to the groups of absolute annotations.InstanceTargets that they target. These renames only affect instance names and paths and use the old module names. During this rename, modules will also have their instance names renamed if they dedup with a module that has different instance names. The second RenameMap renames all component names within modules that dedup with another module that has different component names. The third RenameMap renames original annotations.ModuleTargets to their deduped annotations.ModuleTarget.
This transform will also emit DedupedResult for deduped modules that only have one instance.
-
case class
DedupedResult(original: ModuleTarget, duplicate: Option[IsModule], index: Double) extends MultiTargetAnnotation with Product with Serializable
Holds the mapping from original module to the instances the original module pointed to The original module target is unaffected by renaming
Holds the mapping from original module to the instances the original module pointed to The original module target is unaffected by renaming
- original
Original module
- duplicate
Instance target of what the original module now points to
- index
the normalized position of the original module in the original module list, fraction between 0 and 1
-
trait
DontTouchAllTargets extends HasDontTouches
A globalized form of HasDontTouches which applies to all ReferenceTargets provided with the annotation
-
case class
DontTouchAnnotation(target: ReferenceTarget) extends SingleTargetAnnotation[ReferenceTarget] with DontTouchAllTargets with Product with Serializable
A component that should be preserved
A component that should be preserved
DCE treats the component as a top-level sink of the circuit
- case class ExtModulePathAnnotation(source: ReferenceTarget, sink: ReferenceTarget) extends Annotation with Product with Serializable
-
class
FixAddingNegativeLiterals extends Transform with DependencyAPIMigration
Replaces adding a negative literal with subtracting that literal
Replaces adding a negative literal with subtracting that literal
Verilator has a lint warning if a literal is negated in an expression, because it adds a bit to the literal and thus not all expressions in the add are the same. This is fixed here when we directly subtract the literal instead.
-
class
Flatten extends Transform with DependencyAPIMigration
Takes flatten annotations for module instances and modules and inline the entire hierarchy of modules down from the annotations.
Takes flatten annotations for module instances and modules and inline the entire hierarchy of modules down from the annotations. This transformation instantiates and is based on the InlineInstances transformation.
- Note
Flattening a module means inlining all its fully-defined child instances
,Instances of extmodules are not (and cannot be) inlined
-
case class
FlattenAnnotation(target: Named) extends SingleTargetAnnotation[Named] with Product with Serializable
Tags an annotation to be consumed by this transform
-
class
FlattenRegUpdate extends Transform with DependencyAPIMigration
Flatten register update
Flatten register update
This transform flattens register updates into a single expression on the rhs of connection to the register
-
class
GroupAndDedup extends GroupComponents
Splits a module into multiple modules by grouping its components via GroupAnnotation's Tries to deduplicate the resulting circuit
-
case class
GroupAnnotation(components: Seq[ComponentName], newModule: String, newInstance: String, outputSuffix: Option[String] = None, inputSuffix: Option[String] = None) extends Annotation with Product with Serializable
Specifies a group of components, within a module, to pull out into their own module Components that are only connected to a group's components will also be included
Specifies a group of components, within a module, to pull out into their own module Components that are only connected to a group's components will also be included
- components
components in this group
- newModule
suggested name of the new module
- newInstance
suggested name of the instance of the new module
- outputSuffix
suggested suffix of any output ports of the new module
- inputSuffix
suggested suffix of any input ports of the new module
-
class
GroupComponents extends Transform with DependencyAPIMigration
Splits a module into multiple modules by grouping its components via GroupAnnotation's
-
trait
HasDontTouches extends AnyRef
Lets an annotation mark its ReferenceTarget members as DontTouch
Lets an annotation mark its ReferenceTarget members as DontTouch
This permits a transform to run and remove its associated annotations, thus making their ReferenceTargets new candidates for optimization. This removes the need for the pass writer to reason about pre-existing DontTouchAnnotations that may touch the same node.
-
class
InferResets extends Transform with DependencyAPIMigration
Infers the concrete type of ResetTypes by their connections
Infers the concrete type of ResetTypes by their connections
There are 3 cases 1. An abstract reset driven by and/or driving only asynchronous resets will be inferred as asynchronous reset 1. An abstract reset driven by and/or driving both asynchronous and synchronous resets will error 1. Otherwise, the reset is inferred as synchronous (i.e. the abstract reset is only invalidated or is driven by or drives only synchronous resets)
- Note
This is a global inference because ports can be of type ResetType
,This transform should be run before DedupModules so that similar Modules from generator languages like Chisel can infer differently
-
class
InlineAcrossCastsTransform extends Transform with DependencyAPIMigration
Inline expressions into casts and inline casts into other expressions
Inline expressions into casts and inline casts into other expressions
Because casts are no-ops in the emitted Verilog, this transform eliminates statements that simply contain a cast. It does so by greedily building larger expression trees that contain at most one expression that is neither a cast nor reference-like node.
-
class
InlineBitExtractionsTransform extends Transform with DependencyAPIMigration
Inline nodes that are simple bits
-
class
InlineBooleanExpressions extends Transform with DependencyAPIMigration
Inline Bool expressions
Inline Bool expressions
The following conditions must be satisfied to inline 1. has type Utils.BoolType 2. is bound to a DefNode with name starting with '_' 3. is bound to a DefNode with a source locator that points at the same file and line number. If it is a MultiInfo source locator, the set of file and line number pairs must be the same. Source locators may point to different column numbers. 4. InlineBooleanExpressionsMax has not been exceeded 5. is not a Mux
- case class InlineBooleanExpressionsMax(max: Int) extends NoTargetAnnotation with Product with Serializable
-
class
LegalizeAndReductionsTransform extends Transform with DependencyAPIMigration
Turns andr for expression > 64-bit into equality check with all ones
Turns andr for expression > 64-bit into equality check with all ones
Workaround a bug in Verilator v4.026 - v4.032 (inclusive). For context, see https://github.com/verilator/verilator/issues/2300
-
class
LegalizeClocksAndAsyncResetsTransform extends Transform with DependencyAPIMigration
Ensure Clocks and AsyncResets to be emitted are legal Verilog
-
case class
LogicNode(name: String, inst: Option[String] = None, memport: Option[String] = None) extends Product with Serializable
A case class that represents a net in the circuit.
A case class that represents a net in the circuit. This is necessary since combinational loop checking is an analysis on the netlist of the circuit; the fields are specialized for low FIRRTL. Since all wires are ground types, a given ground type net may only be a subfield of an instance or a memory port. Therefore, it is uniquely specified within its module context by its name, its optional parent instance (a WDefInstance or WDefMemory), and its optional memory port name.
-
abstract
class
ManipulateNames[A <: ManipulateNames[_]] extends Transform with DependencyAPIMigration
Transform for manipulate all the names in a FIRRTL circuit.
Transform for manipulate all the names in a FIRRTL circuit.
- A
the type of the child transform
-
case class
ManipulateNamesAllowlistAnnotation[A <: ManipulateNames[_]](targets: Seq[Seq[Target]], transform: Dependency[A]) extends ManipulateNamesListAnnotation[A] with Product with Serializable
Annotation to filter name manipulation to only manipulate specific Targets in a transform that subclasses ManipulateNames.
Annotation to filter name manipulation to only manipulate specific Targets in a transform that subclasses ManipulateNames. Targets will be renamed if they are not listed in a ManipulateNamesBlocklistAnnotation and also listed in this annotation.
Not providing a ManipulateNamesAllowlistAnnotation means that all targets in a circuit may be renamed.
- A
a sub-type of ManipulateNames
- targets
FIRRTL IR targets to include in name manipulation
- transform
the transform that this should apply to
- Exceptions thrown
java.lang.IllegalArgumentException
if any non-local targets are given- Note
All targets must be local. Name modification in a non-local target (e.g., a node in a specific instance) makes no structural modification and will be ignored during deduplication. If you want this behavior, use a combination of a sub-class of this annotation and a NoDedupAnnotation.
-
case class
ManipulateNamesAllowlistResultAnnotation[A <: ManipulateNames[_]](targets: Seq[Seq[Target]], transform: Dependency[A], oldTargets: Seq[Seq[Target]]) extends MultiTargetAnnotation with Product with Serializable
Records the result of name changes for any targets included in a ManipulateNamesAllowlistAnnotation
Records the result of name changes for any targets included in a ManipulateNamesAllowlistAnnotation
If targets are later removed, then a target and old target will be removed from this annotation. If all targets are removed, then this annotation will be deleted.
- targets
the new targets
- transform
the transform that performed this rename
- oldTargets
the old targets
-
case class
ManipulateNamesBlocklistAnnotation[A <: ManipulateNames[_]](targets: Seq[Seq[Target]], transform: Dependency[A]) extends ManipulateNamesListAnnotation[A] with Product with Serializable
Annotation to prevent name manipulation ofTargets in a transform that subclasses ManipulateNames.
Annotation to prevent name manipulation ofTargets in a transform that subclasses ManipulateNames. All listed targets will not be modified.
- A
a sub-type of ManipulateNames
- targets
FIRRTL IR targets to exclude from name manipulation
- transform
the transform that this should apply to
- Exceptions thrown
java.lang.IllegalArgumentException
if any non-local targets are given- Note
All targets must be local. Name modification in a non-local target (e.g., a node in a specific instance) makes no structural modification and will be ignored during deduplication. If you want this behavior, use a combination of a sub-class of this annotation and a NoDedupAnnotation.
-
sealed
trait
ManipulateNamesListAnnotation[A <: ManipulateNames[_]] extends MultiTargetAnnotation
Base trait for annotations that control the behavior of transforms that sub-class ManipulateNames
Base trait for annotations that control the behavior of transforms that sub-class ManipulateNames
- case class MaxCatLenAnnotation(maxCatLen: Int) extends NoTargetAnnotation with Product with Serializable
-
case class
MustDeduplicateAnnotation(modules: Seq[IsModule]) extends Annotation with Product with Serializable
Marks modules as "must deduplicate"
-
case class
MustDeduplicateReportDirectory(directory: String) extends NoTargetAnnotation with Product with Serializable
Specifies the directory where errors for modules that "must deduplicate" will be reported
-
class
MustDeduplicateTransform extends Transform with DependencyAPIMigration
Checks for modules that have been marked as "must deduplicate"
Checks for modules that have been marked as "must deduplicate"
In cases where marked modules did not deduplicate, this transform attempts to provide context on what went wrong for debugging.
-
case class
NoDedupAnnotation(target: ModuleTarget) extends SingleTargetAnnotation[ModuleTarget] with Product with Serializable
A component, e.g.
A component, e.g. register etc. Must be declared only once under the TopAnnotation
-
case class
OptimizableExtModuleAnnotation(target: ModuleName) extends SingleTargetAnnotation[ModuleName] with Product with Serializable
An firrtl.ir.ExtModule that can be optimized
An firrtl.ir.ExtModule that can be optimized
Firrtl does not know the semantics of an external module. This annotation provides some "greybox" information that the external module does not have any side effects. In particular, this means that the external module can be Dead Code Eliminated.
- Note
Unlike DontTouchAnnotation, we don't care if the annotation is deleted
-
class
PropagatePresetAnnotations extends Transform with DependencyAPIMigration
Propagate PresetAnnotations to all children of targeted AsyncResets Leaf Registers are annotated with PresetRegAnnotation All wires, nodes and connectors along the way are suppressed
Propagate PresetAnnotations to all children of targeted AsyncResets Leaf Registers are annotated with PresetRegAnnotation All wires, nodes and connectors along the way are suppressed
Processing of multiples targets are NOT isolated from one another as the expected outcome does not differ Annotations of leaf registers, wires, nodes & connectors does indeed not depend on the initial AsyncReset reference The set of created annotation based on multiple initial AsyncReset PresetAnnotation
This transform consists of 2 successive walk of the AST I./ Propagate
- 1./ Create all AsyncResetTrees
- 2./ Leverage them to annotate register for specialized emission & PresetTree for cleanUp II./ CleanUpTree
- clean up all the intermediate nodes (replaced with EmptyStmt)
- raise Error on orphans (typically cast of Annotated Reset)
- disconnect Registers from their reset nodes (replaced with UInt(0))
Thanks to the clean-up phase, this transform does not rely on DCE
- Note
This pass must run before InlineCastsTransform
-
class
RemoveKeywordCollisions extends ManipulateNames[Nothing]
Transform that removes collisions with reserved keywords
-
class
RemoveWires extends Transform with DependencyAPIMigration
Replace wires with nodes in a legal, flow-forward order
Replace wires with nodes in a legal, flow-forward order
This pass must run after LowerTypes because Aggregate-type wires have multiple connections that may be impossible to order in a flow-foward way
-
class
RenameModules extends Transform with DependencyAPIMigration
Rename Modules
Rename Modules
using namespace created by analyses.GetNamespace, create unique names for modules
-
class
ReplaceTruncatingArithmetic extends Transform with DependencyAPIMigration
Replaces non-expanding arithmetic
Replaces non-expanding arithmetic
In the case where the result of
add
orsub
immediately throws away the expanded msb, this transform will replace the operation with a non-expanding operatoraddw
orsubw
respectively.- Note
This replaces some FIRRTL primops with ops that are not actually legal FIRRTL. They are useful for emission to languages that support non-expanding arithmetic (like Verilog)
-
class
SimplifyMems extends Transform with DependencyAPIMigration
Lowers memories without splitting them, but without the complexity of ReplaceMemMacros
-
class
SortModules extends Transform with DependencyAPIMigration
Return a circuit where all modules (and external modules) are defined before use.
-
class
VerilogRename extends RemoveKeywordCollisions
Transform that removes collisions with Verilog keywords
-
case class
BlackBoxResourceAnno(target: ModuleName, resourceId: String) extends BlackBoxHelperAnno with SingleTargetAnnotation[ModuleName] with Product with Serializable
- Annotations
- @deprecated
- Deprecated
(Since version FIRRTL 1.5.0) Use either a BlackBoxInlineAnno or a BlackBoxPathAnno
-
class
IdentityTransform extends Transform
Transform that applies an identity function.
Transform that applies an identity function. This returns an unmodified CircuitState.
- Annotations
- @deprecated
- Deprecated
(Since version FIRRTL 1.3) mix-in firrtl.options.IdentityLike[CircuitState]. IdentityTransform will be removed in 1.4.
-
type
LegalizeClocksTransform = LegalizeClocksAndAsyncResetsTransform
- Annotations
- @deprecated
- Deprecated
(Since version FIRRTL 1.4.0) Replaced by LegalizeClocksAndAsyncResetsTransform
Value Members
- object BlackBoxSourceHelper
- object CheckCombLoops
- object CombineCats
- object ConstantPropagation
-
object
CustomRadixTransform extends Transform with DependencyAPIMigration with HasShellOptions
A Transform that generate scripts or config file for Custom Radix
- object DedupAnnotationsTransform
-
object
DedupModules extends LazyLogging
Utility functions for DedupModules
- object DontCheckCombLoopsAnnotation extends NoTargetAnnotation with Product with Serializable
- object DontTouchAnnotation extends Serializable
-
object
EnsureNamedStatements extends Transform with DependencyAPIMigration
Adds default names to print, stop and verification statements if their name is empty.
- object FixAddingNegativeLiterals
- object FlattenRegUpdate
- object InferResets
- object InlineAcrossCastsTransform
- object InlineBitExtractionsTransform
- object InlineBooleanExpressions
- object LegalizeAndReductionsTransform
- object LegalizeClocksAndAsyncResetsTransform
- object LogicNode extends Serializable
- object MustDeduplicateTransform
-
object
NoCircuitDedupAnnotation extends NoTargetAnnotation with HasShellOptions with Product with Serializable
If this Annotation exists in an AnnotationSeq, then the firrtl.transforms.DedupModules transform will *NOT* be run on the circuit.
If this Annotation exists in an AnnotationSeq, then the firrtl.transforms.DedupModules transform will *NOT* be run on the circuit.
- set with '--no-dedup'
-
object
NoConstantPropagationAnnotation extends NoTargetAnnotation with Product with Serializable
Indicate that ConstantPropagation should not be run
-
object
NoDCEAnnotation extends NoTargetAnnotation with Product with Serializable
Indicate that DCE should not be run
- object PropagatePresetAnnotations
-
object
RemoveReset extends Transform with DependencyAPIMigration
Remove Synchronous Reset
Remove Synchronous Reset
- Note
This pass must run after LowerTypes
- object ReplaceTruncatingArithmetic
Deprecated Value Members
-
val
LegalizeClocksTransform: LegalizeClocksAndAsyncResetsTransform.type
- Annotations
- @deprecated
- Deprecated
(Since version FIRRTL 1.4.0) Replaced by LegalizeClocksAndAsyncResetsTransform
This is the documentation for Firrtl.