Process the capsule

The firmware on a device is updated using a capsule through UEFI. This process involves capturing the firmware update payload in a capsule [.cap file], which is then processed by the system firmware to update the device firmware.

The mentioned capsule update is applicable to Qualcomm Linux advanced and base variants only.

UEFI variables used in capsule update

Protocols and services that interact with the platform firmware enable communication between the OS and UEFI. UEFI offers a standard boot environment, data tables with platform information, and boot/runtime service calls for the OS loader and OS.

Table: UEFI variables used in capsule update

Variable name	Description
OsIndications	This variable is owned by the OS and is used to indicate the features the OS wants the firmware to enable or the actions the OS wants the firmware to take. The operating system sets the variable, and UEFI clears it.
OsIndicationsSupported	This variable is owned by the firmware and indicates which OS indication features and actions are supported by the firmware.
OsTrialBootStatus (32‑bit UEFI variable)	Bit map: • 7:0 – Version: Version number of `OsTrialBootStatus` • 11:8 – TrialBootMaxCount: Set by the OS before triggering the capsule update • 15:12 – TrialBootCount: Set or incremented by UEFI (if `TrialBootEnabled` is not cleared by OS). The OS may set this to `TrialBootMaxCount` to trigger firmware rollback • 16 – TrialBootEnabled: Set to `1` by UEFI after capsule update and cleared by the OS after successful OTA update • 31:17 – Unused
EFI system resource table (ESRT)	The ESRT table is set by UEFI after the capsule update.

For more information about the OsIndications and OsIndicationsSupported variables, see Exchanging information between the OS and Firmware.

If there is more than one capsule in the ESP partition (in EFI/UpdateCapsule), consider all the capsules for the update and update them alphabetically.
Store all UEFI non-volatile variables in the Rollback Protection Memory Block (RPMB) partition, which must be in a Provisioned state.
- Autoprovision the RPMB on Qualcomm secure-boot enabled devices.
- On Qualcomm non-secure devices, don’t autoprovision the RPMB; instead, provision it with test keys.
- If you provision the RPMB with test keys on non-secure devices, you can’t re-provision it with a device key when enabling Qualcomm secure boot on the device.
- Use the rpmbClient application for RPMB provisioning from Linux. For more information, see Qualcomm Security Linux Guide.

EFI system resource table (ESRT) for capsule update status

The ESRT is an optional mechanism to identify the device and the system firmware resources that are used to provide firmware updates. Each ESRT entry describes a firmware resource that can be updated and reports the status of the last attempted update. The following table lists the ESRT entries used to report the status of the last attempted update:

Table: ESRT entries

ESRT field	Description
FwClass	Includes a GUID that identifies a firmware component for update through UpdateCapsule().
FwType	Identifies the type of firmware resource.
FwVersion	Represents the current version of the firmware resource. The value must always increase as a larger number represents a newer version.
LowestSupportedFwVersion	Specifies the lowest firmware resource version to which the system or device can roll back to.
CapsuleFlags	Contains the CapsuleGuid flags (bits 0-15) as defined in the EFI_CAPSULE_HEADER that’s set in the capsule header.
LastAttemptVersion	Indicates the last firmware version for which the system attempted an update (uses the same format as the firmware version).
LastAttemptStatus	Describes the result of the last firmware update attempt for the firmware resource entry.

The OS exposes the ESRT content from the sysfs path.

/sys/firmware/efi/esrt/entries/entry0/
sh-5.1# cd /sys/firmware/efi/esrt/entries/entry0/
sh-5.1# ls
capsule_flags  fw_type     last_attempt_status   lowest_supported_fw_version
w_class       fw_version  last_attempt_version

UEFI sets the ESRT table after the capsule update. X represents the firmware version before the capsule update. Y is the version of the firmware, which is available in the capsule [.cap] file.

Last attempted firmware version is available only if RPMB is provisioned.

Last attempted firmware version	Current firmware version	last_attempt_status	Capsule update scenario
Y	Y	0	Update success
Y	X	1	Capsule update failure
0	X	0	Capsule meta-data failure
Y	X	0	Firmware rollback done

For more information about ESRT, see Firmware Update and Reporting - UEFI Specification 2.10 documentation.

Firmware update using Capsule

The flowchart shows how to update the device firmware using the UEFI capsule method, leveraging different UEFI variables and supporting rollback.

Initiation: The over the air (OTA) update process starts, and the OS prepares to update the capsule, signaling the UEFI (through setting OsIndications) to begin the update. The OS sets a TrialBootMaxCount to track the number of trial boots allowed and then reboots the device.
UEFI update: Upon reboot, the system checks for OsIndications. If present, it performs the capsule update, updates the EFI system resource table (ESRT), clears OsIndications, and if TrialBootMaxCount is set, allows TrialBootEnabled and restarts the system again.
Trial boot handling:
- If the OsIndications aren’t set, the system checks if the TrialBootEnabled is active.
- If the TrialBootEnabled is active and the TrialBootCount equals the TrialBootMaxCount, it checks the rollback count.
  - If a rollback is allowed, the UEFI reverts to the firmware, updates the ESRT, and reboots.
  - If a rollback isn’t allowed, it indicates that the rollback limit is reached.
- If the TrialBootCount is less than the TrialBootMaxCount, it increments the TrialBootCount and continues the process.
Completion: The system boots to the OS, checks the ESRT, and if the OS boots successfully, it resets the TrialBootEnabled field.
Result:
- If TrialBootEnabled isn’t active, the OTA update is confirmed as complete.
- The system clears the OtaTrialBootStatus and sets the LwSupportedFwVersion to the current firmware version to disable rollback.
Recovery: If a firmware capsule update fails during the update process, UEFI has a recovery mechanism to maintain the stability and functionality.
1. Rollback: If rollback is allowed, UEFI reverts to the previous firmware version and restores the firmware to its state before the update attempt.
2. ESRT update: The system updates the ESRT to reflect the rollback.
3. Reboot: After the rollback is complete, the UEFI triggers a restart to ensure it’s running the previous, stable firmware version. This process applies the update and enables rollback if issues occur during the trial period.

Authentication is critical to maintain security and stability during firmware updates. It helps with the following:

Ensures the system applies only updates from trusted sources.
Prevents malicious or unauthorized updates.
Verifies the digital signature to confirm integrity during transmission.
Installs only verified and tested updates.
Reduces the risk of system crashes or malfunctions caused by faulty firmware.

Introduction

Architecture

Key Documents

Technologies

System

Release Notes

UEFI variables used in capsule update

EFI system resource table (ESRT) for capsule update status

Firmware update using Capsule

​UEFI variables used in capsule update

​EFI system resource table (ESRT) for capsule update status

​Firmware update using Capsule

UEFI variables used in capsule update

EFI system resource table (ESRT) for capsule update status

Firmware update using Capsule