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

[Jeff McGee]

Forgot to add some people on CC.

On Fri, Oct 12, 2018 at 01:24:30PM -0700, Jeff McGee wrote:
> 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
> _______________________________________________
> Intel-gfx mailing list
> Intel-gfx at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/intel-gfx