FIRRTL Annotations

The Scala FIRRTL Compiler (SFC) provides a mechanism to encode arbitrary metadata and associate it with zero or more “things” in a FIRRTL circuit. This mechanism is an Annotation and the association is described using one or more Targets. Annotations should be viewed as an extension to the FIRRTL IR specification, and can greatly affect the meaning and interpretation of the IR.

Annotations are represented as a dictionary, with a “class” field which describes which annotation it is, and a “target” field which represents the IR object it is attached to. The annotation’s class matches the name of a Java class in the Scala Chisel/FIRRTL code base. Annotations may have arbitrary additional fields attached. Some annotation classes extend other annotations, which effectively means that the subclass annotation implies to effect of the parent annotation.

Annotations are serializable to JSON and either live in a separate file (e.g., during the handoff between Chisel and the SFC) or are stored in-memory (e.g., during SFC-based compilation). The SFC pass API requires that passes describe which targets in the circuit they update. SFC infrastructure then automatically updates annotations so they are always synchronized with their corresponding FIRRTL IR.

An example of an annotation is the DontTouchAnnotation, which can be used to indicate to the compiler that a wire “foo” should not be optimized away.

{
  "class":"firrtl.transforms.DontTouchAnnotation",
  "target":"~MyCircuit|MyModule>foo"
}

Some annotations have more complex interactions with the IR. For example the BoringUtils provides FIRRTL with annotations which can be used to wire together any two things across the module instance hierarchy.

Motivation ¶

Historically, annotations grew out of three choices in the design of FIRRTL IR:

1. FIRRTL IR is not extensible with user-defined IR nodes.
2. FIRRTL IR is not parameterized.
3. FIRRTL IR does not support in-IR attributes.

Annotations have then been used for all manner of extensions including:

1. Encoding SystemVerilog nodes into the IR using special printfs, an example of working around (1) above.
2. Setting the reset vector of different, identical CPU cores, an example of working around (2) above.
3. Encoding sources and sinks that should be wired together by an SFC pass, an example of (3) above.

Targets ¶

A circuit is described, stored, and optimized in a folded representation. For example, there may be multiple instances of a module which will eventually become multiple physical copies of that module on the die.

Targets are a mechanism to identify specific hardware in specific instances of modules in a FIRRTL circuit. A target consists of a circuit, a root module, an optional instance hierarchy, and an optional reference. A target can only identify hardware with a name, e.g., a circuit, module, instance, register, wire, or node. References may further refer to specific fields or subindices in aggregates. A target with no instance hierarchy is local. A target with an instance hierarchy is non-local.

Targets use a shorthand syntax of the form:

target ::= “~” (circuit) (“|” (module) (“/” (instance) “:” (module) )* (“>” (ref) )?)?

A reference is a name inside a module and one or more qualifying tokens that encode subfields (of a bundle) or subindices (of a vector):

reference ::= (name) ("[" (index) "]" | "." (field))*

Targets are specific enough to refer to any specific module in a folded, unfolded, or partially folded representation.

To show some examples of what these look like, consider the following example circuit. This consists of four instances of module Baz, two instances of module Bar, and one instance of module Foo:

circuit Foo:
  module Foo:
    inst a of Bar
    inst b of Bar
  module Bar:
    inst c of Baz
    inst d of Baz
  module Baz:
    skip

Folded Module	Unfolded Modules

Using targets (or multiple targets), any specific module, instance, or combination of instances can be expressed. Some examples include:

If a target does not contain an instance path, it is a local target. A local target points to all instances of a module. If a target contains an instance path, it is a non-local target. A non-local target may not point to all instances of a module. Additionally, a non-local target may have an equivalent local target representation.

Inline Annotations ¶

The MLIR FIRRTL compiler supports an inline format for annotations as an extension to the FIRRTL syntax. These inline annotations are helpful for making single-file annotated FIRRTL code. This is not supported by the Scala FIRRTL compiler.

Inline annotations are attached to the circuit, and are JSON wrapped in %[ and ].

circuit Foo: %[[{"a":"a","target":"~Foo"}]]
  module Foo:
    skip

Annotations in CIRCT ¶

We plan to provide full support for annotations in CIRCT. The FIRRTL dialect current supports:

1. All non-local annotations can be parsed and applied to the correct circuit component.
2. Annotations, with and without references, are copied to the correct ground type in the LowerTypes pass.

