Introduce typeclasses for vendored CDC primitives

[rslawson]

What (what did you do)
This should implement (most of?) the desired changes as per #1222.

Why (context, issues, etc.)
See issue for context.

Dear reviewer (anything you'd like the reviewer to pay close attention to?)
I think there's a GHC bug to be found in here. If in Clash.Cores.Xilinx I write

withXilinxI :: forall r. (forall vendor. (VendorCdcImplicit vendor) => r) -> r
withXilinxI = withVendorI @Xilinx

and then replace all withVendorI @Xilinx with withXilinxI calls, I suddenly get a bunch of compilation errors. If it's somehow possible to get this to work though, I'd appreciate a review comment (:

AI disclaimer (heads-up for more than inline autocomplete)

None.

TODO

Cross-out any that do not apply

• Write (regression) test
• Update documentation, including docs/
• Link to existing issue

[martijnbastiaan]

Overall this LGTM, the GHC bug is too bad.

I do have three comments:

1. Instead of making it a big God class, could you make it into singular classes? This would help us if vendor can't supply all the primitives.
2. I get the appeal of adopting Xilinx's naming scheme, but at the same time I think that scheme doesn't really fit Clash. What do you think of:

• Single: Bit
• ArraySingle: IndependentBits

3. Could you please remove the cdc prefix from the names and design for qualified use? I.e., call sites would look like Cdc.gray.

I'm fairly certain (1) is the way to go, less so of (2), and unswayable on (3) :-)

[rslawson]

Made changes (1) and (3), plus introduced a couple other convenience typeclasses so that it's easier to get the right constraints into scope so that you can call the CDC primitives' functions. I'm a little less enthusiastic about change (2), but I do see the reasoning for it so I did make that change.

[martijnbastiaan]

Almost there.. :)

[martijnbastiaan]

Could you add documentation to each of the the functions? They should cover what they synchronize and under what circumstances they can be used. If it helps, this is Xilinx's decision tree:

This one is also very cool, but more out-of-scope: