[Skiboot] [PATCH v2] Add documentation for ibm, firmware-versions device tree node
Samuel Mendoza-Jonas
sam at mendozajonas.com
Wed Aug 23 15:37:51 AEST 2017
On Wed, 2017-02-22 at 17:02 +1100, Stewart Smith wrote:
> Reviewed-by: Reza Arbab <arbab at us.ibm.com>
> Signed-off-by: Stewart Smith <stewart at 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 at 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";
> + };
More information about the Skiboot
mailing list