Annotations can be parsed using the --annotation-file command line argument to the firtool utility. Alternatively, we provide a non-standard way of encoding annotations in the FIRRTL IR textual representation. We provide this non-standard support primarily to make test writing easier. As an example of this, consider the following JSON annotation file:

[
  {
    "target": "~Foo|Foo",
    "hello": "world"
  }
]

This can be equivalently, in CIRCT, expressed as:

circuit Foo: %[[{"target":"~Foo|Foo","hello":"world"}]]
  module Foo:
    skip

During parsing, annotations are “scattered” into the MLIR representation as operation or port attributes. As an example of this, the above parses into the following MLIR representation:

firrtl.circuit "Foo" {
  firrtl.module @Foo() attributes {annotations = [{hello = "world"}]} {
    firrtl.skip
  }
}

Targets without references have their targets stripped during scattering since target information is redundant once annotation metadata is attached to the IR. Targets with references have the reference portion of the target included in the attribute. The LowerTypes pass then uses this reference information to attach annotation metadata to only the lowered portion of a targeted circuit component.

Annotations are expected to be fully removed via custom transforms, conversion to other MLIR operations, or dropped. A warning will be emitted if there are any unused annotations still in the circuit. For example, the ModuleInliner pass removes firrtl.passes.InlineAnnotation by inlining annotated modules or instances. JSON Annotations map to the builtin MLIR attributes. An annotation is implemented using a DictionaryAttr, which holds the class, target, and any annotation specific data.

Annotations ¶

Annotations here are written in their JSON format. A “reference target” indicates that the annotation could target any object in the hierarchy, although there may be further restrictions in the annotation.

This document describes the annotations supported by CIRCT’s FIRRTL compiler.

Object Type Definitions ¶

These are reusable object types that can be used in annotation parameters.

AugmentedField ¶

A field in an augmented bundle type. This can provide a small description of what the field in the bundle is.

AugmentedType ¶

Represents any Grand Central augmented type (AugmentedGroundType, AugmentedVectorType, or AugmentedBundleType). The actual type is determined by the “class” field in the JSON object.

ReferenceTarget ¶

Represents a reference to a specific component in the FIRRTL circuit hierarchy. Used in Grand Central annotations to specify targets for interface connections.

FIRRTL Annotations ¶

chisel3.ModulePrefixAnnotation ¶

Adds a prefix to the module name during compilation.

Example:

{
  "class": "chisel3.ModulePrefixAnnotation",
  "target": "~Foo|Bar",
  "prefix": "MyPrefix_"
}

chisel3.experimental.Trace$TraceAnnotation ¶

Marks a signal for tracing with its Chisel type information.

Example:

{
  "class": "chisel3.experimental.Trace$TraceAnnotation",
  "target": "~Foo|Bar>signal",
  "chiselType": "UInt<8>",
  "target": "trace_signal"
}

chisel3.experimental.Trace$TraceNameAnnotation ¶

Specifies a trace name for the annotated signal.

Example:

{
  "class": "chisel3.experimental.Trace$TraceNameAnnotation",
  "target": "~Foo|Bar>signal",
  "name": "trace_signal"
}

chisel3.util.experimental.ForceNameAnnotation ¶

Forces a specific name for the annotated component, preventing name changes during compilation.

Example:

{
  "class": "chisel3.util.experimental.ForceNameAnnotation",
  "target": "~Foo|Bar",
  "name": "ForcedName"
}

chisel3.util.experimental.decode.DecodeTableAnnotation ¶

Annotation for decode table specifications in Chisel.

Example:

{
  "class": "chisel3.util.experimental.decode.DecodeTableAnnotation",
  "table": "..."
}

circt.BodyTypeLoweringAnnotation ¶

Specify the type lowering option for module internal signals. This is similar to the Convention annotation, but for internal signals rather than module ports.

When includeHierarchy is false, it indicates the convention is applied only to the specified module. If includeHierarchy is true, the convention is applied to all modules in the hierarchy. If there are multiple annotation instances that specify conventions, the scalarized convention takes precedence over the internal convention.

Example:

{
  "class": "circt.BodyTypeLoweringAnnotation",
  "convention": "scalarized",
  "target": "~Foo|Bar",
  "includeHierarchy": true
}

circt.ConventionAnnotation ¶

Specify the port convention for a module. The port convention controls how a module’s ports are transformed, and how that module can be instantiated, in the output format.

