EDKII User Manual V0.60

Add to my manuals
62 Pages

advertisement

EDKII User Manual V0.60 | Manualzz

EDKII User Manual

June 8, 2008

Revision 0.06

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, 2009 Intel Corporation. ii June, 2009

1

2

3

4

Contents

EDKII Introduction ............................................................................................1

1.1

Overview ..............................................................................................1

1.1.1

UEFI and PI ..............................................................................2

1.1.2

EDK & EDKII ............................................................................2

1.2

Related Information................................................................................4

1.2.1

Useful publications and sources of information...............................4

1.2.2

Publications are available at http://edk2.tianocore.org: ..................4

1.3

Terms...................................................................................................4

1.4

Target Audience .....................................................................................6

Setting Up EDKII Development Environment.........................................................9

2.1

How to Get the EDKII Source ...................................................................9

2.2

EDKII Packages .....................................................................................9

2.3

Third-Part Tools ...................................................................................12

2.3.1

Target for IA-32 and Intel64 Processors .....................................12

2.3.2

Target for Intel Itanium Family Processors (IPF) ..........................14

2.3.3

Target for EFI Byte Code (EBC) Image .......................................15

2.4

A Quick Build .......................................................................................15

EDKII Build Process.........................................................................................17

3.1

Basic build steps introduction .................................................................17

3.2

Build Configuration ...............................................................................18

3.2.1

Configure the active platform ....................................................18

3.2.2

Build command options ............................................................19

3.2.3

Configure the build tool chain and flags ......................................20

3.2.4

Configure the build rules ..........................................................22

3.3

Build Output Directory ..........................................................................22

3.4

Build Single Module ..............................................................................23

3.4.1

Create new Package ................................................................23

3.4.2

Add the module into a package .................................................26

3.4.3

Configure the active platform and build module ...........................29

3.5

Build/Customize Existing Platform...........................................................29

3.5.1

Build Existing Platform .............................................................29

3.5.2

Customize Platform .................................................................30

3.5.3

Sum Up: Create Release Tip for a Platform..................................36

3.6

Common Build Errors ............................................................................37

EDKII Emulation Environment...........................................................................39

4.1

Overview ............................................................................................39

4.2

Emulation Platforms..............................................................................39

4.2.1

NT32 platform ........................................................................39

4.2.2

Unix platform .........................................................................40

4.2.3

Duet platform .........................................................................41

4.3

Shell Environment ................................................................................44

4.3.1

Launch Shell...........................................................................44

iii June, 2009

4.3.2

Shell command .......................................................................48

4.4

Enable Network on Nt32 platform ...........................................................49

4.5

Debugging in Emulation Environment ......................................................51

4.5.1

Print Debug Message ...............................................................51

4.5.2

Single Step Debugging in Nt32 Emulate Platform .........................52

4.5.3

Single Step Debugging in Unix Emulate Platform..........................54

iv June, 2009

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 June, 2009

TABLES

Table 1 Microsoft Visual Studio .........................................................................13

Table 2 Intel C++ Compiler ..............................................................................13

Table 3 Microsoft Window Driver Development Kit (DDK) ......................................13

Table 4 Software Needed by GCC Tool Chain.......................................................14

Table 5 ACPI Compiler .....................................................................................14

Table 6 Microsoft Visual Studio.........................................................................14

Table 7 Intel C++ Compiler for EFI Byte Code Compiler........................................15

Table 8 The list of supported tool chain tags .......................................................20

Table 9 Internal shell commands.......................................................................48

vi June, 2009

Revision History

Revision

Number

0.06

Description Revision

Date

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

09/11/2008

June 9, 2009 vii June, 2009

viii June, 2009

1

EDKII Introduction

This document provides detailed instructions for downloading, configuring and building an EDKII project as well as running EDKII Emulation Environments.

1.1 Overview

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 inturn 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

1.1.1

1.1.2

1.1.2.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.

UEFI 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.

EDK & 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.

Package

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 June, 2009

1.1.2.2

1.1.2

.3

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.

Library 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.

Platform 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 June, 2009

1.2

1.2.1

1.2.2

1.3

 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.

Related Information

Useful publications and sources of information

Unified Extensible Firmware Interface Specification Version 2.1, The Unified EFI

Forum, Inc, 2007, http://www.uefi.org

.

Extensible Firmware Interface Specification Version 1.10, Intel, 2001, http://developer.intel.com/technology/efi .

Intel® Platform Innovation Framework for EFI Specifications, Intel, 2006, http://www.intel.com/technology/framework/ .

Publications are available at http://edk2.tianocore.org:

EDK II MDE (Module Development Environment) Library Specification, Version 0.50,

Intel, 2006.

EDK II DSC File Specification, Version 0.50, Intel, 2007.

EDK II DEC File Specification, Version 0.50, Intel, 2007.

EDK II Extended INF Specification, Version 0.50, Intel, 2007.

EDK II FDF (Flash Description File) File Specification, Version 0.50, Intel, 2007.

EDK II Build Specification, Version 1.00, Intel, 2008.

Terms

The following terms are used throughout this document to describe varying aspects of input localization:

4 June, 2009

EDK

EFI Developer’s kit, the open source project of the Intel Platform

Innovation Framework for EFI that can be found at http://edk.tianocore.org

.

EDK II

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

A generic term to describe the open source project found at http://edk2.tianocore.org

. 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.

Generic term that refers to one of the versions of the EFI specification: EFI

1.02, EFI 1.10, or UEFI 2.1.

Framework

Intel® Platform Innovation Framework for EFI consists of the Foundation, plus 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 Library Specification 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 June, 2009

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, 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

A version of the EFI specification released by the Unified EFI Forum. This specification builds 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 www.uefi.org

.

1.4 Target 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 June, 2009

• IHVs who will be create supported firmware drivers for hardware device, as well as platform integrators using EDKII components and modules.

7 June, 2009

8 June, 2009

2.1

2.2

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 gives a brief introduction to the basic structure of the EDKII source code and provides a quick start to build and launch an NT32 emulation platform.

How to Get the EDKII Source

http://www.tianocore.org

, is 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 is a detailed instruction at https://edk2.tianocore.org/subversion_setup.html

, which walks readers through the installation of the Subversion Software Configuration management Client. This page also provides a detailed instruction on how to setup

Subversion to download EDKII source. EDKII source repository is https://edk2.tianocore.org/svn/edk2/trunk/edk2 .

Before downloading EDKII source, obtain an account on http://www.tianocore.org

.

Please register it at https://www.tianocore.org/servlets/Join .

EDKII 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://buildtools.tianocore.org

to get the source codes of build tools.

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.

9

MdePkg

Declares PROTOCOLs/PPIs/GUIDs and related data structures defined in

UEFI2.1/PI1.0 Specifications ( http://www.uefi.org

) and industry standards. Also, 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 UEFI2.1/PI1.0

Specification. 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

( http://developer.intel.com/technology/framework/spec.htm

). Also, 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 source codes of Shell project. EFI Shell belongs to another project, please visit https://efi-shell.tianocore.org

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://fat-driver2.tianocore.org to get the source code of FAT driver.

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.

10 June, 2009

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.

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

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.

11 June, 2009

2.3

2.3.1

Figure 1 Packages Dependency

From this chart, the following basic dependencies can be discovered, for example:

1. To build OptionRomPkg, only MdePkg and BaseTools are required.

2. To build EdkCompatibilityPkg, only MdePkg, IntelFrameworkPkg and BaseTools are required.

3.

4.

To build EdkShellPkg, only EdkCompatibilityPkg and BaseTools are required.

To build the NT32/Unix/Duet emulation platforms, MdePkg, MdeModulePkg,

IntelFrameworkPkg, IntelFrameworkModulePkg, EdkFatBinPkg,

EdkShellBinPkg and BaseTools are required.

Third-Part Tools

Besides downloading EDKII source, some third-party tools are still needed to build

EDKII. The Third-Party Tools include a C compiler and an assembler. An ACPI compiler is required to build ACPI table.

Target for IA-32 and Intel64 Processors

To build EDKII for the platforms based on IA-32 or Intel64 processors, the following compiler tool chains may be selected.

1. Microsoft Visual Studio

12 June, 2009

One version of Microsoft Visual Studio from the below table may be installed to build EDKII.

Table 1 Microsoft Visual Studio

Name Version URL

http://msdn2.microsoft.com/en-us/vstudio Microsoft Visual

Studio

Microsoft Visual

Studio

2005

Professional

2003 .NET http://msdn2.microsoft.com/en-us/vstudio

2.

By default, the EDKII source on http://www.tianocore.org

is set to use

Microsoft Visual Studio 2005 Professional to build the IA-32 and Intel64 processors-based platforms.

To build a physical platform (because it has 16-bit assembly codes) the

Microsoft Windows Driver Development Kit must be installed. Please refer to

Table 3 to install it.

Intel C++ Compiler (ICC)

Table 2 Intel C++ Compiler

Name Version

Intel C++ Compiler for

Windows

9.1

URL

http://www.intel.com/support/performancetools/c/wi ndows/index.htm

