Objects Managed by UEFI-based Firmware

Several different types of objects can be managed through the services provided by UEFI. Some UEFI drivers may need to access environment variables, but most do not. Rarely do UEFI drivers require the use of a monotonic counter, watchdog timer, or real-time clock. The UEFI System Table is the most important data structure, because it provides access to all UEFI-provided the services and to all the additional data structures that describe the configuration of the platform.

UEFI System Table

The UEFI System Table is the most important data structure in UEFI. A pointer to the UEFI System Table is passed into each driver and application as part of its entry-point handoff. From this one data structure, an UEFI executable image can gain access to system configuration information and a rich collection of UEFI services that includes the following:

The UEFI Boot Services and UEFI Runtime Services are accessed through the UEFI Boot Services Table and the UEFI Runtime Services Table, respectively. Both of these tables are data fields in the UEFI System Table. The number and type of services that each table makes available is fixed for each revision of the UEFI specification. The UEFI Boot Services and UEFI Runtime Services are defined in the UEFI 2.6 Specification.

Protocol services are groups of related functions and data fields that are named by a Globally Unique Identifier (GUID), a 16-byte, statistically-unique entity defined in Appendix A of the UEFI 2.6 Specification. Typically, protocol services are used to provide software abstractions for devices such as consoles, disks, and networks, but they can be used to extend the number of generic services that are available in the platform. Protocols are the mechanism for extending the functionality of UEFI firmware over time. The UEFI 2.6 Specification defines over 30 different protocols, and various implementations of UEFI firmware and UEFI drivers may produce additional protocols to extend the functionality of a platform.

Handle Database

The handle database is composed of objects called handles and protocols. Handles are a collection of one or more protocols, and protocols are data structures that are named by a GUID. The data structure for a protocol may be empty, may contain data fields, may contain services, or may contain both services and data fields. During UEFI initialization, the system firmware, UEFI drivers, and UEFI applications create handles and attach one or more protocols to the handles. Information in the handle database is global and can be accessed by any executable UEFI image.

The handle database is the central repository for the objects that are maintained by UEFI-based firmware. The handle database is a list of UEFI handles, and each UEFI handle is identified by a unique handle number that is maintained by the system firmware. A handle number provides a database “key” to an entry in the handle database. Each entry in the handle database is a collection of one or more protocols. The types of protocols, named by a GUID, that are attached to an UEFI handle determine the handle type. An UEFI handle may represent components such as the following:

Figure 2.1 below shows a portion of the handle database. In addition to the handles and protocols, a list of objects is associated with each protocol. This list is used to track which agents are consuming which protocols. This information is critical to the operation of UEFI drivers, because this information is what allows UEFI drivers to be safely loaded, started, stopped, and unloaded without any resource conflicts.

Figure 2.2 shows the different types of handles that can be present in the handle database and the relationships between the various handle types. All handles reside in the same handle database and the types of protocols that are associated with each handle differentiate the handle type. Like file system handles in an operating system context, the handles are unique for the session, but the values can be arbitrary. Also, like the handle returned from an fopen function in a C library, the value does not necessarily serve a useful purpose in a different process or during a subsequent restart in the same process. The handle is just a transitory value to manage state.

Protocols

The extensible nature of UEFI is built, to a large degree, around protocols. UEFI drivers are sometimes confused with UEFI protocols. Although they are closely related, they are distinctly different. A UEFI driver is an executable UEFI image that installs a variety of protocols of various handles to accomplish its job.

A UEFI protocol is a block of function pointers and data structures or APIs that have been defined by a specification. At a minimum, the specification must define a GUID. This number is the protocol’s real name; boot services like LocateProtocol uses this number to find his protocol in the handle database. The protocol often includes a set of procedures and/ or data structures, called the protocol interface structure. The following code sequence is an example of a protocol definition. Notice how it defines two function definitions and one data field.

Figure 2.3 shows a single handle and protocol from the handle database that is produced by an UEFI driver. The protocol is composed of a GUID and a protocol interface structure. Many times, the UEFI driver that produces a protocol interface maintains additional private data fields. The protocol interface structure itself simply contains pointers to the protocol function. The protocol functions are actually contained within the UEFI driver. An UEFI driver might produce one protocol or many protocols depending on the driver’s complexity.

Not all protocols are defined in the UEFI 2.6 Specification. The EFI Developer Kit II (EDKII) includes many protocols that are not part of the UEFI 2.6 Specification. This project can be found at http://www.tianocore.org. These protocols provide the wider range of functionality that might be needed in any particular implementation, but they are not defined in the UEFI 2.6 Specification because they do not present an external interface that is required to support booting an OS or writing an UEFI driver. The creation of new protocols is how UEFI-based systems can be extended over time as new devices, buses, and technologies are introduced. For example, some protocols that are in the EDK II but not in the UEFI 2.6 Specification are:

The UEFI Application Toolkit also contains a number of UEFI protocols that may be found on some platforms, such as:

The OS loader and drivers should not depend on these types of protocols because they are not guaranteed to be present in every UEFI-compliant system. OS loaders and drivers should depend only on protocols that are defined in the UEFI 2.6 Specification and protocols that are required by platform design guides such as Design Implementation Guide for 64-bit Server.

The extensible nature of UEFI allows the developers of each platform to design and add special protocols. Using these protocols, they can expand the capabilities of UEFI and provide access to proprietary devices and interfaces in congruity with the rest of the UEFI architecture.

