The definitive binding refactor thread, request for comments

This is a summary of all the issues related to the bindings refactor (issues #440, #445, #419, #399, #368, #282, parts of #535, #543), and the proposed path forward. Work on this should begin soon.

Terminology & Conventions

These will primarily be documentation clarifications.

• Terminally-bound nodes will be called hardware
• Non-terminally bound nodes will be called chisel types
• “conventional” (non-flipped) Bundle directionality is as a dataflow source or master (when relevant, for some buses).
  • This is consistent with current Decoupled convention.

Directionality

• Nodes can have these directions: Input, Output, Bidirectional (for Aggregates, below, or Analog), or Unspecified (default).
• Output(...) and Input(...) will (effectively) clear direction of internal nodes, so the top-level node can be set to an input/output.
• Aggregate rules, including Bundles and Vecs:
  • All or no elements must be Unspecified.
  • Considered Bidirectional if there are both Input, Output, or Bidirectional elements, otherwise either Input, Output, or Unspecified.
  • Can only contain chisel types
• Internally: Deduplicate the directionality data source by using only hierarchical directionality (dropping leaf directionality). Leaf directionality can be resolved using parent links.
  • Since top-level bindings are required, that becomes a convenient place to create parent links.
  • Chisel (compatibility mode) didn’t require top-level bindings, but Chisel also skips the directionality system. firrtlDirection (hierarchical directionality) is sufficient to emit FIRRTL.
  • For performance reasons, leaf directionality can still be cached.
  • Bonus: this may eliminate the need for _onModuleClose
• Parent links will be a private chisel3 feature for now.

Binding operations

• Wire(t) must have t of chisel type
• Reg(t), Mem(t), Vec(t) must have t of chisel type that is not Bidirectional (either Input, Output, or Unspecified)
• Vec(t) additionally is defined to create a chisel type.
• IO(t): must have t of chisel type with direction.
• Hardware instantiation binding operations will return a new node (rather than binding directly to the input chisel type node), which I think is current behavior.
• Vec(args*), Vec(elts) deprecated, replace with VecWire(elts) (or similar, someone suggest good names). elts must be a hardware node, and this returns a hardware node.

Node operations

• .chiselCloneType and .cloneType are to be deprecated.
• .getType operator introduced, legal on hardware nodes.
• Do we want a .wipeDir operator? The main use case would be for specifying Mem type, but the same could be done by wrapping it in Input(...).
• Add .requireIsHardware, requireIsChiselType, .requireDirectioned, and .requireUndirectioned APIs.
• These new operations will not be available in compatibility mode, since they depend on parent links.
• Question: should these operators be as a method of the node (myNode.getType) or as a global method (getType(myNode))? The first is consistent with cloneType, but the second is consistent with the binding wrappers and Input(...) / Output(...)

Style recommendations

• Methods parameterized by chisel type (usually called gen) should take a chisel type only, and should requireIsChiselType (or requireDirectioned / requireUndirectioned to sanity-check their inputs. Use of cloneType / getType in these occasions is discouraged and should be the responsibility of the caller.
• Bundles used as structs (as opposed to IOs) should not be directioned, allowing them to be directly used inside Reg/Mem. Directioning should generally happen “late”, like when necessary (either for IO or for truly bidirectional structs).

[aswaterman]

WireDefault makes more sense to me

[ducky64]

(probable bikeshedding!) WireDefault makes sense, but sounds a little verbose. Character-wise, Default is longer than Wire, Vec, IO, Reg, Mem and gives the impression as more of a fallback value (which is how it’s used in C/C++ switch statements). That being said, I can’t think of anything better right now, though. I think init makes sense (but imperfectly), since you are giving the Wire / Vec an initial value. The binding stuff / hardware is essentially implementation details.