2. Overview¶

UEFI allows the extension of platform firmware by loading UEFI driver and UEFI application images. When UEFI drivers and UEFI applications are loaded they have access to all UEFI-defined runtime and boot services. See the Booting Sequence figure below.

Fig. 2.1 Booting Sequence¶

UEFI allows the consolidation of boot menus from the OS loader and platform firmware into a single platform firmware menu. These platform firmware menus will allow the selection of any UEFI OS loader from any partition on any boot medium that is supported by UEFI boot services. An UEFI OS loader can support multiple options that can appear on the user interface. It is also possible to include legacy boot options, such as booting from the A: or C: drive in the platform firmware boot menus.

UEFI supports booting from media that contain an UEFI OS loader or an UEFI-defined System Partition. An UEFI-defined System Partition is required by UEFI to boot from a block device. UEFI does not require any change to the first sector of a partition, so it is possible to build media that will boot on both legacy architectures and UEFI platforms.

2.1. Boot Manager¶

UEFI contains a boot manager that allows the loading of applications written to this specification (including OS first stage loader) or UEFI drivers from any file on an UEFI-defined file system or through the use of an UEFI-defined image loading service. UEFI defines NVRAM variables that are used to point to the file to be loaded. These variables also contain application-specific data that are passed directly to the UEFI application. The variables also contain a human readable string that can be displayed in a menu to the user.

The variables defined by UEFI allow the system firmware to contain a boot menu that can point to all of the operating systems, and even multiple versions of the same operating systems. The design goal of UEFI was to have one set of boot menus that could live in platform firmware. UEFI specifies only the NVRAM variables used in selecting boot options. UEFI leaves the implementation of the menu system as value added implementation space.

UEFI greatly extends the boot flexibility of a system over the current state of the art in the PC-AT-class system. The PC-AT-class systems today are restricted to boot from the first floppy, hard drive, CD-ROM, USB keys, or network card attached to the system. Booting from a common hard drive can cause many interoperability problems between operating systems, and different versions of operating systems from the same vendor.

2.1.1. UEFI Images¶

UEFI Images are a class of files defined by UEFI that contain executable code. The most distinguishing feature of UEFI Images is that the first set of bytes in the UEFI Image file contains an image header that defines the encoding of the executable image.

UEFI uses a subset of the PE32+ image format with a modified header signature. The modification to the signature value in the PE32+ image is done to distinguish UEFI images from normal PE32 executables. The “+” addition to PE32 provides the 64-bit relocation fix-up extensions to standard PE32 format.

For images with the UEFI image signature, the Subsystem values in the PE image header are defined below. The major differences between image types are the memory type that the firmware will load the image into, and the action taken when the image’s entry point exits or returns. A UEFI application image is always unloaded when control is returned from the image’s entry point. A UEFI driver image is only unloaded if control is passed back with a UEFI error code.

// PE32+ Subsystem type for EFI images
#define EFI_IMAGE_SUBSYSTEM_EFI_APPLICATION          10
#define EFI_IMAGE_SUBSYSTEM_EFI_BOOT_SERVICE_DRIVER  11
#define EFI_IMAGE_SUBSYSTEM_EFI_RUNTIME_DRIVER       12

// PE32+ Machine type for EFI images
#define EFI_IMAGE_MACHINE_IA32                       0x014c
#define EFI_IMAGE_MACHINE_IA64                       0x0200
#define EFI_IMAGE_MACHINE_EBC                        0x0EBC
#define EFI_IMAGE_MACHINE_x64                        0x8664
#define EFI_IMAGE_MACHINE_ARMTHUMB_MIXED             0x01C2
#define EFI_IMAGE_MACHINE_AARCH64                    0xAA64
#define EFI_IMAGE_MACHINE_RISCV32                    0x5032
#define EFI_IMAGE_MACHINE_RISCV64                    0x5064
#define EFI_IMAGE_MACHINE_RISCV128                   0x5128

Note

This image type is chosen to enable UEFI images to contain Thumb and Thumb2 instructions while defining the EFI interfaces themselves to be in ARM mode.

Table 2.1 UEFI Image Memory Types¶
Subsystem Type	Code Memory Type	Data Memory Type
EFI_IMAGE_SUSBS YTEM_EFI_APPLICATION	EfiLoaderCode	EfiLoaderData
EFI _IMAGE_SUBSYSTEM_EFI _BOOT_SERVICE_DRIVER	EfiBootServicesCode	EfiBootServicesData
EFI_IMAGE_SUBSYSTE M_EFI_RUNTIME_DRIVER	Ef iRuntimeServicesCode	Ef iRuntimeServicesData

The Machine value that is found in the PE image file header is used to indicate the machine code type of the image. The machine code types for images with the UEFI image signature are defined below. A given platform must implement the image type native to that platform and the image type for EFI Byte Code (EBC). Support for other machine code types is optional to the platform.

A UEFI image is loaded into memory through the EFI_BOOT_SERVICES.LoadImage() Boot Service. This service loads an image with a PE32+ format into memory. This PE32+ loader is required to load all sections of the PE32+ image into memory. Once the image is loaded into memory, and the appropriate fix-ups have been performed, control is transferred to a loaded image at the AddressOfEntryPoint reference according to the normal indirect calling conventions of applications based on supported 32-bit, 64-bit, or 128-bit processors. All other linkage to and from an UEFI image is done programmatically.

2.1.2. UEFI Applications¶

Applications written to this specification are loaded by the Boot Manager or by other UEFI applications. To load a UEFI application the firmware allocates enough memory to hold the image, copies the sections within the UEFI application image to the allocated memory, and applies the relocation fix-ups needed. Once done, the allocated memory is set to be the proper type for code and data for the image. Control is then transferred to the UEFI application’s entry point. When the application returns from its entry point, or when it calls the Boot Service EFI_BOOT_SERVICES.LoadImage(), the UEFI application is unloaded from memory and control is returned to the UEFI component that loaded the UEFI application.

When the Boot Manager loads a UEFI application, the image handle may be used to locate the “load options” for the UEFI application. The load options are stored in nonvolatile storage and are associated with the UEFI application being loaded and executed by the Boot Manager.

2.1.3. UEFI OS Loaders¶

A UEFI OS loader is a special type of UEFI application that normally takes over control of the system from firmware conforming to this specification. When loaded, the UEFI OS loader behaves like any other UEFI application in that it must only use memory it has allocated from the firmware and can only use UEFI services and protocols to access the devices that the firmware exposes. If the UEFI OS loader includes any boot service style driver functions, it must use the proper UEFI interfaces to obtain access to the bus specific-resources. That is, I/O and memory-mapped device registers must be accessed through the proper bus specific I/O calls like those that a UEFI driver would perform.

If the UEFI OS loader experiences a problem and cannot load its operating system correctly, it can release all allocated resources and return control back to the firmware via the Boot Service Exit() call. The Exit() call allows both an error code and ExitData to be returned. The ExitData contains both a string and OS loader-specific data to be returned. If the UEFI OS loader successfully loads its operating system, it can take control of the system by using the Boot Service EFI_BOOT_SERVICES.ExitBootServices() . After successfully calling ExitBootServices() , all boot services in the system are terminated, including memory management, and the UEFI OS loader is responsible for the continued operation of the system.

2.1.4. UEFI Drivers¶

UEFI drivers are loaded by the Boot Manager, firmware conforming to this specification, or by other UEFI applications. To load a UEFI driver the firmware allocates enough memory to hold the image, copies the sections within the UEFI driver image to the allocated memory and applies the relocation fix-ups needed. Once done, the allocated memory is set to be the proper type for code and data for the image. Control is then transferred to the UEFI driver’s entry point. When the UEFI driver returns from its entry point, or when it calls the Boot Service EFI_BOOT_SERVICES.ExitBootServices() , the UEFI driver is optionally unloaded from memory and control is returned to the component that loaded the UEFI driver. A UEFI driver is not unloaded from memory if it returns a status code of EFI_SUCCESS . If the UEFI driver’s return code is an error status code, then the driver is unloaded from memory.

There are two types of UEFI drivers: boot service drivers and runtime drivers. The only difference between these two driver types is that UEFI runtime drivers are available after a UEFI OS loader has taken control of the platform with the Boot Service EFI_BOOT_SERVICES.ExitBootServices().

UEFI boot service drivers are terminated when ExitBootServices() is called, and all the memory resources consumed by the UEFI boot service drivers are released for use in the operating system environment.

A runtime driver of type EFI_IMAGE_SUBSYSTEM_EFI_RUNTIME_DRIVER gets fixed up with virtual mappngs when the OS calls SetVirtualAddressMap() .

2.2. Firmware Core¶

This section provides an overview of the services defined by UEFI. These include boot services and runtime services.

2.2.1. UEFI Services¶

The purpose of the UEFI interfaces is to define a common boot environment abstraction for use by loaded UEFI images, which include UEFI drivers, UEFI applications, and UEFI OS loaders. The calls are defined with a full 64-bit interface, so that there is headroom for future growth. The goal of this set of abstracted platform calls is to allow the platform and OS to evolve and innovate independently of one another. Also, a standard set of primitive runtime services may be used by operating systems.

Platform interfaces defined in this section allow the use of standard Plug and Play Option ROMs as the underlying implementation methodology for the boot services. The interfaces have been designed in such as way as to map back into legacy interfaces. These interfaces have in no way been burdened with any restrictions inherent to legacy Option ROMs.

The UEFI platform interfaces are intended to provide an abstraction between the platform and the OS that is to boot on the platform. The UEFI specification also provides abstraction between diagnostics or utility programs and the platform; however, it does not attempt to implement a full diagnostic OS environment. It is envisioned that a small diagnostic OS-like environment can be easily built on top of an UEFI system. Such a diagnostic environment is not described by this specification. Interfaces added by this specification are divided into the following categories and are detailed later in this document:

Runtime services
Boot services interfaces, with the following subcategories:

– Global boot service interfaces

– Device handle-based boot service interfaces

– Device protocols

– Protocol services

2.2.2. Runtime Services¶

This section describes UEFI runtime service functions. The primary purpose of the runtime services is to abstract minor parts of the hardware implementation of the platform from the OS. Runtime service functions are available during the boot process and also at runtime provided the OS switches into flat physical addressing mode to make the runtime call. However, if the OS loader or OS uses the Runtime Service SetVirtualAddressMap() service, the OS will only be able to call runtime services in a virtual addressing mode. All runtime interfaces are non-blocking interfaces and can be called with interrupts disabled if desired.To ensure maximum compatibility with existing platforms it is recommended that all UEFI modules that comprise the Runtime Services be represented in the MemoryMap as a single EFI_MEMORY_DESCRIPTOR of Type EfiRuntimeServicesCode.