3.

After the downloading web page, select the correct version number to download.

Build EDKII using an Intel C++ Complier requires a Microsoft Visual Studio

installation. Please refer to Table 1 to install one version of Microsoft Visual

Studio.

Microsoft Windows Driver Development Kit (DDK)

Table 3 Microsoft Window Driver Development Kit (DDK)

Name Version URL

Microsoft Windows

Driver Development

Kit (DDK)

2790.1830 http://download.microsoft.com/download/9/0/f/90f0

19ac-8243-48d3-91cf-

81fc4093ecfd/1830_usa_ddk.iso

4. GCC Tool Chain

There are two GCC tool chains. One is used to build and launch Unix

Emulation Platform on platforms based on the IA-32 processor. Another is used to build UEFI images running on the actual platforms.

To build and launch Unix Emulation Platform target, requirements are one of the 32-bit Unix-like operating system environments and a group of software that includes GNU C Compiler, GNU Binutils, GNU Glib C, X11, SQlite and

13 June, 2009

2.3.2

Python. The software provided by a Unix-like operating system can be used

directly, or downloaded and built as listed in Table 4.

Table 4 Software Needed by GCC Tool Chain

Name Version

GNU C Compiler (GCC) 4.2.1

GNU Binutils 2.17.50

GNU Glib C 2.3.6

URL

http://gcc.gnu.org/gcc-4.2/ http://ftp.gnu.org/gnu/binutils/ http://ftp.gnu.org/gnu/glibc/

SQLite

Python

5.

3.0 or later http://www.sqlite.org

2.5.2 or later http://www.python.org/

To build EDKII as a target for IA32 and Intel64 architectures, the updated software to generate the UEFI images capable of running on actual platforms will be needed. First, the SQLite and Python version listed in the upper table will need to be downloaded and installed, then use the script https://buildtools.tianocore.org/svn/buildtools/trunk/BaseTools/gcc/mingwgcc-build.py

to download all needed software and to build automatically. This script belongs to BaseTools project. Use your account on http://www.tianocore.org

to download it.

ACPI Compiler

To build ACPI tables, one of ACPI compilers listed below needs to be installed.

Table 5 ACPI Compiler

Name Version URL

http://acpica.org/downloads/ ACPI Component

Architecture

Microsoft ACPI

Source Language

(ASL) Assembler

20061109 or later

3.0.0NT or later http://www.microsoft.com/whdc/system/pnppwr/powe rmgmt/default.mspx

Target for Intel Itanium Family Processors (IPF)

To build EDKII for the platforms based on Itanium Processor Family (IPF) processors, the following compiler tool chains may be selected.

1. Microsoft Visual Studio

Table 6 Microsoft Visual Studio

Name Version

Microsoft Visual

Studio

2005 Team Suite

URL

http://msdn2.microsoft.com/en-us/vstudio

14 June, 2009

2.3.3

2.4

2.

3.

4.

When installing Microsoft Visual Studio 2005 Team Suite, IA64 support must be selected.

Intel C++ Compiler (ICC)

Please refer to Table 2 to install the Intel C++ Compiler. To build EDKII with

Intel C++ Complier, a Microsoft Visual Studio installation is also required.

Please refer to Table 1 to install one version of Microsoft Visual Studio.

Microsoft Windows Driver Development Kit (DDK)

By default, the EDKII source on http://www.tianocore.org

is set to use

Microsoft Windows Driver Development Kit (DDK) to build the Intel Itanium

Processor Family processors-based platforms. Please refer to Table 3 to install

Microsoft Windows Driver Development Kit (DDK).

ACPI Compiler

To build ACPI tables, one of ACPI compilers listed in Table 5 must be installed.

Target for EFI Byte Code (EBC) Image

The Intel C Compiler for EFI Byte Code creates EFI Byte Code (EBC) images that can be executed by systems implementing the EFI 1.10, UEFI 2.0, or later specifications.

These systems include an EBC interpreter that loads and interprets the EBC image, allowing the image to be executed on multiple platforms and architectures, including those based on Intel Itanium processors, IA-32 architecture-based processors, or

Intel64 architecture-based processors.

Table 7 Intel C++ Compiler for EFI Byte Code Compiler

Name Version URL

Intel C++

Compiler for EFI

Byte Code

1.2 http://www3.intel.com/cd/software/products/asmona/eng/compilers/efibc/index.htm

To build EBC image, the Intel C Compiler for EFI Byte Code and Microsoft Visual

Studio must be installed. Refer to Table 1 for installation of Microsoft Visual Studio.

A Quick Build

The following instructions will build and launch an NT32 emulation platform step by step.

1. Enter EDKII root directory

Run

edksetup.bat --nt32

2.

3.

Run

build

Execute

build run

15 June, 2009

16

3.1

3

EDKII Build Process

Basic build steps introduction

Chapter 2 explained how to build an NT32 platform. In this chapter, the basic build steps are introduced in detail.

Step 1: Download EDKII project as the basic workspace, and install the required tool chain. If necessary, other modules and packages can also be added into this

workspace. This step is shown in Chapter 2.

Step 2: In the workspace (EDKII root directory), run

edksetup

script to set up the build environment. For an Nt32 platform, the

--nt32

option is required to setup the

“standard” places for include (.h) and dll files required by the Nt32 platform.

Step 3: Configure the active platform, such as build options, target, build tool chain

and build rules. The build configuration is introduced in section 3.2.

Step 4: Call

build

command to build the platform, module or target configured in

step 3. See section 3.2.2 regarding the build command option. See section 3.5

regarding the platform build and customization. The module build is introduced in

section 3.4. The build targets are listed in the end of this section.

Step 5: Post build steps can be done according to custom requirements. For an NT32 platform, execute the

build run

command to run NT32 emulation. For the option

ROM image, create the option ROM.

The above

run

is a build target for

build

command to start NT32 emulation. Besides, there are other useful build targets. They are:

build

build all

Build all libraries, component PE/COFF images and FV/FD images.

build clean

Clean the intermediate output files (such as the compiled obj files) except the generated Makefile files (top level and module makefiles) and AutoGen files.

build cleanall

Clean all generated files and directories during build.

build fds

Only generate FV and FD image.

17 June, 2009

3.2 Build Configuration

Build configuration includes three aspects. They are separate for the active platform, the tool chain and build rule. The build configuration information is stored in three txt files: target.txt, tools_def.txt and build_rule.txt. Their template that contains the default setting provided by EDKII is created in the

$(WORKSPACE)/Conf

directory after build step 2. The following sections introduce each txt file.

3.2.1 Configure the active platform

The active platform is the built target. It can be set in the target.txt file or in build command line options. Target.txt is used to filter the build so everything does not always get built. It contains a group of build settings listed in the following example.

Example Conf/target.txt

ACTIVE_PLATFORM = Nt32Pkg/Nt32Pkg.dsc

TARGET = DEBUG

TARGET_ARCH = IA32

TOOL_CHAIN_CONF = Conf/tools_def.txt

TOOL_CHAIN_TAG = MYTOOLS

MULTIPLE_THREAD = Enable

MAX_CONCURRENT_THREAD_NUMBER = 2

BUILD_RULE_CONF = Conf/build_rule.txt

3.2.1.1 ACTIVE_PLATFORM

3.2.1.2

3.2.1.3

ACTIVE_PLATFORM

specifies the

$(WORKSPACE)

relative path and filename of the platform description file (DSC) that will be used for the build. The setting for the example above is the Nt32 platform DSC file.

TARGET

TARGET

refers to zero or more of

DEBUG

,

RELEASE

, or

UserDefined

; separated by a space character. If the line is missing or no value is specified, all valid targets specified in the platform description file will attempt to be built. The current setting is to build the debug platform target.

TARGET_ARCH

TARGET_ARCH

specifies what kind of architecture is for which binary targeted. One or more of

IA32, IPF, X64,

or

EBC

can be set. Multiple values can be specified on a single line by using space character to separate them.

If the platform requires multiple architectures, for example 32bit Pei module and 64bit

Dxe module, this option must be set to

IA32 X64

.

If the module is built for multiple architectures, for example a library is built for

IA32

and

X64

, this option must also be set to

IA32 X64

.

If the line is missing or no value is specified, all supported architectures specified in the platform description file will attempt to be built.

18 June, 2009

3.2.1.4

3.2.1.5

3.2.1.6

3.2.2

3.2.2.1

3.2.2.2

The current setting is to build

IA32

platform.

TOOL_CHAIN_TAG

TOOL_CHAIN_TAG

specifies the tool TagName defined in tools_def.txt to be used for build. By default,

MYTOOLS

TagName is chosen. It refers to Microsoft Visual Studio

2005 for

IA32

and

X64

target architecture, and the Microsoft Windows DDK (WINDDK) version 3790.1830 for

IPF

target architecture.

MULTIPLE_THREAD and MAX_CONCURRENT_THREAD_NUMBER

MULTIPLE_THREAD and MAX_CONCURRENT_THREAD_NUMBER

