Merge pull request #10 from jmarinho/master

OS failed boot + metadata requirements redirection to DEN0118

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

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
 ----------------------
 

source/chapter3-fwupdate.rst

@@ -17,6 +17,7 @@ capsule by invoking the UEFI UpdateCapsule runtime service. The capsule can
 be installed, by the UEFI Implementation, without requiring a system reboot.
 
 The FWU metadata [FWU]_ is managed by the FWU Implementation in the Secure world.
+The FWU metadata is described in Section 4.1 of [FWU]_.
 
 When the flash is owned by the Secure World, the FMP communicates with the FWU Implementation 
 in the secure world using the FF-A Firmware Update ABI [FWU]_
@@ -64,6 +65,7 @@ Two models exist in this platform model:
   The implementation must correctly flush all caches prior to performing the warm reset.
 
 The FWU metadata [FWU]_ is managed by the UEFI implementation.
+The FWU metadata is described in Section 4.1 of [FWU]_.
 
 Example flows
 =============