Upgrade Strategy for Breaking Changes

[Leland-Takamine]

There are two scenarios to consider here:

1. Visualizer/command is newer than the ROM.
2. Visualizer/command is older than the ROM.

Note: Case (2) is far less frequent and is only possible in the following scenario:

• Device is flashed with nanoscope client version V.
• A nanoscope client with version < V is used to trace the device.

This could happen if a user downgrades their nanoscope command or traces their device from another computer.

Proposed Solution

The nanoscope command and the Nanoscope ROM will each be versioned using semantic versioning. Matching major (and minor?) version numbers indicate that the command and the ROM are compatible with one another. The nanoscope command will check this condition before the execution of every command and display an upgrade message if the check fails. These are the messages for each scenario above:

Please update your Nanoscope ROM:
    Nanoscope Client version: 2.1.0
    Nanoscope ROM version: 1.0.0

To update your ROM, run the following commands:
    brew update && brew upgrade nanoscope
    nanoscope flash

Please update your Nanoscope Client:
    Nanoscope Client version: 1.0.0
    Nanoscope ROM version: 2.1.0

To update your client, run the following commands:
    brew update && brew upgrade nanoscope

Determining ROM Version

Before packaging our ROM, update the out/target/product/angler/system/build.prop to include this property:

build.prop

ro.build.nanoscope=1.0.0

The Nanoscope client will query this system property to determine compatibility. We already have a release script at art/make-release.sh. The script should be updated to include logic to update the build.prop file.

Alternatives Considered

Catch exceptions

Nanoscope client optimistically parses the trace file. If parsing fails, we'll display a message suggesting to either upgrade the visualizer or device. There are a couple serious issues with this approach:

1. We won't know whether the user should upgrade the client or the ROM.
2. Incompatibility may not cause parsing to fail, in which case we'll render the trace incorrectly.

[Leland-Takamine]

We should also define our final strategy in the wiki.

[Leland-Takamine]

Closed by #36