Add compatiblity table between harp hardware core implementations

[bruno-f-cruz]

Since we are now maintaining two cores: atmel and pico, it is likely that the two cores will not implement the same set of core registers (e.g. optional ones). It is important to come up with a way to keep track of this information. Some suggestions include:

• Keep a separate, subset of the core.yml on each core repository. This could potentially be interesting if automatically generating code downstream, as it could be made core-aware
• Keep a markdown-like file that documents functionality implemented
• Keep a table of register by core with information of what each core implements

[PathogenDavid]

How do we currently document registers provided by a device? Is it just device.yml or does anything have nice HTML/Markdown documentation? (And is said documentation generated or hand-authored?)

It seems like a reasonable side-task of the C# generator (or maybe a separate generator) could be to emit documentation like this. Creating register documentation for cores could just be running that generator without a device.yml or even just a dummy device.yml that's empty.

[bruno-f-cruz]

We are generating documentation from the yml to the docs webpage

This process runs during the docfx build using this script when we generate the docs for each one of the csharp interfaces.

The issue here is that the device.yml is NOT privy to the core register the device implements, which is kept in a single core.yml file that represents the super-set of harp core interfaces. This has few implications, but the bottom line is that device-specific generated bonsai interfaces do not interact with core registers at all, that work has been pushed to the Bonsai.Harp namespace that, at the moment, is shared across all devices, regardless of which core registers they implement (it targets the superset core.yml file)

[PathogenDavid]

The issue here is that the device.yml is NOT privy to the core register the device implements

This on its own feels like something potentially worth solving, but either way the formats of device.yml and core.yml are similar enough that such a tool could pretty easily handle both.

[bruno-f-cruz]

I think that from the point of view of generating a common device.yml would likely not be too hard. As I said before (despite we deciding not to move ahead with it), I think that having the SDK reference (pico / atmel) in the device.yml may afford this sort of strategy, wherein at code generation time, you try to fetch the relevant core.yml. The biggest issue with this approach is how bloated the device-specific interface operators may become. You suddenly have an extra 20 enum values to pick from (well 20 * 2 for the Parse operators). These are registers that people rarely interact with so we have gotten away with scoping them to the Bonsai.Harp core package instead. To be clear, I am not opposed to merge a per architecture core.yml, but I think we need to figure out how to fit it with the current editor UI.

[PathogenDavid]

I'm not saying the core registers need to be surfaced as device registers on the Bonsai interface. I'm focused on the core issue here of documentation.

[bruno-f-cruz]

Gotcha! Sure scoping to that to docs makes a lot of sense to me :). It would only require adding the SDK reference to the device.yml I believe.