Chapter 2
Under the UEFI Shell
You cannot create experience. You must undergo it.
—Albert Camus
The UEFI Shell provides an interactive command-line environment. The shell includes such facilities as scripting and a hierarchical set of command profiles. This allows for usages spanning in-situ field diagnostics to a full provisioning environment. As the UEFI Shell is just a distinguished UEFI application, it bears mentioning some of the underlying capabilities of UEFI upon which the shell depends.
Shell and UEFI
The UEFI Shell is launched as a UEFI application. UEFI applications are formatted as PE/COFF executables and are loaded into memory and relocated in memory via the UEFI LoadImage() service and invoked via the UEFI StartImage() service. The UEFI Shell, like any application, has two input parameters. These input parameters include an image handle and a pointer to the UEFI System Table, respectively.
To begin with the first argument, the image handle is an opaque data object that can be used with the UEFI protocol services to discover information, such as other protocols associated with this handle, via querying UEFI boot services, such as locate and handle protocols. Implementations such as EDKII typically have the image handle as a pointer to the underlying data structure defining the handle, but this is an implementation specific art and not guaranteed across other implementations. This handle can be used to discover other protocols associated with an application, such as the loaded image protocol. The loaded image protocol is something of a selfpointer with respect to the image that describes where the information is loaded in memory and other properties.
A protocol is typically published by the UEFI core or a UEFI driver. A relationship of a protocol to the UEFI Shell is shown in Figure 2.1:
The second argument, or a pointer to the UEFI System Table, is important in that it provides function pointers to the boot and runtime services, along with pointers to other GUID-annotated tables. This service set, such as the boot services, includes the protocol services mentioned above. The boot and runtime services are a set of base capabilities that any UEFI conformant system needs to supply to an application. Beyond the accessor functions of the protocol database, there are boot services for memory allocation, events, and other system capabilities. The latter are termed ‘boot services’ since they expire at the ExitBootServices() event. The UEFI Shell itself is a boot services application, so it can leverage all of these capabilities. The relationship of the UEFI Shell to the UEFI API’s are described by the UEFI specification, this relationship is shown diagrammatically in Figure 2.2.
Beyond the boot services there are another set of services called ‘runtime,’ which include UEFI variables, time, and monotonic counter support. The runtime APIs are purposely kept simple because these APIs must be callable after Exit-BootServices() and share the machine hardware at runtime with the hypervisor or operating system.
A more detailed layering of the UEFI shell and the underlying implementation is shown in Figure 2.3. A conformant shell implementation should only depend upon the interfaces and data objects defined in the main UEFI specification. As such, the platform-specific firmware can include but is not limited to things such as infrastructure based upon the UEFI platform initialization (PI) specification.
There are instances, though, where a UEFI Shell application may choose to access PI interfaces. These include diagnostics that want to access all the application processors in a symmetric multiprocessor (SMP) system. An example of such an API includes the EFI_MP_SERVICES protocol from volume 2 of the PI specification published by the UEFI Forum. In leveraging an underlying PI API, however, the UEFI Shell application is limiting its potential portability since a UEFI implementation, including the UEFI Shell, may not have PI-conforming firmware underneath.
And finally, the cessation of UEFI boot services is shown in Figure 2.4.
What this means is that like many boot service capabilities, the UEFI Shell ceases to be operational once the main operating system or hypervisor takes over.
Evolution and Revolution
The UEFI Shell is both evolutionary and revolutionary. The evolutionary aspect includes many simple firmware environments that have a command-line monitor to send commands at the low end. At the high end, many RISC workstations have an ability to drop into a command-line environment. As such, having a bare-metal environment wherein raw system resources can be ‘peeked’ and ‘poked’ (e.g., use the MM and PCI shell commands), is important for system maintenance.
The revolutionary aspect of the UEFI shell is that it provides an editing, networking, and other capabilities often found in an operating system. This allows a universal environment for diagnostics and other OS-absent applications.