From patchwork Wed Feb 22 06:02:54 2017 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stewart Smith X-Patchwork-Id: 730916 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 3vSmxp1yR5z9s7R for ; Wed, 22 Feb 2017 17:03:10 +1100 (AEDT) Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 3vSmxp17bMzDqGV for ; Wed, 22 Feb 2017 17:03:10 +1100 (AEDT) X-Original-To: skiboot@lists.ozlabs.org Delivered-To: skiboot@lists.ozlabs.org Received: from mx0a-001b2d01.pphosted.com (mx0b-001b2d01.pphosted.com [148.163.158.5]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 3vSmxj4dkRzDq5g for ; Wed, 22 Feb 2017 17:03:05 +1100 (AEDT) Received: from pps.filterd (m0098417.ppops.net [127.0.0.1]) by mx0a-001b2d01.pphosted.com (8.16.0.20/8.16.0.20) with SMTP id v1M5msC8122330 for ; Wed, 22 Feb 2017 01:03:03 -0500 Received: from e34.co.us.ibm.com (e34.co.us.ibm.com [32.97.110.152]) by mx0a-001b2d01.pphosted.com with ESMTP id 28rwnhx4bb-1 (version=TLSv1.2 cipher=AES256-SHA bits=256 verify=NOT) for ; Wed, 22 Feb 2017 01:03:02 -0500 Received: from localhost by e34.co.us.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Tue, 21 Feb 2017 23:03:02 -0700 Received: from d03dlp02.boulder.ibm.com (9.17.202.178) by e34.co.us.ibm.com (192.168.1.134) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; Tue, 21 Feb 2017 23:03:00 -0700 Received: from b03cxnp07028.gho.boulder.ibm.com (b03cxnp07028.gho.boulder.ibm.com [9.17.130.15]) by d03dlp02.boulder.ibm.com (Postfix) with ESMTP id C05293E40041 for ; Tue, 21 Feb 2017 23:02:59 -0700 (MST) Received: from b03ledav006.gho.boulder.ibm.com (b03ledav006.gho.boulder.ibm.com [9.17.130.237]) by b03cxnp07028.gho.boulder.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id v1M62xd615139222; Tue, 21 Feb 2017 23:02:59 -0700 Received: from b03ledav006.gho.boulder.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 9A462C6047; Tue, 21 Feb 2017 23:02:59 -0700 (MST) Received: from birb.localdomain (unknown [9.185.16.50]) by b03ledav006.gho.boulder.ibm.com (Postfix) with ESMTP id 2C47EC603C; Tue, 21 Feb 2017 23:02:59 -0700 (MST) Received: by birb.localdomain (Postfix, from userid 1000) id 5D19A2261241; Wed, 22 Feb 2017 17:02:55 +1100 (AEDT) From: Stewart Smith To: skiboot@lists.ozlabs.org Date: Wed, 22 Feb 2017 17:02:54 +1100 X-Mailer: git-send-email 2.9.3 In-Reply-To: <20170220231349.13144-1-stewart@linux.vnet.ibm.com> References: <20170220231349.13144-1-stewart@linux.vnet.ibm.com> X-TM-AS-GCONF: 00 X-Content-Scanned: Fidelis XPS MAILER x-cbid: 17022206-0016-0000-0000-0000063D96EA X-IBM-SpamModules-Scores: X-IBM-SpamModules-Versions: BY=3.00006661; HX=3.00000240; KW=3.00000007; PH=3.00000004; SC=3.00000204; SDB=6.00825355; UDB=6.00404114; IPR=6.00602810; BA=6.00005161; NDR=6.00000001; ZLA=6.00000005; ZF=6.00000009; ZB=6.00000000; ZP=6.00000000; ZH=6.00000000; ZU=6.00000002; MB=3.00014385; XFM=3.00000011; UTC=2017-02-22 06:03:01 X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 17022206-0017-0000-0000-0000379BF1B0 Message-Id: <20170222060254.24323-1-stewart@linux.vnet.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10432:, , definitions=2017-02-22_03:, , signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 spamscore=0 suspectscore=1 malwarescore=0 phishscore=0 adultscore=0 bulkscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1612050000 definitions=main-1702220059 Subject: [Skiboot] [PATCH v2] Add documentation for ibm, firmware-versions device tree node X-BeenThere: skiboot@lists.ozlabs.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Mailing list for skiboot development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: skiboot-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org Sender: "Skiboot" Reviewed-by: Reza Arbab Signed-off-by: Stewart Smith Reviewed-by: Samuel Mendoza-Jonas --- 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 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"; + };