The options are:

• scalarized: Convert aggregate ports (i.e. vector or bundles) into multiple ground-typed ports.

Example:

{
  "class": "circt.ConventionAnnotation",
  "convention": "scalarized",
  "target": "~Foo|Bar/d:Baz"
}

circt.ExcludeFromFullResetAnnotation ¶

This annotation indicates that the target module should be excluded from the FullResetAnnotation of a parent module.

Example:

{
  "class": "circt.IgnoreFullAsyncResetAnnotation",
  "target": "~Foo|Bar/d:Baz"
}

circt.FullResetAnnotation ¶

The target must be a signal that is a reset. The type of the signal must be (or inferred to be) the same as the reset type specified in the annotation.

Indicates that all reset-less registers which are children of the module containing the target will have the reset targeted attached, with a reset value of 0.

The module containing the target of this annotation is not allowed to reside in multiple hierarchies.

Example:

{
  "class": "circt.FullResetAnnotation",
  "target": "~Foo|Bar/d:Baz>reset",
  "resetType": "async"
}

circt.OutputDirAnnotation ¶

Specify the output directory for a module. The target must be a public module, and must be local.

Example:

{
  "class": "circt.OutputDirAnnotation",
  "target": "~Foo|Bar",
  "dirname": "output/bar"
}

circt.VerbatimBlackBoxAnno ¶

Specifies verbatim black box source code with one or more files. Each file object in the files array contains:

• content: The literal source code content
• output_file: Path to the output file

This annotation is used internally by CIRCT to represent partially lowered FIRRTL extmodules with verbatim content.

Example:

{
  "class": "circt.VerbatimBlackBoxAnno",
  "target": "~Foo|MyBlackBox",
  "files": [
    {
      "content": "module MyBlackBox(\n  input clk,\n  output out\n);\n  assign out = clk;\nendmodule",
      "output_file": "blackbox.v"
    }
  ]
}

firrtl.AttributeAnnotation ¶

Attaches SV attributes to a specified target. A reference target must be a wire, node, reg, or module.

This annotation doesn’t prevent optimizations so it’s necessary to add DontTouchAnnotation if users want to preserve the target.

Example:

{
  "class": "firrtl.AttributeAnnotation",
  "target": "~Foo|Foo>r",
  "description": "debug = \"true\""
}

Scala documentation: https://javadoc.io/doc/edu.berkeley.cs/firrtl_2.13/latest/firrtl/AttributeAnnotation.html

firrtl.DocStringAnnotation ¶

Attaches a comment to a specified target. A reference target must be a wire, node, reg, or module.

This annotation doesn’t prevent optimizations so it’s necessary to add DontTouchAnnotation if users want to preserve the target.

Example:

{
  "class": "firrtl.DocStringAnnotation",
  "target": "~Foo|Foo>r",
  "description": "comment"
}

Scala documentation: https://javadoc.io/doc/edu.berkeley.cs/firrtl_2.13/latest/firrtl/DocStringAnnotation.html

firrtl.annotations.LoadMemoryAnnotation ¶

Specifies a file to load memory contents from during simulation.

Example:

{
  "class": "firrtl.annotations.LoadMemoryAnnotation",
  "target": "~Foo|Bar>mem",
  "fileName": "mem_init.hex",
  "hexOrBinary": "h"
}

firrtl.annotations.MemoryFileInlineAnnotation ¶

Specifies inline memory file loading for simulation.

Example:

{
  "class": "firrtl.annotations.MemoryFileInlineAnnotation",
  "target": "~Foo|Bar>mem",
  "filename": "mem_inline.hex",
  "hexOrBinary": "h"
}

firrtl.annotations.TargetToken$Field ¶

This is used to represent an index in to an aggregate type, such as an index or array.

firrtl.passes.InlineAnnotation ¶

Indicates that the target should be inlined.

Example:

{
  "class": "firrtl.passes.InlineAnnotation",
  "target": "~Foo|Bar/d:Baz"
}

Scala documentation: https://javadoc.io/doc/edu.berkeley.cs/firrtl_2.13/latest/firrtl/passes/InlineAnnotation.html

firrtl.passes.wiring.SinkAnnotation ¶

Marks a component as a wiring sink for the WiringTransform.

Example:

