Deprecate `R_TIMESTAMP_OFFSET` from Device specification

[bruno-f-cruz]

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

Summary

R_TIMESTAMP_OFFSET implementation is overly restrictive and confusing. The current proposal suggests deprecating it from the core and moving it to an application-specific register of devices that implement this feature.

Motivation

I believe the way this register is currently implemented is confusing for users and does not serve a "core" functionality of the protocol/devices.

Detailed Design

The current implementation of this register follows the following logic:

1. Unitary increments to the payload translate in 500us positive offsets to the current clock of the device (i.e. (0x01 -> 500us, 0x02 -> 1ms, etc...)
2. This functionality is only used when the device is NOT connected to a hw-provided clock synchronization signal

This feature was implemented to allow devices that do not have a hw-level synchronization (e.g. RFID reader) to synchronize to software-derived synchronization. An example would be a rig where a single clock generator emits a heartbeat message periodically which can in turn be used to "set" the subordinate clock to its value. Since there is a non-negligible delay between the clock -> PC -> RFID, a sub-second offset (note that this sub-second offset cant be injected via the Seconds register), is applied by setting a non-zero value in R_TIMESTAMP_OFFSET.
Under an assumption that boards are subject to a small-jitter, and users go through the trouble of calibrating this delay, this strategy can replace software-based timestamping.

However, given how the protocol does not standardize this "soft-synchronization" strategy, I believe this strategy should be seen as an application-specific feature and thus removed from the harp core, in favor of an application register.

The current proposal is thus:

1. Deprecate R_TIMESTAMP_OFFSET by keeping it in the core for a few versions but encouring users to NOT use it in future versions.
2. In devices that use this feature, implement a new register that mimics this functionality

Drawbacks

Once the register is truly removed, it may be considered a breaking change. However it should be pointed out that is unlikely that people are using this register for any board other than RFID. For the RFID board, one must decide how the new application register interacts with the deprecated one. Shorting writes/reads to a common underlying register may work.

Alternatives

Unresolved Questions

Design Meetings

https://github.com/orgs/harp-tech/discussions/111
#64

[bruno-f-cruz]

We should consider renaming this register into R_RESERVED

[bruno-f-cruz]

Closed via #150