March 1, 2010
Revision 0.7
i
THIS SPECIFICATION IS PROVIDED "AS IS" WITH NO WARRANTIES WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR ANY PARTICULAR PURPOSE, OR ANY WARRANTY OTHERWISE ARISING OUT OF ANY PROPOSAL, SPECIFICATION OR SAMPLE. Except for a limited copyright license to copy this specification for internal use only, no license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted herein.
Intel disclaims all liability, including liability for infringement of any proprietary rights, relating to implementation
of information in this specification. Intel does not warrant or represent that such implementation(s) will not infringe such rights.
Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them.
This document is an intermediate draft for comment only and is subject to change without notice. Readers should not design products based on this document.
Intel and the Intel logo are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.
*Other names and brands may be claimed as the property of others.
Copyright ? 2008 - 2010 Intel Corporation.
ii March, 2010
Contents
1EDKII Introduction (1)
1.1Overview (1)
1.1.1UEFI and PI (2)
1.1.2EDK & EDKII (2)
1.2Related Information (4)
1.2.1Useful publications and sources of information (4)
1.3Terms (4)
1.4Target Audience (6)
2Setting Up EDKII Development Environment (9)
2.1How to Get the EDKII Source (9)
2.2EDKII Packages (9)
2.3Third-Party Tools (13)
2.3.1Target for IA-32 and Intel64 Processors (13)
2.3.2Target for Intel Itanium Family Processors (IPF) (15)
2.3.3Target for EFI Byte Code (EBC) Image (15)
2.4 A Quick Build (16)
3EDKII Build Process (17)
3.1Basic build steps introduction (17)
3.2Build Configuration (18)
3.2.1Configure the active platform (18)
3.2.2Build command options (19)
3.2.3Configure the build tool chain and flags (20)
3.2.4Configure the build rules (22)
3.3Build Output Directory (22)
3.4Build Single Module (23)
3.4.1Create new Package (24)
3.4.2Add the module into a package (26)
3.4.3Configure the active platform and build module (29)
3.5Build/Customize Existing Platform (29)
3.5.1Build Existing Platform (29)
3.5.2Customize Platform (30)
3.5.3Sum Up: Create Release Tip for a Platform (36)
3.6Common Build Errors (37)
4EDKII Emulation Environment (39)
4.1Overview (39)
4.2Emulation Platforms (39)
4.2.1NT32 platform (39)
4.2.2Unix platform (40)
4.2.3Duet platform (41)
4.3Shell Environment (44)
4.3.1Launch Shell (44)
4.3.2Shell command (48)
iii March, 2010
4.4Enable Network on Nt32 platform (49)
4.5Debugging in Emulation Environment (51)
4.5.1Print Debug Message (51)
4.5.2Single Step Debugging in Nt32 Emulate Platform (52)
4.5.3Single Step Debugging in Unix Emulate Platform (54)
iv March, 2010
FIGURES
Figure 1 Packages Dependency (12)
Figure 2 Startup flow for Duet environment (42)
Figure 3 Select "Boot Manager" Menu (45)
Figure 4 Select "EFI Internal Shell" from "Boot Manager" (45)
Figure 5 Select "Boot Maintenance Manager" from Front Page (46)
Figure 6 Select "Boot From File" menu (47)
Figure 7 Select disk contains "EFI Shell" binary image (47)
Figure 8 Select Shell.efi binary image (48)
Figure 9 EFI network driver layout (50)
Figure 10 Debug/Info message output (52)
Figure 11 INT 3 is triggered (53)
Figure 12 Select System Debugger (53)
Figure 13 Debugger is launched at first break point (54)
v March, 2010
TABLES
Table 1 Microsoft Visual Studio (13)
Table 2 Intel C++ Compiler (13)
Table 3 Microsoft Window Driver Development Kit (DDK) (14)
Table 4 Software Needed by GCC Tool Chain (14)
Table 5 ACPI Compiler (15)
Table 6 Microsoft Visual Studio (15)
Table 7 Intel C++ Compiler for EFI Byte Code Compiler (16)
Table 8 The list of supported tool chain tags (21)
Table 9 Internal shell commands (48)
vi March, 2010
Revision History
Revision Number Description Revision
Date
0.5 Initial
document 09/11/2008 0.6 UnixPkg instruction, and Tools_def.txt updates, plus Run
network under NT32, DUET Unix build and set up, Option
ROM generation, and general editing and formatting
June 9, 2009
0.7 EdkII project website and repository update, plus new core
package introduction, new MDEPKG_NDEBUG build macro,
generic build error info
March 1, 2010
vii March, 2010
viii March, 2010
1
EDKII Introduction This document provides detailed instructions for downloading, configuring and building an EDKII project as well as running EDKII Emulation Environments.
1.1Overview
This chapter describes the features introduced by EDKII project and elaborates the
role played by several key features. This chapter provides readers with a basic understanding on EDKII after reading.
The features introduced by EDKII include:
Minimal unit of distribution.
EDKII introduces the concept of Packages. It is the basic unit of code
release. Compared to EDK, EDK II users can release and work with
"Packages", as opposed to the “Whole Source Tree”.
Different implementations for the same functionality.
EDKII introduces the concept of Library Class/Library Instance. Library
class is a set of standard interfaces for common support routines, and
library instance supplies the implementation of these interfaces. Platform
integrator can select different implementations upon various application
scenarios.
Uniform configuration interface for module writers.
Platform Configuration Database (PCD) is a mechanism that provides
module writers a uniform interface to extract external input information
determined in build time or run time of firmware. This mechanism
standardizes the exposure of platform and module settings that can in-
turn facilitate platform porting.
Cross-architecture and Cross-compiler ability.
EDKII source supports various architectures, such as IA32, X64, IA64, and
various tool-chains, such as Microsoft VC, GNU GCC and Intel ICC. To
support this capability, EDKII offers specific implementations for
architecture-related or compiler-related functions in libraries.
Binary compatibility for pre-PI modules.
The EDKII provides thunk drivers to address the binary compatibility
issues with using existing pre-PI EDK modules in a platform comprised of
mostly EDK II modules.
1
Refined basic APIs (known as Module Development Environment Library).
In EDKII there are many APIs that are refined and appended for module
developers, such as the PCI library, I/O library and Print library, etc.
Enhanced build system.
Its infrastructure is based on Python that is independent of the operating
system. It exposes several configuration files that a user can utilize to
choose the various tool-chains, even the build rule or generated target.
EDKII provides definitions and the library interface required by EDK modules, so it
makes EDK modules that can be integrated into the EDKII.
1.1.1UEFI and PI
The Unified Extensible Firmware Interface (UEFI) Specification defines a group of
standard interfaces between the operating system (OS) and the platform firmware.
UEFI's predecessor was the Extensible Firmware Interface (EFI), originally developed
by Intel. Intel later contributed ownership of the EFI specification to a non-profit,
industry trade organization The Unified EFI Forum, who is now responsible for its
development and promotion.
The UEFI Platform Initialization Specification (also known as the “PI”) is a set of
specifications developed, in conjunction with UEFI, by The Unified EFI Forum. The PI
Specification was preceded by Intel Platform Innovation Framework for EFI (also
known as “the Framework”). While UEFI/EFI specifies the OS-to-firmware interface,
the PI/Framework specification specifies the structure used to build the firmware
beneath the OS-to-firmware interface.
1.1.2EDK & EDKII
The EFI Developer Kit (EDK) is an Open Source release of the Framework
Foundations, defined in the Framework Core Interface Specifications (CIS), plus a set
of sample drivers and three sample targets implemented for the Nt32, Unix, and DUET
platforms. In addition to Open Sourcing the Framework Foundation code, the EDK
allows for the development, debugging, and testing of EFI and DXE drivers, Option
ROMs, and pre-Boot applications.
To solve customer feedback exposed by using EDK, Intel started a remodeling plan
now known as EDKII. It focuses on how to make it easy for customers to write a
specific kind of module, to port and to customize modules to a platform. The following
sections elaborate on several key concepts introduced by EDKII, such as Package,
Library Class/Library Instance and PCD, etc.
1.1.
2.1Package
The EDK could not be compiled without the entire source tree. Furthermore, the unit
of distribution required the EDK as the whole tree. To solve this issue, EDKII
introduced the new concept, the "Package". Using this, a release and its work can be
made with "Packages" as opposed to requiring the “Whole Source Tree”.
2 March, 2010
A package is the minimal unit of distribution—as well as providing a natural split in a
big project—which serves various purposes. For example, from the viewpoint of
hardware a developer may divide CPU/chipset/platform related definitions and drivers
into three individual packages that facilitate a user's distribution and reuse.
Developers also can put all modules that are independent of various platforms into a
single package. Therefore, developers only need focus on platform-specific code when
porting to a new platform.
The EDKII provides a set of packages, which are introduced in next chapter. As some
of the packages are not necessary for building a given module or firmware, Firmware
developers can only choose relevant packages to finish building or releasing.
Additionally, a developer can also create and distribute his or her own package based
on the EDKII code base. For further information, please refer to the EDKII Package
Specification.
1.1.
2.2Library class/Library Instance
Because demand exists for the same functionality in the development of firmware, but
different implementations may be needed, such as:
?using C code to provide cross-architecture ability rather than using assembly
to provide better performance,
?using I/O port to perform PCI configuration cycles but not using memory I/O
instructions.
The Library Class is a set of standard API definitions that are used to provide certain
functionality. A module writer can directly use them to program. A library instance
supplies the implementation of these APIs. The relationship between library class and
library instance is one-to-many. A library class may have multiple implementations,
that is, multiple library instances.
A module only depends on a library class and not concrete implementations, so the
same module source code can be easily configured to link with different library
instances for various requirements.
The EDKII provides many library classes/library instances to facilitate user
development in the MdePkg.
For example, MdePkg provides a library class named BaseMemoryLib, in which there
are many APIs related to memory operation. For this library class there are multiple
library instances, such as the following:
?one implemented in C to cross platform,
?one implemented in ASM to improve the efficiency of memory operation..
The platform integrator can selectively choose various library instances.
1.1.
2.3Platform Configuration Database
PCD is a unified mechanism used by a module to extract information from external
sources and control procedure behavior. The information can come from many
different places. Information could be known
?at compile time,
3 March, 2010
?at flash image generation time,
?on the fly (when firmware code is being executed).
The module writer does not need to know where the information has come from
because the platform developer can make the selection. The module's source code can
remain unchanged to support multiple platforms, as all the external input information
is extracted by unified PCD interfaces.
For example, a PCD, "PcdDebugPrintErrorLevel", is used to control the debug print
level. Thus, a module developer only needs to call the PCD interface PcdGet32
(PcdDebugPrintErrorLevel) to extract its value. The value of the PCD is determined by
a platform configuration in the module build. Various values may cause different
behavior, such as enabling or disabling the display of particular debug print
statements.
1.2Related Information
1.2.1Useful publications and sources of information
Unified Extensible Firmware Interface Specification Version 2.1, The Unified EFI
Forum, Inc, 2007, https://www.doczj.com/doc/9b828722.html,.
Extensible Firmware Interface Specification Version 1.10, Intel, 2001,
https://www.doczj.com/doc/9b828722.html,/technology/efi.
Intel? Platform Innovation Framework for EFI Specifications, Intel, 2006,
https://www.doczj.com/doc/9b828722.html,/technology/framework/.
https://www.doczj.com/doc/9b828722.html, site documentation
https://www.doczj.com/doc/9b828722.html,/projects/edk2/files/
EDK II INF File Specification, Version 1.2, Intel, 2009.
EDK II DSC File Specification, Version 1.2, Intel, 2009.
EDK II DEC File Specification, Version 1.2, Intel, 2009.
EDK II FDF (Flash Description File) File Specification, Version 1,2, Intel, 2009.
EDK II Build Specification, Version 1.2, Intel, 2009.
1.3Terms
The following terms are used throughout this document to describe varying aspects of
input localization:
4 March, 2010
EDK
EFI Developer’s kit, the open source project of the Intel Platform
Innovation Framework for EFI that can be found at
https://www.doczj.com/doc/9b828722.html,/apps/mediawiki/tianocore/index.php?title=EDK . EDK II
A generic term to describe the open source project found at
https://www.doczj.com/doc/9b828722.html,/apps/mediawiki/tianocore/index.php?title=EDK2 .
In this document, it refer to the new release of EDK II which support build
infrastructure that makes use of the Extended INF, DEC and Extended
DSC.
EDK II Module
A generic term to describe a module that is developed using the new
release of EDK II project that supports the library class, library instances,
packaging concept and Extended INF, DEC and Extended DSC files.
EFI
Generic term that refers to one of the versions of the EFI specification: EFI
1.02, EFI 1.10, UEFI
2.1, UEFI 2.2 or UEFI 2.
3.
Framework
Intel? Platform Innovation Framework for EFI consists of the Foundation,
and other modular components that characterize the portability surface for
modular components designed to work on any implementation of the
Tiano architecture.
Library Class
A library class defines the API or interface set for a library. The consumer
of the library is coded to the library class definition. Library classes are
defined via a library class .h file that is published by a package. See the
EDK 2.0 Module Development Environment Library Specification for a list
of libraries defined in this package.
Library Instance
An implementation of one or more library classes. See the EDK 2.0 Module
Development Environment Package Document at
https://www.doczj.com/doc/9b828722.html,/projects/edk2/files/ for a list of library defined in
this package.
Module
A module is either an executable image or a library instance. For a list of
module types supported by this package, see module type.
5 March, 2010
Module Type
All libraries and components belong to one of the following module types:
BASE, SEC, PEI_CORE, PEIM, DXE_CORE, DXE_DRIVER,
DXE_RUNTIME_DRIVER, SMM_CORE, DXE_SMM_DRIVER,
DXE_SAL_DRIVER, UEFI_DRIVER, or UEFI_APPLICATION. These
definitions provide a framework that is consistent with a similar set of
requirements. A module that is of module type BASE, depends only on
headers and libraries provided in the MDE, while a module that is of
module type DXE_DRIVER depends on common DXE components. Package
A package is a container in which a set of modules are organized together
in accordance with certain purpose or rule.
PCD
Platform Configuration Database.
PI
Platform Initialization Specification.
UEFI Application
An application that follows the UEFI specification. The only difference
between a UEFI application and a UEFI driver is that an application is
unloaded from memory when it exits regardless of return status, while a
driver that returns a successful return status is not unloaded when its
entry point exits.
UEFI Driver
A driver that follows the UEFI specification.
UEFI Specification Version 2.1, 2.2 and 2.3
A series of the UEFI specifications released by the Unified EFI Forum.
These specifications build on the EFI 1.10 specification and transfers
ownership of the EFI specification from Intel to a non-profit, industry trade
organization.
Unified EFI Forum
A non-profit collaborative trade organization formed to promote and
manage the UEFI standard. For more information, see https://www.doczj.com/doc/9b828722.html,. 1.4Target Audience
This document is intended to be a reference for those who are just starting EDKII development, for the following:
? IBVs and OEMs who will implement UEFI/PI drivers or other firmware products based on EDKII.
6 March, 2010
? IHVs who will be create supported firmware drivers for hardware device, as well as platform integrators using EDKII components and modules.
7 March, 2010
8 March, 2010
2
Setting Up EDKII Development
Environment This chapter explains how to download the EDKII source code, and introduces the
third-party software needed by the EDKII build process. This chapter also introduces
the basic structure of the EDKII source code and provides a quick start to build and
launch an NT32 emulation platform.
2.1How to Get the EDKII Source
https://www.doczj.com/doc/9b828722.html,
(https://www.doczj.com/doc/9b828722.html,/apps/mediawiki/tianocore/index.php?title=Welcome_to_Tiano
Core ) is the website of the EFI and Framework Open Source Community, where
there are the documentation, source and binaries available. Users may also access the
Forums, Issue Tracking, Mailing Lists, RSS Feeds and Source Control on this website.
The Source Control is Subversion for all projects on this website, including EDKII
project.
There are systematic instructions at
(https://www.doczj.com/doc/9b828722.html,/apps/mediawiki/tianocore/index.php?title=Step-by-
step_instructions ), which help new developers set up their build environment and
build their first EDK II package. The instructions also cover setting up builds for Unix-
like platforms, including building a GCC UEFI cross compiler for EDK II development.
The EDKII source repository is
https://https://www.doczj.com/doc/9b828722.html,/svnroot/edk2/trunk/edk2/.
Before downloading EDKII source, obtain an account on https://www.doczj.com/doc/9b828722.html,.
Please register it at https://https://www.doczj.com/doc/9b828722.html,/account/registration/.
2.2EDKII Packages
EDKII source consists of several packages, shown in the following directories of the
download directory.
BaseTools
Provides the binary build tools and the templates of configuration files for
building. Build tools belong to another project, please visit
https://www.doczj.com/doc/9b828722.html,/apps/mediawiki/tianocore/index.php?title=Edk2-
buildtools to get the source codes of build tools.
9
Conf
Only has one readme.txt file. This directory will be used to contain the
configuration files of building target and compiler parameters used for
building.
MdePkg
Declares PROTOCOLs, PPIs, GUIDs and related data structures defined in
UEFI, EFI, and PI Specifications (https://www.doczj.com/doc/9b828722.html,) and industry
standards. In addition, this package encompasses library instances
defined in Module Development Environment, which provides services for
all the execution phases in the Intel Platform Innovation Framework for
EFI.
MdeModulePkg
Provides a group of modules crossing platforms, based on UEFI, EFI, and
PI Specifications. It also includes the libraries instances serviced for these
modules.
IntelFrameworkPkg
Declares PROTOCOLs, PPIs, GUIDs and related data structures are defined
in Intel Platform Innovation Framework Specification for EFI
(https://www.doczj.com/doc/9b828722.html,/technology/framework/spec.htm). In addition,
this package encompasses library instances based on Intel Platform
Innovation Framework Specification.
IntelFrameworkModulePkg
Provides a group of libraries instances and modules crossing platforms,
based on Intel Platform Innovation Framework Specification. It also
includes the libraries instances serviced for these modules.
EdkShellPkg
Provides the build instructions of Shell project. EFI Shell belongs to
another project, please visit
https://www.doczj.com/doc/9b828722.html,/apps/mediawiki/tianocore/index.php?title=Efi-shell
for more details.
EdkShellBinPkg
Provides the binary Shell files and the binary shell applications for
different CPUs architectures.
EdkFatBinPkg
Provides the binary FAT drivers for different CPUs architectures. FAT driver
belongs to another project, please visit
https://www.doczj.com/doc/9b828722.html,/apps/mediawiki/tianocore/index.php?title=Edk2-
fatdriver2 to get the source code of FAT driver.
10 March, 2010
Nt32Pkg
Launched at 32-bit Microsoft Window operating system and provides a
UEFI runtime environment.
UnixPkg
Launched in general 32-bit Unix-like operating system, such as a UNIX or
Linux distributions.
DuetPkg
Provides UEFI runtime environment based on legacy BIOS on the real
machine.
OptionRomPkg
Shows the sample drivers to build PCI compliant Option ROMimage for
different CPUs architectures.
EdkCompatibilityPkg(ECP)
Includes EDK style definitions of EFI1.10, EFI2.0 and all definitions of Intel
Framework Specification and the EDK libraries instances to allow EDK style
modules to be used in EDKII context. It also has some thunk drivers that
provide transition between the different protocols defined in UEFI2.1/PI1.0
specifications and the Intel Platform Innovation Framework Specification.
The primary goal of the ECP is to enable build compatibility of EDK
modules in the EDKII and to address the binary compatibility issues with
using existing pre-PI EDK modules in a platform comprised of mostly
EDKII modules.
PcAtChipsetPkg
Designed to public interfaces and implementation that follows PcAt de
facto standard.
UefiCpuPkg
Provides UEFI compatible CPU modules and libraries.
OvmfPkg
Aims to support firmware for Virtual Machines using the edk2 code base.
More information can be found at:
https://www.doczj.com/doc/9b828722.html,/apps/mediawiki/tianocore/index.php?title=OVMF . Each package has the similar structure of directories. For example, MdePkg has the following directories and sub-directories:
Include\ -- public header files of MDE Package
Ia32\ -- internal header files specified to IA-32 architecture
X64\ -- internal header files specified to x64 architecture
Ipf\ -- internal header files specified to IPF architecture
11 March, 2010
12
March, 2010
Ebc\ -- internal header files specified to EBC architecture Uefi\ -- public header files containing UEFI2.1 definitions Pi\ -- public header files containing PI1.0 definitions Protocol\ -- public header files containing PROTOCOLs definitions Ppi\ -- public header files containing PPIs definitions Guid\ -- public header files containing GUIDs definitions IndustryStandard\
-- public header files containing Industry Standard Library\ -- public header files containing MDE Libraries classes Library\ -- MDE libraries instances
The internal header files only could be referred by those public header files.
A dependency relationship exists among EDKII packages. For example, the module in MdeModulePkg uses the protocols defined in MdePkg, so MdeModulePkg will depend on MdePkg. The following chart illustrates the dependencies among the packages in
EDKII.
Figure 1 Packages Dependency
From this chart, the following basic dependencies can be discovered, for example: