On Mon, Oct 22, 2018 at 03:54:45PM -0700, Jeff McGee wrote: > See https://lists.freedesktop.org/archives/intel-gfx/2018-October/178452.html > for RFC v1 and the helpful feedback incorporated into this v2. thanks! I liked the new one. Acked-by: Rodrigo Vivi <rodrigo.vivi@xxxxxxxxx> > > 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 _______________________________________________ Intel-gfx mailing list Intel-gfx@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/intel-gfx
