[Intel-gfx] [RFC] GuC firmware versioning change

[Jeff McGee]

The GuC firmware team is proposing a change to the firmware versioning scheme.
The goal is to more accurately track the firmware interface to help users
manage dependencies on that interface. The proposed scheme is based on
semver.org with some additions to handle branching.

The proposed version number would have 4 fields: BASE.MAJOR.MINOR.PATCH.
Contrast this with the 2 fields in the current version number: MAJOR.MINOR.
Side note, the current firmware encodes a BRANCH and CLIENT number as well, but
they have not been needed by i915. So a firmware released with the proposed
scheme would be named <platform>_guc_ver<base>_<major>_<minor>_<patch>.bin
(ex: skl_guc_ver1_5_4_7.bin) instead of the current
<platform>_guc_ver<major>_<minor>.bin (ex: skl_guc_ver9_33.bin).

The BASE number is an ID that is used to identify a set of releases in which
the MAJOR.MINOR.PATCH semantics are consistent. In other words, two releases
from the same BASE can be compared via their MAJOR.MINOR.PATCH to infer their
relationship as described below. Two releases from a different BASE cannot be
reliably compared. The BASE number facilitates arbitrary branching which can
create duplicate and/or disconnected MAJOR.MINOR.PATCH versions. This type of
branching is expected to be rare, and so BASE will rarely change. When a new
BASE is created, the MAJOR.MINOR.PATCH reset to starting values.

The MAJOR number conforms to the major in semver.org. It increments on a
backwards incompatible change of the interface. It resets to 1 on a change of
BASE. The MAJOR number basically works the same between the current and
proposed versioning schemes.

The MINOR number conforms to the minor in semver.org. It increments on a
backwards compatible change of the interface (new interfaces that are optional
to use). It will also increment on substantial new internal functionality that
doesn't affect the interface but should be called out to the user. It resets to
0 on a change of MAJOR. The MINOR number in the current versioning scheme
increments on any backwards compatible change. The proposed versioning scheme
breaks this into the MINOR number just described and the PATCH number below.

The PATCH number conforms to the patch in semver.org. It increments on a
backwards compatible internal change, usually a bug fix. It resets to 0 on a
change of MINOR.

The MAJOR.MINOR collectively define the interface version. Because the MINOR
may also increment on a substantial internal change, it doesn't always mark an
interface change, e.g. 4.5 and 4.6 may have identical interfaces. But the
determination of interface compatibility is unchanged, e.g. 4.6 is always
backwards compatible with 4.5.

Each MAJOR.MINOR may continue to receive internal fixes along a branch even
after the main branch for that BASE has moved on to another MAJOR.MINOR.
Releases from these fix-only branches increment only the PATCH number on that
MAJOR.MINOR, and therefore remain semantically consistent with the main branch.
No change of BASE is therefore needed. Consider an example:

v1.1.0.0   v1.1.0.1   v1.1.0.2   v1.1.1.0   v1.1.1.1
----O----------O----------O----------O----------O    <-- main adopts v1.1.1.x
                           \
                            \
                             \
                              O----------O     <-- fixes for interface v1.1.0.x
                          v1.1.0.3   v1.1.0.4

There is no need to change the BASE because the branching happened from the
last fix (v1.1.0.2) on the main branch prior to the change of interface
(v1.1.1.0). As long as only fixes are applied to v1.1.0.x, there is no risk of
version number clash. All of these release versions remain semantically
connected with one small caveat. If this set of release versions came
sequentially along a single branch, one could infer that the exact fixes in
v1.1.0.4 were inherited by v1.1.1.0. With this "hidden" branching, this may
not be true as in this example. One would need to review the v1.1.1.0 release
notes to check.

Please provide any feedback on the proposed change.

Thanks,
Jeff