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

[Jeff McGee]

See https://lists.freedesktop.org/archives/intel-gfx/2018-October/178452.html
for RFC v1 and the helpful feedback incorporated into this v2.

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.

The proposed version number would consist of these 3 mandatory fields in order
of significance: MAJOR.MINOR.PATCH. Contrast this with the 2 fields in the
current version number: MAJOR.MINOR. The version block in the firmware header
will be refactored to contain these 3 fields so that i915 can continue to
verify the version before loading. The firmware file would adopt a change of
naming format to match:

Current:  <platform>_guc_ver<major>_<minor>.bin         (skl_guc_ver9_33.bin)
Proposed: <platform>_guc_ver<major>_<minor>_<patch>.bin (skl_guc_ver5_4_7.bin)

The MAJOR number conforms to the major in semver.org. It increments on a
backwards incompatible change of the interface. 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 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. Consider an
example:

 v1.0.0     v1.0.1     v1.0.2     v1.1.0     v1.1.1
----O----------O----------O----------O----------O    <-- main adopts v1.1.x
                           \
                            \
                             \
                              O----------O     <-- fixes for interface v1.0.x
                           v1.0.3     v1.0.4

The key here is that the branching happened from the last fix (v1.0.2) on the
main branch prior to the change of interface (v1.1.0). As long as only fixes
are applied to v1.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.0.4 were inherited by v1.1.0. With this "hidden"
branching, this may not be true as this example shows. One should always review
the release notes to confirm release ancestry and content.

The above scenario of continued fixes on a given interface version represents
the most common form of release branching expected, and can be handled quite
smoothly within the proposed scheme as shown. But it may also be necessary to
branch from an arbitrary point and with an arbitrary scope of changes. Such a
scenario could not be handled with the basic 3 fields without violating
semver.org semantics. One or more additional version fields will need to be
defined. The GuC firmware team intends to avoid this scenario as long as
possible, though some day a customer or other situation might force it upon us.

For now we will just defer the design for handling the aforementioned scenario,
though I am summarizing some options below to be considered if and when. None
of these are being put into effect immediately as part of the proposed change.

At minimum we will need a 4th field to contain a branch ID. This will be a
numeric ID in the firmware image header, but can be mapped to a descriptive
branch string via a table that is part of the official firmware interface
documentation. If and when the branch ID field is added, it will start with a
value of 1 for that first branch, the mainline being implicitly branch ID 0.
There seems to be two logical choices for how to version the releases coming
from a branch. The best choice depends on the intent of the branch as described
below.

For branches that are short-lived, primarily for fixes, and make only minor or
no changes to the interface, the ability to track their relationship to the
mainline is of utmost importance. Releases along this type of branch always
carry the same major.minor.patch version of the mainline branch-off point. The
branch ID field maps to a string that describes the customer or usage of the
branch. A 5th field is then needed to increment successive releases from the
branch. We accept that by using a single release number we cannot distiguish
the types of changes from release to release. Below is an example for a branch
ID that maps to "projfoo".

 v2.0.0     v2.0.1     v2.0.2     v2.1.0     v2.1.1
----O----------O----------O----------O----------O
                \
                 \
                  \
                   O------------------O
            v2.0.1-projfoo-0   v2.0.1-projfoo-1

For branches that are long-lived and diverge significantly from the mainline,
one might consider them separate forked firmware projects entirely. We don't
care to track them with respect to mainline. We want to restart
major.minor.patch to track significant evolution within the branch/fork. The
branch ID field maps to a string with which we might consider renaming the
firmware project, instead of using the hypen post-fix designation. This kind of
branching should happen extremely rarely if ever. Below is an example for a
branch/fork ID that maps to "newguc".

 v2.0.0     v2.0.1     v2.0.2     v2.1.0     v2.1.1
----O----------O----------O----------O----------O
                \
                 \
                  \
                   O--------------O--------------O--------------O
             newguc v1.0.0  newguc v1.0.1  newguc v1.1.0  newguc v2.0.0

Both of the above approaches could be supported simultaneously by the firmware
where each branch ID would document the model that it follows.

Thanks,
Jeff