Tuesday, December 18, 2012

Accessing UEFI from the operating system runtime


Sometimes the question arises about accessing UEFI services during the operating system runtime.   Recall that UEFI demarcates its core services into boot services and runtime services.   The former are only available prior to the invocation of ExitBootServices(), whereas the latter are available during the life of the platform for a UEFI-aware operating system.   This is the design intent.   Other boot services components can expose content during runtime if said content is allocated in runtime services memory and exposes itself through infrastructure like an installable GUIDed table.

In practice today, these services are not necessarily exposed 1:1 between an operating system services and the corresponding UEFI runtime service.

For Windows, the only API that I know of for accessing UEFI entail the UEFI variable services.   Check out Get/Set firmware environment variables services http://msdn.microsoft.com/en-us/library/windows/desktop/ms724934(v=vs.85).aspx and http://msdn.microsoft.com/en-us/library/windows/desktop/ms724325(v=vs.85).aspx, respectively.

Linux provides access to the UEFI variable services through sysfs, too.  Some detail can be found at 

Beyond variables, though, UEFI interfaces are opaque at OS runtime for Windows.   For Linux the UEFI system table is a kernel global object for Linux drivers.

The net result is that you cannot get to the UEFI RT or the system table at OS runtime, I'm afraid.   The Linux sysfs is the closest but even there it doesn't expose each UEFI RT call point.  The reason that the UEFI variable services are exposed in the fashion they are via Win32 calls is that OS installer programs have needed them since EFI1.02 back in 1999.   Writing UEFI RT code is pretty tricky because of things like the OS owning the hardware, the virtual mapping of the firmware, etc.(i.e., tough for firmware folks).  Also, the OS guys don't necessarily trust firmware and the UEFI RT code/data isn't hardware isolated from the other OS kernel components and drivers.

As such, the preferred industry approach to having a runtime interface to the platform is ACPI since ACPI runs in a sandbox with an interpreted bytecode AML.  There is some interesting open source implementations of ACPI at http://www.acpica.org/, for example.   UEFI is great for pre-OS applications and usages, of course.  And one model observed today is to stage activities from the OS, such as writing a file to the UEFI system partition, and then rebooting so that an associated UEFI application can act upon the file or directive from the OS agent.

Of course, UEFI runtime services are always available in the pre-OS, namely during the boot services (BS) phase.

3/10/14 update-
Windows now has kernel-mode variants of its access API's http://msdn.microsoft.com/en-us/library/windows/hardware/jj151553(v=vs.85).aspx and there is a nice description of variable access from Linux at firmware.intel.com/blog/accessing-uefi-variables-linux

5/22/14 update-
Regarding the protection of the platform resources by the OS, you need to have administrative privileges in Windows and Linux in order to access the OS API's that abstract the UEFI variable interface from user-land code.

11/5/14 update -
if you boot via Int19h PC/AT BIOS process, the UEFI runtime memory is given back to the OS and is reported as available via the memory map call in E820h Int15h call. As such, there is no way to invoke Get/Set Variable from a PC/AT "Legacy" BIOS boot.

Tuesday, December 4, 2012

Errata, PI1.2.1a and all that

Recall that the UEFI Forum (www.uefi.org) governs several specifications.   The first is the main UEFI specification which serves as the contract between the platform firmware and several pre-OS components.  The latter components include pre-OS applications, drivers, OS runtimes.   The other specification under the aegis of the UEFI Forum is the platform initialization, or "PI" specifications.   These five volumes describe interoperability between components that comprise the construction of the platform firmware, including the Pre-EFI Initiation (PEI) phase and the Driver Execution Environment (DXE).   For both the UEFI and PI specifications, major specification releases entail updates to functionality and capabilities.  A fortiori, such changes entail updates to the version fields in the various services tables, such as the UEFI System Table for UEFI and the PEI, DXE, and SMM services tables for PI, respectively.   These service table revisions allow for software to detect the variant of a given platform firmware in case a certain service has evolved modal behavior or to ascertain if a certain capability exists.

With all that in mind, evolution of the UEFI and PI specifications can also occur via the errata process.  If you think of the major specification updates to be a forward direction evolving process, the errata process is more lateral in that it clarifies issues within a given set of specifications without introducing interoperability issues.   This interop issue is important in that there is no software discernible difference between various implementations of errata for a given UEFI or PI major version, so such changes cannot be probed by software via the version number conceit listed earlier.

Finally we get to the point of this blog posting and the PI 1.2.1a specification.   The 'a' suffix means that this revision of the specification consists of the first errata against the PI 1.2.1a specification.   Recall that the PI 1.2.1 specification was released on May 2, 2012.   The PI 1.2.1a specification, in turn, was released on October 26, 2012.   This five month cadence is not unreasonable, with the most frequent errata cycle being once per quarter if there are sufficient bugs to address.

For PI 1.2.1a specification, the errata includes the following:

- Adding a 'boot with manufacturing mode'
- Addition of a simple signed firmware volume and file
- Clarification of memory usage across the S3 boot path
- Root handler processing clarification in SMI

and other clean-up.

The creation of errata allow for consistency in the software definitions.  This, along with conformant implementations of the UEFI and PI specifications at http://sourceforge.net/apps/mediawiki/tianocore/index.php?title=EDK2, provides an evolution of the platform firmware between the addition of new features and capabilities in major specification revision updates.