Because a protocol is “named” by a GUID, no other protocols should have that same identification number. Care must be taken when creating a new protocol to define a new GUID for it. UEFI fundamentally assumes that a specific GUID exposes a specific protocol interface. Cutting and pasting an existing GUID or hand-modifying an existing GUID creates the opportunity for a duplicate GUID to be introduced. A system containing a duplicate GUID inadvertently could find the new protocol and think that it is another protocol, crashing the system as a result. For these types of bugs, finding the root cause is also very difficult. The GUID allows for naming APIs without having to worry about namespace collision. In systems such as PC/AT BIOS, services were added as an enumeration. For example, the venerable Int15h interface would pass the service type in AX. Since no central repository or specification managed the evolution of Int15h services, several vendors defined similar service numbers, thus making interoperability with operating systems and pre-OS applications difficult. Through the judicious use of GUIDs to name APIs and an association to develop the specification, UEFI balances the need for API evolution with interoperability.

UEFI Images

All UEFI images contain a PE/COFF header that defines the format of the executable code as required by the Microsoft Portable Executable and Common Object File Format Specification (Microsoft 2008). The target for this code can be an IA-32 processor, an Itanium® processor, x64, ARM, or a processor agnostic, generic EFI Byte Code (EBC). The header defines the processor type and the image type. Presently there are three processor types and the following three image types defined:

The value of the UEFI Image format is that various parties can create binary executables that interoperate. For example, the operating system loader for Microsoft Windows† and Linux for an UEFI-aware OS build is simply an UEFI application. In addition, third parties can create UEFI drivers to abstract their particular hardware, such as a networking interface host bus adapter (HBA) or other devices. UEFI images are loaded and relocated into memory with the Boot Service gBS->LoadImage(). Several supported storage locations for UEFI images are available, including the following:

In general, UEFI images are not compiled and linked at a specific address. Instead, the UEFI image contains relocation fix-ups so the UEFI image can be placed anywhere in system memory. The Boot Service gBS->LoadImage() does the following:

This instance of the EFI_LOADED_IMAGE_PROTOCOL contains information about the UEFI image that was loaded. Because this information is published in the handle database, it is available to all UEFI components.

After an UEFI image is loaded with gBS->LoadImage(), it can be started with a call to gBS->StartImage(). The header for an UEFI image contains the address of the entry point that is called by gBS->StartImage(). The entry point always receives the following two parameters:

These two items allow the UEFI image to do the following:

The operations that the UEFI image performs in its entry point vary depending on the type of UEFI image. Figure 2.4 shows the various UEFI image types and the relationships between the different levels of images.

Table 2.1: Description of Image Types

Events and Task Priority Levels

Events are another type of object that is managed through UEFI services. An event can be created and destroyed, and an event can be either in the waiting state or the signaled state. A UEFI image can do any of the following:

Because UEFI does not support interrupts, it can present a challenge to driver writers who are accustomed to an interrupt-driven driver model. Instead, UEFI supports polled drivers. The most common use of events by an UEFI driver is the use of timer events that allow drivers to periodically poll a device. Figure 2.5 shows the different types of events that are supported in UEFI and the relationships between those events.

Table 2.2: Description of Event Types

The following three elements are associated with every event:

The notification function for a wait event is executed when the state of the event is checked or when the event is being waited upon. The notification function of a signal event is executed whenever the event transitions from the waiting state to the signaled state. The notification context is passed into the notification function each time the notification function is executed. The TPL is the priority at which the notification function is executed. Table 2.3: lists the four TPL levels that are defined today. Additional TPLs could be added later. An example of a compatible addition to the TPL list could include a series of “Interrupt TPLs” between TPL_NOTIFY and TPL_HIGH_LEVEL in order to provide interrupt-driven I/O support within UEFI.

Table 2.3: Task Priority Levels Defined in UEFI

TPLs serve the following two purposes:

For priority definition, you use this mechanism only when more than one event is in the signaled state at the same time. In these cases, the application executes the notification function that has been registered with the higher priority first. Also, notification functions at higher priorities can interrupt the execution of notification functions executing at a lower priority.

For creating locks, code running in normal context and code in an interrupt context can access the same data structure because UEFI does support a single-timer interrupt. This access can cause problems and unexpected results if the updates to a shared data structure are not atomic. An UEFI application or UEFI driver that wants to guarantee exclusive access to a shared data structure can temporarily raise the task priority level to prevent simultaneous access from both normal context and interrupt context. The application can create a lock by temporarily raising the task priority level to TPL_HIGH_LEVEL. This level blocks even the one-timer interrupt, but you must take care to minimize the amount of time that the system is at TPL_HIGH_LEVEL. Since all timer-based events are blocked during this time, any driver that requires periodic access to a device is prevented from accessing its device. A TPL is similar to the IRQL in Microsoft Windows and the SPL in various Unix implementations. A TPL describes a prioritization scheme for access control to resources.

Summary

This chapter has introduced some of the basic UEFI concepts and object types. These items have included events, protocols, task priority levels, image types, handles, GUIDs, and service tables. Many of these UEFI concepts, including images and protocols, are used extensively by other firmware technology, including the UEFI Platform Initialization (PI) building blocks, such as the DXE environment. These concepts will be revisited in different guises in subsequent chapters.