[patch] Define Circuit Subcomponents

[mmaloney-sf]

Adds a section defining Circuit Subcomponents.

This notion is latent in the implementations, but is central to FIRRTL's semantics.

Intuitively, subcomponents are what you "dot into" or "index into". Eg, c[0].x is a reference to a subcomponent of a circuit component c.

Circuit subcomponents unify the notion of references, both static (sub-index and sub-field) and dynamic (sub-access). They are the entities which are the targets of a connect (... I believe this is a categorical statement). They are also important for reasoning about the initialization coverage of a module definition.

[mmaloney-sf]

For clarity, the direct subcomponent relation needs to be defined on the cross product of the kind and type of components.

There are only seven kinds. Since there are infinitely many types, we need to break them into a finite number of cases:

• Ground types, enums, probes, and properties are grouped together
• Vector types
• Bundle types

The first case is the grab bag of types which don't give rise to proper subcomponents.

The second case, vectors, splits up in the "obvious" way: you get one direct subcomponent per element in the vector and each has the base type.

The third case, bundles, is trickier because of flips. It still splits up in the "obvious" way: each field gives rise to a direct subcomponent with the field type of the corresponding field. However, the flip can change the subcomponent's kind.

When indexing into wires, nodes, and registers the kind never changes. When indexing into instances and memories, the subcomponents are as if you are "viewing" the port from the outside. The effect on kinds is a bit confusing at first glance, but it should check out when you work through the logic. (Or else be exactly backwards. As a matter of policy, I refuse to make guarantees I get my orientations correct. Ever.) Remember: output ports need to be driven and input ports drive. You need to ignore the fact that output and input suggest an absolute orientation. It's really hard to put into words -- work through this section carefully to see what I mean.

[mmaloney-sf]

I took what I had written up and cleaned it up a bit (apologies to @seldridge and @dtzSiFive for having to read my initial draft!):

• Lead off with two motivating examples
• Lead off with the full definition of direct subcomponent
• Added a third section on references (the proper name for anything that looks like c.x[0]).
• Fold in the sections on sub-field, sub-index, and sub-access (still a WIP)

[mmaloney-sf]

I also identified a few quirks:

• firtool actually allows field access into muxes and other arbitrary expressions. This is disallowed by the grammar.
• const parses really funny. When you write const UInt<8>[3] it's as if you had written (const UInt)<8>[3] (with the const is on the inner type), whereas const { x : UInt<8> } has the const on the outer type. This leads to a really ugly rule about the type of subcomponents when the thing has a bundle type.
• There is a lot of ink spilled over sub-field, sub-index, and sub-access. It's mostly examples. As far as I can tell, this was an attempt to specify how these things work, despite not having defined the underlying concept (subcomponents). I'm planning to delete most of this material.