[RFC] Annotations subsume ExecutionOptions?

After thinking more about @azidar’s comments related to command line options as “that’s just an annotation”, I think I have an idea on how the options and annotations can be better unified. (Note: this may be me either not realizing that I’m parroting what was being said or that this may have been discussed before.)

Basically, command line options are annotations and with the maturity of the annotations refactor it makes sense to have a discussion about whether ExecutionOptionsManager is needed in its current capacity.

Currently, ExecutionsOptionsManager is serving two purposes:

1. Maintaining Driver-level information, e.g., the input file name (inputFileNameOverride for FirrltExecutionOptions)
2. Providing lightweight shims to generate annotations either indirectly with the help of the Driver (e.g., noDCE) or directly in the options manager (e.g., inline)

However, there are two oddities here that make things somewhat incongruent now that the annotations refactor is in place and lacking in extensibility once new, custom annotations/transforms are added:

Incongruency of annotations vs. Options: All options are just annotations. These either target nothing (NoTargetAnnotation) or some named component (SingleTargetAnnotation) or, assumedly, some to-be-defined multiple components (a not-yet-implemented MultiTargetAnnotation). The ability to define both “top level options” (e.g., CommonOptions) as well as NoTargetAnnotations seems particularly kludgy. Unifying on one (assumedly annotations) then means that everything that needs this information is passed along with the only thing that matters, the Circuit state.

Difficulties in adding command line options for external transforms: If I go and build an external library that adds annotations and transforms, it would be great if I can hack these directly into the command line option parsing providing by the current options manager. The current approach to doing this would seem to be to define my own options manager. While not insurmountable, this gets complicated if I"m combining several FIRRTL libraries together and want to run all their transforms. Here, there’s nothing that precludes forcing annotations to expose what options they take or using a trait that gets mixed into annotations (e.g., HasCommandLineOptions). The job of the options manager is then to use reflection to find all annotations that exist or all annotations that have the CLI options trait and running their methods to generate help text and parse everything. You then get some nice magic in that all the external libraries that may be used are then automatically included in command line parsing. Note: the ability of reflection to adequately do this has not been verified on my part, yet.

This seems intuitive to me and perhaps the direction that @jackkoenig was thinking with the annotations refactor (or this may have been brought up and discussed before).

The major downside of this is that this may not be doable in a way that avoids a simultaneous refactor of Chisel’s options manager. Furthermore, there are odd situations that may arise if certain annotations incorrectly modify (or delete) top-level, Driver-like annotations (like directories or output filenames). Technically this should all be allowable, though…

I can think about this some more and/or try to get a small PR that migrates an existing annotation into using this approach.

• Type of issue

  • Other enhancement

• What is the use case for changing the behavior?

This enables writers of custom passes to expose their command line options all the way to the top.

• Impact

  • API addition (no impact on existing code)

• Development Phase

  • proposal

• Other information (e.g. detailed explanation, stacktraces, related issues, suggestions how to fix, links for us to have context, eg. Stack Overflow, gitter, etc)

[seldridge]

@ducky64: Thanks for taking all these notes! I’ll try to work up some responses so that the wider community can see what’s going on with this.

@edwardcwang: There are two levels of impact, depending on what you’re doing:

1. Using FIRRTL fat jar as an executable: No impact. I.e., Rocket Chip should be unaffected.
2. Explicitly Constructing an ExecutionOptionsManager: You need to modify your code to not mutate options since var (chiselOptions, commonOptions, firrtlOptions) either no longer exist or are immutable. This results in you being highly advised to pass all options directly to the options manager. Most of the required modifications are pretty basic and make the construction of an options manager use the same API as the FIRRTL fat jar. Here’s one example: https://github.com/freechipsproject/firrtl/pull/765/files#diff-5663f8e864f20e181ba77401a196b733L522.

Note that for 2 you can always build a complete ExecutionOptionsManager (that will not error when you view it) from an incomplete ExecutionOptionsManager (that will error when you view it) with additional options that make in complete. The problem only comes if you want to “view” the annotations that an options manager collects before it has enough options to do this (it is an “incomplete” options manager). One example of doing this is how one of the old Chisel3 Driver.execute methods had to be modified as the FIRRTL source is not initially available: https://github.com/freechipsproject/chisel3/pull/804/files#diff-f7a19e5d7b232a5be3545b8ed7de50a5R168

[ducky64]

Feedback notes from today’s live mega-PR review, discussion including @seldridge @jackkoenig @ucbjrl @chick

• Augmented options parser seems useful and fine. Perhaps name it something more descriptive.
• HasChiselExecutionOptions trait: you really only need it if building an ExecutionOptionsManager. But can define a new class that pre-mixes things in for you.
• To add a new option, need to know the existing ones. You can have conflicts, can consider style guidelines for external libraries (like having a prefix).
• If you’re building your own ExecutionOptionsManager, you need to mix in all the right traits, but a failure should be a static (compile-time) failure. Can we have these propagate more automatically? This has been a problem.
• What about a more drastic refactoring that gets rid of the execution options manager in favor of annotations? Just want some way to parse arguments?
  • Things that query options should query annotations instead? Then the whole managers discussion may be moot?
• People are currently using ExecutionOptionsManager, especially where that is invoked programmatically. Like in some Berkeley chip tapeouts. Tried to preserve as much of the existing semantics as possible, though not 100%.
• Why chiselOptions can’t be a var (making it a val breaks compatibility)? We could, but probably shouldn’t?
• All the Chisel Driver stuff works, only stuff using ExecutionOptionsManager explicitly might break.
• FirrtlOption and ChiselOption are just type tags. Perhaps the functionality of the option should be encoded in the object itself, instead of in the viewer?
  • Can we seal some options? Some options exist in a different file, but can refactor to seal things.
• Still multiple sources of options: annotations file (which itself is an option), command line options. Confusing?
• Validation happens in both scopt and on annotations sequence
• Must bump Chisel as well, Chisel tests pass with a Chisel PR that @seldridge has. Treadle, firrtl-interpreter, and testers need to be bumped as well.
• Is there a more elegant way to define the top name (which is needed for the target-dir, which now depends on the circuit compile)? Is there a better future path for top name? Can we start deprecating stuff? Larger issue with Circuit and scopes?
• Where can common options shared between libraries be put? (example: between firrtl and treadle, they might be 90% the same)
• Is there a cleaner way to specify “add all the transforms”?