are used to enable multithread build. We recommend setting the number of concurrent threads to one more than the number of computer cores or CPUs in the machine used. This feature is only available for "spawn" build mode, such as platform build. However, the clean, cleanall or stand-alone module build is still using the normal way.

TOOL_CHAIN_CONF and BUILD_RULE_CONF

TOOL_CHAIN_CONF

and

BUILD_RULE_CONF

specify the name of the files, which specify the tool chains and build rules to be used for build. By default, tools_def.txt and build_rule.txt are used.

Build command options

Build

command provides the command line options to configure the build process, which can override the build configurations in target.txt. If the corresponding build option is not set, the build setting is from target.txt. Otherwise, the build setting is decided by build command line options. Some usual usages of

Build

command are followed.

Set the build configuration (Target, Arch, and Tool chain) build -a X64 -t MYTOOLS -b DEBUG

The active platform defined in target.txt file will be built to the debug images for

X64

arch under

MYTOOLS

tool chain. The active platform is not overridden.

-a

option sets the build arch to override

TARGET_ARCH

setting in target.txt.

-t

option sets the tool chain to override

TOOL_CHAIN_TAG

setting in target.txt.

-b

option sets the build target to override

TARGET

setting in target.txt.

Set the active platform build -p MyPlatform\MyPlatformPkg.dsc

MyPlatform is built as the active platform.

19 June, 2009

3.2.2.3

3.2.2.4

3.2.3

-p

option sets the active platform to override

ACTIVE_PLATFORM

setting in target.txt.

Build a specified module build -m MdeModulePkg\Application\HelloWorld\HelloWorld.inf

The “HelloWorld” application is built as the single module based on the active platform specified in target.txt. This application INF file must be specified in the active platform

DSC file.

-m

option sets the INF file name of the module to be built. This setting is not supported in target.txt.

Build a specified FV/FD image build -p Nt32Pkg/Nt32Pkg.dsc -i FvRecovery -r Nt32

The FvRecovery FvImage and Nt32 FD image will be created for NT32 platform.

-r

option sets the name of FD image to be generated. The name must be from [FD] section in FDF file.

-i

option sets the name of FV image to be generated. The name must be from [FV] section in FDF file.

The full build command usage can be obtained by

build --help

and

Build_Utility_Man_Page

located at https://buildtools.tianocore.org/svn/buildtools/trunk/BaseTools/UserManuals .

Configure the build tool chain and flags

The third party tools and tool flags are described in tools_def.txt file. The template tools_def.txt file defines the following tool chain tags commonly used in EDKII:

Table 8 The list of supported tool chain tags

Tool Chain Tags Description

VS2003

VS2005

DDK3790

UINIXGCC

ELFGCC

CYGGCC

ICC

MYTOOLS win32 - Microsoft Visual Studio .NET 2003, Intel EBC, Intel ASL win32 - Microsoft Visual Studio 2005 Team Suite Edition, Intel EBC,

Intel ASL (also compatible with VS 2005 Express, Standard, and Pro) win32 - Microsoft Windows DDK 3790.1830, Intel EBC, Intel ASL

Mingwin GCC, No EBC, Intel ASL

Linux ELF GCC, No EBC, Intel ASL win32 - CygWin GCC, Intel EBC, Intel ASL win32 - Intel C Compiler V9.1, Intel EBC, Intel ASL win32 - VS2005 for IA32/X64, WINDDK 3790.1830 for IPF, Intel

EBC, Intel ASL

20 June, 2009

3.2.3.1

3.2.3.2

3.2.3.3

VS2003xASL

VS2005xASL

DDK3790xASL

CYGGCCxASL

ICCxASL

VS2005x86

ICCx86

VS2005x86xASL

ICCx86xASL

CYGGCCx86

CYGGCCx86xASL win32 - Microsoft Visual Studio .NET 2003, Intel EBC, Microsoft ASL win32 - Microsoft Visual Studio 2005 Team Suite Edition, Intel EBC,

Microsoft ASL win32 - Microsoft Windows DDK 3790.1830, Intel EBC, Microsoft ASL win32 - CygWin GCC, Intel EBC, Microsoft ASL win32 - Intel C Compiler V9.1, Intel EBC, Microsoft ASL win64 - Microsoft Visual Studio 2005 Team Suite Edition (x86), Intel

EBC, Intel ASL (also compatible with VS 2005 Express, Standard, and

Pro) win64 - Intel C Compiler V9.1 (x86), Intel EBC, Intel ASL win64 - Microsoft Visual Studio 2005 Team Suite Edition (x86), Intel

EBC, Microsoft ASL (also compatible with VS 2005 Express, Standard, and Pro) win64 - Intel C Compiler V9.1 (x86), Intel EBC, Microsoft ASL win64 - CygWin GCC (x86), Intel EBC (x86), Intel ASL win64 - CygWin GCC (x86), Intel EBC (x86), Microsoft ASL

Change tool chain location

When the tool chain location is different from the default setting in tools_def.txt, users can change the tool path definition to point to their tool chain location. For example, if the VS2003 installation directory is

D:\Program Files\Microsoft Visual Studio

.NET 2003

, these two path macros need to be changed as follows:

DEFINE VS2003_BIN = D:\Program Files\Microsoft Visual Studio .NET

2003\Vc7\bin

DEFINE VS2003_DLL = D:\Program Files\Microsoft Visual Studio .NET

2003\Common7\IDE

Change tool flags

When the default tool flags don't meet requirements, update them in tools_def.txt.

For example, to disable all compiler optimization for

VS2003

tool chain, the

VS2003 CC

FLAGS

needs to use

/Od

option in place of

/O1

option like:

DEBUG_VS2003_IA32_CC_FLAGS = /nologo /c /WX /W4 /Gs8192 /Gy /D UNICODE

/Od /GL /FIAutoGen.h /EHs-c- /GR- /GF /GX- /Zi /Gm

Add new tool chain

For tool chains other than the tool chain list (given above) defined in tools_def.txt, add it into tools_def.txt file. Similar to the existing tool chain definition, such as

VS2003

, users can quickly define the new TagName to contain their tool chain and tool flags.

21 June, 2009

3.2.4

3.3

For more detail information refer to the template tools_def.txt file and EDK II Build

Specification Chapter 5.

Configure the build rules

The build rules describes how the individual source files are compiled and linked.

These rules are defined in build_rule.txt file. The template build_rule.txt file provides the common build rules to cover all source files in EDKII, such as

*.c, *.h, *.asm

files and so on. However, if a new type file is added to be built, the corresponding build rule for this file must be created into build_rule.txt. The instructions on how to create build rule can be referred to in the EDK II Build Specification Chapter 5.

Build Output Directory

When the platform is built successfully, all build output files are generated into the directory:

$(WORKSPACE)/$(OUTPUT_DIRECTORY)/$(TARGET)_$(TOOL_CHAIN_TAG)

WORKSAPCE

is the EDKII root directory.

OUTPUT_DIRECTORY

is from the platform DSC file

[Defines]

section. For the platforms provided by EDKII, this value is always set to

Build/PlatformName

so that all output files are in the same build directory.

TARGET, TOOL_CHAIN_TAG

and

ARCH

are determined by settings in target.txt or the build command line options.

The EFI images (*.efi) and EFI OptionRom images (*.rom) are created in

$(ARCH)

subdirectory:

$(WORKSPACE)/$(OUTPUT_DIRECTORY)/$(TARGET)_$(TOOL_CHAIN_TAG)/$(ARCH)

The FV (*.fv) and FD (*.fd) images are created in

FV

subdirectory:

$(WORKSPACE)/$(OUTPUT_DIRECTORY)/$(TARGET)_$(TOOL_CHAIN_TAG)/FV

Autogen.c/h

is created in the

DEBUG

subdirectory of the module output directory:

$(WORKSPACE)/$(OUTPUT_DIRECTORY)/$(TARGET)_$(TOOL_CHAIN_TAG)/$(ARCH)/$(MO

DULE INF RELATIVE PATH to WORKSPACE)/$(MODULE INF NAME)/DEBUG

Intermediate output files, such as *.obj, are created in the module OUTPUT subdirectory of the module output directory:

$(WORKSPACE)/$(OUTPUT_DIRECTORY)/$(TARGET)_$(TOOL_CHAIN_TAG)/$(ARCH)/$(MO

DULE INF RELATIVE PATH to WORKSPACE)/$(MODULE INF NAME)/DEBUG

22 June, 2009

3.4

3.4.1

For an Nt32 platform, its

OUTPUT_DIRECTORY

is set to

Build/NT32

in NT32.dsc. The build configuration is as follows:

TARGET

is

DEBUG; TOOL_CHAIN_TAG

is

MYTOOLS

;

ARCH

is

IA32

.

The components of an EFI image are in:

$(WORKSPACE)/Build/Nt32/DEBUG_MYTOOLS/IA32

The FV and FD images are in:

$(WORKSPACE)/Build/Nt32/DEBUG_MYTOOLS/FV

The output directory for the Helloworld application of

MdeModulePkg/Application/HelloWorld/HelloWorld.inf are:

