Adds tests for the PhaseManager. This includes outputs in
"test_run_dir" of Graphviz output. This will automatically generate a
PNG if "dot" is on the path. Otherwise, it will just generate the
Graphviz output.

This adds the PhaseManager class which can be used to determine a
sequence of Phases that should be run given the new Dependency API. A
PhaseManager determines an ordering that results in some target Phases
being run (without invalidations) given an initial state (some other
set of Phases).

This follows the original suggestion of @azidar with one (critical)
modification to the algorithm: the (DFS-based) topological sort of
dependencies is seeded using a topological sort of the
invalidations (this uses the DiGraph.seededLinearize method). This
ensures that the number of repeated Phases is kept to a minimum. (I am
not sure if this is actually optimal, however.)

This additionally adds some methods that generate Graphviz for the
Prerequisite/Invalidate graph.

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

This adds a DependencyAPI trait for Phase. This defines three member
functions that form the basis of defining dependencies between Phases:
prerequisites, dependents, and invalidates. Prerequisites define a set
of Phases that must run *before* some Phase. Dependents other Phases
which depend on this Phase (a way of "injecting" a prerequisite into
another Phase). Invalidates defines a function that can be called to
filter some collection of Phases to remove them from a Set (invalidate
that they ran).

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

This adds a method to DiGraph called "seededLinearize". This
generalizes the original topological sort ("linearize") to be
parametric in an initial set of vertices. This enables the user to
massage the DFS to produce a better topological sort if they have
information about how the DFS should proceed.

The initial set of vertices is expected to be made ordered via a
LinkedHashSet.

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

This removes the runTransform method from Stage in favor of a
DeletedWrapper Phase that wraps a Phase in logic to generate
DeletedAnnotations.

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

This abstracts away option writing such that users no longer have to
understand scopt semantics. This adds a ShellOption class and a
HasShellOptions trait for something which provides one or more
ShellOptions.

This refactors the FIRRTL codebase to use this style of option
specification.

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

This switches the OptionsView/Viewer typeclass to use more canonical
approaches and helper methods. This uses a context bound instead of an
explicitly specified implicit argument. Additionally, this adds an
apply method to OptionsView to enable more canonical use of the
OptionsView typeclass.

With this, you can now do things like `Viewer[FirrtlOptions].view` in
addition to the old (and still available)
`Viewer.view[FirrtlOptions]`. Uses of the latter are updated to use
the former.

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

- Add tests for DriverCompatibility.AddImplicitEmitter
- Add tests for DriverCompatibility.AddImplicitOutputFile
- Use a different top name in DriverSpec emit circuit tests for better
  coverage
- Add tests for DriverCompatibility.WriteEmitted
- Add catchWrites firrtlTests utility to intercept file writes
- Add tests for WriteOutputAnnotations
- Add tests for --custom-transforms reversing

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

This adds FirrtlStage, a reimplementation of the original FIRRTL
Driver as a Stage. This updates the original firrtl.options package to
implement FirrtlStage (namely, TransformLike is added). Finally, the
original FIRRTL Driver is converted to a compatibility wrapper around
FirrtlStage.

For background, Stage and Phase form the basis of the Chisel/FIRRTL
Hardware Compiler Framework (HCF). A Phase is a class that performs a
mathematical transformation on an AnnotationSeq (in effect, a
generalization of a FIRRTL transform). Curtly, a Stage is a Phase that
also provides a user interface for generating annotations. By their
construction, Phases are designed to be composed sequentially into a
transformation pipeline.

This modifies the existing options package (which provides
Stage/Phase) to build out a type hierarchy around Stage/Phase. This
adds TransformLike[A] which implements a mathematical transformation
over some type A. Additionally, and as an interface between different
TransformLikes, this adds Translator[A, B] which extends
TransformLike[A], but does an internal transformation over type B.
This is used to interface Phases with the existing FIRRTL compiler.

This adds a runTransform method to Phase that, like
Transform.runTransform, will automatically detect deleted Annotations
and generate DeletedAnnotations.

The new FirrtlStage, a reimplementation of FIRRTL's Driver, is added
as a Stage composed of the following Phases:

  1. AddDefaults - add default annotations
  2. AddImplicitEmitter - adds an implicit emitter derived from the
     compiler
  3. Checks - sanity check the AnnotationSeq
  4. AddCircuit - convert FIRRTL input files/sources to circuits
  5. AddImplicitOutputFile - add a default output file
  6. Compiler - run the FIRRTL compiler
  7. WriteEmitted - write any emitted modules/circuits to files