{
  "class": "firrtl.passes.wiring.SinkAnnotation",
  "target": "~Foo|Bar>sink",
  "pin": "myPin"
}

firrtl.passes.wiring.SourceAnnotation ¶

Marks a component as a wiring source for the WiringTransform.

Example:

{
  "class": "firrtl.passes.wiring.SourceAnnotation",
  "target": "~Foo|Bar>source",
  "pin": "myPin"
}

firrtl.stage.RunFirrtlTransformAnnotation ¶

Specifies a FIRRTL transform to run during compilation. This annotation is recognized but ignored by CIRCT.

Example:

{
  "class": "firrtl.stage.RunFirrtlTransformAnnotation",
  "transformClass": "firrtl.transforms.MyCustomTransform"
}

firrtl.transforms.BlackBox ¶

Attached to any external module created from any of the other blackbox annotations, such as BlackBoxInlineAnno.

This is used when generating metadata about external modules to distinguish generated modules. This annotation is internal to the MLIR FIRRTL compiler.

Example:

{
  "class": "firrtl.transforms.BlackBox",
  "target": "~Foo|Foo"
}

firrtl.transforms.BlackBoxInlineAnno ¶

Specifies the black box source code (text) inline. Generates a file with the given name in the target directory.

Example:

{
  "class": "firrtl.transforms.BlackBoxInlineAnno",
  "target": "~Foo|Foo",
  "name": "blackbox-inline.v",
  "text": "module ExtInline(); endmodule\n"
}

Scala documentation: https://javadoc.io/doc/edu.berkeley.cs/firrtl_2.13/latest/firrtl/transforms/BlackBoxInlineAnno.html

firrtl.transforms.BlackBoxPathAnno ¶

Specifies the file path as source code for the module. Copies the file to the target directory.

Example:

{
  "class": "firrtl.transforms.BlackBoxPathAnno",
  "target": "~Foo|Foo",
  "path": "myfile.v"
}

Scala documentation: https://javadoc.io/doc/edu.berkeley.cs/firrtl_2.13/latest/firrtl/transforms/BlackBoxPathAnno.html

firrtl.transforms.BlackBoxTargetDirAnno ¶

Overrides the target directory into which black box source files are emitted.

Example:

{
  "class": "firrtl.transforms.BlackBoxTargetDirAnno",
  "targetDir": "/tmp/circt/output"
}

Scala documentation: https://javadoc.io/doc/edu.berkeley.cs/firrtl_2.13/latest/firrtl/transforms/BlackBoxTargetDirAnno.html

firrtl.transforms.DedupGroupAnnotation ¶

This annotation assigns the targeted module to a dedup group. Modules that belong to a dedup group may only be deduplicated with modules that are part of the same group.

Example:

{
  "class": "firrtl.transforms.DedupGroupAnnotation",
  "target": "~Foo|Bar",
  "group": "group1"
}

firrtl.transforms.DontTouchAnnotation ¶

Prevents the removal of elements through optimization.

This annotation is an optimization barrier. For example, it blocks constant propagation through it. This annotation also ensures that the name of the object is preserved, and not discarded or modified.

Example:

{
  "class": "firrtl.transforms.DontTouchAnnotation",
  "target": "~Foo|Bar/d:Baz"
}

Scala documentation: https://javadoc.io/doc/edu.berkeley.cs/firrtl_2.13/latest/firrtl/DontTouchAnnotation.html

firrtl.transforms.FlattenAnnotation ¶

Indicates that the target should be flattened, which means that child instances will be recursively inlined.

Example:

{
  "class": "firrtl.transforms.FlattenAnnotation",
  "target": "~Foo|Bar/d:Baz"
}

Scala documentation: https://javadoc.io/doc/edu.berkeley.cs/firrtl_2.13/latest/firrtl/transforms/FlattenAnnotation.html

firrtl.transforms.MustDeduplicateAnnotation ¶

This annotation causes the deduplication pass to check that the listed modules are deduplicated with each other.

Example:

{
  "class": "firrtl.transforms.MustDeduplicateAnnotation",
  "modules": ["~Foo|Bar", "~Foo|Baz"]
}

firrtl.transforms.NoDedupAnnotation ¶

Prevents deduplication of the annotated module. Both regular modules and external modules can be deduplicated, so this annotation can target either.

Example:

{
  "class": "firrtl.transforms.NoDedupAnnotation",
  "target": "~Foo|Bar"
}

