1. Introduction

1.1. Overview

This specification defines the core code and services that are required for an implementation of the driver execution environment (DXE) phase of the Unified Extensible Firmware Interface (UEFI) Foundation. This DXE core interface specification (CIS) does the following:

  • Describes the basic components of the DXE phase.

  • Provides code definitions for services and functions that are architecturally required by the Unified Extensible Firmware Interface Specification (UEFI 2.0 specification).

  • Presents a set of backward-compatible extensions to the UEFI 2.0 specification.

  • Describes the machine preparation that is required for subsequent phases of firmware execution.

See Organization of the DXE CIS for more information.

1.2. Organization of the DXE CIS

This DXE core interface specification (CIS) is organized as shown in Organization of the DXE CIS. Because the DXE Foundation is just one component of a PI Architecture-based firmware solution, there are a number of additional specifications that are referred to throughout this document.

Table 1.4 Organization of the DXE CIS

Book

Description

Overview

Describes the major components of DXE, including the boot manager, firmware core, protocols, and requirements.

Boot Manager

Describes the boot manager, which is used to load UEFI drivers, UEFI applications, and UEFI OS loaders.

UEFI System Table

Describes the DXE Service table.

Services - Boot Services

Describes specific event types for DXE Foundation.

Runtime Capabilities

Contains definitions of a runtime protocol for status code support.

Services - DXE Services

Contains definitions for the fundamental services that are present in a DXE-compliant system before an OS is booted.

Protocols - Device Path Protocol

Defines the device path extensions required by the DXE Foundation.

DXE Foundation

Describes the DXE Foundation that consumes HOBs, Firmware Volumes, and DXE Architectural Protocols to produce an UEFI System Table, UEFI Boot Services, UEFI Runtime Services, and the DXE Services.

DXE Dispatcher

Describes the DXE Dispatcher that is responsible for loading and executing DXE drivers from Firmware Volumes.

DXE Drivers

Describes the different classes of DXE drivers that may be stored in Firmware Volumes.

DXE Architectural Protocols

Describes the Architectural Protocols that are produced by DXE drivers. They are also consumed by the DXE Foundation to produce the UEFI Boot Services, UEFI Runtime Services, and DXE Services.

DXE Runtime Protocols

Lists success, error, and warning codes returned by DXE and UEFI interfaces.

Dependency Expression Grammar

Describes the BNF grammar for a tool that can convert a text file containing a dependency expression into a dependency section of a DXE driver stored in a Firmware Volume.

1.3. Target Audience

This document is intended for the following readers:

  • IHVs and OEMs who will be implementing DXE drivers that are stored in firmware volumes.

  • BIOS developers, either those who create general-purpose BIOS and other firmware products or those who modify these products for use in various vendor architecture-based products.

1.4. Conventions Used in this Document

This document uses the typographic and illustrative conventions described below.

1.4.1. Data Structure Descriptions

Supported processors are “little endian” machines. This distinction means that the low-order byte of a multibyte data item in memory is at the lowest address, while the high-order byte is at the highest address. Some supported processors may be configured for both “little endian” and “big endian” operation. All implementations designed to conform to this specification will use “little endian” operation.

In some memory layout descriptions, certain fields are marked reserved. Software must initialize such fields to zero and ignore them when read. On an update operation, software must preserve any reserved field.

The data structures described in this document generally have the following format:

STRUCTURE NAME

The formal name of the data structure.

Summary

A brief description of the data structure.

Prototype

A “C-style” type declaration for the data structure.

Parameters

A brief description of each field in the data structure prototype.

Description

A description of the functionality provided by the data structure, including any limitations and caveats of which the caller should be aware.

Related Definitions

The type declarations and constants that are used only by this data structure.

1.4.2. Protocol Descriptions

The protocols described in this document generally have the following format:

Protocol Name

The formal name of the protocol interface.

Summary

A brief description of the protocol interface.

GUID

The 128-bit Globally Unique Identifier (GUID) for the protocol interface.

Protocol Interface Structure