The Driver is converted to a compatibility layer that replicates old
Driver behavior. This is implemented by first using new toAnnotation
methods for CommonOptions and FirrtlExecutionOptions that enable
AnnotationSeq generation. Second, the generated AnnotationSeq is
preprocessed and sent to FirrtlStage. The resulting Phase order is
then:

  1. AddImplicitAnnotationFile - adds a default annotation file
  2. AddImplicitFirrtlFile - adds a default FIRRTL file using top name
  3. AddImplicitOutputFile - adds an output file from top name
  4. AddImplicitEmitter - adds a default emitter derived from a
     compiler and any split modules command line option
  5. FirrtlStage - the aforementioned new FirrtlStage

Finally, the output AnnotationSeq is then viewed as a
FirrtlExecutionResult. This compatibility layer enables uninterrupted
usage of old Driver infrastructure, e.g., FirrtlExecutionOptions and
CommonOptions can still be mutated directly and used to run the
Driver.

This results in differing behavior between the new FirrtlStage and the
old Driver, specifically:

  - FirrtlStage makes a clear delineation between a "compiler" and an
    "emitter". These are defined using separate options. A compiler is
    "-X/--compiler", while an emitter is one of "-E/--emit-circuit" or
    "-e/--emit-modules".
  - Related to the above, the "-fsm/--split-modules" has been removed
    from the FirrtlStage. This option is confusing once an implicit
    emitter is removed. It is also unclear how this should be handled
    once the user can specify multiple emitters, e.g., which emitter
    should "--split-modules" apply to?
  - WriteOutputAnnotations will, by default, not write
    DeletedAnnotations to the output file.
  - The old top name ("-tn/--top-name") option has been removed from
    FirrtlStage. This option is really a means to communicate what
    input and output files are as opposed to anything associated with
    the circuit name. This option is preserved for the Driver
    compatibility layer.

Additionally, this changes existing transform scheduling to work for
emitters (which subclass Transform). Previously, one emitter was
explicitly scheduled at the end of all transforms for a given
compiler. Additional emitters could be added, but they would be
scheduled as transforms. This fixes this to rely on transform
scheduling for all emitters. In slightly more detail:

  1. The explicit emitter is removed from Compiler.compile
  2. An explicit emitter is added to Compiler.compileAndEmit
  3. Compiler.mergeTransforms will schedule emitters as late as
     possible, i.e., all emitters will occur after transforms that
     output their input form.
  4. All AddImplicitEmitter phases (DriverCompatibility and normal)
     will add RunFirrtlTransformAnnotations to add implicit emitters

The FIRRTL fat jar utilities are changed to point at FirrtlStage and not
at the Driver. This has backwards incompatibility issues for users
that are using the utilities directly, e.g., Rocket Chip.

The Logger has been updated with methods for setting options based on
an AnnotationSeq. This migrates the Logger to use AnnotationSeq as
input parameters, e.g., for makeScope. Old-style methods are left in
place and deprecated. However, the Logger is not itself a Stage.
The options of Logger Annotations are included in the base Shell and
Stage is updated to wrap its Phases in a Logger scope.

Additionally, this changes any code that does option parsing to always
prepend an annotation as opposed to appending an annotation. This is
faster, but standardizing on this has implications for dealing with
the parallel compilation annotation ordering.

A Shell will now put the initial annotations first (in the order the
user specified) and then place all annotations generating from parsing
after that. This adds a test case to verify this behavior.

Discovered custom transforms (via `RunFirrtlTransformAnnotation`s) are
discovered by the compiler phase in a user-specified order, but are
stored in reverse order to more efficiently prepend (as opposed to
append) to a list. This now reverses the transform order before
execution to preserve backwards compatibility of custom transform
ordering.

The Compiler phase also generates one deleted annotation for each
`RunFirrtlTransformAnnotation`. These are also reversed.

Miscellaneous small changes:

  - Only mix in HasScoptOptions into Annotation companion objects (h/t
    @jackkoenig)
  - Store Compiler in CompilerAnnotation
  - CompilerNameAnnotation -> CompilerAnnotation
  - Make Emitter abstract in outputSuffix (move out of FirrtlOptions)
  - Add DriverCompatibility.AddImplicitOutputFile that will add an
    output file annotation based on the presence of a
    TopNameAnnotation. This is important for compatibility with the
    old Driver.
  - Cleanup Scaladoc
  - Refactor CircuitOption to be abstract in "toCircuit" that converts
    the option to a FirrtlCircuitAnnotation. This allows more of the
    conversion steps to be moved out of AddCircuit and into the actual
    annotation.
  - Add WriteDeletedAnnotation to module WriteOutputAnnotations
  - A method for accessing a FirrtlExecutionResultView is exposed in
    FIRRTL's DriverCompatibilityLayer
  - Using "--top-name/-tn" or "--split-modules/-fsm" with FirrtlStage
    generates an error indicating that this option is no longer
    supported
  - Using FirrtlStage without at least one emitter will generate a
    warning
  - Use vals for emitter in Compiler subclasses (these are used to
    build RunFirrtlTransformAnnotations and the object should be
    stable for comparisons)
  - Fixes to tests that use LowTransformSpec instead of
    MiddleTransformSpec. (SimpleTransformSpec is dumb and won't
    schedule transforms correctly. If you rely on an emitter, you need
    to use the right transform spec to test your transform if you're
    relying on an emitter.)

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