$(WORKSPACE)/Build/Nt32/DEBUG_MYTOOLS/IA32/MdeModulePkg/Application/Hello

World/HelloWorld/OUTPUT

Autogen.c/h for Helloworld application are in:

$(WORKSPACE)/Build/Nt32/DEBUG_MYTOOLS/IA32/MdeModulePkg/Application/Hello

World/HelloWorld/DEBUG

Build Single Module

In general, the single module (such as UEFI application and Option ROM ) can be built by the following steps:

1.

2.

3.

Create a new package to contain this module. (Skip if the package exists)

Add this module into a package. (Skip if the module is in a package)

Run the

edksetup

script to set up the build environment.

4.

5.

Configure the active platform to the package platform.

Call the

build

command with

-m

option to build this module.

Create new Package

This step is only needed for a module that is not in any package. Creating the package also creates two package meta-data files: DEC and DSC.

The package declaration (DEC) file is used to define the package public information, such as the header files, Library Class, Ppi/Protocol/Guid and PCD. The following example is a dummy DEC file without any public information, and only defines the package name and guid.

23 June, 2009

Example Package.dec

[Defines]

DEC_SPECIFICATION = 0x00010005

PACKAGE_NAME = PackageName

PACKAGE_GUID = xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

PACKAGE_VERSION = 0.1

[Includes]

#include header file path, relative to package directory

[LibraryClasses]

#libraryclassname|librarclass header file name, relative to workspace

[Guids]

#GuidCName = {xxxxxxxx,xxxx,xxxx,{xx,xx,xx,xx,xx,xx,xx,xx}},

[Ppis]

#PpiGuidCName = {xxxxxxxx,xxxx,xxxx,{xx,xx,xx,xx,xx,xx,xx,xx}},

[Protocols]

#ProtocolGuidCName = {xxxxxxxx,xxxx,xxxx,{xx,xx,xx,xx,xx,xx,xx,xx}},

[PcdsFeatureFlag]

#PcdTokenSpaceCGuidName.PcdName|TRUE or FLASE|BOOLEAN|TokenNumber

[PcdsFixedAtBuild]

#PcdTokenSpaceCGuidName.PcdName|Value|DataType|TokenNumber

[PcdsPatchableInModule]

#PcdTokenSpaceCGuidName.PcdName|Value|DataType|TokenNumber

[PcdsDynamic]

#PcdTokenSpaceCGuidName.PcdName|Value|DataType|TokenNumber

[PcdsDynamicEx]

#PcdTokenSpaceCGuidName.PcdName|Value|DataType|TokenNumber

If necessary, the module in this package can publish the information in this file. The detail can be referred to EDKII DEC Specification.

The platform build description (DSC) file includes the modules to be built, and their dependent library instances and PCD values. The following example is from the EDKII

OptionRom DSC file. This DSC is created in order to build two option ROM drivers.

24 June, 2009

Example OptionRomPkg.dsc

[Defines]

PLATFORM_NAME = OptionRomPkg

PLATFORM_GUID = C7B25F37-B1F4-4c46-99CB-3EA7DCF5FCDC

PLATFORM_VERSION = 0.1

DSC_SPECIFICATION = 0x00010005

OUTPUT_DIRECTORY = Build/OptionRomPkg

SUPPORTED_ARCHITECTURES = IA32|IPF|X64|EBC

BUILD_TARGETS = DEBUG|RELEASE

SKUID_IDENTIFIER = DEFAULT

[SkuIds]

0|DEFAULT #The entry: 0|DEFAULT is reserved and required.

[LibraryClasses]

DebugLib | MdePkg/Library/UefiDebugLibStdErr/UefiDebugLibStdErr.inf

BaseLib | MdePkg/Library/BaseLib/BaseLib.inf

BaseMemoryLib | MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf

……

[PcdsFeatureFlag]

gEfiMdePkgTokenSpaceGuid.PcdComponentNameDisable|FALSE

gEfiMdePkgTokenSpaceGuid.PcdDriverDiagnosticsDisable|FALSE

gEfiMdePkgTokenSpaceGuid.PcdComponentName2Disable|FALSE

gEfiMdePkgTokenSpaceGuid.PcdDriverDiagnostics2Disable|FALSE

……

[PcdsFixedAtBuild]

gEfiMdePkgTokenSpaceGuid.PcdMaximumUnicodeStringLength|0x0

gEfiMdePkgTokenSpaceGuid.PcdMaximumAsciiStringLength|0x0

gEfiMdePkgTokenSpaceGuid.PcdMaximumLinkedListLength|0x0

……

[Components]

OptionRomPkg/AtapiPassThruDxe/AtapiPassThruDxe.inf

OptionRomPkg/CirrusLogic5430Dxe/CirrusLogic5430Dxe.inf

3.4.1.1 [Defines] section

3.4.1.2

The DSC name and guid are declared here.

OUTPUT_DIRECTORY

specifies the platform

output directory referred to section 3.3.

SUPPORTED_ARCHITECTURES

lists the supported

ARCHs

.

BUILD_TARGETS

defines the supported target.

[LibraryClasses] section

3.4.1.3

This section includes all library instances required by the modules in

[Components]

section. The library instance is specified as follows:

LibraryClassName | Library Instance INF file relative to workspace

.

[Pcds*] section

These sections set the values for the different type PCD used by the module. If the value of the used PCD is not set in the DSC file, the PCD value will be the default value in the package DEC file that publishes this PCD.

25 June, 2009

3.4.1.4

3.4.2

[Components] section

The modules to be built are specified here.

Add the module into a package

The module should be grouped into a package. It can be placed into the package directory according to the package layout. The recommended package layout refers to

section 2.2

To build the module, its INF file must be specified into the

[Components]

section of a

DSC file, and its dependent library instances and PCD values also need to be set in the corresponding section of the DSC file.

The module INF file includes the source files, the used Ppi/Protocol/Guid CName, the dependent library classes and PCD. The following example is from MdeModulePkg

Application HelloWorld INF file. It doesn't depend on any Ppi, Protocol and Guid, but it uses five library classes and two PCDs.

26 June, 2009

Example HelloWorld.inf

[Defines]

INF_VERSION = 0x00010005

BASE_NAME = HelloWorld

FILE_GUID = 6987936E-ED34-44db-AE97-1FA5E4ED2116

MODULE_TYPE = UEFI_APPLICATION

VERSION_STRING = 1.0

EDK_RELEASE_VERSION = 0x00020000

EFI_SPECIFICATION_VERSION = 0x00020000

ENTRY_POINT = UefiMain

[Sources]

HelloWorld.c

[Packages]

MdePkg/MdePkg.dec

[LibraryClasses]

UefiBootServicesTableLib

UefiApplicationEntryPoint

UefiLib

DebugLib

PcdLib

[Guids]

[Ppis]

[Protocols]

[FeaturePcd]

gEfiMdeModulePkgTokenSpaceGuid.PcdHelloWorldPrintEnable

[Pcd]

gEfiMdeModulePkgTokenSpaceGuid.PcdHelloWorldPrintString

gEfiMdeModulePkgTokenSpaceGuid.PcdHelloWorldPrintTimes

3.4.2.1 [LibraryClasses] section

The names of library classes required by the module are listed here. HelloWorld is an example to explain how to get all required library instances by the module. From the above HelloWorld INF file, we know that HelloWorld directly depends on

UefiLib,

DebugLib, UefiApplicationEntryPoint, UefiBootServicesTableLib

and

PcdLib

library classes. For these library classes, there are multiple library instances provided in MdePkg. The following five instances are chosen for this application:

UefiApplicationEntryPoint|MdePkg/Library/UefiApplicationEntryPoint/UefiAp plicationEntryPoint.inf

UefiBootServicesTableLib|MdePkg/Library/UefiBootServicesTableLib/UefiBoot

ServicesTableLib.inf

UefiLib|MdePkg/Library/UefiLib/UefiLib.inf

DebugLib|MdePkg/Library/UefiDebugLibStdErr/UefiDebugLibStdErr.inf

PcdLib|MdePkg/Library/DxePcdLib/DxePcdLib.inf

Of the five instances shown above, the

UefiLib

library instance requires more library classes:

PrintLib, BaseLib, BaseMemoryLib

and

MemoryAllocationLib

. Another four library instances are chosen:

27 June, 2009

3.4.2.2

PrintLib|MdePkg/Library/BasePrintLib/BasePrintLib.inf

MemoryAllocationLib|MdePkg/Library/DxeMemoryAllocationLib/DxeMemoryAlloca tionLib.inf

BaseMemoryLib|MdePkg/Library/BaseMemoryLib/BaseMemoryLib.inf

BaseLib|MdePkg/Library/BaseLib/BaseLib.inf

Finally,

BaseLib

depends on the extra

TimeLib

. The time library NULL instance is added.

TimerLib|MdePkg/Library/BaseTimerLibNullTemplate/BaseTimerLibNullTemplate

.inf

To build HelloWorld module, there are the ten library instances that must be specified in the

[LibraryClasses]

section in the DSC file.

[Pcd*] section

