[v2] Add documentation for ibm, firmware-versions device tree node

Message ID 20170222060254.24323-1-stewart@linux.vnet.ibm.com
State Accepted
Headers show

Commit Message

Stewart Smith Feb. 22, 2017, 6:02 a.m.
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)
---
 doc/device-tree/ibm,firmware-versions.rst | 139 ++++++++++++++++++++++++++++++
 1 file changed, 139 insertions(+)
 create mode 100644 doc/device-tree/ibm,firmware-versions.rst

Comments

Samuel Mendoza-Jonas Aug. 23, 2017, 5:37 a.m. | #1
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";
> +        };
Stewart Smith Dec. 1, 2017, 6:41 a.m. | #2
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.

Patch

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";
+        };