From d6a78fdf7a31d7b14b636a1307d0f2e5ab512171 Mon Sep 17 00:00:00 2001
From: Jose Marinho <jose.marinho@arm.com>
Date: Mon, 8 Nov 2021 12:35:19 +0000
Subject: [PATCH] Distinguish between two for OS boot failure after update

1. OS tests deem FW bad: OS asks for FW revert
2. OS fails to boot: NWd FW must request FW revert

+ intro text retouches about how the rollback counters are updated.
---
 source/chapter1-about.rst | 28 ++++++++++++++--------------
 source/chapter2-uefi.rst  |  2 ++
 2 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/source/chapter1-about.rst b/source/chapter1-about.rst
index 88878f6..2b81de9 100644
--- a/source/chapter1-about.rst
+++ b/source/chapter1-about.rst
@@ -82,20 +82,20 @@ without UEFI is outside the scope of this document.
 Transactional updates
 ---------------------
 Since firmware updates are independent from the OS upgrades, an important aspect of the update
-policy is the device functionality.  If the OS ends up being unusable after a firmware update,
-the device must rollback to its previous firmware version automatically.
-Any number of firmware components that were involved in the update must be reverted.
-
-Since each firmware element may have its own rollback counters, this can be achieved by having
-the kernel (or some trusted user-space application communicating to a device manager) act as
-the ultimate authority of the device usability.
-Instead of having each firmware component non-volatile counter (used for rollback protection)
-increased upon successful update, we can leave the counter untouched until the operating system
-has reached a verdict.  If the OS decides the current state is operational it will signal via UEFI
-services and send capsule update indicating the transaction is successful.
-The Non-secure firmware will, on next reboot, signal the individual firmware binaries to
-increase their rollback counter to the correct value.  This assumes A/B partitions for all
-firmware components and a TF-A upgrade mechanism that supports this functionality.
+policy is the device functionality.  If the OS ends up being unusable after a firmware update (while the platform is in the Trial state [FWU]_),
+the device must be able to detect this occurrence and steps must be taken to move the platform to
+the previously working firmware.
+Two scenarios can be considered:
+
+#. The FW acceptance tests, executed by the OS, fail: The OS must request a FW downgrade by using the methodology described in :ref:`revert-sec`.
+
+#. The OS fails to boot, e.g. due to a watchdog timer fire: The Normal World FW must keep a counter of the attempted OS boots in the Trial State. If the platform is in the Trial State after a platform specific number of OS boot attempts, the Normal World FW must take the steps to revert the FW to the previous active FW bank.
+
+If the FW acceptance tests, executed by the OS, pass, then the newly installed FW can be made permanent.
+To mark the FW as permanent the OS  will install an acceptance capsule as described in :ref:`OS directed FW image acceptance`.
+The Non-secure firmware will, on next reboot, mark all FW images in the active bank as accepted and
+update the rollback counters to the new values (if applicable) [FWU]_.
+Once all the FW images in the active bank are accepted, the device transitions from the Trial state to the Regular state [FWU]_.
 
 .. image:: images/update_overview.png
   :width: 400px
diff --git a/source/chapter2-uefi.rst b/source/chapter2-uefi.rst
index d885240..80c5928 100644
--- a/source/chapter2-uefi.rst
+++ b/source/chapter2-uefi.rst
@@ -54,6 +54,8 @@ explicitly accept the image by installing an acceptance capsule as described in
 A UEFI implementation can opt to implicitly accept any FW image. It is
 strongly recommended that the FW image acceptance is treated as an OS responsibility.
 
+.. _revert-sec:
+
 OS requested FW revert
 ----------------------
 
-- 
GitLab