The different types of PCD used by the module are specified into the PCD type section, such as

[FeaturePcd]

,

[FixedPcd]

sections. But if the PCD type is not limited, it should be in

[Pcd]

section and its PCD type is decided according to the setting in DSC file. This application uses a feature flag PCD of

PcdHelloWorldPrintEnable

and two common type PCDs of

PcdHelloWorldPrintString

and

PcdHelloWorldPrintTimes.

Next, get all required library instances and PCDs and add them into DSC file.

HelloWorld is also an example for explaining their dependencies.

In last section, all required library instances are chosen, and the PCD used by them is decided. The following PCDs are used. Of PCDs,

PcdHelloWorldPrintEnable

,

PcdHelloWorldPrintString

and

PcdHelloWorldPrintTimes

are directly used by

HelloWorld. Other PCDs are from these chosen library instances.

Although the used PCDs seem numerous, most of them can directly use their default value defined in package DEC file. For users not wanting to use the default value, the new value can be set in the

[PCD]

section of DSC file to override the default setting.

28 June, 2009

3.4.3

3.5

3.5.1

[PcdsFixedAtBuild] gEfiMdePkgTokenSpaceGuid.PcdSpinLockTimeout gEfiMdePkgTokenSpaceGuid.PcdMaximumLinkedListLength gEfiMdePkgTokenSpaceGuid.PcdMaximumAsciiStringLength gEfiMdePkgTokenSpaceGuid.PcdMaximumUnicodeStringLength gEfiMdePkgTokenSpaceGuid.PcdDebugPrintErrorLevel gEfiMdePkgTokenSpaceGuid.PcdDebugClearMemoryValue gEfiMdePkgTokenSpaceGuid.PcdDebugPropertyMask gEfiMdeModulePkgTokenSpaceGuid.PcdHelloWorldPrintString gEfiMdeModulePkgTokenSpaceGuid.PcdHelloWorldPrintTimes

[PcdsFeatureFlag] gEfiMdePkgTokenSpaceGuid.PcdDriverDiagnosticsDisable gEfiMdePkgTokenSpaceGuid.PcdComponentNameDisable gEfiMdePkgTokenSpaceGuid.PcdDriverDiagnostics2Disable gEfiMdePkgTokenSpaceGuid.PcdComponentName2Disable gEfiMdeModulePkgTokenSpaceGuid.PcdHelloWorldPrintEnable

Configure the active platform and build module

To configure the active platform, the target.txt file or the build command can be used.

The instructions refer to sections 3.2.1 and 3.2.2.

The following example builds AtapiPassThruDxe module in EDKII OptionRom package to the release EFI images for EBC arch under the default

MYTOOLS

tool tag.

build -m OptionRomPkg/AtapiPassThruDxe/.inf -a EBC -t MYTOOLS -b RELEASE

-p OptionRomPkg/OptionRomPkg.dsc

If AtapiPassThruDxe module sets PCI options in its INF [Defines] section, the EFI option ROMimage will also be generated. PCI options can be set like:

[Defines]

INF_VERSION = 0x00010005

BASE_NAME = AtapiPassThruDxe

FILE_GUID = E49061CE-99A7-41d3-AB3A-36E5CFBAD63E

MODULE_TYPE = UEFI_DRIVER

ENTRY_POINT = InitializeAtapiPassThru

## PCI option for VendorId, DeviceId, ClassCode and Revision

PCI_VENDOR_ID = 0x8086

PCI_DEVICE_ID = 0x29c2

PCI_CLASS_CODE = 0x030000

PCI_REVISION = 0x1000

Build/Customize Existing Platform

This section introduces how to build an existing platform in detail and how to customize the platform for different purposes such as debug or release image, optimization for performance, optimization for small size, etc.

Build Existing Platform

Use the following steps to build an existing platform:

1. Download all packages required by this platform into workspace.

2. Run "

edksetup

" script to setup build environment.

29 June, 2009

3.5.2

3.

4.

Configure $(WORKSPACE)\Conf\taget.txt file.

Run "

build

" command.

After building, all output files will be generated into

"

$(WORKSPACE)\$(OUTPUT_DIRECTORY)\$(TARGET)_$(TOOL_CHAIN_TAG)

"(Refer to

section 3.3). FD image burned to flash device is generate at

"

$(WORKSPACE)\$(OUTPUT_DIRECTORY)\$(TARGET)_$(TOOL_CHAIN_TAG)\FV

".

Unlike building a single module, a general platform building requires an FDF (Flash

Device File) which is specified in the DSC

[defines]

section. An FDF file is a plain text file that describes the contents and layout of FV and FD file section by section.

Customize Platform

This section provides general customization instructions:

 Add/Remove Module

 Adjust Flash Layout, such as size and base address

 Customize Build Option

 Change Library Instance

To customize for specific purpose, one or more above instruction can be used. At the end of section an example of creating release platform is given for elaborating these instructions.

Add/Remove module 3.5.2

.1

3.5.2.

1.1 Add a module MdeModulePkg/Universal/Tcp4Dxe/Tcp4Dxe.inf into

FvRecovery firmware volume in Nt32 emulation

1.

2.

Add the module INF file into NT32 DSC file if the module is not in the DSC file

(Refer to section 3.4.2).

Search for the [Fv.FvRecovery] section in Nt32Pkg\Nt32Pkg.fdf.

[Fv.FvRecovery] looks as follows:

30 June, 2009

[FV.FvRecovery]

#

# Basic definitions for a Firmware Volume

#

FvAlignment = 16 #FV alignment and FV attributes setting.

ERASE_POLARITY = 1

……

READ_LOCK_STATUS = TRUE

#

# FV's Apriori file definition:

# the line start with "INF" indicate following INF path is for a module,

# whose dispatching order will be specified in PEI/DXE Apriori file.

#

APRIORI PEI {

INF MdeModulePkg/Universal/PCD/Pei/Pcd.inf

INF IntelFrameworkModulePkg/Universal/StatusCode/Pei/PeiStatusCode.inf

}

APRIORI DXE {

INF MdeModulePkg/Universal/PCD/Dxe/Pcd.inf

INF Nt32Pkg/MetronomeDxe/MetronomeDxe.inf

}

#

# Module which will be put into this FV.

# The line start with "INF" indicate following INF path is for a module,

# which will be put into this FV. All modules will be put into this FV

# as their following order.

#

INF MdeModulePkg/Core/Pei/PeiMain.inf

INF MdeModulePkg/Universal/PCD/Pei/Pcd.inf

INF IntelFrameworkModulePkg/Universal/StatusCode/Pei/PeiStatusCode.inf

INF Nt32Pkg/BootModePei/BootModePei.inf

………………

INF MdeModulePkg/Application/HelloWorld/HelloWorld.inf

#

# Binary image will be put into this FV

#

FILE DRIVER = 961578FE-B6B7-44c3-AF35-6BC705CD2B1F {

SECTION PE32 = FatBinPkg/EnhancedFatDxe/Ia32/Fat.efi

}

………………

# New moudle will be added into this FV.

INF MdeModulePkg/Universal/Tcp4Dxe/Tcp4Dxe.inf

As descriptions in the sample FvRecovery, a general FV section includes the basic definition, Apriori file definition, modules, and binary images. The Apriori file is generated at the beginning of FV image. The following module's order in the generated FV image is the same as their order specified in the FV section.

3. Put the "

INF MdeModulePkg/Universal/Tcp4Dxe/Tcp4Dxe.inf

section.

" at end of FV

3.5.2.1.2 Remove a module/binary image from FV

1.

2.

3.

Search for the module INF or binary image description in FDF file.

Delete the reference of module INF path or binary image description.

If the module is also included in platform build DSC file, it will be removed from the [Component] section in DSC file.

31 June, 2009

3.5.2

.2

3.5.2.3

3.5.2.3.1

Adjust flash layout

Flash device image is described as [FD.XXX] section in FDF file. An example NT32 FD section follows:

[FD.Nt32]

# FD basic definitions

BaseAddress = 0x0 #The base address of the FLASH Device.

Size = 0x002a0000 #The size in bytes of the FLASH Device

ErasePolarity = 1

BlockSize = 0x10000

NumBlocks = 0x2a

#########################################################################

#

# Following are lists of FD Region layout which correspond to the

# locations of different images within the flash device.

#

# Regions must be defined in ascending order and may not overlap.

#

#########################################################################

0x00000000|0x00280000

FV = FvRecovery

0x00280000|0x0000c000

…………………

0x0028c000|0x00002000

…………………

0x0028e000|0x00002000

…………………

0x00290000|0x00010000

#NV_FTW_SPARE

……………………

An FD section includes basic definitions and region information. A layout region start with an eight digital hex offset followed by the pipe "|" character, and then followed by the size of region. A layout region may contain a firmware volume, variable, or user defined data.

To adjust flash layout, the offset and size value for each region may be updated to make sure that all regions are not overlapped in one FD section.

Customize build option

