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>

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