diff --git a/source/chapter1-about.rst b/source/chapter1-about.rst index 830f0f281a956cfe3ca9996a2c86ca50ffe78039..4c34bcfb59ceb28a82b893f3f3dae7de47f53981 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 4ba87792301c35121dfca72f6e7577456436e814..00c4dbdb786250a423fae761a397d793292dbeb1 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 ---------------------- diff --git a/source/chapter3-fwupdate.rst b/source/chapter3-fwupdate.rst index 5ce5fb04abb2ecd806b35af50335c2c84f090e86..1d146d9e15907bbfa91cf3e0d96f4cea95556b92 100644 --- a/source/chapter3-fwupdate.rst +++ b/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 =============