A “C-style” data structure definition containing the procedures and data fields produced by this protocol interface.

Parameters

A brief description of each field in the protocol interface structure.

Description

A description of the functionality provided by the interface, including any limitations and caveats of which the caller should be aware.

Related Definitions

The type declarations and constants that are used in the protocol interface structure or any of its procedures.

1.4.3. Procedure Descriptions

The procedures described in this document generally have the following format:

ProcedureName()

The formal name of the procedure.

Summary

A brief description of the procedure.

Prototype

A “C-style” procedure header defining the calling sequence.

Parameters

A brief description of each field in the procedure prototype.

Description

A description of the functionality provided by the interface, including any limitations and caveats of which the caller should be aware.

Related Definitions

The type declarations and constants that are used only by this procedure.

Status Codes Returned

A description of any codes returned by the interface. The procedure is required to implement any status codes listed in this table. 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.

1.4.4. Instruction Descriptions

A dependency expression instruction description generally has the following format:

InstructionName

The formal name of the instruction.

Syntax

A brief description of the instruction.

Description

A description of the functionality provided by the instruction accompanied by a table that details the instruction encoding.

Operation

Details the operations performed on operands.

Behaviors and Restrictions

An item-by-item description of the behavior of each operand involved in the instruction and any restrictions that apply to the operands or the instruction.

1.4.5. Pseudo-Code Conventions

Pseudo code is presented to describe algorithms in a more concise form. None of the algorithms in this document are intended to be compiled directly. The code is presented at a level corresponding to the surrounding text.

In describing variables, a list is an unordered collection of homogeneous objects. A queue is an ordered list of homogeneous objects. Unless otherwise noted, the ordering is assumed to be First In First Out (FIFO).

Pseudo code is presented in a C-like format, using C conventions where appropriate. The coding style, particularly the indentation style, is used for readability and does not necessarily comply with an implementation of the Unified Extensible Firmware Interface Specification (UEFI 2.0 specification).

1.4.6. Typographic Conventions

This document uses the typographic and illustrative conventions described below:

Plain text

The normal text typeface is used for the vast majority of the descriptive text in a specification.

Plain text (blue)

In the online help version of this specification, any plain text that is underlined and in blue indicates an active link to the cross-reference. Click on the word to follow the hyperlink. Note that these links are not active in the PDF of the specification.

Bold

In text, a Bold typeface identifies a processor register name. In other instances, a Bold typeface can be used as a running head within a paragraph.

Italic

In text, an Italic typeface can be used as emphasis to introduce a new term or to indicate a manual or specification name.

BOLD Monospace

Computer code, example code segments, and all prototype code segments use a BOLD Monospace typeface with a dark red color. These code listings normally appear in one or more separate paragraphs, though words or segments can also be embedded in a normal text paragraph.

Bold Monospace In the online help version of this specification, words in a Bold Monospace typeface that is underlined and in blue indicate an active hyperlink to the code definition for that function or type definition. Click on the word to follow the hyperlink. Note that these links are not active in the PDF of the specification. Also, these inactive links in the PDF may instead have a Bold Monospace appearance that is underlined but in dark red. Again, these links are not active in the PDF of the specification.

Italic Monospace In code or in text, words in Italic Monospace indicate placeholder names for variable information that must be supplied (i.e., arguments).

Plain Monospace In code, words in a Plain Monospace typeface that is a dark red color but is not bold or italicized indicate pseudo code or example code. These code segments typically occur in one or more separate paragraphs.

1.5. Requirements

This document is an architectural specification that is part of the Platform Initialization Architecture (PI Architecture) family of specifications defined and published by the Unified EFI Forum. The primary intent of the PI Architecture is to present an interoperability surface for firmware components that may originate from different providers. As such, the burden to conform to this specification falls both on the producer and the consumer of facilities described as part of the specification.

In general, it is incumbent on the producer implementation to ensure that any facility that a conforming consumer firmware component might attempt to use is present in the implementation. Equally, it is incumbent on a developer of a firmware component to ensure that its implementation relies only on facilities that are defined as part of the PI Architecture. Maximum interoperability is assured when collections of conforming components are designed to use only the required facilities defined in the PI Architecture family of specifications.