As mentioned in section 3.2.3, $(WORKSPACE)\Conf\tools_def.txt file defines the global tool tag which group different compiler/linker options. Modifications in this file will affect all platform build or single module build in specified tool tag. Developer can override the global compiler/linker option for the specified platform or module.

Specific build option for platform

The [BuildOptions] section in the platform build DSC file is used to override the global build option. The build option in this section is appended to the end of the global build option. For example, this gives the following section in the platform build DSC file:

32 June, 2009

[BuildOptions]

MSFT:*_*_*_CC_FLAGS = /Fa$* /FAsc /FR$(@R).SBR

MSFT:

Microsoft compiler family.

First

*

: Target. "*" means for all valid targets: DEBUG_RELEASE

Second

*

: Tool chain tag. "*" means for all valid tool chain tags defined in tools_def.txt

Third

*

: Architecture. "*" means for all valid architectures, such as IA32, x64, IPF.

CC

: Command type. The build command type. CC is compiling command.

FLAGS

: Attribute. The attributes of commands which should be customized.

3.5.2.3.2 Specific build option for module

The build options for module can be overridden in the module INF or in the build option section of the platform build DSC file.

To override the build option in the module INF, add a [BuildOptions] section into the module INF file. This section is same as the [BuildOptions] section in the platform's build DSC.

To override the build option in the DSC file, use the following steps:

1. Find the module INF in [Components] section of DSC file.

2. Add the module's override section by using "{" and "}" under the module's

INF.

[Components.IA32]

}

3. Add the <BuildOptions> override section

[Components.IA32]

<BuildOptions>

MSFT:*_*_*_CC_FLAGS = /Fa$* /FAsc /FR$(@R).SBR

}

The final build option for a module is based on global build option in tools_def.txt.

Append build options from the module's INF. Append the platform's overridden build

33 June, 2009

3.5.2.4

3.5.2.5

3.5.2.5.1

option in the DSC file, then append the module's overridden build options in the DSC file.

Change library instance

Different library instances that produce the same library class are designed for different purposes, such as for a PEI/DXE phase, optimization for performance or size, for different architectures, etc.

In the platform DSC, different library instances can be selected for a specific library class in the [LibraryClasses] section. For example,

IntelFrameworkModulePkg/Library/PeiDxeDebugLibReportStatusCode/PeiDxeDebu gLibReportStatusCode.inf

library instance is selected for

DebugLib

library class for

DXE_DRIVER.

First, search for the

[LibraryClasses.common.DXE_DRIVER]

section in DSC file. If not found, the new section is added.

Then, add this library instance into the section given above and remove the originally selected debug library instance.

[LibraryClasses.common.DXE_DRIVER]

,

DebugLib|IntelFrameworkModulePkg/Library/PeiDxeDebugLibReportStatusCode/P eiDxeDebugLibReportStatusCode.inf

Configure PCD

The PCD mechanism provides FeatureFlag, FixeAtBuild, PatchabeInModule, and

Dynamic/DynamicEx types for a PCD token. These types are often-used customization methods:

 Macro: in which the value is fixed at build time,

 Global variable: in which the value can be fixed at build time and could be changed at runtime,

 EFI variable: in which the value is produced/consumed at runtime.

The PCD mechanism unifies these customization methods.

The PCD type and value for a PCD token can be customized by platform developers, as shown below.

Configure PCD type

The PCD type comes from section name in the INF/DEC/DSC file.

If the PCD section's name is [PCDs] in the module's INF, the Module developer is unconcerned about how to produce or consume an customizable value in a specific platform. In another words, the Module developer isn’t concerned about the final PCD type in the DSC file. This is because a PCD's value may be fixed at build time in a specific platform, but may be produced at runtime in another specific platform. Module

34 June, 2009

developers should use the following macro—defined in

MdeLib\Include\Library\PcdLib.h—to get the value of this customizable information:

#define PcdGet8(TokenName) _PCD_GET_MODE_8_##TokenName

#define PcdGet16(TokenName) _PCD_GET_MODE_16_##TokenName

#define PcdGet32(TokenName) _PCD_GET_MODE_32_##TokenName

#define PcdGet64(TokenName) _PCD_GET_MODE_64_##TokenName

#define PcdGetPtr(TokenName) _PCD_GET_MODE_PTR_##TokenName

#define PcdGetBool(TokenName) _PCD_GET_MODE_BOOL_##TokenName

The Platform developer must determine the final PCD type for a PCD token.

For example, the module MdePkg\Library\BasePciExpressLib\BasePciExpressLib.inf uses PCD PcdPciExpressBaseAddress, which indicates the base address of PciExpress

Bar. Its value is fixed at 0xE0000000 in specific platforms, so that in the platform's

DSC file the PCD is written as follows:

[PcdsFixedAtBuild.common]

gEfiMdePkgTokenSpaceGuid.PcdPciExpressBaseAddress|0xE0000000

In another platform, the address of the PciExpress bar might be produced by a specific

(but not fixed) PCIEX register, so that the PCD would be used as type PcdDynamic, as shown below:

[PcdsDynamicDefault.common] gEfiMdePkgTokenSpaceGuid.PcdPciExpressBaseAddress|0xE0000000

Above, the PcdsDynamicDefault type is a dynamic type. In the platform, there are three dynamic types for a PCD token, according to the storage of PCD value:

 PcdsDynamicDefault: the PCD value is stored in PCD database.

 PcdsDynamicHii: the PCD value is stored in a variable in flash.

 PcdsDynamicVpd: the PCD value is stored in an fix address specified by platform Developer.

3.5.2.5.2 Configure PCD value

Besides PCD type customization, PCD value customization is common usage for a PCD token. For example, in platform's DSC file:

[PcdsFixedAtBuild] gEfiMdePkgTokenSpaceGuid.PcdDebugPrintErrorLevel | 0x80000000

The value 0x80000000 means the message only marked as DEBUG_ERROR could be displayed. The valid values for this PCD come from

MdeLib\Include\Library\DebugLib.h:

#define DEBUG_INIT 0x00000001 // Initialization

#define DEBUG_WARN 0x00000002 // Warnings

#define DEBUG_LOAD 0x00000004 // Load events

35 June, 2009

3.5.3

#define DEBUG_FS 0x00000008 // EFI File system

#define DEBUG_POOL 0x00000010 // Alloc & Free's

#define DEBUG_PAGE 0x00000020 // Alloc & Free's

#define DEBUG_INFO 0x00000040 // Verbose

#define DEBUG_VARIABLE 0x00000100 // Variable

#define DEBUG_BM 0x00000400 // Boot Manager

#define DEBUG_BLKIO 0x00001000 // BlkIo Driver

#define DEBUG_NET 0x00004000 // SNI Driver

#define DEBUG_UNDI 0x00010000 // UNDI Driver

#define DEBUG_LOADFILE 0x00020000 // UNDI Driver

#define DEBUG_EVENT 0x00080000 // Event messages

#define DEBUG_ERROR 0x80000000 // Error

The platform developer can change value 0x80000000 to any other valid value in the range above.

Sum Up: Create Release Tip for a Platform.

This section provides an example of how to make a release tip for an existing platform by using customization instructions mentioned in preceding sections. To make the release binary, the following steps may be taken:

1. Turn off all debug code which around with DEBUG_CODE() macro.

PcdDebugPropertyMask is used to provide this type customization. Its value is bit-or from the following macros:

#define DEBUG_PROPERTY_DEBUG_ASSERT_ENABLED 0x01

#define DEBUG_PROPERTY_DEBUG_PRINT_ENABLED 0x02

#define DEBUG_PROPERTY_DEBUG_CODE_ENABLED 0x04

#define DEBUG_PROPERTY_CLEAR_MEMORY_ENABLED 0x08

#define DEBUG_PROPERTY_ASSERT_BREAKPOINT_ENABLED 0x10

#define DEBUG_PROPERTY_ASSERT_DEADLOOP_ENABLED 0x20

2.

In the platform release version, changing its value to 0x0 will turn off all debug code.

Turn off all debug message output

PcdDebugPrintErrorLevel is used for controlling what type of debug message could be output, as mentioned above.

36 June, 2009

3.

In platform release version, changing its value to 0x0 will turn off all debug message output.

Review all library instances and try to select optimized library instances for library class.

4.

5.

Remove unnecessary module from firmware volume file.

In the release version, platform does not need internal shell functionality, so remove the binary shell from FDF file.

Use RELEASE target build platform. For example:

build -p Nt32Pkg\Nt32Pkg.dsc -b RELEASE

Under RELEASE target, the compiler/linker options are selected for maximum optimization in tools_def.txt.

3.6 Common Build Errors

The following lists the common build errors and their solutions.

'build' is not recognized as an internal or external command.

The workspace and tools path are not set before build.

edksetup

script can be used to set build environment.

No active platform specified in target.txt or build command line.

Active platform is not set. Nothing is to be built. The target build platform must be set to

ACTIVE_PLATFORM

in target.txt or build command line

(

build -p active_platform.dsc

).

Active platform supports [IA32] only, but [X64] is given.

The chosen ARCH is not supported by the active platform. Nothing is to be built. Only supported ARCH by the active platform can be set to

TARGET_ARCH

in target.txt or build command line (

build -a ARCH

).

Module is not employed by active platform

Single module build doesn't succeed. This module needs to be specified in the active platform DSC file.

File/directory not found, IntelFrameworkPkg\IntelFrameworkPkg.dec

Package DEC file is not found. The required package needs to be placed into the workspace.

Cannot open include file: 'windows.h': No such file or directory

This error may happen when building an NT32 platform. Windows header files required by NT32 are not in system path.

edksetup.bat --nt32 can set this path.

37 June, 2009

Failed to start command C:\Program Files\Microsoft Visual Studio

8\Vc\bin\nmake.exe

VS2005 nmake command is not found. VS2005 may not be installed.

Because the default tool chain is MYTOOLS with VS2005, change the default tool chain to the third-party tool chain. For example: for a VS2003 compiler, set VS2003 tool chain to

TOOL_CHAIN_TAG

in target.txt or build command line (

build -t VS2003

).

38 June, 2009

4

EDKII Emulation Environment

4.1

4.2

4.2.1

4.2.1

.1

Overview

An Emulation platform is not an actual platform, but is designed to prove the stability of EDKII's core modules and develop a hardware-independent module. The differences between emulated platforms and actual platforms are its loader and emulated hardware devices.

EDKII provides three emulation platforms: Nt32, Unix and Duet platforms.

Emulation Platforms

NT32 platform

Overview

Nt32 platform is launched in the 32-bit Microsoft Window operating system and provides UEFI runtime environment.

The SecMain module, the Nt32 platform loader, is a Windows application. It establishes emulated hardware environment such as allocating Windows memory to simulate system memory for Nt32 platform and mapping FD file to a Windows memory region to simulate flash device. After that, SecMain invokes PeiCore's entry as an actual platform handing off to the PEI phase.

Nt32 platform provides many emulated devices written in a Windows API. For example, GOP device is a window, and physical/virtual disk is a mapping of window's directory.

Nt32 platform requires following packages, which can be downloaded from https://edk2.tianocore.org/svn/edk2

(please ref to chapter 2)

 MdePkg

 MdeModulePkg

 IntelFrameworkPkg

 IntelFrameworkModulePkg

 Nt32Pkg

 edkShellBinPkg

39 June, 2009

4.2.2

4.2.2.1

4.2.2

.2

 EdkFatBinPkg

 BaseTools

The steps of building/launching NT32 platform has been introduced at chapter 3.1.

Unix platform

Overview

Similar to Nt32 platform, Unix emulate platform is launched in general host Unix-like operating systems, such as various Unix and Linux distribution, etc.

The SecMain module, the Unix emulate platform loader, is an executable ELF program.

It establishes emulate environment in host Unix-like operating systems, such as creating emulate system memory and flash device into host OS memory. SecMain invoke PeiCore's entry as real platform to handle off to PEI phase.

Unix platform provides many emulate devices to simulate device in an actual platform.

These emulate devices are written in POSIX/X11 API. For example, GOP device is a window-based X11 API, and physical/virtual disk is a mapping of the host operating system's directory.

Unix platform requires the following packages, which can be downloaded from https://edk2.tianocore.org/svn/edk2

(please refer to chapter 2)

 MdePkg

 MdeModulePkg

 IntelFrameworkPkg

 IntelFrameworkModulePkg

 UnixPkg

 edkShellBinPkg

 EdkFatBinPkg

 BaseTools

Build and Launch

The build steps for Unix emulation platforms are follows:

1.

2.

3.

Build tools are executed from Python source code directly in a Unix-like OS.

First, download build tools from https://buildtools.tianocore.org/svn/buildtools/trunk/BaseTools .

Some build-related tools are written in C code. Type "

make -f GNUmakefile

" to build these tools under the downloaded build tools directory.

Create a soft link to the downloaded directory into

$(WORKSPACE)\Conf

directory. The link name is "BaseToolsSource", for example:

40 June, 2009

4.2.3

4.2.3

.1 ln -s /home/usr/BaseTools /home/usr/Edk2Workspace/Conf/BaseToolsSource

4.

5.

Run "

. edksetup.sh BaseTools

" under the workspace's directory to set system environment, such as WORKSPACE, EDK_TOOLS_PATH etc.

Run "

build -p UnixPkg\UnixPkg.dsc -a IA32 -t ELFGCC

" to build Unix emulated platform.

SecMain, the loader program for emulate environment, is built to the

$(WORKSPACE)/Build/Unix/DEBUG_ELFGCC/IA32

directory.

The Unix emulation is launched by executing SecMain.

Duet platform

Overview

Unlike Nt32 and Unix emulation platforms, Duet platform provides a UEFI runtime environment based on Legacy BIOS or UEFI implementation with legacy supporting actual machines.

The Duet platform is started up by a boot loader from floppy/usb/hard disk. Duet's boot loader collects following platform information:

 Memory description array from legacy E820 table

 SMBIOS table

 ACPI RSD (Root System Description) table

 MPS (MultiProcessor Specification) table

 Other ACPI table.

Because platform initialization has completed, Duet platform does not need the PEI phase. Duet boot loader transfers to DxeCore in by passing the collected platform information mentioned above.

41 June, 2009

Legacy BIOS call "int 19" to load Duet boot sector to 0x7C00

Duet boot sector find and load

Duet boot loader

Duet boot loader collects platform information and builds them into HOB

Duet DxeIpl module load FV in boot disk and find DxeCore in loaded FV

Duet boot loader transfer to DXE phase.

Figure 2 Startup flow for Duet environment

Duet platform requires the following packages, which can be downloaded from https://edk2.tianocore.org/svn/edk2

(please refer to chapter 2)

 MdePkg

 MdeModulePkg

 IntelFrameworkPkg

 IntelFrameworkModulePkg

 DuetPkg

 edkShellBinPkg

 EdkFatBinPkg

 BaseTools

42 June, 2009

4.2.3

.2 Build and Launch

4.2.3.

2.1 Windows

4.2.3.2.2

Building steps for Duet platform is the same as other actual platforms described in

chapter 3.

To launch a Duet platform, create a Duet boot disk and use the Duet boot disk to boot the machine.

CreateBootDisk.bat under the DuetPkg is used to create a bootable floppy/usb/hard disk from which the Duet platform is launched. The command line and options are:

CreateBootDisk [usb|floppy|ide] DiskNumber [FAT12|FAT16|FAT32]

 If the boot media is floppy and the floppy disk number is

a:

in the host machine, run "

CreateBootDisk floppy a: FAT12

".

 If the boot media is usb and the usb disk number is e: in the host machine, run "

CreateBootDisk usb e: [FAT16|FAT32]

".

 If the boot media is a hard disk, it is not possible to create a bootable hard disk in the host machine directly. Instead, copy the boot and FV files to a usb disk, then use EfiLdrImage tool shell application

(This EFI tool is built from EDK project's

Edk\Sample\Platform\Duet\Tools\EfildrImage) to create boot sector in target hard disk in an UEFI environment.

Linux

The Duet platform also can be built with the Mingw tool chain under a Linux environment.

Steps for building Mingw tool chain

1, Check out the build project from the svn repository: https://buildtools.tianocore.org/svn/buildtools/trunk/BaseTools

2, Build the buildtools with command "

make -f GNUmakefile

"

3, Enter “gcc” folder and run "mingw-gcc-install.py", which will download/build/install

MinGw GCC and corresponding binutil automatically.

4, Create soft symbol link to match the default path provided in tools_def.txt with the following command:

"

ln -s /BaseTools/gcc/symlinks/ar /opt/tiano/i386-tiano-pe/i386-tianope/bin/ar

"

"

ln -s /BaseTools/gcc/symlinks/gcc /opt/tiano/i386-tiano-pe/i386-tianope/bin/gcc

"

43 June, 2009

4.3

4.3.1

4.3.1.1

"

ln -s /BaseTools/gcc/symlinks/ld /opt/tiano/i386-tiano-pe/i386-tianope/bin/ld

"

Note: File <Workspace>/Conf/tools_def.txt gives UNIXGCC tool chain to describe the build options for MinGW GCC. UNIXGCC tool chain is used to build Duet platform.

Steps for building Duet platform under UNIXGCC tool chain

1, Open a Linux shell command and enter workspace folder

2, Create soft link “BaseToolsSource” under <Workspace>/Conf folder to point the repository of build tools, such as:

"

ln –s /BaseTools /edk2/Conf/BaseToolsSource

"

3, Run "

. edksetup.sh BaseTools

" from workspace folder.

4, Run "

build –p DuetPkg/DuetPkg.dsc –a IA32 –t UNIXGCC

"

5, Run "

DuetPkg/PostBuild.sh IA32

"

Steps for creating Duet boot floppy disk

1, Inset a blank floppy

2, Run "

DuetPkg/CreateBootDisk.sh floppy /media/floppy0 /dev/fd0 FAT12

"

Shell Environment

