* Transform, not run in LegalizeAndReduction test

Switch from using FirrtlStage.transform to FirrtlStage.run in one
test. The latter is problematic as it doesn't include wrappers or
pre/post phases which are how things will work in the future for doing
file writing (via HowToSerialize ideas).

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Use execute in FIRRTL testing infra (not run)

Changes the FirrtlStage method in FIRRTL testing infrastructure from
"run" (which does not include Stage-global Phases) to "execute" (which
does).

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Add HowToSerialize Annotation mix-in

This adds an Annotation mix-in, HowToSerialize, that allows an
annotation to declare how it should be serialized to a file. The
mix-in is abstract in a baseFileName and a suffix (used to generate a
filename), a howToSerialize method (defining the string contents of
the file), and a howToResume method (that defines a replacement for
the file-serialized annotation that allows this to be resumed) [^1].

A default implementation for generating a filename (called filename)
is defined that will put the baseFileName+suffix file in the target
directory. This can be overridden by the annotation if desired.

[^1]: When an annotation is serialized to a file, it should be removed
from the emitted JSON-serialized annotations. The howToResume method
defines a way of adding replacement annotations to the JSON-serialized
annotations that tell a downstream tool how to find the serialized
file. E.g., if a FIRRTL circuit is written to a file, this could be
used to add a FirrtlFileAnnotation defining the location of the new
file.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Handle HowToSerialize in WriteOutputAnnotations

This extends firrtl.options.phase.WriteOutputAnnotations to serialize
HowToSerialize annotations to files.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Test HowToSerialize in WriteOutputAnnotationsSpec

This adds tests of the HowToSerialize mix-in inside the
WriteOutputAnnotationsSpec.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* [skip chisel tests] Migrate to HowToSerialize

This migrates EmittedAnnotations (and its children) to mixin the
HowToSerialize trait. This enables this annotations to be
automatically written to files via WriteOutputAnnotations

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Deprecated firrtl.stage.phases.WriteEmitted

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Use streams in HowToSerialize

This converts the HowToSerialize trait to use a Stream[Char] when
defining how an annotation should be serialized.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Switch from Stream[Char] to Stream[Byte]

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Change howToSerialize method to Iterable

Change the type of the HowToSerialize.howToSerialize method from a
stream to an iterable. Using the latter (the superset of both lazy
streams and non-lazy things like String) avoids problems with users
having to choose laziness when they already have an eager object.

In effect, this makes the API more general.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Add Scaladoc to HowToSerialize trait

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Change HowToSerialize to CustomFileEmission

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Add default implementation of replacements

Add a default implementation of CustomFileEmission.replacements.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Avoid unnecessary 2x monad in CustomFileEmission

Change the type of CustomFileEmission.replacements from
Option[AnnotationSeq] to AnnotationSeq. The latter has all the
properties of the former that I'm trying to express here: (1) can
emptiness and (2) monadicity (if the AnnotationSeq is converted to a
sequence first). The latter property is exploited in the
WriteOutputAnnotations phase to concisely flatMap over the annotations
and doing the double-monad is unnecessary.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Restrict CustomFileEmission filename API

Change the API of CustomFileEmission to use a final def for the actual
filename. The baseFileName is then made a method with an AnnotationSeq
parameter to allow the filename to change as a function of other
annotations, e.g., by an output circuit annotation.

By restricting this API, we have more control over the default
behavior of where things are written using the fixed behavior of the
filename method---files will always be written using the behavior that
StageOptions define. Previously, if users want customized behavior,
they would need to duplicate this StageOptions functionality (and
likely subtly deviate from the standard behavior and introduce
problems with their build).

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Add file conflict behavior for CustomFileEmission

Set behavior of file conflicts in CustomFileEmission to be the
following: No two annotations in the same annotation sequence can
serialize to the same file during the WriteOutputAnnotations phase.
However, if the output annotation file already exists, it will be
overwritten.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Return relative path from getBuildFileName

Change FirrtlOptions.getBuildFileName to simply serialize the
underlying Java File instead of converting this to its canonical path.
This should improve the relocatability of files produced by the
CustomFileEmission API.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Normalize paths in StageOptions.getBuildFile

Normalize paths inside the getBuildFileName utility of StageOptions.
Add a check to prevent a null pointer dereference.

Co-authored-by: Jack Koenig <koenig@sifive.com>
Co-authored-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Refer to CustomFIleEmission in deprecation message

Co-authored-by: Jack Koenig <koenig@sifive.com>
Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Simplify CustomFileEmission toBytes implementation

Co-authored-by: Jack Koenig <koenig@sifive.com>
Co-authored-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Use toBytes, not getBytes, in CustomFileEmission

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

Co-authored-by: Jack Koenig <koenig@sifive.com>