As this document is an architectural specification, care has been taken to specify architecture in ways that allow maximum flexibility in implementation for both producer and consumer. However, there are certain requirements on which elements of this specification must be implemented to ensure a consistent and predictable environment for the operation of code designed to work with the architectural interfaces described here.

For the purposes of describing these requirements, the specification includes facilities that are required, such as interfaces and data structures, as well as facilities that are marked as optional.

In general, for an implementation to be conformant with this specification, the implementation must include functional elements that match in all respects the complete description of the required facility descriptions presented as part of the specification. Any part of the specification that is not explicitly marked as “optional” is considered a required facility.

Where parts of the specification are marked as “optional,” an implementation may choose to provide matching elements or leave them out. If an element is provided by an implementation for a facility, then it must match in all respects the corresponding complete description.

In practical terms, this means that for any facility covered in the specification, any instance of an implementation may only claim to conform if it follows the normative descriptions completely and exactly. This does not preclude an implementation that provides additional functionality, over and above that described in the specification. Furthermore, it does not preclude an implementation from leaving out facilities that are marked as optional in the specification.

By corollary, modular components of firmware designed to function within an implementation that conforms to the PI Architecture are conformant only if they depend only on facilities described in this and related PI Architecture specifications. In other words, any modular component that is free of any external dependency that falls outside of the scope of the PI Architecture specifications is conformant. A modular component is not conformant if it relies for correct and complete operation upon a reference to an interface or data structure that is neither part of its own image nor described in any PI Architecture specifications.

It is possible to make a partial implementation of the specification where some of the required facilities are not present. Such an implementation is non-conforming, and other firmware components that are themselves conforming might not function correctly with it. Correct operation of non-conforming implementations is explicitly out of scope for the PI Architecture and this specification.

1.6. Conventions used in this document

1.6.1. Number formats

A binary number is represented in this standard by any sequence of digits consisting of only the Western-Arabic numerals 0 and 1 immediately followed by a lower-case b (e.g., 0101b). Underscores or spaces may be included between characters in binary number representations to increase readability or delineate field boundaries (e.g., 0 0101 1010b or 0_0101_1010b).

A hexadecimal number is represented in this standard by 0x preceding any sequence of digits consisting of only the Western-Arabic numerals 0 through 9 and/or the upper-case English letters A through F (e.g., 0xFA23). Underscores or spaces may be included between characters in hexadecimal number representations to increase readability or delineate field boundaries (e.g., 0xB FD8C FA23 or 0xB_FD8C_FA23).

A decimal number is represented in this standard by any sequence of digits consisting of only the Arabic numerals 0 through 9 not immediately followed by a lower-case b or lower-case h (e.g., 25).

This standard uses the following conventions for representing decimal numbers:

  • the decimal separator (i.e., separating the integer and fractional portions of the number) is a period;

  • the thousands separator (i.e., separating groups of three digits in a portion of the number) is a comma;

  • the thousands separator is used in the integer portion and is not used in the fraction portion of a number.

1.6.2. Binary prefixes

This standard uses the prefixes defined in the International System of Units (SI) (see http://www.bipm.org/en/si/si_brochure/chapter3/prefixes.html) for values that are powers of ten.

Table 1.5 SI prefixes

Factor

Factor

Name

Symbol

103

1,000

kilo

K

106

1,000,000

mega

M

109

1,000,000,000

giga

G

This standard uses the binary prefixes defined in ISO/IEC 80000-13 Quantities and units – Part 13: Information science and technology and IEEE 1514 Standard for Prefixes for Binary Multiples for values that are powers of two.

Table 1.6 Binary prefixes

Factor

Factor

Name

Symbol

210

1,024

kibi

Ki

220

1,048,576

mebi

Mi

230

1,073,741,824

gibi

Gi

For example, 4 KB means 4,000 bytes and 4 KiB means 4,096 bytes.