freechips.rocketchip.annotations.InternalVerifBlackBoxAnnotation ¶

Marks an external module as an internal verification black box for RocketChip. When instantiated inside the DUT, the module is marked for coverage extraction.

Example:

{
  "class": "freechips.rocketchip.annotations.InternalVerifBlackBoxAnnotation",
  "target": "~Foo|VerifBlackBox"
}

freechips.rocketchip.util.RetimeModuleAnnotation ¶

This annotation is used to mark modules which should be retimed, and is generally just passed through to other tools.

Example:

{
  "class": "freechips.rocketchip.util.RetimeModuleAnnotation",
  "target": "~Foo|Bar"
}

sifive.enterprise.firrtl.AddSeqMemPortAnnotation ¶

This annotation causes an extra port to be added to all SRAM modules in the DUT. The extra port is a regular module port of unsigned integer type with the specified width. These extra ports are commonly used to implement SRAM features not represented by the FIRRTL memory op, such as MBIST. The added port will be wired to the DUT, where it will be tied to 0.

Example:

{
  "class":"sifive.enterprise.firrtl.AddSeqMemPortAnnotation",
  "name":"user_outputs",
  "input":false,
  "width":1
}

sifive.enterprise.firrtl.AddSeqMemPortsFileAnnotation ¶

This annotation is used to emit metadata about the extra ports created by AddSeqMemPortAnnotation. This file is emitted relative to the MetadataDirAnnotation. The file lists each SRAM and provides the mapping to where it is in the hierarchy, and gives its IO prefix at the DUT top level.

Example:

{
  "class":"sifive.enterprise.firrtl.AddSeqMemPortsFileAnnotation",
  "filename":"SRAMPorts.txt"
}

sifive.enterprise.firrtl.ConvertMemToRegOfVecAnnotation$ ¶

Circuit-level annotation that converts all memories in the design to register vectors. This annotation does not target specific memories - it applies to the entire circuit.

Example:

{
  "class": "sifive.enterprise.firrtl.ConvertMemToRegOfVecAnnotation$"
}

sifive.enterprise.firrtl.ExtractAssertionsAnnotation ¶

Triggers extraction of assertions to a separate file.

Example:

{
  "class": "sifive.enterprise.firrtl.ExtractAssertionsAnnotation",
  "directory": "assertions"
}

sifive.enterprise.firrtl.ExtractAssumptionsAnnotation ¶

Triggers extraction of assumptions to a separate file.

Example:

{
  "class": "sifive.enterprise.firrtl.ExtractAssumptionsAnnotation",
  "directory": "assumptions"
}

sifive.enterprise.firrtl.ExtractBlackBoxAnnotation ¶

This annotation causes the ExtractInstances pass to move the annotated instance, or all instances if the annotation is on a module, upwards in the hierarchy. If the dest field is present and non-empty, the instances are placed in a module underneath the DUT (marked by MarkDUTAnnotation) with the name provided in that field. If the dest field is empty, the instances are extracted out of the DUT, such that the DUT gains additional ports that correspond to the extracted instance ports.

This allows the DUT to be instantiated and custom implementations for the extracted instances to be provided at the instantiation site. Instances are never extracted out of the root module of the design.

Applies to modules and instances.

Example:

{
  "class": "sifive.enterprise.firrtl.ExtractBlackBoxAnnotation",
  "target": "~Foo|BlackBox",
  "filename": "blackbox_extract.txt",
  "prefix": "bb",
  "dest": "BlackBoxes"
}

sifive.enterprise.firrtl.ExtractClockGatesFileAnnotation ¶

This annotation causes the ExtractInstances pass to move instances of extmodules whose defnames end in EICG_wrapper upwards in the hierarchy, either out of the DUT if group is omitted or empty, or into a submodule of the DUT with the name given in group. The wiring prefix is hard-coded to clock_gate.

Applies to the circuit.

Example:

{
  "class": "sifive.enterprise.firrtl.ExtractClockGatesFileAnnotation",
  "filename": "clock_gates.txt",
  "group": "ClockGates"
}

sifive.enterprise.firrtl.ExtractCoverageAnnotation ¶

Triggers extraction of coverage statements to a separate file.

Example:

{
  "class": "sifive.enterprise.firrtl.ExtractCoverageAnnotation",
  "directory": "coverage"
}

sifive.enterprise.firrtl.ExtractSeqMemsFileAnnotation ¶

