"Accessing UEFI from the operating system runtime" http://vzimmer.blogspot.com/2012/12/accessing-uefi-form-operating-system.html represents my most frequently accessed blog posting. In fact I scrawled this quick posting in response to an engineer having recently sent me a mail referencing the above posting and decrying lack of information on access to the UpdateCapsule interface from the various OS's.
To begin, let's start with the API exposed by the UEFI firmware is defined as followed:
The capsule in memory follows:
From my perspective as a 'builder' of firmware I often focus on the underlying constituent elements, but that's a smaller audience than the consumers of the firmware. At the time of the posting, the UEFI Variable interface was the more important interface in order to access both UEFI specification defined variables, namely those {GUID, Unicode String} named pairs codified in the UEFI specification, and vendor-defined variable GUID's and Names.
In the five years that have followed that posting, there's another important extensible run time interface that has been exposed to the operating system run time, namely the UpdateCapsule interface. The Capsule infrastructure began as part of the Intel Framework corpus https://www.intel.com/content/www/us/en/architecture-and-technology/unified-extensible-firmware-interface/efi-capsule-specification.html, but was eventually donated into the UEFI Forum in a similar specification arc as HII. Recall that much of the Intel Framework specifications, such as PEI and DXE, became pillars of the UEFI Platform Initialization (PI) specifications, but when an interface needs interoperability between the pre-OS ISV's and OS runtimes, that is purveiw of the UEFI (and ACPI) specifications. Microsoft complemented this Framework-era capsule infrastructure with the ESRT, or a list of updatable elements in the platform defined by a list of GUID's.
Although the UpdateCapsule API can be used to convey any information from the run into the pre-OS, including crash-dump, management information, etc, the 'firmware update' usage is the most important from a business perspective.
And regarding the API, having a definition of the interface and the data enveloping mechanism are necessary but not sufficient. You also need producers of the update interface on system boards and infrastructure software to invoke the interface. To that end, the EDKII community has published a rich set of infrastructure code to provide the interface https://github.com/tianocore/tianocore.github.io/wiki/Capsule-Based-Firmware-Update-and-Firmware-Recovery with a detailed code explication in https://github.com/tianocore-docs/Docs/raw/master/White_Papers/A_Tour_Beyond_BIOS_Capsule_Update_and_Recovery_in_EDK_II.pdf. On the operating system side, there is infrastructure to support invoking the interface for both Linux https://lists.gt.net/linux/kernel/2149809 and Microsoft Windows https://docs.microsoft.com/en-us/windows-hardware/drivers/bringup/system-and-device-firmware-updates-via-a-firmware-driver-package.
The Linux kernel exposes the capsule loader interface via sysfs in a similar fashion to how the UEFI variable interfaces are exposed. The Windows implementation, though, doesn't expose the direct interface but instead conjoins issuing capsules on top of the infrastructure for installing drivers. This is where the distinction between capsules as a mechanism to pass a GUID-named data payload with a scatter-gather list in memory back to firmware compares to usage of this interface to pass payloads that are a firmware update. On the latter point of updates, the Linux community has build out the fwupd service http://fwupd.org/ to facilitate pushing out updates in a similar fashion to Windows Update http://www.uefi.org/sites/default/files/resources/2014_UEFI_Plugfest_07_Microsoft.pdf. https://blueprints.launchpad.net/ubuntu/+spec/foundations-w-uefi-capsule-update provides an interesting view into steps involved in plumbing a Linux distribution for this end-to-end use case, too.
You can think of the UpdateCapsule invocation as a syscall back to the firmware. This is different than UEFI Variables where the expectation that the 'set' call persists immediately without and intervening platform restart. Instead, by having the UpdateCapsule take effect (typically) across a restart, the update of the underlying firmware can occur in the early boot of the firmware Trusted Computing Base (TCB) prior to running third party code. Or a capsule can just be passed through, such as the case of the OS runtime sending its panic screen to be displayed across a restart to its UEFI OS loader.
Philosophical postlude -
The difference between UpdateCaspule versus the Get/Set Variable interface is that the latter has been available in the EFI (and then UEFI) OS's since 1999. Update Capsule, and the corresponding ESRT, have only appeared more recently. If I had a chance to invoke George Cox's http://vzimmer.blogspot.com/2015/06/guids-revisions-interrupts.html "I could do it better the 2nd time" penchant of engineering, I would have argued that art such as UEFI Authenticated Variables would have been better built as signed UEFI Capsules versus UEFI Variables since authentication-at-reset in the PI phase (BIOS TCB) is much easier to build than an authentication agent in the firmware that is isolated from the OS or hypervisor run time, as needed by the UEFI Authenticated Variables.
To begin, let's start with the API exposed by the UEFI firmware is defined as followed:
From my perspective as a 'builder' of firmware I often focus on the underlying constituent elements, but that's a smaller audience than the consumers of the firmware. At the time of the posting, the UEFI Variable interface was the more important interface in order to access both UEFI specification defined variables, namely those {GUID, Unicode String} named pairs codified in the UEFI specification, and vendor-defined variable GUID's and Names.
In the five years that have followed that posting, there's another important extensible run time interface that has been exposed to the operating system run time, namely the UpdateCapsule interface. The Capsule infrastructure began as part of the Intel Framework corpus https://www.intel.com/content/www/us/en/architecture-and-technology/unified-extensible-firmware-interface/efi-capsule-specification.html, but was eventually donated into the UEFI Forum in a similar specification arc as HII. Recall that much of the Intel Framework specifications, such as PEI and DXE, became pillars of the UEFI Platform Initialization (PI) specifications, but when an interface needs interoperability between the pre-OS ISV's and OS runtimes, that is purveiw of the UEFI (and ACPI) specifications. Microsoft complemented this Framework-era capsule infrastructure with the ESRT, or a list of updatable elements in the platform defined by a list of GUID's.
Although the UpdateCapsule API can be used to convey any information from the run into the pre-OS, including crash-dump, management information, etc, the 'firmware update' usage is the most important from a business perspective.
And regarding the API, having a definition of the interface and the data enveloping mechanism are necessary but not sufficient. You also need producers of the update interface on system boards and infrastructure software to invoke the interface. To that end, the EDKII community has published a rich set of infrastructure code to provide the interface https://github.com/tianocore/tianocore.github.io/wiki/Capsule-Based-Firmware-Update-and-Firmware-Recovery with a detailed code explication in https://github.com/tianocore-docs/Docs/raw/master/White_Papers/A_Tour_Beyond_BIOS_Capsule_Update_and_Recovery_in_EDK_II.pdf. On the operating system side, there is infrastructure to support invoking the interface for both Linux https://lists.gt.net/linux/kernel/2149809 and Microsoft Windows https://docs.microsoft.com/en-us/windows-hardware/drivers/bringup/system-and-device-firmware-updates-via-a-firmware-driver-package.
The Linux kernel exposes the capsule loader interface via sysfs in a similar fashion to how the UEFI variable interfaces are exposed. The Windows implementation, though, doesn't expose the direct interface but instead conjoins issuing capsules on top of the infrastructure for installing drivers. This is where the distinction between capsules as a mechanism to pass a GUID-named data payload with a scatter-gather list in memory back to firmware compares to usage of this interface to pass payloads that are a firmware update. On the latter point of updates, the Linux community has build out the fwupd service http://fwupd.org/ to facilitate pushing out updates in a similar fashion to Windows Update http://www.uefi.org/sites/default/files/resources/2014_UEFI_Plugfest_07_Microsoft.pdf. https://blueprints.launchpad.net/ubuntu/+spec/foundations-w-uefi-capsule-update provides an interesting view into steps involved in plumbing a Linux distribution for this end-to-end use case, too.
You can think of the UpdateCapsule invocation as a syscall back to the firmware. This is different than UEFI Variables where the expectation that the 'set' call persists immediately without and intervening platform restart. Instead, by having the UpdateCapsule take effect (typically) across a restart, the update of the underlying firmware can occur in the early boot of the firmware Trusted Computing Base (TCB) prior to running third party code. Or a capsule can just be passed through, such as the case of the OS runtime sending its panic screen to be displayed across a restart to its UEFI OS loader.
Philosophical postlude -
The difference between UpdateCaspule versus the Get/Set Variable interface is that the latter has been available in the EFI (and then UEFI) OS's since 1999. Update Capsule, and the corresponding ESRT, have only appeared more recently. If I had a chance to invoke George Cox's http://vzimmer.blogspot.com/2015/06/guids-revisions-interrupts.html "I could do it better the 2nd time" penchant of engineering, I would have argued that art such as UEFI Authenticated Variables would have been better built as signed UEFI Capsules versus UEFI Variables since authentication-at-reset in the PI phase (BIOS TCB) is much easier to build than an authentication agent in the firmware that is isolated from the OS or hypervisor run time, as needed by the UEFI Authenticated Variables.