stage: allow a RunFirrtlTransformAnnotation(_:Emitter) annotation to be used in place of a CompilerAnnotation (#1835)

* scalatest: replace deprecated FlatSpec and add new Matchers import

* scalatest: 3.1.2 -> 3.2.1

Adds missing deprecation warnings to firrtl.Compiler methods: compile
and compileAndEmit. This provides a more informative message to the
user about how to actually migrate. Without this, the user only has
the generic deprecation warning about class Compiler.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Using the new trait to overwrite serialize at the
leaf classes, we ensure that new, e.g., Expression
nodes will not automatically try to call
`Serializer.serialize` which would fail by default.

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

* InstanceKeyGraph: add staticInstanceCount, getGraph and getChildrenInstanceMap

* InstanceKeyGraph: reachableModules, unreachableModules, lowestCommonAncestor and fullHierarchy

* Replace usage of InstanceGraph with InstanceKeyGraph

Also deprecates all unused methods.

* WiringUtils: make new version of sinksToSources package private

This will make our live easier next time we need to change it.

* CircuitGraph: use InstanceKeyGraph

* InstanceKeyGraphSpec: respect maximum line width

* InstanceKeyGraph: make constructor private

* InstanceKeyGraph: move lowestCommonAncestor function to Wiring

* WiringUtils: update deprecation message

* Use signed output in LargeParamExecutionTest

Change the Verilog used in LargeParamExecutionTest to match its
ExtModule specification. An ExtModule with an SInt port should map to
a separate Verilog module with a signed port and this is disjoint from
an ExtModule with a UInt port.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* Error on ExtModules w/ same defname, diff. ports

Adds a high form check to ensure that external modules that have the
same defname also have exactly the same ports.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Co-authored-by: chick <chick@qrhino.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

* Avoid repeated inlining in FlattenRegUpdate

When-else structure can lead to the same complex mux structure being
the default on several branches in register update logic. When these are
inlined, it can lead to artifical unreachable branches that show up as
coverage holes in coverage of the emitted Verilog. This commit changes
the inlining logic to prevent inlining any reference expression that
shows up multiple times because this is a common indicator of the
problematic case.

* Add tests for improved register update logic emission

* Improve FlattenRegUpdate comment and add more tests

* [skip formal checks] ICache equivalence check verified locally

They are never used outside of the class
not even in tests.

* WIP Commit

* Add EdgeDataDiGraph with views to amortize graph construction

* WIP, got basic structure, need tests to pipeclean

* First tests pass. Need more.

* Tests pass, more need to be written

* More tests pass! Things should work, except for memories

* Added clearPrev to fix digraph uses where caching prev breaks

* Removed old Component. Documented IRLookup

* Added comments. Make prev arg to getEdges

* WIP: Refactoring for CircuitGraph

* Refactored into CircuitGraph. Can do topological module analysis

* Removed old versions

* Added support for memories

* Added cached test

* More stufffff

* Added implicit caching of connectivity

* Added tests for IRLookup, and others

* Many major changes.

Replaced CircuitGraph as ConnectionGraph
Added CircuitGraph to be top-level user-facing object
ConnectionGraph now automatically shortcuts getEdges
ConnectionGraph overwrites BFS as PriorityBFS
Added leafModule to Target
Added lookup by kind to IRLookup
Added more tests

* Reordered stuff in ConnectionGraph

* Made path work with deep hierarchies. Added PML for IllegalClockCrossings

* Made pathsInDAG work with current shortcut semantics

* Bugfix: check pathless targets when shortcutting paths

* Added documentation/licenses

* Removed UnnamedToken and related functionality

* Added documentation of ConnectionGraph

* Added back topo, needed for correct solving of intermediate modules

* Bugfix. Cache intermediate clockSources from same BFS with same root, but not BFS with different root

* Added literal/invalid clock source, and unknown top for getclocksource

* Bugfix for clocks in bundles

* Add CompleteTargetSerializer and test

* remove ClockFinder, be able to compile.

* test is able to compile, but need to fix.

* public and abstract DiGraph, remove DiGraphLike.

* revert some DiGraph code, ConnectionGraphSpec passed.

* CircuitGraphSpec passed.

* minimize diff between master

* codes clean up

* override linearize and revert DiGraph

* keep DiGraph unchanged.

* make ci happy again.

* codes clean up.

* bug fix for rebase

* remove wir

* make scaladoc happy again.

* update for review.

* add some documentation.

* remove tag

* wip IRLookup

* code clean up and add some doucmentations.

* IRLookup cache with ModuleTarget guarded.

* make unidoc and 2.13 happy

Co-authored-by: Adam Izraelevitz <azidar@gmail.com>
Co-authored-by: Albert Magyar <albert.magyar@gmail.com>
Co-authored-by: Jack Koenig <koenig@sifive.com>

* ir: use Serializer.serialize where possible

* ir.Serializer: serialize MultiInfo correctly

* ir.Serializer: empty body needs to result in a skip statement

The firrtl grammar requires at least one statement.

* ir.Serializer: correctly serialize fixed point types and literals

* Serializer: change Seq -> Iterable in order to be Scala 2.13 compatible

Scala 2.13 support

0.9.16+ fixes https://github.com/scalacenter/scalafix/issues/1109
-Ywarn-unused-imports seems to be no longer supported by 2.13:
https://github.com/scala/scala/releases/tag/v2.13.0

This should not be needed in firrtl.

The values end up being converted to BigDecimal
anyways.

Extending HashMap is discouraged.

semanticdb seemed to be missing a 2.13 package

* WiringUtils.sinksToSources: make sinkInsts order deterministic

* WiringUtils: make owners a LinkedHashMap

* Wiring: only make something a Wire if it isn't a port already

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

* InferTypesFlowsAndKindsSpec: test the results of InferTypes, ResolveKinds and ResolveFlows

* Don't use passes sub-package in tests

This changes two test files using the "passes" sub-package to
"firrtl.passes". This allows a new "firrtlTests.passes" package to be
freely created and used without a name collision.

Signed-off-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>

* ResolveFlows: only depends on types and working ir

The types are needed to know the orientation of
a bundle field of a SubField node.

* InferTypes: fix bugs with unknown widths on ports and memories

* LoweringCompileSpec: Uniquify pass moved

Co-authored-by: Schuyler Eldridge <schuyler.eldridge@ibm.com>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

* RenameMapSpec: try rename instance and port

* RenameMapSpec: explicit chaining is required

Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

dshl amount must be < 20 bits, not <= 20 bits.

Resolves #1794

Create new scopes for child statements of Conditionally

* See #1505
* Inferred mports are implicitly added to scope of their parent mem
* This allows current chisel3 emission to work with new scope checks
* This may change in a future refactor of CHIRRTL memory ports

* Add specific test for shadowing