This changes the base Shell to print information about all registered
libraries/transforms. This addresses an @azidar comment about difficulty
debugging whether registration worked.

This also changes the "FIRRTL Transform Options" help text for registered
transforms to only print if registered transforms exist.

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

Designs with no SeqMems should produce empty MemConf strings, and this should be parsable without excepting (#1060)

* Add serialization support for LoadMemoryFileType in LoadMemoryAnnotation
Add custom LoadMemoryFileTypeSerializer.
Add test to verify LoadMemoryAnnotation can be correctly serialized/deserialized.

* Simplify and focus LoadMemoryAnnotation serialization/deserialization.
Respond to comments on earlier implementations.

* Add type FileType definition for current chisel3 code.

* Copy MemConf.scala from ucb-bar/barstools#35 into memlib.
This provides a data structure wrapper around the existing memory conf format
which contains both reading and writing methods, making it easier to write code
that needs to read the format.

* Add MemConf tests and use a Map[MemPort, Int] for port lists instead of a Seq[MemPort] which is a bit less fragile.

* Don't create nodes to hold Muxes with >0 void cases

* Added test case demonstrating void error

* Memoize intermediate expression when checking for WVoid-ness

* Add --nodedup option to facilitate FIRRTL to verilog regression testing.

* Short-circuit the DedupModules transform if NoCircuitDedupAnnotation exists.

* Create a simple generic graphviz renderer for DiGraph
There are three basic kinds
- A simple default renderer
- A ranked renderer that places nodes in columns based on depth from sources
- A sub-graph render for graphs that contain a loop
  - Renders just nodes that are part of first loop found
  - Plus the neighbors of the loop
  - Loop edges are shown in red.

* Create a simple generic graphviz renderer for DiGraph
- Moved the graph loop finder into DiGraph
- Fixed scala doc per Edward's comments

* Run CheckHighForm after all non-emitter transforms in firrtl tests

* Remove shlw from checks.scala

* Removed mistake in fix

* Fix FirrtlSpec fix

Fix almost all scaladoc warnings, add source links

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

This fixes all Scaladoc warnings except for those trying to link to
Java.

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

* refactor InferWidths to allow for extra contraints, add InferWidthsWithAnnos

* add test cases

* add ResolvedAnnotationPaths trait to InferWidthsWithAnnos

* remove println

* cleanup tests

* remove extraneous constraints

* use foreachStmt instead of mapStmt

* remove support for aggregates

* fold InferWidthsWithAnnos into InferWidths

* throw exception if ref not found, check for annos before AST walk

Instead, just forward the exception

Previously would require all requested reviewers must have approved a PR before merging.

* No time left for you - quickly rename deep bundles still occasionally fails.
Run the "quick" calibration test three times and choose the maximum as the basis for comparison with the "deep" test.

* Rename local variable to less confusing name.

* Correctly handle dots in loaded memory paths

* Added test for loadmem filename

* Attempt to deal with timing vagaries in UniquifySpec.quicklyrenamedeepbundles
Switching to Scala 2.12.8 cause this test to start failing on OSX. Try earlier scheme to compare shallow vs deep to reduce brittleness.

* Address review concerns; update comment.

Fixes #219

* Adds AsyncResetType (similar to ClockType)
* Registers with reset signal of type AsyncResetType are async reset
  registers
* Registers with async reset can only be reset to literal values
* Add initialization logic for async reset registers

Add "mverilog" Compiler Option, MinimumVerilogEmitter

This uses the foldShiftRight method of the ConstantPropagation
Transform when legalizing Shr PrimOps. This has the effect of removing
literals with bit extracts from the MinimumVerilogCompiler.

This makes the formerly private foldShiftRight method of a public
method of the ConstantPropagation companion object.

Tests in the MimimumVerilogCompilerSpec are updated to check that Shr
is handled as intended.

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