| Message ID | 20170222060254.24323-1-stewart@linux.vnet.ibm.com |
|---|---|
| State | Accepted |
| Headers | show |
On Wed, 2017-02-22 at 17:02 +1100, Stewart Smith wrote: > Reviewed-by: Reza Arbab <arbab@us.ibm.com> > Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com> > -- > Changes in v2: > - Clarify that 1.0b > 1.0, bringing in line with Debian/RPM specs > (found by Reza, reviewed on IRC) I just noticed this never got merged, does an extra Reviewed-by: Samuel Mendoza-Jonas <sam@mendozajonas.com> help? :) > --- > doc/device-tree/ibm,firmware-versions.rst | 139 ++++++++++++++++++++++++++++++ > 1 file changed, 139 insertions(+) > create mode 100644 doc/device-tree/ibm,firmware-versions.rst > > diff --git a/doc/device-tree/ibm,firmware-versions.rst b/doc/device-tree/ibm,firmware-versions.rst > new file mode 100644 > index 0000000..99cd6b2 > --- /dev/null > +++ b/doc/device-tree/ibm,firmware-versions.rst > @@ -0,0 +1,139 @@ > +ibm,firmware-versions node > +========================== > + > +The `ibm,firmware-versions` node contains information on the versions of > +various firmware components as they were **during boot**. It **does not** > +change if there are pending or runtime updates. It represents (to the best > +of boot firmware's ability) what versions of firmware were during this boot. > + > +================= ======== ============================================ > +Property Required Value > +================= ======== ============================================ > +version POWER9 See below > +skiboot N component version number > +occ N component version number > +buildroot N component version number > +capp-ucode N component version number > +petitboot N component version number > +open-power N component version number > +hostboot-binaries N component version number > +MACHINE-xml N MACHINE (e.g. habanero) machine XML version > +hostboot N component version number > +linux N component version number > +================= ======== ============================================ > + > +``version`` property > +^^^^^^^^^^^^^^^^^^^^ > + > +This property **must** exist on POWER9 and above systems. It **may** exist > +on POWER8 systems. > + > +If this property exists, it **must** conform to this specification. > +It's a single version number of the firmware image. In the event of a system > +supporting multiple firmware sides, this represents the **default** boot side. > +That is, the version that is applicable when determining if a machine > +requires a firmware update. > + > +Examples (for three different platforms): > + > +- ``IBM-sandwich-20170217`` > +- ``open-power-habanero-v1.14-45-g78d89280c3f9-dirty`` > +- ``open-power-SUPERMICRO-P8DTU-V2.00.GA2-20161028`` > + > +To compare two versions (for the purpose of determining if the current > +installed firmware is in need of updating to the one being compared against) > +we need a defined set of rules on how to do this comparison. > + > +Version numbers are **not** intended to be compared across platforms. > + > +The version string may include a description at the start of it. This > +description can contain any set of characters but **must not** contain > +a '-' followed by a digit. It also **must not** contain '-v' or '-V' followed > +by a digit. > + > +Each part of the version string is separated by a '-' character. Leading > +sections are ignored, until one starts with a digit (0-9) or a 'v' or 'V', > +followed by a digit. Where there is a leading 'v' or 'V', it is also stripped. > + > +For the above three examples, we'd be left with: > + > +- ``20170217`` > +- ``1.14-45-g78d89280c3f9-dirty`` > +- ``2.00.GA2-20161028`` > + > +Each section is now compared until a difference is found. All comparisons > +are done *lexically*. The lexical comparison sorts in this order: tilde (~), > +all letters, non-letters. The tilde is special and sorts before an end of part. > +This allows the common usage of designating pre-release builds by a tailing > +section beginning with a '~'. > + > +For example: "1.0~20170217", "1.0~rc4" and "1.0~beta1" all sort > +**before** "1.0" > + > +Note that "1.0beta" sorts **after** "1.0" > + > +The start of the version string contains an optional *epoch*. If not present, > +it is zero. This allows a reset of versioning schemes. All versions with an > +epoch of N+1 are greater than those with epoch N, no matter what the version > +strings would compare. For example "0:4.0" is **less** than "1:1.0". Increasing > +the epoch should **not** be a regular occurance. > + > +For the remainder of the version strings, each part (separated by '.' or '-') > +is compared lexically. There are two exceptions: any part beginning with "-g" > +or "-p" followed by a hexadecimal string is compared as a string, and if they > +are different the versions are determined to be different. For example, the > +sections "-g78d89280c3f9" and "-g123456789abc" differ and for all comparisons > +(less than, greater than, equal) the result should be true. > + > +For those who have been paying attention, this scheme should look very > +familiar to those who are familiar with RPM and Debian package versioning. > + > +The below table shows comparisons between versions and what the result should > +be: > + > +=========================== =========================== ==================== > +A B Result > +=========================== =========================== ==================== > +1.14-45-g78d89280c3f9-dirty 1.14-45-g78d89280c3f9-dirty Equal > +1.14-45-g78d89280c3f9-dirty 1.14-45-g78d89280c3f9 A > B > +1.14-45-g78d89280c3f9-dirty 1.14-45-g123456789abc A < B, A > B, A != B > +1.14-45-g78d89280c3f9-dirty 1.14-46 A < B > +1.14-45-g78d89280c3f9-dirty 1.15 A < B > +1.14-45-g78d89280c3f9-dirty 1:1.0 A < B > +1.0 1.0~daily20170201 A > B > +1.0.1 1.0~daily20170201 A > B > +1.0 1.0.1 A < B > +1.0 1.0beta A < B > +=========================== =========================== ==================== > + > +Examples > +^^^^^^^^ > + > +New style (required for POWER9 and above): > + > +.. code-block:: dts > + > + ibm,firmware-versions { > + version = "open-power-habanero-v1.14-45-g78d89280c3f9-dirty"; > + skiboot = "5.4.0"; > + occ = "d7efe30"; > + linux = "4.4.32-openpower1"; > + }; > + > +Old-style: > + > +.. code-block:: dts > + > + ibm,firmware-versions { > + occ = "d7efe30-opdirty"; > + skiboot = "5.4.0-opdirty"; > + buildroot = "211bd05"; > + capp-ucode = "1bb7503-opdirty"; > + petitboot = "v1.3.1-opdirty-d695626"; > + open-power = "habanero-f7b8f65-dirty"; > + phandle = <0x1000012e>; > + hostboot-binaries = "56532f5-opdirty"; > + habanero-xml = "6a78496-opdirty-526ff79"; > + hostboot = "09cfacb-opdirty"; > + linux = "4.4.32-openpower1-opdirty-85cf528"; > + };
Samuel Mendoza-Jonas <sam@mendozajonas.com> writes: > On Wed, 2017-02-22 at 17:02 +1100, Stewart Smith wrote: >> Reviewed-by: Reza Arbab <arbab@us.ibm.com> >> Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com> >> -- >> Changes in v2: >> - Clarify that 1.0b > 1.0, bringing in line with Debian/RPM specs >> (found by Reza, reviewed on IRC) > > I just noticed this never got merged, does an extra > > Reviewed-by: Samuel Mendoza-Jonas <sam@mendozajonas.com> > > help? :) Yes, yes it does. Merged to master as of 2f8c9acf8985bae54eeb9778319c4ffb1d77bbbe Of course, now we actually have to make the code comply to the spec I just merged. Luckily, there's documentation, so the code is absolutely not going to conform to it.
diff --git a/doc/device-tree/ibm,firmware-versions.rst b/doc/device-tree/ibm,firmware-versions.rst new file mode 100644 index 0000000..99cd6b2 --- /dev/null +++ b/doc/device-tree/ibm,firmware-versions.rst @@ -0,0 +1,139 @@ +ibm,firmware-versions node +========================== + +The `ibm,firmware-versions` node contains information on the versions of +various firmware components as they were **during boot**. It **does not** +change if there are pending or runtime updates. It represents (to the best +of boot firmware's ability) what versions of firmware were during this boot. + +================= ======== ============================================ +Property Required Value +================= ======== ============================================ +version POWER9 See below +skiboot N component version number +occ N component version number +buildroot N component version number +capp-ucode N component version number +petitboot N component version number +open-power N component version number +hostboot-binaries N component version number +MACHINE-xml N MACHINE (e.g. habanero) machine XML version +hostboot N component version number +linux N component version number +================= ======== ============================================ + +``version`` property +^^^^^^^^^^^^^^^^^^^^ + +This property **must** exist on POWER9 and above systems. It **may** exist +on POWER8 systems. + +If this property exists, it **must** conform to this specification. +It's a single version number of the firmware image. In the event of a system +supporting multiple firmware sides, this represents the **default** boot side. +That is, the version that is applicable when determining if a machine +requires a firmware update. + +Examples (for three different platforms): + +- ``IBM-sandwich-20170217`` +- ``open-power-habanero-v1.14-45-g78d89280c3f9-dirty`` +- ``open-power-SUPERMICRO-P8DTU-V2.00.GA2-20161028`` + +To compare two versions (for the purpose of determining if the current +installed firmware is in need of updating to the one being compared against) +we need a defined set of rules on how to do this comparison. + +Version numbers are **not** intended to be compared across platforms. + +The version string may include a description at the start of it. This +description can contain any set of characters but **must not** contain +a '-' followed by a digit. It also **must not** contain '-v' or '-V' followed +by a digit. + +Each part of the version string is separated by a '-' character. Leading +sections are ignored, until one starts with a digit (0-9) or a 'v' or 'V', +followed by a digit. Where there is a leading 'v' or 'V', it is also stripped. + +For the above three examples, we'd be left with: + +- ``20170217`` +- ``1.14-45-g78d89280c3f9-dirty`` +- ``2.00.GA2-20161028`` + +Each section is now compared until a difference is found. All comparisons +are done *lexically*. The lexical comparison sorts in this order: tilde (~), +all letters, non-letters. The tilde is special and sorts before an end of part. +This allows the common usage of designating pre-release builds by a tailing +section beginning with a '~'. + +For example: "1.0~20170217", "1.0~rc4" and "1.0~beta1" all sort +**before** "1.0" + +Note that "1.0beta" sorts **after** "1.0" + +The start of the version string contains an optional *epoch*. If not present, +it is zero. This allows a reset of versioning schemes. All versions with an +epoch of N+1 are greater than those with epoch N, no matter what the version +strings would compare. For example "0:4.0" is **less** than "1:1.0". Increasing +the epoch should **not** be a regular occurance. + +For the remainder of the version strings, each part (separated by '.' or '-') +is compared lexically. There are two exceptions: any part beginning with "-g" +or "-p" followed by a hexadecimal string is compared as a string, and if they +are different the versions are determined to be different. For example, the +sections "-g78d89280c3f9" and "-g123456789abc" differ and for all comparisons +(less than, greater than, equal) the result should be true. + +For those who have been paying attention, this scheme should look very +familiar to those who are familiar with RPM and Debian package versioning. + +The below table shows comparisons between versions and what the result should +be: + +=========================== =========================== ==================== +A B Result +=========================== =========================== ==================== +1.14-45-g78d89280c3f9-dirty 1.14-45-g78d89280c3f9-dirty Equal +1.14-45-g78d89280c3f9-dirty 1.14-45-g78d89280c3f9 A > B +1.14-45-g78d89280c3f9-dirty 1.14-45-g123456789abc A < B, A > B, A != B +1.14-45-g78d89280c3f9-dirty 1.14-46 A < B +1.14-45-g78d89280c3f9-dirty 1.15 A < B +1.14-45-g78d89280c3f9-dirty 1:1.0 A < B +1.0 1.0~daily20170201 A > B +1.0.1 1.0~daily20170201 A > B +1.0 1.0.1 A < B +1.0 1.0beta A < B +=========================== =========================== ==================== + +Examples +^^^^^^^^ + +New style (required for POWER9 and above): + +.. code-block:: dts + + ibm,firmware-versions { + version = "open-power-habanero-v1.14-45-g78d89280c3f9-dirty"; + skiboot = "5.4.0"; + occ = "d7efe30"; + linux = "4.4.32-openpower1"; + }; + +Old-style: + +.. code-block:: dts + + ibm,firmware-versions { + occ = "d7efe30-opdirty"; + skiboot = "5.4.0-opdirty"; + buildroot = "211bd05"; + capp-ucode = "1bb7503-opdirty"; + petitboot = "v1.3.1-opdirty-d695626"; + open-power = "habanero-f7b8f65-dirty"; + phandle = <0x1000012e>; + hostboot-binaries = "56532f5-opdirty"; + habanero-xml = "6a78496-opdirty-526ff79"; + hostboot = "09cfacb-opdirty"; + linux = "4.4.32-openpower1-opdirty-85cf528"; + };