In all cases memory used by the runtime services must be reserved and not used by the OS. runtime services memory is always available to an UEFI function and will never be directly manipulated by the OS or its components. UEFI is responsible for defining the hardware resources used by runtime services, so the OS can synchronize with those resources when runtime service calls are made, or guarantee that the OS never uses those resources. See the table below for lists of the Runtime Services functions.

Table 2.2 UEFI Runtime Services¶
Name	Description
GetTime()	Returns the current time, time context, and time keeping capabilities.
SetTime()	Sets the current time and time context.
GetWakeupTime()	Returns the current wakeup alarm settings.
SetWakeupTime()	Sets the current wakeup alarm settings.
GetVariable()	Returns the value of a named variable.
GetNextVariableName()	Enumerates variable names.
SetVariable()	Sets, and if needed creates, a variable.
SetVirtualAddressMap()	Switches all runtime functions from physical to virtual addressing.
ConvertPointer()	Used to convert a pointer from physical to virtual addressing.
Get Next High Monotonic Count	Subsumes the platform’s monotonic counter functionality.
ResetSystem()	Resets all processors and devices and reboots the system.
Update Capsule	Passes capsules to the firmware with both virtual and physical mapping.
QueryCapsuleCapabilities()	Returns if the capsule can be supported via UpdateCapsule().
QueryVariableInfo()	Returns information about the EFI variable store.

2.3. Calling Conventions¶

Unless otherwise stated, all functions defined in the UEFI specification are called through pointers in common, architecturally defined, calling onventions found in C compilers. Pointers to the various global UEFI functions are found in the EFI_RUNTIME_SERVICES and EFI_BOOT_SERVICES tables that are located via the system table. Pointers to other functions defined in this specification are located dynamically through device handles. In all cases, all pointers to UEFI functions are cast with the word EFIAPI . This allows the compiler for each architecture to supply the proper compiler keywords to achieve the needed calling conventions. When passing pointer arguments to Boot Services, Runtime Services, and Protocol Interfaces, the caller has the following responsibilities:

It is the caller’s responsibility to pass pointer parameters that reference physical memory locations. If a pointer is passed that does not point to a physical memory location (i.e., a memory mapped I/O region), the results are unpredictable and the system may halt.
It is the caller’s responsibility to pass pointer parameters with correct alignment. If an unaligned pointer is passed to a function, the results are unpredictable and the system may halt.
It is the caller’s responsibility to not pass in a NULL parameter to a function unless it is explicitly allowed. If a NULL pointer is passed to a function, the results are unpredictable and the system may hang.
Unless otherwise stated, a caller should not make any assumptions regarding the state of pointer parameters if the function returns with an error.
A caller may not pass structures that are larger than native size by value and these structures must be passed by reference (via a pointer) by the caller. Passing a structure larger than native width (4 bytes on supported 32-bit processors; 8 bytes on supported 64-bit processor instructions) on the stack will produce undefined results.

Calling conventions for supported 32-bit and supported 64-bit applications are described in more detail below. Any function or protocol may return any valid return code.

All public interfaces of a UEFI module must follow the UEFI calling convention. Public interfaces include the image entry point, UEFI event handlers, and protocol member functions. The type EFIAPI is used to indicate conformance to the calling conventions defined in this section. Non public interfaces, such as private functions and static library calls, are not required to follow the UEFI calling conventions and may be optimized by the compiler.

2.3.1. Data Types¶

See the table below which lists the common data types that are used in the interface definitions, and the following table, Modifiers for Common UEFI Data Types, lists their modifiers. Unless otherwise specified all data types are naturally aligned. Structures are aligned on boundaries equal to the largest internal datum of the structure and internal data are implicitly padded to achieve natural alignment.

The values of the pointers passed into or returned by the UEFI interfaces must provide natural alignment for the underlying types.

Common UEFI Data Types

Table 2.3 Common UEFI Data Types¶
Mnemonic	Description
BOOLEAN	Logical Boolean. 1-byte value containing a 0 for FALSE or a 1 for TRUE. Other values are undefined.
INTN	Signed value of native width. (4 bytes on supported 32-bit processor instructions, 8 bytes on supported 64-bit processor instructions, 16 bytes on supported 128-bit processor instructions)
UINTN	Unsigned value of native width. (4 bytes on supported 32-bit processor instructions, 8 bytes on supported 64-bit processor instructions, 16 bytes on supported 128-bit processor instructions)
INT8	1-byte signed value.
UINT8	1-byte unsigned value.
INT16	2-byte signed value.
UINT16	2-byte unsigned value.
INT32	4-byte signed value.
UINT32	4-byte unsigned value.
INT64	8-byte signed value.
UINT64	8-byte unsigned value.
INT128	16-byte signed value.
UINT128	16-byte unsigned value.
CHAR8	1-byte character. Unless otherwise specified, all 1-byte or ASCII characters and strings are stored in 8-bit ASCII encoding format, using the ISO-Latin-1 character set.
CHAR16	2-byte Character. Unless otherwise specified all characters and strings are stored in the UCS-2 encoding format as defined by Unicode 2.1 and ISO/IEC 10646 standards.
VOID	Undeclared type.
EFI_GUID	128-bit buffer containing a unique identifier value. Unless otherwise specified, aligned on a 64-bit boundary.
EFI_STATUS	Status code. Type UINTN.
EFI_HANDLE	A collection of related interfaces. Type VOID *.
EFI_EVENT	Handle to an event structure. Type VOID *.
EFI_LBA	Logical block address. Type UINT64.
EFI_TPL	Task priority level. Type UINTN.
EFI_MAC_ADDRESS	32-byte buffer containing a network Media Access Control address.
EFI_IPv4_ADDRESS	4-byte buffer. An IPv4 internet protocol address.
EFI_IPv6_ADDRESS	16-byte buffer. An IPv6 internet protocol address.
EFI_IP_ADDRESS	16-byte buffer aligned on a 4-byte boundary. An IPv4 or IPv6 internet protocol address.
<Enumerated Type>	Element of a standard ANSI C enum type declaration. Type INT32.or UINT32. ANSI C does not define the size of sign of an enum so they should never be used in structures. ANSI C integer promotion rules make INT32 or UINT32 interchangeable when passed as an argument to a function.
sizeof (VOID *)	4 bytes on supported 32-bit processor instructions. 8 bytes on supported 64-bit processor instructions. 16 bytes on supported 128-bit processor.
Bitfields	Bitfields are ordered such that bit 0 is the least significant bit.

Table 2.4 Modifiers for Common UEFI Data Types¶
Mnemonic	Description
IN	Datum is passed to the function.
OUT	Datum is returned from the function.
OPTIONAL	Passing the datum to the function is optional, and a NULL may be passed if the value is not supplied.
CONST	Datum is read-only.
EFIAPI	Defines the calling convention for UEFI interfaces.

2.3.2. IA-32 Platforms¶

All functions are called with the C language calling convention. The general-purpose registers that are volatile across function calls are eax, ecx, and edx. All other general-purpose registers are nonvolatile and are preserved by the target function. In addition, unless otherwise specified by the function definition, all other registers are preserved.

Firmware boot ‘services and runtime services run in the following processor execution mode prior to the OS calling ExitBootServices():

Uniprocessor, as described in chapter 8.4 of:

— Intel 64 and IA-32 Architectures Software Developer’s Manual

— Volume 3, System Programming Guide, Part 1

— Order Number: 253668-033US, December 2009