The EFI Shell is a simple, interactive environment that allows EFI device drivers to be loaded, EFI applications to be launched, and operating systems to be booted. In addition, the EFI Shell also provides a set of basic commands used to manage files and the system environment variables etc.

Launch Shell

The Shell, actually an EFI application, could be launched internally if the shell binary is built in the firmware volume, or externally from a floppy/usb/hard disk.

Launch Internal Shell

1. After launching emulate environment; access the "Boot Manager" menu as follows:

44 June, 2009

2.

Figure 3 Select "Boot Manager" Menu

If shell binary is built in a firmware volume, "EFI Internal Shell" item is listed as an boot option as follows:

45

Figure 4 Select "EFI Internal Shell" from "Boot Manager"

June, 2009

4.3.1.2 Launch External Shell

1.

2.

Insert disk that contains a shell binary image or verify that the shell binary image is put at the directory that is emulated as a physical disk in an

Nt32/Duet platform.

Boot the machine to the front page, select the "Boot Maintenance Manager" menu, and enter it.

3.

Figure 5 Select "Boot Maintenance Manager" from Front Page

Select the "Boot From File" menu and enter it.

46 June, 2009

4.

Figure 6 Select "Boot From File" menu

Select the disk that contains the shell binary in the device path list for disks.

47

Figure 7 Select disk contains "EFI Shell" binary image

June, 2009

5. In "File Explorer" menus, navigate the disk and find the "shell.efi" file.

4.3.2

Figure 8 Select Shell.efi binary image

6. Select "Shell.efi" in the file list and enter.

Shell command

Obtain the user manual and development manual for shell environment from https://efi-shell.tianocore.org/ .

Some useful internal shell commands are: alias attrib cd cls connect copy cp

Table 9 Internal shell commands

Command Description

Displays, creates, or deletes aliases in the EFI Shell.

Displays or changes the attributes of files/directories.

Displays or changes the current directory.

Clears the standard output with a background color.

Binds an EFI driver to a device and starts the driver.

Copies one or more files/directories to another location.

Copies one or more files/directories to another location.

48 June, 2009

4.4

load ls map mkdir mv reconnect reset rm set time touch type unload ver vol

Command

date del dh dir disconnect drivers drvcfg drvdiag echo exit help, ?

Description

Displays the current date or sets the date in the system.

Deletes one or more files or directories.

Displays the handles in the EFI environment.

Displays a list of files and subdirectories.

Disconnects one or more drivers from a device.

Displays a list of drivers that follow the EFI Driver Model.

Invokes the Driver Configuration Protocol.

Invokes the Driver Diagnostics Protocol.

Displays messages or turns command echoing on or off.

Exits the EFI Shell.

Displays the list of commands or verbose help of a command.

Loads EFI drivers.

Displays a list of files and subdirectories.

Displays or defines mappings.

Creates one or more directories.

Moves one or more files/directories to a destination.

Disconnects a driver from a device and then connects it again.

Resets the system.

Deletes one or more files or directories.

Displays/creates/changes/deletes environment variables.

Displays the current time or sets the time of the system.

Updates the time with the current time.

Displays the contents of a file.

Unloads a protocol image.

Displays the version information.

Displays volume information of the file system.

Enable Network on Nt32 platform

EDKII provides UEFI network stack drivers in the MdeModulePkg\Universal\Network folder and brings the support of TCP/IP networking, with different drivers implementing different TCP/IP protocols.

The hierarchal layering of the drivers is shown in the following image.

49 June, 2009

Figure 9 EFI network driver layout

To help develop networking applications, EDKII provides a SNPNT32Dxe driver in

Nt32Pkg\SnpNt32Dxe folder which implements the

EFI_SIMPLE_NETWORK_PROTOCOL for the NT32 platform. In conjunction with the

UEFI network stack drivers this driver can be used to develop and test networking applications on Windows® NT operating system through the EDK’s NT32 platform emulation environment.

The SNPNT32 driver depends on the WinPcap® (download it from http://www.winpcap.org/install/default.htm

) to transmit and receive packets on the

Windows® system. To limit the number of symbols imported into the NT32 platform,

SnpNt32 call the functions in the SnpNt32Io dynamic library to transmit/receive packets. The SnpNt32Io library in turn consumes the service provided by WinPcap®.

To enable/test network functionality, following steps should be taken:

1) Install WinPcap application

2) Download SnpNt32Io dynamic library source code from https://networkio.tianocore.org/ , build it and generate SnpNt32Io.dll.

3) Add following drivers into Nt32Pkg.dsc's [Components] section

MdeModulePkg/Universal/Network/DpcDxe/DpcDxe.inf

MdeModulePkg/Universal/Network/ArpDxe/ArpDxe.inf

MdeModulePkg/Universal/Network/Dhcp4Dxe/Dhcp4Dxe.inf

MdeModulePkg/Universal/Network/Ip4ConfigDxe/Ip4ConfigDxe.inf

MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Dxe.inf

MdeModulePkg/Universal/Network/MnpDxe/MnpDxe.inf

50 June, 2009

4.5

4.5.1

MdeModulePkg/Universal/Network/Mtftp4Dxe/Mtftp4Dxe.inf

MdeModulePkg/Universal/Network/Tcp4Dxe/Tcp4Dxe.inf

MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Dxe.inf

Nt32Pkg/SnpNt32Dxe/SnpNt32Dxe.inf

4) Also add them into [FD.Fv_Recovery] section in Nt32Pkg.fdf file:

INF MdeModulePkg/Universal/Network/DpcDxe/DpcDxe.inf

INF MdeModulePkg/Universal/Network/ArpDxe/ArpDxe.inf

INF MdeModulePkg/Universal/Network/Dhcp4Dxe/Dhcp4Dxe.inf

INF MdeModulePkg/Universal/Network/Ip4ConfigDxe/Ip4ConfigDxe.inf

INF MdeModulePkg/Universal/Network/Ip4Dxe/Ip4Dxe.inf

INF MdeModulePkg/Universal/Network/MnpDxe/MnpDxe.inf

INF MdeModulePkg/Universal/Network/Mtftp4Dxe/Mtftp4Dxe.inf

INF MdeModulePkg/Universal/Network/Tcp4Dxe/Tcp4Dxe.inf

INF MdeModulePkg/Universal/Network/Udp4Dxe/Udp4Dxe.inf

INF Nt32Pkg/SnpNt32Dxe/SnpNt32Dxe.inf

5) Build Nt32 platform.

6) Copy SnpNt32Io.dll into Build/NT32/DEBUG_MYTOOLS/IA32/ directory.

7) To test the Network functionality, launch Nt32 emulate and enter "Internal shell".

The EFI application Ifconfig.efi and ping.efi are the commands to test network functionality.

Debugging in Emulation Environment

There are two major debugging methods: print debug messages, and single step by break pointer. Printing debug messages is a popular debug method and very simple, but single step by break point may be different in each emulated platform.

Print Debug Message

The DebugLib libray class defined in MdePkg provide useful interfaces such as

DEBUG()

,

ASSERT()

,

ASSERT_EFI_ERROR()

etc, which are easily used in a module's source code. For example:

51 June, 2009

DEBUG ((EFI_D_ERROR, "This is error debug information"))

DEBUG ((EFI_D_INFO, "This is help debug information"))

EFI_D_ERROR

,

EFI_D_INFO

indicates information level. To get more information level definition, reference MdePkg\Include\Libarry\DebugLib.h. For example:

#define DEBUG_INFO 0x00000040 // Verbose

#define DEBUG_ERROR 0x80000000 // Error

#define EFI_D_INFO DEBUG_INFO

#define EFI_D_ERROR DEBUG_ERROR

PcdDebugPrintErrorLevel

is used to control platform's debug information level. Its value equals sum of all valid information level. It can be customized in a platform's

DSC file. For example, for a platform to enable debug and info message, the value of

PcdDebugPrintErrorLevel

would be

0x80000040

.

4.5.2

Figure 10 Debug/Info message output

Single Step Debugging in Nt32 Emulate Platform

Put "

_asm int 3;

" at the location to be debugged.

When launching Nt32 emulate platform, Windows system default debugger is launched automatically and stops at the location of "

_asm int 3;

"

52 June, 2009

Figure 11 INT 3 is triggered

Click the "Cancel" button and system debuggers will be listed in following dialog.

Select the "New instance of Visual Studio 2005" if the emulation is built by Visual

Studio 2005.

53

Figure 12 Select System Debugger

June, 2009

4.5.3

Figure 13 Debugger is launched at first break point

Single Step Debugging in Unix Emulate Platform

Single step debugging in Unix emulates platforms is like the Nt32 emulated platform:

1. Put "

asm("int $3")

" at the location to be debugged

2.

3.

Enter $(WORKSPACE)/Build/Unix/DEBUG_ELFGCC/IA32/

ELF execution SecMain module should be loaded by GDB program in Unix host machine. For example: "

gdb SecMain

".

54 June, 2009

advertisement

Was this manual useful for you? Yes No
Thank you for your participation!

* Your assessment is very important for improving the workof artificial intelligence, which forms the content of this project

Related manuals

Download PDF

advertisement

Table of contents