This annotation causes the ExtractInstances pass to move memory instances upwards in the hierarchy, either out of the DUT if group is omitted or empty, or into a submodule of the DUT with the name given in group. The wiring prefix is hard-coded to mem_wiring.

Applies to the circuit.

Example:

{
  "class": "sifive.enterprise.firrtl.ExtractSeqMemsFileAnnotation",
  "filename": "seq_mems.txt",
  "group": "Memories"
}

sifive.enterprise.firrtl.FullAsyncResetAnnotation ¶

The target must be a signal that is or is inferred to be an asynchronous reset.

Indicates that all reset-less registers which are children of the module containing the target will have the asynchronous reset targeted attached, with a reset value of 0.

The module containing the target of this annotation is not allowed to reside in multiple hierarchies.

Example:

{
  "class": "circt.FullResetAnnotation",
  "target": "~Foo|Bar/d:Baz>reset",
  "resetType": "async"
}

sifive.enterprise.firrtl.IgnoreFullAsyncResetAnnotation ¶

This annotation indicates that the target should be excluded from the FullAsyncResetAnnotation of a parent module.

Example:

{
  "class": "circt.IgnoreFullAsyncResetAnnotation",
  "target": "~Foo|Bar/d:Baz"
}

sifive.enterprise.firrtl.InjectDUTHierarchyAnnotation ¶

This annotation can be used to add an extra level of hierarchy in the design under the DUT (indicated with a MarkDUTAnnotation). All logic in the original DUT will be moved into a module with the specified name. This is typically used in combination with ExtractBlackBoxAnnotation to not intermix the original DUT contents with extracted module instantiations.

If the moveDut field is true, then the newly created module with the specified name will be treated as the design-under-test. The MarkDUTAnnotation will be moved to this module. If this field is false, then the design-under-test will not be changed.

This annotation should only appear zero or once.

Example:

{
  "class": "sifive.enterprise.firrtl.InjectDUTHierarchyAnnotation",
  "name": "Logic",
  "moveDut": false
}

sifive.enterprise.firrtl.MarkDUTAnnotation ¶

This annotation is used to mark the top module of the device under test. This can be used to distinguish modules in the test harness from modules in the DUT.

Example:

{
  "class":"sifive.enterprise.firrtl.MarkDUTAnnotation",
  "target":"Core.Core"
}

sifive.enterprise.firrtl.MetadataDirAnnotation ¶

This annotation is used to define the directory where metadata should be emitted. When this annotation is not present, metadata will be emitted to the “metadata” directory by default.

Example:

{
  "class":"sifive.enterprise.firrtl.MetadataDirAnnotation",
  "dirname":"build/metadata"
}

sifive.enterprise.firrtl.ModuleHierarchyAnnotation ¶

This annotation indicates that a module hierarchy JSON file should be emitted for the module hierarchy rooted at the design under test (DUT), as indicated by the MarkDUTAnnotation. See the SV attribute, firrtl.moduleHierarchyFile, for information about the JSON file format.

Example:

{
  "class": "sifive.enterprise.firrtl.ModuleHierarchyAnnotation",
  "filename": "./dir/hier.json"
}

sifive.enterprise.firrtl.RetimeModulesAnnotation ¶

This annotation triggers the creation of a file containing a JSON array containing the names of all modules annotated with the RetimeModuleAnnotation.

Example:

{
  "class": "sifive.enterprise.firrtl.RetimeModulesAnnotation",
  "filename": "retime_modules.json"
}

sifive.enterprise.firrtl.SitestBlackBoxAnnotation ¶

This annotation triggers the creation of a file containing a JSON array of the defnames of all external modules in the device under test which are not imported or inlined blackbox modules. This will only collect modules which are instantiated under a module annotated with MarkDUTAnnotation.

If any external modules (including imported and inlined blackboxes) have a SitestBlackBoxLibrariesAnnotation, the libraries specified in that annotation will be included in the output.

Example:

{
  "class": "sifive.enterprise.firrtl.SitestBlackBoxAnnotation",
  "filename": "dut_blackboxes.json"
}

sifive.enterprise.firrtl.SitestBlackBoxLibrariesAnnotation ¶

This annotation is used to specify additional library names that should be included in the blackbox metadata for an external module. When applied to an external module, the specified libraries will be added to the blackbox resource list in the generated metadata. Both the defname and any libraries specified by this annotation will be included in the metadata for non-imported and non-inlined blackboxes.

