[Skiboot] [PATCH] Add documentation for ibm, firmware-versions device tree node
Stewart Smith
stewart at linux.vnet.ibm.com
Tue Feb 21 10:13:49 AEDT 2017
Signed-off-by: Stewart Smith <stewart at linux.vnet.ibm.com>
---
doc/device-tree/ibm,firmware-versions.rst | 134 ++++++++++++++++++++++++++++++
1 file changed, 134 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..bddbabb
--- /dev/null
+++ b/doc/device-tree/ibm,firmware-versions.rst
@@ -0,0 +1,134 @@
+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: empty part,
+tilde (~), all letters, non-letters. This means an empty part sorts **before**
+any part beginning with a '~'. 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"
+
+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.
+
+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.0b 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";
+ };
--
2.9.3
More information about the Skiboot
mailing list