Add device interface specification

[bruno-f-cruz]

This is a first stab at describing the device interface, device.yml specification.
It provides a high-level description on how the document is organized, validated and used by downstream tooling. I also provides a few examples.

I think we could add more detail in the following points:

• converter
• interfaceType
• The way that @glopesdev ended up resolving the heterogeneous registers Heterogenous register types in yaml schema #40

[bruno-f-cruz]

We should also address #214
One idea is that scalar registers should NEVER specify length. If length is specied (even if 0) the register interface must always return a array type

Documention on heterogenous registers here(harp-tech/generators#87)

[banchan86]

Looks pretty good to me! I thought it was well written and clear with the accompanying examples. Just minor suggestions for clarity and one stumbling block regarding the bitmasks.

[banchan86]

So the first line duplicates/contradicts the "Schema Reference" at the end of the file, which states that it's defined by a set of 3 files (device.json, core.json, registers.json). I think it might help to bring the "Schema Reference" section with the table up here and delete this line, as I also find that section is a little out of place at the end of the article.

I also realize the term device.yml is never used anywhere, while core.yml is mentioned. I feel like it can be brought in here.

Suggested change

	A device interface file is a YAML document whose schema is defined by `./schema/device.json`. The root level of the document contains metadata fields describing the device and a `registers` map that declares all application registers. Optional `bitMasks` and `groupMasks` sections define named masks that can be referenced by registers.
	The root level of the device interface file (`device.yml`) contains metadata fields describing the device and a `registers` map that declares all application registers. Optional `bitMasks` and `groupMasks` sections define named masks that can be referenced by registers.

[banchan86]

Suggested change

	# yaml-language-server: $schema=https://harp-tech.org/draft-02/schema/device.json
	%YAML 1.1
	---
	# yaml-language-server: $schema=https://harp-tech.org/draft-03/schema/device.json

Add yaml version directive and update the schema directive link which is now on draft-03

[banchan86]

Suggested change

	A YAML language-server schema directive SHOULD be placed at the top of the file to enable editor validation and autocompletion:
	A YAML version and language-server schema directive SHOULD be placed at the top of the file to enable editor validation and autocompletion:

Include the YAML version directive here?

[banchan86]

Suggested change

Every Harp device also exposes a set of core registers (addresses 0–31) that are common to all devices. These registers are defined in a separate file (`core.yml`) and follow the same YAML schema described in this document. Core registers handle device identification, timestamping, operation mode control, and other shared functionality. See [Device Registers and Operation](Device.md#core-registers) for the full specification of core register behavior.

Every Harp device also exposes a set of core registers (addresses 0–31) defined in a separate [`core.yml`](./schema/core.yml) file that follows the same YAML schema described in this document. Core registers handle device identification, timestamping, operation mode control, and other shared functionality. As these registers are common to all devices, `core.yml` does not need to be included alongside `device.yml`. See [Device Registers and Operation](Device.md#core-registers) for the full specification of core register behavior.

I feel like one thing that is not obvious to people is whether or not they should include core.yml in the device repository, so I suggested edits here, and added link to schema/core.yml.

[banchan86]

Suggested change

	When multiple access modes are needed, they SHOULD be expressed as a YAML sequence (1–3 unique values):
	When multiple access modes are needed, they MUST be expressed as a YAML sequence (1–3 unique values):

Is there another way of expressing multiple access modes? If not, should it be a MUST?

[banchan86]

Suggested change

	| `HarpVersion` | Custom type composed from multiple elements that describes a SemVer-like version. When using this `interfaceType`, the `length` MUST be equal to 3 |
	| `HarpVersion` | Custom type composed from multiple elements that describes a [semantic version](https://semver.org/). When using this `interfaceType`, the `length` MUST be equal to 3 |

Changed text and added link, similar to what was done in Device.MD

[banchan86]

So one thing that really tripped me up is I am not sure when one should define the bitmask in the payloadSpec and when one should define it in the "bitMask" section of the device.yml. Are these reasons correct?

Define bitmask in payloadSpec:

• When combining offset and bitmask to locate a member?
• When separating heterogenous type members with different-sized bitfields?

Define bitmask in bitMasks section:

• When defining the same type members, with equal-size bitfields?

I also think I may have the wrong mental model and might be completely off about the distinction between the two 😆 A note about the differences between the two might help other confused readers like me.

[banchan86]

Suggested change

	| `int` | Signed integer. |
	| `uint` | Unsigned integer. |
	| `int` | 32-bit signed integer. |
	| `uint` | 32-bit unsigned integer. |

[banchan86]

Hmm, I feel like this section might be better placed in the walkthrough of the properties in the "Registers" section. The example will have to be changed to get rid of the yaml anchors and aliases.

[banchan86]

As mentioned there is some overlap with this and the document overview section so might be better to move this up there.

[glopesdev]

While fixing a client defect I measured what the three generator targets actually do with length, and found two things the specification could settle. Both are cheap to write down and neither needs a schema change.

An absent length and length: 1 are different declarations, and the specification does not say so. registers.json gives length a minimum of 1 and leaves it optional, so absence carries meaning that is written nowhere. Both generator targets read absence as a single value and any declared length as an array, so length: 1 produces ushort[] in C# and an array register in Python, while omitting it produces ushort and a scalar. That is a reasonable rule and worth stating, because a client that defaults the field to 1 instead of leaving it absent silently produces the wrong type. That is exactly the bug we just fixed in the Python client.

A payloadSpec member offset must fall inside the register payload, and nothing enforces it. A register that declares no length is one element, so a member at offset: 1 is out of bounds. The C# generator does not reject that schema, it crashes with IndexOutOfRangeException, and the Python target emits a payload spanning two elements. A sentence saying member offsets are bounded by the register length, with absence meaning one element, would make that a validation error rather than a generator crash.

One related observation, which may belong in the interface types section rather than here. A member narrower than the register element, for example an interfaceType: bool member of a U16 register, leaves the payload extent ambiguous. C# reads a whole ushort and the Python client currently reads one byte, which cannot be right on the wire since a U16 payload is always a multiple of two bytes. If the specification says a register payload is always a whole number of elements of its declared type, both targets have a rule to follow and the disagreement becomes a bug in one of them rather than an open question.