Example:

{
  "class": "sifive.enterprise.firrtl.SitestBlackBoxLibrariesAnnotation",
  "target": "~Foo|MyExtModule",
  "libraries": ["lib1", "lib2"]
}

sifive.enterprise.firrtl.SitestTestHarnessBlackBoxAnnotation ¶

This annotation triggers the creation of a file containing a JSON array of the defnames of all external modules in the test harness which are not imported or inlined blackbox modules. This will only collect modules which are not instantiated under a module annotated with MarkDUTAnnotation.

If any external modules (including imported and inlined blackboxes) have a SitestBlackBoxLibrariesAnnotation, the libraries specified in that annotation will also be included in the output.

Example:

{
  "class": "sifive.enterprise.firrtl.SitestTestHarnessBlackBoxAnnotation",
  "filename": "testharness_blackboxes.json"
}

sifive.enterprise.firrtl.TestBenchDirAnnotation ¶

This annotation is used to indicate where to emit the test bench modules generated by GrandCentral.

Example:

{
  "class": "sifive.enterprise.firrtl.TestBenchDirAnnotation",
  "dirname": "output/testbench"
}

sifive.enterprise.firrtl.TestHarnessPathAnnotation ¶

Specifies the path to the test harness module.

Example:

{
  "class": "sifive.enterprise.firrtl.TestHarnessPathAnnotation",
  "path": "TestHarness.v"
}

sifive.enterprise.grandcentral.AugmentedBundleType ¶

Creates a SystemVerilog interface for each bundle type in Grand Central views.

Example:

{
  "class": "sifive.enterprise.grandcentral.AugmentedBundleType",
  "defName": "MyInterface",
  "elements": [
    {
      "name": "field1",
      "description": "First field",
      "tpe": {"class": "sifive.enterprise.grandcentral.AugmentedGroundType", "ref": {...}}
    }
  ]
}

sifive.enterprise.grandcentral.AugmentedGroundType ¶

Creates a SystemVerilog logic type for Grand Central views.

Example:

{
  "class": "sifive.enterprise.grandcentral.AugmentedGroundType",
  "ref": { ... }
}

sifive.enterprise.grandcentral.AugmentedVectorType ¶

Creates a SystemVerilog unpacked array for Grand Central views.

Example:

{
  "class": "sifive.enterprise.grandcentral.AugmentedVectorType",
  "elements": [
    {"class": "sifive.enterprise.grandcentral.AugmentedGroundType", "ref": {...}},
    {"class": "sifive.enterprise.grandcentral.AugmentedGroundType", "ref": {...}}
  ]
}

sifive.enterprise.grandcentral.ExtractGrandCentralAnnotation ¶

This annotation controls where to “extract” Grand Central collateral from the circuit. This annotation is mandatory and can only appear once if the full Grand Central transform pipeline is run.

The directory member has no effect on the filename member, i.e., the directory will not be prepended to the filename.

The filename is optional. When specified, all binds will be emitted to that file. When omitted, each module will have an associated bindfile in directory named <module>-bind.sv.

Example:

{
  "class": "sifive.enterprise.grandcentral.ExtractGrandCentralAnnotation",
  "directory": "gct-dir",
  "filename": "bindings.sv"
}

sifive.enterprise.grandcentral.GrandCentralHierarchyFileAnnotation ¶

This annotation, if present, will emit a YAML representation of all interfaces that were generated by the Grand Central views pass. Equivalently, this is a different serialization of the information contained in all ViewAnnotations.

Example:

{
  "class" : "sifive.enterprise.grandcentral.GrandCentralHierarchyFileAnnotation",
  "filename" : "directory/file.yaml"
}

The format of the produced YAML file is a one-to-one mapping of the SystemVerilog interface to YAML. Consider the following SystemVerilog interface produced by GrandCentral:

interface Foo;
  // A 4-bit type
  logic [3:0] a;
  // A 2D vector of an 8-bit type
  logic [7:0] b [1:0][0:0];
  // A 1D vector of instances of Bar
  Bar bar[4]();
endinterface

interface Bar;
  logic c;
endinterface

interface Baz;
  logic d;
endinterface

This will produce the following YAML representation:

