add ElaborationArtefactAnnotation

[albertchen-sifive]

Stopgap solution to issue of ElaborationArtefacts outputting stale instance paths. This adds ElaborationArtefactAnnotation which contains the filename and list of Tokens that contain the contents of the file. Token subclasses are StringToken, ModulePathToken, and ReferencePathToken. ModulePathToken and ReferencePathToken contain Targets that are updated by firrtl. ElaborationArtefactsTransform serializes the ElaborationArtefactAnnotations

ElaborationArtefactAnnotations can be annotated with the ElaborationArtefactAnnotation.annotate and Token.apply methods e.g.

ElaborationArtefactAnnotation.annotate("foo.json",
  Seq(Token(s"""{ foo: $foo, bar: $bar, mod: """"), Token(module), Token("""", ref: """"), Token(module.reset), Token("""" }"""))

there is a TokensInterpolator implicit to make constructing Tokens easier.

ElaborationArtefactAnnotation.annotate("foo.json",
  tokens"""{ foo: $foo, bar: $bar, mod: $module, ref: ${module.reset} }""")

Token.apply requires a Tokenizer typeclass instance. instances are defined for String, Data, BaseModule, SyncReadMem

Type of change: feature request

Impact: API addition (no impact on existing code)

Development Phase: implementation

Release Notes

[DecodeTheEncoded]

so, what is the purpose of ElaborationArtefacts in general? I have no idea what it is for? Thanks!

[albertchen-sifive]

ElaborationArtefacts is a way to emit metadata to the generator build directory during elaboration. it's used to emit graphml and dts along with a bunch of other metadata files

rocket-chip/src/main/scala/subsystem/BaseSubsystem.scala

Lines 32 to 35 in 147bdcc

	ElaborationArtefacts.add("graphml", outer.graphML)
	ElaborationArtefacts.add("dts", outer.dts)
	ElaborationArtefacts.add("json", outer.json)
	ElaborationArtefacts.add("plusArgs", PlusArgArtefacts.serialize_cHeader)

the ElaborationArtefacts.add method takes two arguments, first one is the file extension and the second is the contents of that file as a String. so ElaborationArtefacts.add("foo", "bar") would write a file called $configName.foo with contents bar, where $configName would be either the config name or the name specified by the --name cmdline argument if it is present.

this PR adds ElaborationArtefactsAnnotation which works similarly to ElaborationArtefacts except that it is passed as an annotation through the firrtl compiler and takes a list of Tokens which may embed firrtl Targets. this allows for emitting metadata that relies on having correct instance paths and signal names.

[DecodeTheEncoded]

ElaborationArtefacts is a way to emit metadata to the generator build directory during elaboration. it's used to emit graphml and dts along with a bunch of other metadata files

rocket-chip/src/main/scala/subsystem/BaseSubsystem.scala

Lines 32 to 35 in 147bdcc

	ElaborationArtefacts.add("graphml", outer.graphML)
	ElaborationArtefacts.add("dts", outer.dts)
	ElaborationArtefacts.add("json", outer.json)
	ElaborationArtefacts.add("plusArgs", PlusArgArtefacts.serialize_cHeader)

the ElaborationArtefacts.add method takes two arguments, first one is the file extension and the second is the contents of that file as a String. so ElaborationArtefacts.add("foo", "bar") would write a file called $configName.foo with contents bar, where $configName would be either the config name or the name specified by the --name cmdline argument if it is present.

this PR adds ElaborationArtefactsAnnotation which works similarly to ElaborationArtefacts except that it is passed as an annotation through the firrtl compiler and takes a list of Tokens which may embed firrtl Targets. this allows for emitting metadata that relies on having correct instance paths and signal names.

Sorry for the delayed reply, Thank you for your detailed reply, I got it!