— See “Links to UEFI-Related Documents” ( http://uefi.org/uefi) under the heading “Intel Processor Manuals.””
Protected mode
Paging mode may be enabled. If paging mode is enabled, PAE (Physical Address Extensions) mode is recommended. If paging mode is enabled, any memory space defined by the UEFI memory map is identity mapped (virtual address equals physical address). The mappings to other regions are undefined and may vary from implementation to implementation.
Selectors are set to be flat and are otherwise not used
Interrupts are enabled-though no interrupt services are supported other than the UEFI boot services timer functions (All loaded device drivers are serviced synchronously by “polling.”)
Direction flag in EFLAGs is clear
Other general purpose flag registers are undefined
128 KiB, or more, of available stack space
The stack must be 16-byte aligned. Stack may be marked as non-executable in identity mapped page tables.
Floating-point control word must be initialized to 0x027F (all exceptions masked, double-precision, round-to-nearest)
Multimedia-extensions control word (if supported) must be initialized to 0x1F80 (all exceptions masked, round-to-nearest, flush to zero for masked underflow).
CR0.EM must be zero
CR0.TS must be zero

An application written to this specification may alter the processor execution mode, but the UEFI image must ensure firmware boot services and runtime services are executed with the prescribed execution environment.

After an Operating System calls ExitBootServices() , firmware boot services are no longer available and it is illegal to call any boot service. After ExitBootServices, firmware runtime services are still available and may be called with paging enabled and virtual address pointers if SetVirtualAddressMap() has been called describing all virtual address ranges used by the firmware runtime service. For an operating system to use any UEFI runtime services, it must:

Preserve all memory in the memory map marked as runtime code and runtime data
Call the runtime service functions, with the following conditions:

— In protected mode

— Paging may or may not be enabled, however if paging is enabled and SetVirtualAddressMap() has not been called, any memory space defined by the UEFI memory map is identity mapped (virtual address equals physical address), although the attributes of certain regions may not have all read, write, and execute attributes or be unmarked for purposes of platform protection. The mappings to other regions are undefined and may vary from implementation to implementation. See description of SetVirtualAddressMap() for details of memory map after this function has been called.

— Direction flag in EFLAGs clear

— 4 KiB, or more, of available stack space

— The stack must be 16-byte aligned

— Floating-point control word must be initialized to 0x027F (all exceptions masked, double-precision, round-to-nearest)

— Multimedia-extensions control word (if supported) must be initialized to 0x1F80 (all exceptions masked, round-to-nearest, flush to zero for masked underflow)

— CR0.EM must be zero

— CR0.TS must be zero

— Interrupts disabled or enabled at the discretion of the caller
ACPI Tables loaded at boot time can be contained in memory of type EfiACPIReclaimMemory (recommended) or EfiACPIMemoryNVS . ACPI FACS must be contained in memory of type EfiACPIMemoryNVS.
The system firmware must not request a virtual mapping for any memory descriptor of type EfiACPIReclaimMemory or EfiACPIMemoryNVS .
EFI memory descriptors of type EfiACPIReclaimMemory and EfiACPIMemoryNVS must be aligned on a 4 KiB boundary and must be a multiple of 4 KiB in size.
Any UEFI memory descriptor that requests a virtual mapping via the EFI_MEMORY_DESCRIPTOR having the EFI_MEMORY_RUNTIME bit set must be aligned on a 4 KiB boundary and must be a multiple of 4 KiB in size.
An ACPI Memory Op-region must inherit cacheability attributes from the UEFI memory map. If the system memory map does not contain cacheability attributes, the ACPI Memory Op-region must inherit its cacheability attributes from the ACPI name space. If no cacheability attributes exist in the system memory map or the ACPI name space, then the region must be assumed to be non-cacheable.
ACPI tables loaded at runtime must be contained in memory of type EfiACPIMemoryNVS . The cacheability attributes for ACPI tables loaded at runtime should be defined in the UEFI memory map. If no information about the table location exists in the UEFI memory map, cacheability attributes may be obtained from ACPI memory descriptors. If no information about the table location exists in the UEFI memory map or ACPI memory descriptors, the table is assumed to be non-cached.
In general, UEFI Configuration Tables loaded at boot time (e.g., SMBIOS table) can be contained in memory of type EfiRuntimeServicesData (recommended), EfiBootServicesData , EfiACPIReclaimMemory or EfiACPIMemoryNVS . Tables loaded at runtime must be contained in memory of type EfiRuntimeServicesData (recommended) or EfiACPIMemoryNVS .

Note: Previous EFI specifications allowed ACPI tables loaded at runtime to be in the EfiReservedMemoryType and there was no guidance provided for other EFI Configuration Tables. EfiReservedMemoryType is not intended to be used for the storage of any EFI Configuration Tables. Also, only OSes conforming to the UEFI Specification are guaranteed to handle SMBIOS table in memory of type EfiBootServicesData.

2.3.2.1. Handoff State¶

When a 32-bit UEFI OS is loaded, the system firmware hands off control to the OS in flat 32-bit mode. All descriptors are set to their 4GiB limits so that all of memory is accessible from all segments.

The Figure below (Stack After AddressOfEntryPoint Called, IA-32 )shows the stack after AddressOfEntryPoint in the image’s PE32+ header has been called on supported 32-bit systems. All UEFI image entry points take two parameters. These are the image handle of the UEFI image, and a pointer to the EFI System Table.

Fig. 2.2 Stack After AddressOfEntryPoint Called, IA-32¶

2.3.2.2. Calling Convention¶

All functions are called with the C language calling convention. The general-purpose registers that are volatile across function calls are eax , ecx , and edx . All other general-purpose registers are nonvolatile and are preserved by the target function.

In addition, unless otherwise specified by the function definition, all other CPU registers (including MMX and XMM) are preserved.

The floating point status register is not preserved by the target function. The floating point control register and MMX control register are saved by the target function.

If the return value is a float or a double, the value is returned in ST(0).

2.3.3. Intel^®Itanium^®-Based Platforms¶

UEFI executes as an extension to the SAL execution environment with the same rules as laid out by the SAL specification.

During boot services time the processor is in the following execution mode:

Uniprocessor, as detailed in chapter 13.1.2 of:

— Intel Itanium Architecture Software Developer’s Manual

— Volume 2: System Architecture

— Revision 2.2

— January 2006

— See “Links to UEFI-Related Documents” ( http://uefi.org/uefi) under the heading “Intel Itanium Documentation”.

— Document Number: 245318-005
Physical mode
128 KiB, or more, of available stack space
16 KiB, or more, of available backing store space

— FPSR.traps: Set to all 1’s (all exceptions disabled)

— FPSR.sf0:
.pc: Precision Control - 11b (extended precision)
.rc: Rounding Control - 0 (round to nearest)
.wre: Widest Range Exponent - 0 (IEEE mode)
.ftz: Flush-To-Zero mode - 0 (off)

— FPSR.sf1:
.td: Traps Disable = 1 (traps disabled)
.pc: Precision Control - 11b (extended precision)
.rc: Rounding Control - 0 (round to nearest)
wreWidest Range Exponent - 1 (full register exponent range)
ftz Flush-To-Zero mode - 0 (off)

— FPSR.sf2,3:
.td Traps Disable = 1 (traps disabled)
pc: Precision Control - 11b (extended precision)
.rc: Rounding Control - 0 (round to nearest)
.wre: Widest Range Exponent - 0 (IEEE mode)
.ftz: Flush-To-Zero mode - 0 (off)

An application written to this specification may alter the processor execution mode, but the UEFI image must ensure firmware boot services and runtime services are executed with the prescribed execution environment.

After an Operating System calls ExitBootServices(), firmware boot services are no longer available and it is illegal to call any boot service. After ExitBootServices, firmware runtime services are still available When calling runtime services, paging may or may not be enabled, however if paging is enabled and SetVirtualAddressMap() has not been called, any memory space defined by the UEFI memory map is identity mapped (virtual address equals physical address). The mappings to other regions are undefined and may vary from implementation to implementation. See description of SetVirtualAddressMap() for details of memory map after this function has been called. After ExitBootServices(), runtime service functions may be called with interrupts disabled or enabled at the discretion of the caller.

ACPI Tables loaded at boot time can be contained in memory of type EfiACPIReclaimMemory (recommended) or EfiACPIMemoryNVS. CPI FACS must be contained in memory of type EfiACPIMemoryNVS.
The system firmware must not request a virtual mapping for any memory descriptor of type EfiACPIReclaimMemory or EfiACPIMemoryNVS.
EFI memory descriptors of type EfiACPIReclaimMemory and EfiACPIMemoryNVS. must be aligned on an 8 KiB boundary and must be a multiple of 8 KiB in size.
Any UEFI memory descriptor that requests a virtual mapping via the EFI_MEMORY_DESCRIPTOR having the EFI_MEMORY_RUNTIME bit set must be aligned on an 8 KiB boundary and must be a multiple of 8 KiB in size.
An ACPI Memory Op-region must inherit cacheability attributes from the UEFI memory map. If the system memory map does not contain cacheability attributes the ACPI Memory Op-region must inherit its cacheability attributes from the ACPI name space. If no cacheability attributes exist in the system memory map or the ACPI name space, then the region must be assumed to be non-cacheable.
ACPI tables loaded at runtime must be contained in memory of type EfiACPIMemoryNVS . The cacheability attributes for ACPI tables loaded at runtime should be defined in the UEFI memory map. If no information about the table location exists in the UEFI memory map, cacheability attributes may be obtained from ACPI memory descriptors. If no information about the table location exists in the UEFI memory map or ACPI memory descriptors, the table is assumed to be non-cached.
In general, Configuration Tables loaded at boot time (e.g., SMBIOS table) can be contained in memory of type EfiRuntimeServicesData (recommended), EfiBootServicesData, EfiACPIReclaimMemory or EfiACPIMemoryNVS. Tables loaded at runtime must be contained in memory of type EfiRuntimeServicesData (recommended) or EfiACPIMemoryNVS.

Note: Previous EFI specifications allowed ACPI tables loaded at runtime to be in the EfiReservedMemoryType and there was no guidance provided for other EFI Configuration Tables. EfiReservedMemoryType is not intended to be used by firmware. Also, only OSes conforming to the UEFI Specification are guaranteed to handle SMBIOS table in memory of type EfiBootServicesData.

Refer to the IA-64 System Abstraction Layer Specification ( Appendix Q — References) for details.

UEFI procedures are invoked using the P64 C calling conventions defined for Intel ® Itanium ® -based applications. Refer to the document 64 Bit Runtime Architecture and Software Conventions for IA-64 ( Appendix Q — References ) for more information.

2.3.3.1. Handoff State¶

UEFI uses the standard P64 C calling conventions that are defined for Itanium-based operating systems. The Figure below shows the stack after ImageEntryPoint has been called on Itanium-based systems. The arguments are also stored in registers: out0 contains EFI_HANDLE and out1 contains the address of the EFI_SYSTEM_TABLE . The gp for the UEFI Image will have been loaded from the plabel pointed to by the AddressOfEntryPoint in the image’s PE32+ header. All UEFI image entry points take two parameters. These are the image handle of the image, and a pointer to the System Table.

Fig. 2.3 Stack after AddressOfEntryPoint Called, Itanium-based Systems¶

The SAL specification ( Appendix Q — References) defines the state of the system registers at boot handoff. The SAL specification also defines which system registers can only be used after UEFI boot services have been properly terminated.

2.3.3.2. Calling Convention¶

UEFI executes as an extension to the SAL execution environment with the same rules as laid out by the SAL specification. UEFI procedures are invoked using the P64 C calling conventions defined for Intel^®Itanium^®-based applications. Refer to the document 64 Bit Runtime Architecture and Software Conventions for IA-64 (see the index appendix for more information).

For floating point, functions may only use the lower 32 floating point registers Return values appear in f8-f15 registers. Single, double, and extended values are all returned using the appropriate format. Registers f6-f7 are local registers and are not preserved for the caller. All other floating point registers are preserved. Note that, when compiling UEFI programs, a special switch will likely need to be specified to guarantee that the compiler does not use f32-f127, which are not normally preserved in the regular calling convention for Itanium. A procedure using one of the preserved floating point registers must save and restore the caller’s original contents without generating a NaT consumption fault.

Floating point arguments are passed in f8-f15 registers when possible. Parameters beyond the registers appear in memory, as explained in Section 8.5 of the Itanium Software Conventions and Runtime Architecture Guide. Within the called function, these are local registers and are not preserved for the caller. Registers f6-f7 are local registers and are not preserved for the caller. All other floating point registers are preserved. Note that, when compiling UEFI programs, a special switch will likely need to be specified to guarantee that the compiler does not use f32-f127, which are not normally preserved in the regular calling convention for Itanium. A procedure using one of the preserved floating point registers must save and restore the caller’s original contents without generating a NaT consumption fault.

The floating point status register must be preserved across calls to a target function. Flags fields in SF1,2,3 are not preserved for the caller. Flags fields in SF0 upon return will reflect the value passed in, and with bits set to 1 corresponding to any IEEE exceptions detected on non-speculative floating-point operations executed as part of the callee.

Floating-point operations executed by the callee may require software emulation. The caller must be prepared to handle FP Software Assist (FPSWA) interruptions. Callees should not raise IEEE traps by changing FPSR.traps bits to 0 and then executing floating-point operations that raise such traps.

2.3.4. x64 Platforms¶

All functions are called with the C language calling convention. Detailed Calling Conventions for more detail.

During boot services time the processor is in the following execution mode:

Uniprocessor, as described in chapter 8.4 of:

— Intel 64 and IA-32 Architectures Software Developer’s Manual, Volume 3, System Programming Guide, Part 1, Order Number: 253668-033US, December 2009

— See “Links to UEFI-Related Documents” ( http://uefi.org/uefi) under the heading “Intel Processor Manuals”.
Long mode, in 64-bit mode
Paging mode is enabled and any memory space defined by the UEFI memory map is identity mapped (virtual address equals physical address), although the attributes of certain regions may not have all read, write, and execute attributes or be unmarked for purposes of platform protection. The mappings to other regions, such as those for unaccepted memory, are undefined and may vary from implementation to implementation.
Selectors are set to be flat and are otherwise not used.
Interrupts are enabled-though no interrupt services are supported other than the UEFI boot services timer functions (All loaded device drivers are serviced synchronously by “polling.”)
Direction flag in EFLAGs is clear
Other general purpose flag registers are undefined
128 KiB, or more, of available stack space
The stack must be 16-byte aligned. Stack may be marked as non-executable in identity mapped page tables.
Floating-point control word must be initialized to 0x037F (all exceptions masked, double-extended-precision, round-to-nearest)
Multimedia-extensions control word (if supported) must be initialized to 0x1F80 (all exceptions masked, round-to-nearest, flush to zero for masked underflow).
CR0.EM must be zero
CR0.TS must be zero

For an operating system to use any UEFI runtime services, it must:

Preserve all memory in the memory map marked as runtime code and runtime data
Call the runtime service functions, with the following conditions:
In long mode, in 64-bit mode
Paging enabled
All selectors set to be flat with virtual = physical address. If the UEFI OS loader or OS used SetVirtualAddressMap() to relocate the runtime services in a virtual address space, then this condition does not have to be met. See description SetVirtualAddressMap() for details of memory map after this function has been called.
Direction flag in EFLAGs clear
4 KiB, or more, of available stack space
The stack must be 16-byte aligned
Floating-point control word must be initialized to 0x037F (all exceptions masked, double-extended-precision, round-to-nearest)
Multimedia-extensions control word (if supported) must be initialized to 0x1F80 (all exceptions masked, round-to-nearest, flush to zero for masked underflow)
CR0.EM must be zero
CR0.TS must be zero
Interrupts may be disabled or enabled at the discretion of the caller.
ACPI Tables loaded at boot time can be contained in memory of type EfiACPIReclaimMemory (recommended) or EfiACPIMemoryNVS . ACPI FACS must be contained in memory of type EfiACPIMemoryNVS .
The system firmware must not request a virtual mapping for any memory descriptor of type EfiACPIReclaimMemory or EfiACPIMemoryNVS .
EFI memory descriptors of type EfiACPIReclaimMemory and EfiACPIMemoryNVS must be aligned on a 4 KiB boundary and must be a multiple of 4 KiB in size.
Any UEFI memory descriptor that requests a virtual mapping via the EFI_MEMORY_DESCRIPTOR having the EFI_MEMORY_RUNTIME bit set must be aligned on a 4 KiB boundary and must be a multiple of 4 KiB in size.
An ACPI Memory Op-region must inherit cacheability attributes from the UEFI memory map. If the system memory map does not contain cacheability attributes, the ACPI Memory Op-region must inherit its cacheability attributes from the ACPI name space. If no cacheability attributes exist in the system memory map or the ACPI name space, then the region must be assumed to be non-cacheable.
ACPI tables loaded at runtime must be contained in memory of type EfiACPIMemoryNVS . The cacheability attributes for ACPI tables loaded at runtime should be defined in the UEFI memory map. If no information about the table location exists in the UEFI memory map, cacheability attributes may be obtained from ACPI memory descriptors. If no information about the table location exists in the UEFI memory map or ACPI memory descriptors, the table is assumed to be non-cached.
In general, UEFI Configuration Tables loaded at boot time (e.g., SMBIOS table) can be contained in memory of type EfiRuntimeServicesData (recommended), EfiBootServicesData , EfiACPIReclaimMemory or EfiACPIMemoryNVS . Tables loaded at runtime must be contained in memory of type EfiRuntimeServicesData (recommended) or EfiACPIMemoryNVS.

Note: Previous EFI specifications allowed ACPI tables loaded at runtime to be in the EfiReservedMemoryType and there was no guidance provided for other EFI Configuration Tables. EfiReservedMemoryType is not intended to be used by firmware. Also, only OSes conforming to the UEFI Specification are guaranteed to handle SMBIOS table in memory of type EfiBootServicesData.

2.3.4.1. Handoff State¶

Rcx - EFI_HANDLE

Rdx - EFI_SYSTEM_TABLE*

RSP - <return address>

2.3.4.2. Detailed Calling Conventions¶

The caller passes the first four integer arguments in registers. The integer values are passed from left to right in Rcx, Rdx, R8, and R9 registers. The caller passes arguments five and above onto the stack. All arguments must be right-justified in the register in which they are passed. This ensures the callee can process only the bits in the register that are required.

The caller passes arrays and strings via a pointer to memory allocated by the caller. The caller passes structures and unions of size 8, 16, 32, or 64 bits as if they were integers of the same size. The caller is not allowed to pass structures and unions of other than these sizes and must pass these unions and structures via a pointer.

The callee must dump the register parameters into their shadow space if required. The most common requirement is to take the address of an argument.

If the parameters are passed through varargs then essentially the typical parameter passing applies, including spilling the fifth and subsequent arguments onto the stack. The callee must dump the arguments that have their address taken.

Return values that fix into 64-bits are returned in the Rax register. If the return value does not fit within 64-bits, then the caller must allocate and pass a pointer for the return value as the first argument, Rcx. Subsequent arguments are then shifted one argument to the right, so for example argument one would be passed in Rdx. User-defined types to be returned must be 1,2,4,8,16,32, or 64 bits in length.

The registers Rax, Rcx Rdx R8, R9, R10, R11, and XMM0-XMM5 are volatile and are, therefore, destroyed on function calls.

The registers RBX, RBP, RDI, RSI, R12, R13, R14, R15, and XMM6-XMM15 are considered nonvolatile and must be saved and restored by a function that uses them.

Function pointers are pointers to the label of the respective function and don’t require special treatment.

A caller must always call with the stack 16-byte aligned.

For MMX, XMM and floating-point values, return values that can fit into 64-bits are returned through RAX (including MMX types). However, XMM 128-bit types, floats, and doubles are returned in XMM0. The floating point status register is not saved by the target function. Floating-point and double-precision arguments are passed in XMM0 - XMM3 (up to 4) with the integer slot (RCX, RDX, R8, and R9) that would normally be used for that cardinal slot being ignored (see example) and vice versa. XMM types are never passed by immediate value but rather a pointer will be passed to memory allocated by the caller. MMX types will be passed as if they were integers of the same size. Callees must not unmask exceptions without providing correct exception handlers.

In addition, unless otherwise specified by the function definition, all other CPU registers (including MMX and XMM) are preserved.

2.3.4.3. Enabling Paging or Alternate Translations in an Application¶

Boot Services define an execution environment where paging is not enabled (supported 32-bit) or where translations are enabled but mapped virtual equal physical (x64) and this section will describe how to write an application with alternate translations or with paging enabled. Some Operating Systems require the OS Loader to be able to enable OS required translations at Boot Services time.

If a UEFI application uses its own page tables, GDT or IDT, the application must ensure that the firmware executes with each supplanted data structure. There are two ways that firmware conforming to this specification can execute when the application has paging enabled.

Explicit firmware call
Firmware preemption of application via timer event

An application with translations enabled can restore firmware required mapping before each UEFI call. However the possibility of preemption may require the translation enabled application to disable interrupts while alternate translations are enabled. It’s legal for the translation enabled application to enable interrupts if the application catches the interrupt and restores the EFI firmware environment prior to calling the UEFI interrupt ISR. After the UEFI ISR context is executed it will return to the translation enabled application context and restore any mappings required by the application.

2.3.5. AArch32 Platforms¶

All functions are called with the C language calling convention specified in Detailed Calling Convention . In addition, the invoking OSs can assume that unaligned access support is enabled if it is present in the processor.

During boot services time the processor is in the following execution mode:

Unaligned access should be enabled if supported; Alignment faults are enabled otherwise.
Uniprocessor.
A privileged mode.
The MMU is enabled (CP15 c1 System Control Register (SCTLR) SCTLR.M=1) and any RAM defined by the UEFI memory map is identity mapped (virtual address equals physical address). The mappings to other regions are undefined and may vary from implementation to implementation
The core will be configured as follows (common across all processor architecture revisions):
- MMU enabled
- Instruction and Data caches enabled
- Access flag disabled
- Translation remap disabled
- Little endian mode
- Domain access control mechanism (if supported) will be configured to check access permission bits in the page descriptor
- Fast Context Switch Extension (FCSE) must be disabled
This will be achieved by:
- Configuring the CP15 c1 System Control Register (SCTLR) as follows: I=1, C=1, B=0, TRE=0, AFE=0, M=1
- Configuring the CP15 c3 Domain Access Control Register (DACR) to 0x33333333.
- Configuring the CP15 c1 System Control Register (SCTLR), A=1 on ARMv4 and ARMv5, A=0, U=1 on ARMv6 and ARMv7.
The state of other system control register bits is not dictated by this specification.
Implementations of boot services will enable architecturally manageable caches and TLBs i.e., those that can be managed directly using CP15 operations using mechanisms and procedures defined in the ARM Architecture Reference Manual. They should not enable caches requiring platform information to manage or invoke non-architectural cache/TLB lockdown mechanisms
MMU configuration — Implementations must use only 4k pages and a single translation base register. On devices supporting multiple translation base registers, TTBR0 must be used solely. The binding does not mandate whether page tables are cached or un-cached.
- On processors implementing the ARMv4 through ARMv6K architecture definitions, the core is additionally configured to disable extended page tables support, if present.
  
  This will be achieved by configuring the CP15 c1 System Control Register (SCTLR) as follows: XP=0
- On processors implementing the ARMv7 and later architecture definitions, the core will be configured to enable the extended page table format and disable the TEX remap mechanism.
  
  This will be achieved by configuring the CP15 c1 System Control Register (SCTLR) as follows: XP=1, TRE=0
Interrupts are enabled-though no interrupt services are supported other than the UEFI boot services timer functions (All loaded device drivers are serviced synchronously by “polling.”)
128 KiB or more of available stack space

For an operating system to use any runtime services, it must:

Preserve all memory in the memory map marked as runtime code and runtime data
Call the runtime service functions, with the following conditions:
- In a privileged mode.
- The system address regions described by all the entries in the EFI memory map that have the EFI_MEMORY_RUNTIME bit set must be identity mapped as they were for the EFI boot environment. If the OS Loader or OS used SetVirtualAddressMap() to relocate the runtime services in a virtual address space, then this condition does not have to be met. See description of SetVirtualAddressMap() for details of memory map after this function has been called.
- The processor must be in a mode in which it has access to the system address regions specified in the EFI memory map with the EFI_MEMORY_RUNTIME bit set.
- 4 KiB, or more, of available stack space
- Interrupts may be disabled or enabled at the discretion of the caller

An application written to this specification may alter the processor execution mode, but the invoking OS must ensure firmware boot services and runtime services are executed with the prescribed execution environment.

If ACPI is supported:

ACPI Tables loaded at boot time can be contained in memory of type EfiACPIReclaimMemory (recommended) or EfiACPIMemoryNVS. ACPI FACS must be contained in memory of type EfiACPIMemoryNVS
The system firmware must not request a virtual mapping for any memory descriptor of type EfiACPIReclaimMemory or EfiACPIMemoryNVS.
EFI memory descriptors of type EfiACPIReclaimMemory and EfiACPIMemoryNVS must be aligned on a 4 KiB boundary and must be a multiple of 4 KiB in size.
Any UEFI memory descriptor that requests a virtual mapping via the EFI_MEMORY_DESCRIPTOR having the EFI_MEMORY_RUNTIME bit set must be aligned on a 4 KiB boundary and must be a multiple of 4 KiB in size.
An ACPI Memory Op-region must inherit cacheability attributes from the UEFI memory map. If the system memory map does not contain cacheability attributes, the ACPI Memory Op-region must inherit its cacheability attributes from the ACPI name space. If no cacheability attributes exist in the system memory map or the ACPI name space, then the region must be assumed to be non-cacheable.
ACPI tables loaded at runtime must be contained in memory of type EfiACPIMemoryNVS. The cacheability attributes for ACPI tables loaded at runtime should be defined in the UEFI memory map. If no information about the table location exists in the UEFI memory map, cacheability attributes may be obtained from ACPI memory descriptors. If no information about the table location exists in the UEFI memory map or ACPI memory descriptors, the table is assumed to be non-cached.
In general, UEFI Configuration Tables loaded at boot time (e.g., SMBIOS table) can be contained in memory of type EfiRuntimeServicesData (recommended), EfiBootServicesData , EfiACPIReclaimMemory or EfiACPIMemoryNVS. Tables loaded at runtime must be contained in memory of type EfiRuntimeServicesData (recommended) or EfiACPIMemoryNVS.

Note: Previous EFI specifications allowed ACPI tables loaded at runtime to be in the EfiReservedMemoryType and there was no guidance provided for other EFI Configuration Tables. EfiReservedMemoryType is not intended to be used by firmware. Also, only OSes conforming to the UEFI Specification are guaranteed to handle SMBIOS table in memory of type EfiBootServicesData.

2.3.5.1. Handoff State¶

R0 - EFI_HANDLE

R1 - EFI_SYSTEM_TABLE*

R14 - Return Address

2.3.5.2. Enabling Paging or Alternate Translations in an Application¶

Boot Services define a specific execution environment. This section will describe how to write an application that creates an alternative execution environment. Some Operating Systems require the OS Loader to be able to enable OS required translations at Boot Services time, and make other changes to the UEFI defined execution environment.

If a UEFI application uses its own page tables, or other processor state, the application must ensure that the firmware executes with each supplanted functionality. There are two ways that firmware conforming to this specification can execute in this alternate execution environment:

Explicit firmware call
Firmware preemption of application via timer event

An application with an alternate execution environment can restore the firmware environment before each UEFI call. However the possibility of preemption may require the alternate execution-enabled application to disable interrupts while the alternate execution environment is active. It’s legal for the alternate execution environment enabled application to enable interrupts if the application catches the interrupt and restores the EFI firmware environment prior to calling the UEFI interrupt ISR. After the UEFI ISR context is executed it will return to the alternate execution environment enabled application context.

An alternate execution environment created by a UEFI application must not change the semantics or behavior of the MMU configuration created by the UEFI firmware prior to invoking ExitBootServices(), including the bit layout of the page table entries.

After an OS loader calls ExitBootServices() it should immediately configure the exception vector to point to appropriate code.

2.3.5.3. Detailed Calling Convention¶

The base calling convention for the ARM binding is defined here:

Procedure Call Standard for the ARM Architecture V2.06 (or later)

See “Links to UEFI-Related Documents” (http://uefi.org/uefi) under the heading “Arm Architecture Base Calling Convention”.

This binding further constrains the calling convention in these ways:

Calls to UEFI defined interfaces must be done assuming that the target code requires the ARM instruction set state. Images are free to use other instruction set states except when invoking UEFI interfaces.
Floating point, SIMD, vector operations and other instruction set extensions must not be used.
Only little endian operation is supported.
The stack will maintain 8 byte alignment as described in the AAPCS for public interfaces.
Use of coprocessor registers for passing call arguments must not be used
Structures (or other types larger than 64-bits) must be passed by reference and not by value
The EFI ARM platform binding defines register r9 as an additional callee-saved variable register.

2.3.6. AArch64 Platforms¶

AArch64 UEFI will only execute 64-bit ARM code, as the ARMv8 architecture does not allow for the mixing of 32-bit and 64-bit code at the same privilege level.

All functions are called with the C language calling convention specified in Detailed calling Convention section below. During boot services only a single processor is used for execution. All secondary processors must be either powered off or held in a quiescent state.

The primary processor is in the following execution mode:

Unaligned access must be enabled.
Use the highest 64 bit non secure privilege level available; Non-secure EL2 (Hyp) or Non-secure EL1(Kernel).
The MMU is enabled and any RAM defined by the UEFI memory map is identity mapped (virtual address equals physical address). The mappings to other regions are undefined and may vary from implementation to implementation
The core will be configured as follows:
- MMU enabled
- Instruction and Data caches enabled
- Little endian mode
- Stack Alignment Enforced
- NOT Top Byte Ignored
- Valid Physical Address Space
- 4K Translation Granule

This will be achieved by:

Configuring the System Control Register SCTLR_EL2 or SCTLR_EL1:

EE=0, I=1, SA=1, C=1, A=0, M=1

Configuring the appropriate Translation Control Register:

TCR_EL2
- TBI=0
- PS must contain the valid Physical Address Space Size.
- TG0=00
TCR_EL1
- TBI0=0
- IPS must contain the valid Intermediate Physical Address Space Size.
- TG0=00

Note: The state of other system control register bits is not dictated by this specification.

All floating point traps and exceptions will be disabled at the relevant exception levels (FPCR=0, CPACR_EL1.FPEN=11, CPTR_EL2.TFP=0). This implies that the FP unit will be enabled by default.
Implementations of boot services will enable architecturally manageable caches and TLBs i.e., those that can be managed directly using implementation independent registers using mechanisms and procedures defined in the ARM Architecture Reference Manual. They should not enable caches requiring platform information to manage or invoke non-architectural cache/TLB lockdown mechanisms.
MMU configuration: Implementations must use only 4k pages and a single translation base register. On devices supporting multiple translation base registers, TTBR0 must be used solely. The binding does not mandate whether page tables are cached or un-cached.
Interrupts are enabled, though no interrupt services are supported other than the UEFI boot services timer functions (All loaded device drivers are serviced synchronously by “polling”). All UEFI interrupts must be routed to the IRQ vector only.
The architecture generic timer must be initialized and enabled. The Counter Frequency register (CNTFRQ) must be programmed with the timer frequency. Timer access must be provided to non-secure EL1 and EL0 by setting bits EL1PCTEN and EL1PCEN in register CNTHCTL_EL2.
The system firmware is not expected to initialize EL2 registers that do not have an architectural reset value, except in cases where firmware itself is running at EL2 and needs to do so.
128 KiB or more of available stack space
The ARM architecture allows mapping pages at a variety of granularities, including 4KiB and 64KiB. If a 64KiB physical page contains any 4KiB page with any of the following types listed below, then all 4KiB pages in the 64KiB page must use identical ARM Memory Page Attributes (as described in Map: EFI Cacheability Attributes to AArch64Memory Types ):

– EfiRuntimeServicesCode

– EfiRuntimeServicesData

– EfiReserved

– EfiACPIMemoryNVS

Mixed attribute mappings within a larger page are not allowed.

Note: This constraint allows a 64K paged based Operating System to safely map runtime services memory.

For an operating system to use any runtime services, Runtime services must:

Support calls from either the EL1 or the EL2 exception levels.
Once called, simultaneous or nested calls from EL1 and EL2 are not permitted.

Note: Sequential, non-overlapping, calls from EL1 and EL2 are permitted.

Runtime services are permitted to make synchronous SMC and HVC calls into higher exception levels.

Note: These rules allow Boot Services to start at EL2, and Runtime services to be assigned to an EL1 Operating System. In this case a call to SetVirtualAddressMap()is expected to provided an EL1 appropriate set of mappings.

For an operating system to use any runtime services, it must:

Enable unaligned access support.
Preserve all memory in the memory map marked as runtime code and runtime data
Call the runtime service functions, with the following conditions:
- From either EL1 or EL2 exception levels.
- Consistently call runtime services from the same exception level. Sharing of runtime services between different exception levels is not permitted.
- Runtime services must only be assigned to a single operating system or hypervisor. They must not be shared between multiple guest operating systems.
- The system address regions described by all the entries in the EFI memory map that have the EFI_MEMORY_RUNTIME bit set must be identity mapped as they were for the EFI boot environment. If the OS Loader or OS used SetVirtualAddressMap() to relocate the runtime services in a virtual address space, then this condition does not have to be met. See description of SetVirtualAddressMap() for details of memory map after this function has been called.
- The processor must be in a mode in which it has access to the system address regions specified in the EFI memory map with the EFI_MEMORY_RUNTIME bit set.
- 8 KiB, or more, of available stack space.
- The stack must be 16-byte aligned (128-bit).
- Interrupts may be disabled or enabled at the discretion of the caller.

An application written to this specification may alter the processor execution mode, but the invoking OS must ensure firmware boot services and runtime services are executed with the prescribed execution environment.

If ACPI is supported :

ACPI Tables loaded at boot time can be contained in memory of type EfiACPIReclaimMemory (recommended) or EfiACPIMemoryNVS.
ACPI FACS must be contained in memory of type EfiACPIMemoryNVS. The system firmware must not request a virtual mapping for any memory descriptor of type EfiACPIReclaimMemory or EfiACPIMemoryNVS.
EFI memory descriptors of type EfiACPIReclaimMemory and EfiACPIMemoryNVS must be aligned on a 4 KiB boundary and must be a multiple of 4 KiB in size.
Any UEFI memory descriptor that requests a virtual mapping via the EFI_MEMORY_DESCRIPTOR having the EFI_MEMORY_RUNTIME bit set must be aligned on a 4 KiB boundary and must be a multiple of 4 KiB in size.
An ACPI Memory Op-region must inherit cacheability attributes from the UEFI memory map. If the system memory map does not contain cacheability attributes, the ACPI Memory Op-region must inherit its cacheability attributes from the ACPI name space. If no cacheability attributes exist in the system memory map or the ACPI name space, then the region must be assumed to be non-cacheable.
ACPI tables loaded at runtime must be contained in memory of type EfiACPIMemoryNVS. The cacheability attributes for ACPI tables loaded at runtime should be defined in the UEFI memory map. If no information about the table location exists in the UEFI memory map, cacheability attributes may be obtained from ACPI memory descriptors. If no information about the table location exists in the UEFI memory map or ACPI memory descriptors, the table is assumed to be non-cached.
In general, UEFI Configuration Tables loaded at boot time (e.g., SMBIOS table) can be contained in memory of type EfiRuntimeServicesData (recommended), EfiBootServicesdata , EfiACPIReclaimMemory or EfiACPIMemoryNVS. Tables loaded at runtime must be contained in memory of type EfiRuntimeServicesData (recommended) or EfiACPIMemoryNVS.

Note: Previous EFI specifications allowed ACPI tables loaded at runtime to be in the EfiReservedMemoryType and there was no guidance provided for other EFI Configuration Tables. EfiReservedMemoryType is not intended to be used by firmware. UEFI 2.0 clarified the situation moving forward. Also, only OSes conforming to UEFI Specification are guaranteed to handle SMBIOS table in memory of type EfiBootServiceData.

2.3.6.1. Memory types¶

Table 2.5 Map: EFI Cacheability Attributes to AArch64Memory Types¶
EFI Memory Type	ARM Memory Type: MAIR attribute encoding Attr<n> [7:4] [3:0]	ARM Memory Type: Meaning
EFI_MEMORY_UC (Not cacheable)	0000 0000	Device-nGnRnE (Device non-Gathering, non-Reordering, no Early Write Acknowledgement)
EFI_MEMORY_WC (Write combine)	0100 0100	Normal Memory Outer non-cacheable Inner non-cacheable
EFI_MEMORY_WT (Write through)	1011 1011	Normal Memory Outer Write-through non-transient Inner Write-through non-transient
EFI_MEMORY_WB (Write back)	1111 1111	Normal Memory Outer Write-back non-transient Inner Write-back non-transient
EFI_MEMORY_UCE		Not used or defined

Table 2.6 Map: UEFI Permission Attributes to ARM Paging Attributes¶
EFI Memory Type	ARM Paging Attributes
EFI_MEMORY_XP	EL2 translation regime: XN Execute never EL1/0 translation regime: UXN Unprivileged execute never PXN Privileged execute never
EFI_MEMORY_RO	Read only access AP[2]=1
EFI_MEMORY_RP EFI_MEMORY_WP	Not used or defined

2.3.6.2. Handoff State¶

X0 - EFI_HANDLE

X1 - EFI_SYSTEM_TABLE

X30 - Return Address

2.3.6.3. Enabling Paging or Alternate Translations in an Application¶

Boot Services define a specific execution environment. This section will describe how to write an application that creates an alternative execution environment. Some Operating Systems require the OS Loader to be able to enable OS required translations at Boot Services time, and make other changes to the UEFI defined execution environment.

If a UEFI application uses its own page tables, or other processor state, the application must ensure that the firmware executes with each supplanted functionality. There are two ways that firmware conforming to this specification can execute in this alternate execution environment:

Explicit firmware call
Firmware preemption of application via timer event

An application with an alternate execution environment can restore the firmware environment before each UEFI call. However the possibility of preemption may require the alternate execution-enabled application to disable interrupts while the alternate execution environment is active. It’s legal for the alternate execution environment enabled application to enable interrupts if the application catches the interrupt and restores the EFI firmware environment prior to calling the UEFI interrupt ISR. After the UEFI ISR context is executed it will return to the alternate execution environment enabled application context.

An alternate execution environment created by a UEFI application must not change the semantics or behavior of the MMU configuration created by the UEFI firmware prior to invoking ExitBootServices(), including the bit layout of the page table entries.

After an OS loader calls ExitBootServices() it should immediately configure the exception vector to point to appropriate code.

2.3.6.4. Detailed Calling Convention¶

The base calling convention for the AArch64 binding is defined in the document Procedure Call Standard for the ARM 64-bit Architecture Version A-0.06 (or later):

See “Links to UEFI-Related Documents” ( http://uefi.org/uefi) under the heading “ARM 64-bit Base Calling Convention”

This binding further constrains the calling convention in these ways:

The AArch64 execution state must not be modified by the callee.
All code exits, normal and exceptional, must be from the A64 instruction set.
Floating point and SIMD instructions may be used.
Optional vector operations and other instruction set extensions may only be used:
- After dynamically checking for their existence.
- Saving and then later restoring any additional execution state context.
- Additional feature enablement or control, such as power, must be explicitly managed.
Only little endian operation is supported.
The stack will maintain 16 byte alignment.
Structures (or other types larger than 64-bits) must be passed by reference and not by value.
The EFI AArch64 platform binding defines the platform register (r18) as “do not use”. Avoiding use of r18 in firmware makes the code compatible with both a fixed role for r18 defined by the OS platform ABI and the use of r18 by the OS and its applications as a temporary register.

2.3.7. RISC-V Platforms¶

All functions are called with the C language calling convention. See Detailed Calling Convention for more detail. On RISC-V platform, three privileged levels are currently introduced in RISC-V architecture. Beyond the User privilege, Supervisor privilege and Machine privileges cover all aspects of RISC-V system. The privileged instructions are also defined in each privilege level.

Table 2.7 RISC-V Platforms¶
Level	Encoding	Name	Abbreviation
0	0	User/Application	U
1	1	Supervisor	S
2	10	Reserved
3	11	Machine	M

A RISC-V platform can contain one or more RISC-V cores and other components such as physical memory, fixed-function accelerators and I/O devices. The term RISC-V core refers to a component which contains an independent instruction fetch unit. A RISC-V core may have multiple RISC-V-compatible hardware threads, or hart. RISC-V UEFI firmware could be executed in either Machine mode or Supervisor mode during the entire POST, according to the hart capability and the platform design. However, RISC-V UEFI firmware has to switch the boot hart to Supervisor mode at either early or late POST if the platform is designed to boot a Supervisor mode OS or OS loader.

The machine mode has the highest privilege and this mode is the only mandatory privilege level for RISC-V platforms; all other privilege levels are optional depending on the platform requirements. Machine mode is the initial privelege mode entered at the power-on reset. This level is used in UEFI for low-level access to a hardware platform.

UEFI firmware implementation may provide the Supervisor Binary Interface (SBI) to allow the Supervisor mode execution environment to invoke privileged functions or access privileged hardware.

The processor is in the following execution mode during boot service:

Total 32 general-purpose registers x1-x31. Register x0 is hardwired to 0. Each register has its ABI (Application Binary Interface) name. See Detailed Calling Convention for more detail.
The width of the native base integer depends on the RISC-V privileged mode implementation. XLEN is a general term which used to refer the width of base integer in bits.

— For the Base Integer ISA in 32-bit width, XLEN = 32

— For the Base Integer ISA in 64-bit width, XLEN = 64

— For the Base Integer ISA in 128-bit width, XLEN = 128
The width of processor registers could be determined by placing the immediate 4 in a register then shifting the register left by 31 bits at a time. If zero after one shift, then the machine is RV32. If zero after two shifts, then the machine is RV64, else RV128.
Processor reset vector is platform specified. In UEFI, it is configured to the platform implementation-defined reset vector. The reset vector address is the first instruction which fetched by RISC-V processor when the power-on reset.
The mcause value after reset have implementation-speciﬁc interpretation, value 0 should be returned on implementations that do not distinguish diﬀerent reset conditions. Implementations that distinguish diﬀerent reset conditions should only use 0 to indicate the most complete reset (e.g., hard reset). The causes of reset could be power-on reset, external hard reset, brownout detected, watchdog timer elapse, sleep-mode wakeup, etc., which machine-mode UEFI system firmware has to distinguish.
The mstatus.xIE indicates the current processor interrupt activation in current privilege mode.

— mstatus.MIE is set to one while mstatus.SIE and mstatus.UIE are set to zero during early UEFI POST stage.
The machine mode interrupt is enabled during boot service in UEFI. Two kinds of interrupts are enabled, one is for timer interrupt and another is software interrupt.
mie.MSIE = 1
mie.MTIE = 1
The memory is in physical addressing mode. Page is disabled in RISC-V machine mode during UEFI boot service.
I/O access is through memory map I/O.
Only support Machine level Control and Status Registers (CSRs) in UEFI.
Machine ISA (misa) register contains the information regarding to the capabilities of CPU implementation. The misa.MXL field encodes the native base integer ISA width in machine mode. MXLEN (Machine XLEN) is given by setting of misa.MXL.

— misa.MXL = 1, MXLEN is 32 bit

— misa.MXL = 2, MXLEN is 64 bit

— misa.MXL = 3, MXLEN is 128 bit
RISC-V processor supports extensive customization and specialization instruction sets. RISC-V variations provide various purposes of processor implementations and the processor capability is reported in the extension bits in misa register. UEFI drivers will need to know the capabilities of processor before executing the specified RISC-V extension instructions. The extensions fields encodes the presence of the standard extensions, with a single bit per letter of the alphabet. (Bit 0 encodes presence of extension “A”, Bit 1 encodes presence of extension “B” and so on. Currently the single letter extension mnemonics are as below,

— A - Atomic extension

— B - Tentatively reserved for Bit operations extension

— C - Compressed extension

— D - Double-Precision Floating-Point extension

— E - Reduced Register Set Indicator RV32E (16 registers)

— F - Single-Precision Floating-Point extension

— G - Additional standard extensions present

— H - Hypervisor extension

— I - RV32I/64I/128I base ISA

— J - Tentatively reserved for Dynamically Translated Languages extension

— K - Reserved

— L - Tentatively reserved for Decimal Floating-Point extension

— M - Integer Multiplication and Division extension

— N - User-level interrupts supported

— O - Reserved

— P - Tentatively reserved for Packed-SIMD extension

— Q - Quad-Precision Floating-Point extension

— S - Supervisor mode implemented

— T - Tentatively reserved for Transactional Memory extension

— U - User mode implemented

— V - Tentatively reserved for Vector extension

— W - Reserved

— X - Non-standard extension present

— Y - Reserved

— Z - Reserved

— Zifenci - Instruction-Fetch Fence

— Zicsr - Control and Status Register Access
Machine Vendor ID Register

— The mvendorid is a 32-bit read-only register encoding the manufacture of the part. Value of 0 indicates this field is not implemented or this is a non-commercial implementation.
Machine Architecture ID Register

— The marchid is an MXLEN-bit read-only register encoding the base microarchitecture of the hart. The combination of mvendorid and marchid should uniquely identify the type of hart microarchitecture that is implemented.
Machine Implementation ID Register

— This provides a unique encoding of the version of processor implementation.

An application written to this specification may alter the processor execution mode, but the UEFI image must ensure firmware boot services and runtime services are executed with the prescribed execution environment.

After an Operating System calls ExitBootServices (), firmware boot services are no longer available and it is illegal to call any boot service. After ExitBootServices, firmware runtime services are still available and may be called with paging enabled and virtual address pointers if SetVirtualAddressMap () has been called describing all virtual address ranges used by the firmware runtime service.

If ACPI is supported:

ACPI Tables loaded at boot time can be contained in memory of type EfiACPIReclaimMemory (recommended) or EfiACPIMemoryNVS. ACPI FACS must be contained in memory of type EfiACPIMemoryNVS
The system firmware must not request a virtual mapping for any memory descriptor of type EfiACPIReclaimMemory or EfiACPIMemoryNVS.
EFI memory descriptors of type EfiACPIReclaimMemory and EfiACPIMemoryNVS must be aligned on a 4 KiB boundary and must be a multiple of 4 KiB in size.
Any UEFI memory descriptor that requests a virtual mapping via the EFI_MEMORY_DESCRIPTOR having the EFI_MEMORY_RUNTIME bit set must be aligned on a 4 KiB boundary and must be a multiple of 4 KiB in size.
An ACPI Memory Op-region must inherit cacheability attributes from the UEFI memory map. If the system memory map does not contain cacheability attributes, the ACPI Memory Op-region must inherit its cacheability attributes from the ACPI name space. If no cacheability attributes exist in the system memory map or the ACPI name space, then the region must be assumed to be non-cacheable.
ACPI tables loaded at runtime must be contained in memory of type EfiACPIMemoryNVS.

The cacheability attributes for ACPI tables loaded at runtime should be defined in the UEFI memory map. If no information about the table location exists in the UEFI memory map, cacheability attributes may be obtained from ACPI memory descriptors. If no information about the table location exists in the UEFI memory map or ACPI memory descriptors, the table is assumed to be non-cached.

In general, UEFI Configuration Tables loaded at boot time (e.g., SMBIOS table) can be contained in memory of type EfiRuntimeServicesData (recommended), EfiBootServicesData, EfiACPIReclaimMemory or EfiACPIMemoryNVS. Tables loaded at runtime must be contained in memory of type EfiRuntimeServicesData (recommended) or EfiACPIMemoryNVS.

Note: Previous EFI specifications allowed ACPI tables loaded at runtime to be in the EfiReservedMemoryType and there was no guidance provided for other EFI Configuration Tables. EfiReservedMemoryType is not intended to be used by firmware. The UEFI Specification intends to clarify the situation moving forward. Also, only OSes conforming to the UEFI Specification are guaranteed to handle SMBIOS table in memory of type EfiBootServicesData.

2.3.7.1. Handoff State¶

When UEFI firmware hands off control to Supervisor mode OS, RISC-V boot hart must be operated in Supervisor mode, and the memory addressing must be operated in Bare mode which is no memory address translation or protection through the virtual page table entry.

In order to describe the heterogeneous RISC-V cores and harts for the next boot stage after POST, UEFI firmware must build up the information of core and hart hardware capabilities in the firmware data structure if the target bootable image requires this information. (e.g. If the platform supports SMBIOS structure, SMBIOS record type 44 record, see “Link to UEFI Specification-Related Document” on https://uefi.org/uefi under the heading “RISC-V Processor SMBIOS Specification”).

UEFI firmware must exposes RISC-V boot hart ID in the firmware data structure to OS:

If platform supports SMBIOS, then SMBIOS type 44 record for the boot hart must have “Boot Hart” set to 1 in “RISC-V Processor-specific Data” structure.
If platform supports Device Tree, the Device Tree must contains a unsigned integer (32bit) property “boot-hartid” under the /chosen node which would indicate the booting hart ID to the supervisor OS.

If the platform supports Device Tree structure to describe the system configurations, the Flattened Device Blob (DTB) must be installed in the EFI Configuration Table (EFI Configuration Table & Properties Table for details).

All UEFI images takes two parameters: the UEFI image handle and the pointer to EFI System Table. According to the RISC-V calling convention, EFI_HANDLE is passed through the a0 register and EFI_SYSTEM_TABLE is passed through the a1 register.

x10: EFI_HANDLE (ABI name: a0)

x11: EFI_SYSTEM_TABLE * (ABI name: a1)

x1: Return Address (ABI name: ra)

2.3.7.2. Data Alignment¶

In the RV32I and RV64I, the datatypes must be aligned at its natural size when stored in memory. The following table describes the datatype and its alignment in RV32I and RV64I in UEFI.

Table 2.8 RV32 datatype alignment¶
Datatype	Description	Alignment
BOOLEAN	Logical Boolean	1
INTN	Signed value in native width.	4
UINTN	Unsigned value in native width.	4
INT8	1-byte signed value	1
UINT8	1-byte unsigned value	1
INT16	2-byte signed value	2
UINT16	2-byte unsigned value	2
INT32	4-byte signed value	4
UINT32	4-byte unsigned value	4
INT64	8-byte signed value	8
UINT64	8-byte unsigned value	8
CHAR8	1-byte character	1
CHAR16	2-byte character	2
VOID	Undeclared type	4

Table 2.9 RV64 datatype alignment¶
Datatype	Description	Alignment
BOOLEAN	Logical Boolean	1
INTN	Signed value in native width.	8
UINTN	Unsigned value in native width.	8
INT8	1-byte signed value	1
UINT8	1-byte unsigned value	1
INT16	2-byte signed value	2
UINT16	2-byte unsigned value	2
INT32	4-byte signed value	4
UINT32	4-byte unsigned value	4
INT64	8-byte signed value	8
UINT64	8-byte unsigned value	8
CHAR8	1-byte character	1
CHAR16	2-byte character	2
VOID	Undeclared type	8

2.3.7.3. Detailed Calling Convention¶

The RISC-V calling convention passes arguments in register when necessary. In RISC-V, total 32 general registers are declared, each register has its corresponding ABI name.

Table 2.10 Register name and ABI name¶
Register	ABI Name	Description
x0	zero	Hardwired to zero
x1	ra	Return address
x2	sp	Stack pointer
x3	gp	Global pointer
x4	tp	Thread pointer
x5-7	t0-2	Temporaries
x8	s0/fp	Saved register/frame pointer
x9	s1	Saved register
x10-11	a0-1	Function arguments/Return values
x12-17	a2-7	Function arguments
x18-27	s2-11	Saved registers
x28-31	t3-6	Temporaries

In the RISC-V calling convention, up to eight integer registers are used for passing argument, a0-a7. a0-a7 are the ABI names and the corresponding registers are x10-x17. Values are returned from functions in integer registers a0 and a1, those are register x10 and x11. In the standard RISC-V calling convention, the stack grows downward and the stack point is always kept 16-byte aligned. Five integer register t0-t6 are temporary registers that are volatile across calls and must be saved by the caller if later used. Twelve integer registers s0-s11 are preserved across calls and must be saved by the callee if used.

In view of the following statement:

“In the standard ABI, procedures should not modify the integer registers tp and gp, because signal handlers may rely upon their values”

mentioned in the RISC-V EFL psABI Specification, and the RISC-V calling convention that gp and tp registers are not assigned a specific owner to save and restore their values (see links below), UEFI firmware must neither trust the values of tp and gp nor make an assumption of owning the write access to these register in any circumstances. (Such as in EFI Boot service, EFI Runtime service, EFI Management Mode service and any UEFI firmware interfaces which may invoked by the EFI drivers, OS or external firmware payload.)

Preserve the values in gp or tp register if UEFI firmware needs to change them, and never touch them after ExitBootServices(). Whether and how to preserve gp and tp in the UEFI firmware environment is implementation-specific.

See Links to UEFI Specification-Related Documents (https://uefi.org/uefi) under the heading “RISC-V EFL psABI Specification”, and the RISC-V assembly programmer’s handbook section in the RISC-V Unprivileged ISA specification.

2.4. Protocols¶

The protocols that a device handle supports are discovered through the EFI_BOOT_SERVICES.HandleProtocol() Boot Service or EFI_BOOT_SERVICES.OpenProtocol() Boot Service. Each protocol has a specification that includes the following:

The protocol’s globally unique ID (GUID)
The Protocol Interface structure
The Protocol Services

Unless otherwise specified a protocol’s interface structure is not allocated from runtime memory and the protocol member functions should not be called at runtime. If not explicitly specified a protocol member function can be called at a TPL level of less than or equal to TPL_NOTIFY ( Event, Timer, and Task Priority Services ). Unless otherwise specified a protocol’s member function is not reentrant or MP safe.

Any status codes defined by the protocol member function definition are required to be implemented, Additional error codes may be returned, but they will not be tested by standard compliance tests, and any software that uses the procedure cannot depend on any of the extended error codes that an implementation may provide.

To determine if the handle supports any given protocol, the protocol’s GUID is passed to HandleProtocol() or OpenProtocol() . If the device supports the requested protocol, a pointer to the defined Protocol Interface structure is returned. The Protocol Interface structure links the caller to the protocol-specific services to use for this device.

The Figue below shows the construction of a protocol. The UEFI driver contains functions specific to one or more protocol implementations, and registers them with the Boot Service, see EFI_BOOT_SERVICES.InstallProtocolInterface(). The firmware returns the Protocol Interface for the protocol that is then used to invoke the protocol specific services. The UEFI driver keeps private, device-specific context with protocol interfaces.

Fig. 2.4 Construction of a Protocol¶

The following C code fragment illustrates the use of protocols:

// There is a global "EffectsDevice" structure. This
// structure contains information  to the device.

// Connect to the ILLUSTRATION_PROTOCOL on the EffectsDevice,
// by calling HandleProtocol with the device’s EFI device handle
// and the ILLUSTRATION_PROTOCOL GUID.

EffectsDevice.Handle = DeviceHandle;
Status = HandleProtocol (
   EffectsDevice.EFIHandle,
   &IllustrationProtocolGuid,
   &EffectsDevice.IllustrationProtocol
   );

// Use the EffectsDevice illustration protocol’s "MakeEffects"
// service to make flashy and noisy effects.

      Status = EffectsDevice.IllustrationProtocol->MakeEffects (
      EffectsDevice.IllustrationProtocol,
      TheFlashyAndNoisyEffect
      );

The Table below, UEFI Protocols , lists the UEFI protocols defined by this specification.

Table 2.11 UEFI Protocols¶
Protocol	Description
EFI Loaded Image Protocol	Provides information on the image.
EFI Loaded Image Device Path Protocol	Specifies the device path that was used when a PE/COFF image was loaded through the EFI Boot Service LoadImage().
EFI Device Path Protocol	Provides the location of the device.
EFI Driver Binding Protocol	Provides services to determine if an UEFI driver supports a given controller, and services to start and stop a given controller.
EFI_DRIVER_FAMILY_OVERRIDE_PROTOCOL	Provides a the Driver Family Override mechanism for selecting the best driver for a given controller.
EFI Platform Driver Override Protocol	Provide a platform specific override mechanism for the selection of the best driver for a given controller.
EFI_BUS_SPECIFIC_DRIVER_OVERRIDE_PROTOCOL	Provides a bus specific override mechanism for the selection of the best driver for a given controller.
EFI_DRIVER_DIAGNOSTICS2_PROTOCOL	Provides diagnostics services for the controllers that UEFI drivers are managing.
EFI_COMPONENT_NAME2_PROTOCOL	Provides human readable names for UEFI Drivers and the controllers that the drivers are managing.
EFI_SIMPLE_TEXT_INPUT_PROTOCOL	Protocol interfaces for devices that support simple console style text input.
EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL	Protocol interfaces for devices that support console style text displaying.
EFI_SIMPLE_POINTER_PROTOCOL	Protocol interfaces for devices such as mice and trackballs.
EFI_SERIAL_IO_PROTOCOL	Protocol interfaces for devices that support serial character transfer.
EFI_LOAD_FILE_PROTOCOL	Protocol interface for reading a file from an arbitrary device.
EFI_LOAD_FILE2_PROTOCOL	Protocol interface for reading a non-boot option file from an arbitrary device
EFI_SIMPLE_FILE_SYSTEM_PROTOCOL	Protocol interfaces for opening disk volume containing a UEFI file system.
EFI_FILE_PROTOCOL	Provides access to supported file systems.
EFI_DISK_IO_PROTOCOL	A protocol interface that layers onto any BLOCK_IO or BLOCK_IO_EX interface.
EFI_BLOCK_IO_PROTOCOL	Protocol interfaces for devices that support block I/O style accesses.
EFI_BLOCK_IO2_PROTOCOL	Protocol interfaces for devices that support block I/O style accesses. This interface is capable of non-blocking transactions.
EFI_UNICODE_COLLATION_PROTOCOL	Protocol interfaces for string comparison operations.
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL	Protocol interfaces to abstract memory, I/O, PCI configuration, and DMA accesses to a PCI root bridge controller.
EFI PCI I/O Protocol	Protocol interfaces to abstract memory, I/O, PCI configuration, and DMA accesses to a PCI controller on a PCI bus.
EFI_USB_IO_PROTOCOL	Protocol interfaces to abstract access to a USB controller.
EFI_SIMPLE_NETWORK_PROTOCOL	Provides interface for devices that support packet based transfers.
EFI_PXE_BASE_CODE_PROTOCOL	Protocol interfaces for devices that support network booting.
EFI_BIS_PROTOCOL	Protocol interfaces to validate boot images before they are loaded and invoked.
EFI_DEBUG_SUPPORT_PROTOCOL	Protocol interfaces to save and restore processor context and hook processor exceptions.
EFI_DEBUGPORT_PROTOCOL	Protocol interface that abstracts a byte stream connection between a debug host and a debug target system.
EFI_DECOMPRESS_PROTOCOL	Protocol interfaces to decompress an image that was compressed using the EFI Compression Algorithm.
EFI_EBC_PROTOCOL	Protocols interfaces required to support an EFI Byte Code interpreter.
EFI_GRAPHICS_OUTPUT_PROTOCOL	Protocol interfaces for devices that support graphical output.
EFI_NVM_EXPRESS_PASS_THRU_PROTOCOL	Protocol interfaces that allow NVM Express commands to be issued to an NVM Express controller.
EFI_EXT_SCSI_PASS_THRU_PROTOCOL	Protocol interfaces for a SCSI channel that allows SCSI Request Packets to be sent to SCSI devices.
EFI_USB2_HC_PROTOCOL	Protocol interfaces to abstract access to a USB Host Controller.
EFI_AUTHENTICATION_INFO_PROTOCOL	Provides access for generic authentication information associated with specific device paths
EFI_DEVICE_PATH_UTILITIES_PROTOCOL	Aids in creating and manipulating device paths.
EFI_DEVICE_PATH_TO_TEXT_PROTOCOL	Converts device nodes and paths to text.
EFI_DEVICE_PATH_FROM_TEXT_PROTOCOL	Converts text to device paths and device nodes.
EFI_EDID_DISCOVERED_PROTOCOL	Contains the EDID information retrieved from a video output device.
EFI_EDID_ACTIVE_PROTOCOL	Contains the EDID information for an active video output device.
EFI_EDID_OVERRIDE_PROTOCOL	Produced by the platform to allow the platform to provide EDID information to the producer of the Graphics Output protocol
EFI iSCSI Initiator Name Protocol	Sets and obtains the iSCSI Initiator Name.
EFI_TAPE_IO_PROTOCOL	Provides services to control and access a tape drive.
EFI Managed Network Protocol	Used to locate communication devices that are supported by an MNP driver and create and destroy instances of the MNP child protocol driver that can use the underlying communications devices.
EFI_ARP_SERVICE_BINDING_PROTOCOL	Used to locate communications devices that are supported by an ARP driver and to create and destroy instances of the ARP child protocol driver.
EFI_ARP_PROTOCOL	Used to resolve local network protocol addresses into network hardware addresses.
EFI_DHCP4_SERVICE_BINDING_PROTOCOL	Used to locate communication devices that are supported by an EFI DHCPv4 Protocol driver and to create and destroy EFI DHCPv4 Protocol child driver instances that can use the underlying communications devices.
EFI_DHCP4_PROTOCOL	Used to collect configuration information for the EFI IPv4 Protocol drivers and to provide DHCPv4 server and PXE boot server discovery services.
EFI_TCP4_SERVICE_BINDING_PROTOCOL	Used to locate EFI TCPv4Protocol drivers to create and destroy child of the driver to communicate with other host using TCP protocol.
EFI_TCP4_PROTOCOL	Provides services to send and receive data stream.
EFI_IP4_SERVICE_BINDING_PROTOCOL	Used to locate communication devices that are supported by an EFI IPv4 Protocol Driver and to create and destroy instances of the EFI IPv4 Protocol child protocol driver that can use the underlying communication device.
EFI_IP4_PROTOCOL	Provides basic network IPv4 packet I/O services.
EFI_IP4_CONFIG2_PROTOCOL	The EFI IPv4 Config Protocol driver performs platform- and policy-dependent configuration of the EFI IPv4 Protocol driver.
EFI_IP4_CONFIG2_PROTOCOL	The EFI IPv4 Configuration II Protocol driver performs platform- and policy-dependent configuration of the EFI IPv4 Protocol driver.
EFI_UDP4_SERVICE_BINDING_PROTOCOL	Used to locate communication devices that are supported by an EFI UDPv4 Protocol driver and to create and destroy instances of the EFI UDPv4 Protocol child protocol driver that can use the underlying communication device.
EFI_UDP4_PROTOCOL	Provides simple packet-oriented services to transmit and receive UDP packets.
EFI_MTFTP4_SERVICE_BINDING_PROTOCOL	Used to locate communication devices that are supported by an EFI MTFTPv4 Protocol driver and to create and destroy instances of the EFI MTFTPv4 Protocol child protocol driver that can use the underlying communication device.
EFI_MTFTP4_PROTOCOL	Provides basic services for client-side unicast or multicast TFTP operations.
EFI_HASH_PROTOCOL	Allows creating a hash of an arbitrary message digest using one or more hash algorithms.
EFI_HASH_SERVICE_BINDING_PROTOCOL	Used to locate hashing services support provided by a driver and create and destroy instances of the EFI Hash Protocol so that a multiple drivers can use the underlying hashing services.
EFI_SD_MMC_PASS_THRU_PROTOCOL	Protocol interface that allows SD/eMMC commands to be sent to an SD/eMMC controller.

2.5. UEFI Driver Model¶

The UEFI Driver Model is intended to simplify the design and implementation of device drivers, and produce small executable image sizes. As a result, some complexity has been moved into bus drivers and in a larger part into common firmware services.

A device driver is required to produce a Driver Binding Protocol on the same image handle on which the driver was loaded. It then waits for the system firmware to connect the driver to a controller. When that occurs, the device driver is responsible for producing a protocol on the controller’s device handle that abstracts the I/O operations that the controller supports. A bus driver performs these exact same tasks. In addition, a bus driver is also responsible for discovering any child controllers on the bus, and creating a device handle for each child controller found.

One assumption is that the architecture of a system can be viewed as a set of one or more processors connected to one or more core chipsets. The core chipsets are responsible for producing one or more I/O buses. The UEFI Driver Model does not attempt to describe the processors or the core chipsets. Instead, the UEFI Driver Model describes the set of I/O buses produced by the core chipsets, and any children of these I/O buses. These children can either be devices or additional I/O buses. This can be viewed as a tree of buses and devices with the core chipsets at the root of that tree.

The leaf nodes in this tree structure are peripherals that perform some type of I/O. This could include keyboards, displays, disks, network, etc. The nonleaf nodes are the buses that move data between devices and buses, or between different bus types. Desktop System shows a sample desktop system with four buses and six devices.

Fig. 2.5 Desktop System¶

Server System is an example of a more complex server system. The idea is to make the UEFI Driver Model simple and extensible so more complex systems like the one below can be described and managed in the preboot environment. This system contains six buses and eight devices.

Fig. 2.6 Server System¶

The combination of firmware services, bus drivers, and device drivers in any given platform is likely to be produced by a wide variety of vendors including OEMs, IBVs, and IHVs. These different components from different vendors are required to work together to produce a protocol for an I/O device than can be used to boot a UEFI compliant operating system. As a result, the UEFI Driver Model is described in great detail in order to increase the interoperability of these components

This remainder of this section is a brief overview of the UEFI Driver Model. It describes the legacy option ROM issues that the UEFI Driver Model is designed to address, the entry point of a driver, host bus controllers, properties of device drivers, properties of bus drivers, and how the UEFI Driver Model can accommodate hot-plug events.

2.5.1. Legacy Option ROM Issues¶

Legacy option ROMs have a number of constraints and limitations that restrict innovation on the part of platform designers and adapter vendors. At the time of writing, both ISA and PCI adapters use legacy option ROMs. For the purposes of this discussion, only PCI option ROMs will be considered; legacy ISA option ROMs are not supported as part of the UEFI Specification .

The following is a list of the major constraints and limitations of legacy option ROMs. For each issue, the design considerations that went into the design of the UEFI Driver Model are also listed. Thus, the design of the UEFI Driver Model directly addresses the requirements for a solution to overcome the limitations implicit to PC-AT-style legacy option ROMs.

2.5.1.1. 32-bit/16-Bit Real Mode Binaries¶

Legacy option ROMs typically contain 16-bit real mode code for an IA-32 processor. This means that the legacy option ROM on a PCI card cannot be used in platforms that do not support the execution of IA-32 real mode binaries. Also, 16-bit real mode only allows the driver to access directly the lower 1 MiB of system memory. It is possible for the driver to switch the processor into modes other than real mode in order to access resources above 1 MiB, but this requires a lot of additional code, and causes interoperability issues with other option ROMs and the system BIOS. Also, option ROMs that switch the processor into to alternate execution modes are not compatible with Itanium Processors.