- name: Foo
  fields:
    - name: a
      description: A 4-bit type
      dimensions: [  ]
      width: 4
    - name: b
      description: A 2D vector of an 8-bit type
      dimensions: [ 1, 2 ]
      width: 8
  instances:
    - name: bar
      description: A 1D vector of instances of Bar
      dimensions: [ 4 ]
      interface:
        name: Bar
        fields:
          - name: c
            dimensions: [ ]
            width: 1
        instances: []
- name: Baz:
  fields:
    - name: d
      dimensions: [ ]
      width: 1
  instances: []

sifive.enterprise.grandcentral.GrandCentralView$SerializedViewAnnotation ¶

These annotations are used to represent a SystemVerilog interface, a location in which it should be instantiated, and XMRs to drive the interface. Any XMR sources receive DontTouchAnnotation to prevent these from being inadvertently deleted.

Either ViewAnnotation or GrandCentralView$SerializedViewAnnotation are the same in CIRCT. The latter has its “view” value serialized (again) to JSON and string-escaped. When CIRCT sees any JSON string it tries to recursively deserialize it. If this fails, this is deemed to be a string. If this succeeds, then the JSON is unpacked.

Example:

{
  "class": "sifive.enterprise.grandcentral.GrandCentralView$SerializedViewAnnotation",
  "name": "MyView",
  "companion": "~Foo|Companion",
  "parent": "~Foo|Parent",
  "view": {...}
}

sifive.enterprise.grandcentral.MemTapAnnotation ¶

Annotation for memory taps in Grand Central. This annotation has custom resolution logic that resolves ‘source’ and ‘sink’ fields internally, so it does not use standard target resolution.

Example:

{
  "class": "sifive.enterprise.grandcentral.MemTapAnnotation",
  "keys": ["mem_tap_1", "mem_tap_2"]
}

sifive.enterprise.grandcentral.ViewAnnotation ¶

Annotation for Grand Central views. Similar to SerializedViewAnnotation but with the view field not serialized to JSON.

Example:

{
  "class": "sifive.enterprise.grandcentral.ViewAnnotation",
  "name": "MyView",
  "companion": "~Foo|Companion",
  "parent": "~Foo|Parent",
  "view": {...}
}

sifive.enterprise.grandcentral.ViewAnnotation.companion ¶

Companion annotation for Grand Central views. Not in SFC (Scala FIRRTL Compiler). This annotation is created by applyGCTView and has a ’target’ field that points to the companion module. It is applied to modules and processed by the GrandCentral pass.

Example:

{
  "class": "sifive.enterprise.grandcentral.ViewAnnotation.companion",
  "target": "~Foo|Companion"
}

Attributes in SV ¶

Some annotations transform into attributes consumed by non-FIRRTL passes. This section describes well-defined attributes used by HW/SV passes.

firrtl.moduleHierarchyFile ¶

Used by HWExportModuleHierarchy. Signifies a root from which to dump the module hierarchy as a json file. This attribute is a list of files to output to, and has type ArrayAttr<OutputFileAttr>.

The exported JSON file encodes a recursive tree of module instances as JSON objects, with each object containing the following members:

• instance_name - A string describing the name of the instance. Note that the root module will have its instance_name set to the module’s name.
• module_name - A string describing the name of the module.
• instances - An array of objects, where each object is a direct instance within the current module.

firrtl.extract.assert ¶

Used by SVExtractTestCode. Specifies the output directory for extracted modules. This attribute has type OutputFileAttr.

firrtl.extract.assume ¶

Used by SVExtractTestCode. Specifies the output directory for extracted modules. This attribute has type OutputFileAttr.

firrtl.extract.cover ¶

Used by SVExtractTestCode. Specifies the output directory for extracted modules. This attribute has type OutputFileAttr.

firrtl.extract.assert.bindfile ¶

Used by SVExtractTestCode. Specifies the output file for extracted modules’ bind file. This attribute has type OutputFileAttr.

firrtl.extract.assume.bindfile ¶

Used by SVExtractTestCode. Specifies the output file for extracted modules’ bind file. This attribute has type OutputFileAttr.

firrtl.extract.cover.bindfile ¶

Used by SVExtractTestCode. Specifies the output file for extracted modules’ bind file. This attribute has type OutputFileAttr.

firrtl.extract.[cover|assume|assert].extra ¶

Used by SVExtractTestCode. Indicates a module whose instances should be extracted from the circuit in the indicated extraction type.