aboutsummaryrefslogtreecommitdiff
path: root/doc/device-tree
diff options
context:
space:
mode:
authorStewart Smith <stewart@linux.vnet.ibm.com>2017-02-22 17:02:54 +1100
committerStewart Smith <stewart@linux.vnet.ibm.com>2017-11-30 23:46:28 -0600
commit2f8c9acf8985bae54eeb9778319c4ffb1d77bbbe (patch)
tree029139761bd0280bf6d241b43ebbfbc974aed4e0 /doc/device-tree
parent78168d1bad23c3877bac284eb7c4b259bc022a38 (diff)
downloadskiboot-2f8c9acf8985bae54eeb9778319c4ffb1d77bbbe.zip
skiboot-2f8c9acf8985bae54eeb9778319c4ffb1d77bbbe.tar.gz
skiboot-2f8c9acf8985bae54eeb9778319c4ffb1d77bbbe.tar.bz2
Add documentation for ibm, firmware-versions device tree node
Reviewed-by: Reza Arbab <arbab@us.ibm.com> Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com> Reviewed-by: Samuel Mendoza-Jonas <sam@mendozajonas.com> Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>
Diffstat (limited to 'doc/device-tree')
-rw-r--r--doc/device-tree/ibm,firmware-versions.rst139
1 files changed, 139 insertions, 0 deletions
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";
+ };