Clarify "Optional" in Device specification

[bruno-f-cruz]

• Proposed
• Prototype: Not Started
• Implementation: Not Started
• Specification: Not Started

Summary

It is currently not clear what Optional entails under the Device specification when referring to a register mandatory implementation.

Detailed Design

We should clarify this behavior. Specifically, the following points should be answered:

• If a writeable register is marked as "optional", is it acceptable to have it implemented as "read-only"?
• If a register is optional, what should happen if someone attempts to read from it?

Design Meetings

[bruno-f-cruz]

From https://github.com/orgs/harp-tech/discussions/129:

All register in the core MUST be available if specified in the corresponding version of the core.yml interface
The notion of optional refers to functionality, not whether it exists as a readable interface in the device.
For instance, an optional register TAG MUST be implemented by exposing a register that can be read from. However, the value of such register is allowed to default to 0, as specified in the spec.
In the future, we should try to keep these Optional registers to a minimum and document the SDK-specific behavior in the corresponding core repository/readme/website documentation.

It would be great to formalize these decisions in the documentation of the protocol and at the same time clarify the Optional behavior for most of the registers, including the newly added ones.

[bruno-f-cruz]

Quickly going over the current set of optional registers in the device specification, I tentatively propose:

1. Optional registers are REQUIRED to, at a minimum, always be readable and included in the read-dump of the device.
2. In most cases, the default values of registers must be "0". But see below.
3. For optional registers that are expected to be writable, registers are expected to be implemented (and return the default value on read), but it is acceptable to return write errors if the function is not implemented. Clients are expected to deal with the replies

We thus end up with the following registers that should be updated

Name	Default Value	Expected Behavior
R_ASSEMBLY_VERSION	0	Expected to be deprecated in the future, but fair to use right now
R_CORE_VERSION_H	??	Should duplicate the new R_VERSION (#68)
R_CORE_VERSION_L	??	Should duplicate the new R_VERSION (#68)
R_TIMESTAMP_MICRO	??	Make required 1
R_OPERATION_CTRL	0	Returns "0" on read for non-implemented features. Can error on write.
R_DEVICE_NAME	0	Can error on write
R_SERIAL_NUMBER	0	Can error on write
R_CLOCK_CONFIG	0	Can error on write
R_TIMESTAMP_OFFSET	0	Will be deprecated (#113)
R_UID	0
R_TAG	0

Footnotes

1. Should this be mandatory? Second-resolution is not currently supported in the standard AFAIK ↩

[bruno-f-cruz]

Closed by #150