Diplomatic Clock Primitives

[hcook]

This PR adds some primitives that can be used to pipe pairs of clock+reset signals through the design diplomatically. Adding this package upstreams some features from https://github.com/sifive/fpga-shells/tree/master/src/main/scala/clocks, which it is intended to (eventually) replace. There are node and edge types for both clock/reset pairs, and groups of such pairs that then must share a synchronous or rational relationship. Mutually asynchronous clocks should always be expressed as individual clock groups (which may then have only a single member).

The PR also adds some test harness clock generation functionality (which is not verilator compatible and so not currently added to regressions here), and includes a set of example clocking adapters, and updates some clocking utility blackbox wrappers to import chisel3.

Right now these features are only employed to drive the clocks of the TileLink buses included by default in BaseSubsystem. It maintains backwards compatibility with devices that tap into the bus clock directly by providing clock and reset outputs from the TLBusWrapper module instances.

This PR also adds the trait Attachable, which wraps the different nodes and members of the subsystem to which devices, tiles and other peripherals might which to attach themselves, including a point for registering additional clocks asynchronous to the tilelink bus clock. However, no code is yet changed to depend on this new trait.

Both Attachable and all the graph types added in the prci package should be considered experimental and are still under active development.

Type of change: other enhancement

Impact: API change

While this PR is mostly additive, it does change how the clock/resets of TLBusWrapper subclasses are to be driven. Mostly, they drive each other's clocks based on the type of TL clock crossing adapter that is inserted between them in the crossToBus and crossFromBus methods. However, the "root" bus needs to have its clockGroupNode driven, which the example HasHierarchicalBusTopology does via BaseSubsystem.asyncClockGroupsNode, which is in turn (by configurable default) driven by the implicit Chisel clock of BaseSubsystem's module implementation, here https://github.com/chipsalliance/rocket-chip/pull/1795/files#diff-3d87f78ef4648ef6b47c853c4581a47bR95

Development Phase: implementation

Future Work:
There are already a set of requested features for future work. These cover both internal functionality of the clocking graph and external application of the graph to use cases in the subsystem. Logging them here for future reference:
Internal features:

• The type of ClockBundle.reset is currently Bool, not the new chisel3.Reset wrapper type. Working theory is that every instance of a ClockBundle should be explicitly told whether it is to be an instance of Bool or an instance of AsyncReset, but this needs to be proven out and won't necessarily be compatible with the version in fpga-shells
• The way in which members of ClockGroupBundles are named is just via HeterogenousBag indexes, this should be improved to be based on the eventual clock sink name.
• Mapping from ClockGroupSourceParameters to ClockSourceParameters needs to be fleshed out. ClockGroups should be capable of resolving into single pairs when only a single source is provided to satisfy all the clocks in a group.
  External features:
• The InterruptBusWrapper should have its own ClockSinkDomain.
• Tiles' crossing type relative to the system bus should be captured diplomatically
• Downstream oeripheral devices in e.g. sifive-blocks should be updated to rely on only the Attachable trait

[hcook]

One year birthday of opening this PR 🎉

[DecodeTheEncoded]

clockGroupNode what does this class do?

[DecodeTheEncoded]

what does "each other" refer to?

While this PR is mostly additive, it does change how the clock/resets of TLBusWrapper subclasses are to be driven. Mostly, they drive each other's clocks based on the type of TL clock crossing adapter that is inserted between them in the crossToBus and crossFromBus methods.
@hcook