Chisel stage

[seldridge]

Related issue:

Type of change: other enhancement

Impact: API addition (no impact on existing code)

Development Phase: implementation

This PR provides a reimplementation of the Chisel Driver as a Stage. This involves three major additions/modifications:

1. Addition of a chisel3.stage package that implements ChiselStage
2. Addition of tests for chisel3.stage
3. Modification of chisel3.Driver to use ChiselStage with a compatibility layer

For a more exhaustive introduction to Stage/Phase, see chipsalliance/firrtl#1005.

Todo

• Add Scaladoc
• Deprecate ChiselExecutionResultView
  • This is an implicit object and can't be deprecated. Instead it's now private [chisel3]
• Note in documentation what is compatibility layer
• Mutate options to match old behavior

Structure

This PR

1. Add expected annotations
2. Write the CLI
3. Add the xOptions class (which is not a case class)
4. Write an options view to construct your xOptions
5. Add methods to existing ExecutionOptions to reconstruct an AnnotationSeq
6. Write all new phases to reimplement Driver functionality:
   • chisel3.stage.phases.Checks
   • chisel3.stage.phases.Elaborate
   • chisel3.stage.phases.Convert
   • chisel3.stage.phases.Emitter
   • chisel3.stage.phases.AddImplicitOutputFile
   • chisel3.stage.phases.AddImplicitOutputAnnotationFile
7. Write ChiselStage
8. Write any necessary compatibility layer and/or re-use existing compatibility layers
9. Write the new Stage
10. Replace old Driver logic with new phases

Anecdotally, this process is non-linear. I did this by incrementally porting the old Driver in pieces and moving whatever functionality I could into it when I had it. Git's --squash and --fixup help a lot for keeping the history sane when you do rebase. Additionally, writing tests as you go is tedious, but likely necessary.

Most of the porting difficulty is (1) deciding, without constraints, what you want the new stage to do and (2) writing the compatibility layer that interfaces this with the old Driver.

There are several temptations here that I think should be avoided:

• Opting to have the old Driver call an old, already ported, sub-Driver (e.g., have chisel3.Driver call firrtl.Driver). This causes the old Driver and the new Stage to use different code paths. While not insurmountable, this would seem to introduce the potential for subtle bugs between the two versions.
• For the same reasons as above, no functionality should differ between the old Driver and the new stage excepting compatibility layer phases and a view to an execution result.

Most of difficulty in not yielding to these temptations is dealing with situations where the old Driver does not do things in a linear, pipe-like order. E.g., the old Chisel Driver would do elaboration and then continually refer back to the elaborated Chisel circuit. The stage doesn't need to do this as it's moving directly towards a CHIRRTL circuit or to run the FIRRTL compiler. However, the compatibility wrapper has to reconstruct what happened. This PR gets around this, kludgily, by viewing deleted annotations. This isn't really advised, but for a compatibility layer it's passable.

Depends on:

• Stage/Phase firrtl#1005.

Includes:

• A number of style/import cleanups to chisel-stage #1095

Release Notes

• Adds ChiselStage, a the Chisel Driver as a firrtl.options.Stage
• The original Chisel Driver is converted to a compatibility layer around ChiselStage

[seldridge]

Note: this is causing testers to fail on:

• chisel3.iotesters.BlackBoxVerilogDeliverySpec
• examples.AccumulatorBlackBoxPeekPokeTestVerilator

[chick]

I am out today but will try and dig into this tonight

[chick]

This looks like a test set-up error. It is failing because VCS is not present. I'll ask @ucbjrl about it this morning

[seldridge]

Looking at this. There's an annoyance in that the old Driver.execute mutates the options and passes that to FIRRTL. This has the effect that running Driver.execute and then inspecting the options manager will differ with this PR as it stands (e.g., getAnnotations). I'm seeing about a fix to preserver backwards compatibility.

[seldridge]

Following up on the previous comment: the specific issue stems from Driver.scala#L236. Inside chisel3.Driver.execute the input options manager is mutated and passed to firrtl.Driver.execute. FIRRTL does not (as far as I can tell) mutate the options manager. However, anything downstream that looks at the mutated options manager has a view of the options just before FIRRTL runs. This includes all input FIRRTL annotations which may be necessary for things like testers.

This is fixed by adding a couple of additional phases. In the new chisel3.Driver, a NoRunFirrtlAnnotation is added to disable ChiselStage running FirrtlStage. After ChiselStage a MutateOptionsManager(a: ExecutionOptionsManager with ...) runs to mutate the options manager. FirrtlStage is then possibly re-enabled. Then a new MaybeFirrtlStage runs that will run FirrtlStage if it's supposed to.

Corollary: mutable state is the root of all evil.

Addendum: if a Stage isn't working, it probably needs more Phases....

[chick]

I think this looks very good. Tests seem clean
Lot's of nitty gritty details
Some errors and warnings in scaladoc
a few other scala style

[chick]

Looks good to me. All my nits are cleaned up.
@jackkoenig @ducky64 either of you want to weigh in here too?

[jackkoenig]

I didn't realize you can ++ Option but it makes sense, cool!