Refactor Version registers

[bruno-f-cruz]

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

Summary

Deprecate the current way to store information regarding the version of hardware, firmware and core in favor of a single register.

Motivation

The current registers 01-07 are used to version hardware, application firmware and harp core. We are moving into a direction where we will additionally need to keep track of the protocol spec as the harp core and its implementation will now diverge given how we support two parallel core hardware implementations (rp2040 and atmega). Since we need to add a new register, I propose we start deprecating the current ones in favor of a single register that stores all this information.

Detailed Design

Deprecate all current registers and add a new one with the following specs:

Register:
Name: Version
Type: U8
Access: Read
Length: 15
PayloadSpec: HarpProtocol[Major, minor, patch], CoreImplementation[Major, minor, patch], App[Major, minor, patch], Hardware[Major, minor, patch], Assembly[Major, minor, patch].

This has a huge benefit of all versions now being able to be read out with a single call.

Finally, until the deprecated registers are removed from the spec, the available information should be duplicated (in this case only Major and Minor versions)

Drawbacks

No real drawback as we will need to add a register anyway.

Alternatives

Adding a new register with the harp protocol version and keep all others as is.

Unresolved Questions

Design Meetings

[bruno-f-cruz]

Filipe suggests removing the assembly (probably deprecate the current register to be removed later). Probably gonna keep it just in case...

The current implementation register will duplicate the future register implementation version and NOT the core version

[Poofjunior]

+1 to this. AIND board hardware follows a major,minor,patch scheme, which we cannot capture under the current protocol.

[glopesdev]

@bruno-f-cruz Picking up here some questions raised in / related to #57. How will the changes in firmware, hardware, and protocol versions propagate into firmware release files? Currently these files contain only two-number firmware, hardware and ATxmega core versions, e.g. SoundCard-fw2.2-harp1.13-hw1.1-ass0.hex.

One proposal would be to extend the numbering scheme for all versions and make harp refer to the protocol version, rather than to the core version, e.g. SoundCard-fw2.2.0-harp1.13.0-hw1.1.0-ass0.hex

However, below are some considerations worth reflecting on against the idea of simply adding "patch" versions to all components of a firmware release string:

1. In the case of changes to the harp protocol, all versions are always pure specifications so there aren't really any "fixes" which are not changes to the spec. This means we could potentially always keep using just two version numbers there;
2. Pure "patch" changes to hardware (hw) shouldn't really affect the behavior of firmware releases. If a hardware change is purely a "fix" then the whole point is that it should work interchangeably with the latest firmware (by definition). If it doesn't, then it probably isn't really just a fix. That means we could potentially keep using just two version numbers here too;

The only complication of 2. is we might not be able to change the hardware "version" reported by the device without changing the firmware really, but this from a point of view of versioning is kind of self-defeating (if there are really no changes between hw1.1.0 and hw1.1.1 you can install any firmware in any of the boards and be "fooled" thinking you have the right hardware fix where you have not, but this is a different problem).

We also discussed dropping the "assembly" version from firmware updates (for similar reasons to hardware "fixes"). This means we could potentially extend only the firmware version component numbering scheme and have a file naming convention like:

SoundCard-fw2.2.0-harp1.13-hw1.1.hex