EFI Shell

Getting Started Guide

Version 0.31
June 27, 2005

Information in this document is provided in connection with Intel products. No license, express or implied, by estoppel or
otherwise, to any intellectual property rights is granted by this document. Except as provided in Intel's Terms and Conditions
of Sale for such products, Intel assumes no liability whatsoever, and INTEL DISCLAIMS ANY EXPRESS OR IMPLIED
WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES
RELATING TO FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT,
COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. Intel products are not intended for use in medical, life
saving, or life sustaining applications. Intel may make changes to specifications and product descriptions at any time,
without notice.
This document contains information on products in the design phase. The information here is subject to change without
notice. Do not finalize a design with this information.
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 as well as the software described in it is furnished under license and may only be used or copied in
accordance with the terms of the license. The information in this manual is furnished for informational use only, is subject to
change without notice, and should not be construed as a commitment by Intel Corporation to update or revise the
information or document. Intel Corporation assumes no responsibility or liability for any errors or inaccuracies that may
appear in this document or any software that may be provided in association with this document.
This document provides website addresses for certain third party websites. The referenced sites are not under the control of
Intel and Intel is not responsible for the content of any referenced site or any link contained in a referenced site. Intel does
not endorse companies or products for sites which it references. If you decide to access any of the third party sites
referenced in this document, you do this entirely at your own risk.
* Other names and brands may be claimed as the property of others.
Intel, the Intel logo, and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United
States and other countries.
Copyright 19992005, Intel Corporation. All Rights Reserved.

Version .031

June 29, 2005

ii

Revision History
Revision

Version 0.31

Revision History

Date

0.10

Initial version

04/28/04

0.20

Beta release updates

06/29/04

0.30

Beta release patch updates

06/15/05

0.31

Additional editing for external release

6/27/05

June 27, 2005

iii

Contents
1 Introduction ...................................................................................................... 7
1.1
1.2
1.3
1.4

Summary........................................................................................................................ 7
Overview ........................................................................................................................ 7
Glossary ......................................................................................................................... 8
Conventions Used in This Document............................................................................. 8
1.4.1
Typographic Conventions................................................................................ 8

2 Development System Setup .......................................................................... 10

2.1
2.2

Install Tools .................................................................................................................. 10

Install EFI Developer Kit (EDK).................................................................................... 10

3 Quick Start Guide ........................................................................................... 11

3.1

3.2
3.3
3.4

Downloading Source Code .......................................................................................... 11

3.1.1
Downloading The EFI Shell ........................................................................... 11
3.1.2
Downloading The EDK .................................................................................. 11
Build EFI Shell.............................................................................................................. 12
Build An EFI Shell Application...................................................................................... 13
Add An EFI Shell Application To Shell Binary.............................................................. 14

4 Directory Structure of the Shell .................................................................... 17

4.1

Description of Directory Structure ................................................................................ 17

Figures
Tables
Table 1-1. Typographic and Illustrative Conventions...................................................................8
Table 4-1 Directory Structure ................................................................................................................. 17

Version 0.31

June 27, 2005

1
Introduction
1.1

Summary
This document provides instructions for using the EFI Shell. In order to build the EFI Shell the EFI
Developer Kit (hereafter referred to as EDK) will also need to be downloaded from
www.TianoCore.org and built
It is intended to be a reference for those people just starting EFI Shell development.

1.2

Overview
This document does not try to explain all of the EFI Shell or the EDK. That information is available
at www.TianoCore.org under TianoCore FAQ and in other material available at the Web site.
Instead, this document is about downloading the code, building it and running it.
Other documentation is available at www.TianoCore.org for the EFI Shell includes the following:
1. EFI Shell Users Guide.Doc - A Users Guide detailing how to use the EFI Shell commands
and other EFI Shell applications
2. EFI Shell Developers Guide.Doc A guide with detailed instructions for developing and
building an EFI shell application using the EFI Shell Package

Version 0.31

June 27, 2005

1.3

Glossary
This document uses the typographic and illustrative conventions described below.
Table 1-1. Typographic and Illustrative Conventions

Term

Definition

EDK

EFI Developer Kit. (needed to build the EFI-Shell)

EDK_SOURCE

An environmental variable that specifies the base directory where

the EFI source files are located. Typically this directory will be
C:\TianoCore\Edk.

EFI

Extensible Firmware Interface

EFI Driver

Modular firmware code that supports chipset or platform features

and is reusable in multiple system contexts. Code relating to a
device or function that is run in the Pre OS phase of execution.
(Formerly known as an option ROM.)

Shell

EFI Shell is a simple, interactive command interpreter that allows

EFI device drivers to be loaded, EFI applications to be launched,
and operating systems to be selected for boot.

1.4

Conventions Used in This Document

This document uses the typographic and illustrative conventions described below.

1.4.1

Typographic Conventions

This document uses the typographic and illustrative conventions described below:
Plain text

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

Plain text (blue)

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

Bold

In text, a Bold typeface identifies a processor register name. In other

instances, a Bold typeface can be used as a running head within a
paragraph.

Italic

In text, an Italic typeface can be used as emphasis to introduce a new

term or to indicate a manual or specification name.

BOLD Monospace

Computer code, example code segments, and all prototype code

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

Version .031

June 29, 2005

Bold Monospace

In the online help version of this specification, words in a

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

Italic Monospace

In code or in text, words in Italic Monospace indicate placeholder

names for variable information that must be supplied (i.e., arguments).

Plain Monospace

In code, words in a Plain Monospace typeface that is a dark red

color but is not bold or italicized indicate pseudo code or example code.
These code segments typically occur in one or more separate paragraphs.

text text text

In the PDF of this specification, text that is highlighted in yellow

indicates that a change was made to that text since the previous revision
of the PDF. The highlighting indicates only that a change was made
since the previous version; it does not specify what changed. If text was
deleted and thus cannot be highlighted, a note in red and highlighted in
yellow (that looks like (Note: text text text.)) appears where the deletion
occurred.

See the master Framework glossary in the Framework Interoperability and Component
Specifications help system for definitions of terms and abbreviations that are used in this document
or that might be useful in understanding the descriptions presented in this document.
See the master Framework references in the Interoperability and Component Specifications help
system for a complete list of the additional documents and specifications that are required or
suggested for interpreting the information presented in this document.
The Framework Interoperability and Component Specifications help system is available at the
following URL:
http://www.intel.com/technology/framework/spec.htm

Version .031

June 29, 2005

2
Development System Setup
This section describes the steps that are necessary to initially set up the local system in preparation
for building an EFI Shell binary and application.

2.1

Install Tools
Several Microsoft tools are used to build the EDK and the EFI-Shell source tree. The following
tools must be installed on the development system.
Microsoft Windows 2000 or Microsoft Windows XP* operating system
For 32-bit Intel architecture (IA-32) platform development:
Microsoft Visual Studio .NET* 2003 Professional (7.1)
For Intel Itanium processor family development:
Microsoft* C/C++ Optimizing Compiler Version 13.10.2240.8 for IA-64 in the Microsoft Windows
Server* 2003 DDK (Build 3790).
If compiling for targets based on Itanium architecture, use NMAKE.EXE, LINK.EXE and
LIB.EXE from the Microsoft Windows Server 2003 DDK (Build 3790).

2.2

Install EFI Developer Kit (EDK)

The EFI Shell project is a sub-project of EDK. It was created for building EFI Shell and
user-defined EFI Shell applications. To use the EFI Shell, users should install the EFI Developer
Kit (EDK) first.
Each EFI Shell snapshot is developed and tested on certain EDK snapshot. This EDK snapshot
name is described in a text file - EDK_Snapshot.txt which can be found with the file shell.inf.
To use the EFI Shell, we strongly suggest users download and install the EDK snapshot that
corresponds to the Shell snapshot desired. Other EDK snapshots, are not tested with this EFI shell
snapshot, and entail potential risk.
Please refer the EDK Getting Started Guide.pdf
(http://edk.tianocore.org/files/documents/16/105/file_105.dat?filename=Edk%20Getting%20Starte
d%20Guide%2e%30%2e%34%31%2epdf) to install the EDK.

Version .031

June 29, 2005

10

3
Quick Start Guide
This quick start guide assumes readers have installed the EFI Developer Kit (EDK), can build the
NT32 tip and IPF tip, and can run the Nt32 emulation.

3.1

Downloading Source Code

The first step is to download the source code from www.TianoCore.org. Currently users need to
register and obtain a login to access the source.

3.1.1

Downloading The EFI Shell

Directions for downloading source using the Web site:

1.
2.
3.
4.
5.
6.
7.
8.

3.1.2

Log on to www.TianoCore.org.
Once logged in, click the Projects tab near the upper left corner of the page.
Click on efi-shell in Name column of the Projects folder.
Under Projects >> efi-shell, there is a Project tools box (upper left of the page). In this box,
click on Documents & files.
Under Documents & files >> efi-shell, click on Releases. Three subdirectories should show up:
Development Snapshots Official Releases and Snapshot/Release Notes..
Click Development Snapshots.
At the Development Snapshots page pick the one with the latest date and click on it. Its a Zip
file so it should automatically launch a decompress program.
Extract the Zip file to the EFI Shell directory. For this example: extract to C:\Shell.

Downloading The EDK

In order to build the EFI Shell, EDK will also need to be downloaded from www.TianoCore.org
Directions for downloading EDK source using the Web site:
1. Click the Projects tab near the upper left corner of the page.
2. Click on edk in Name column of the Projects folder.
3. Under Projects >> edk, there is a Project tools box (upper left of the page). In this box, click on
Documents & files.
4. Under Documents & files >> edk, click on Releases. Two subdirectories should show up:
Development Snapshots and Official Releases.
5. Click Development Snapshots.
6. Under Development Snapshots, pick the snapshot mentioned in the EFI Shells
EDK_Snapshot.txt and click on it. Its a ZIP file which should automatically launch a
decompress program (WinZip).
7. Extract the Zip file to the EDK directory. For this example, extract to C:\EDK.

Version .031

June 29, 2005

11

8. Copy the EFI Shell from C:\Shell to

C:\EDK\Other\Maintained\Application\Shell.

3.2

Build EFI Shell

To build the EFI Shell, users should perform the following steps:
Suppose the EDK is located at C:\EDK and the source code of the shell is located at
C:\EDK\Other\Maintained\Application\Shell. In this instance the .inf file of
shell is C:\EDK\Other\Maintained\Application\Shell\Shell.inf.

To build an IA-32 version of EFI Shell:

Open the description file C:\EDK\Sample\Platform\Nt32\Build\Nt32.dsc
Replace component
"Other\Maintained\Application\Shell\Bin\Shell.inf" with
"Other\Maintained\Application\Shell\Shell.inf" like this:
[Components]

#Other\Maintained\Application\Shell\Bin\Shell.inf
Other\Maintained\Application\Shell\Shell.inf

Type the command:

Cd C:\EDK\Sample\Platform\Nt32\Build
Set the environment variable:
C:\EDK\Sample\Platform\Nt32\Build>Set EDK_SOURCE=C:\EDK
Build:
C:\EDK\Sample\Platform\Nt32\Build>nmake
To build an Itanium architecture version of EFI Shell:
Open the description file C:\EDK\Sample\Platform\IPF\Build\IPF.dsc
Replace component
"Other\Maintained\Application\Shell\Bin\Shell.inf" with
"Other\Maintained\Application\Shell\Shell.inf" like this:
[Components]

#Other\Maintained\Application\Shell\Bin\Shell.inf
Other\Maintained\Application\Shell\Shell.inf

Type the command:

Cd C:\EDK\Sample\Platform\IPF\Build
Set the environment variable:

Version .031

June 29, 2005

12

C:\EDK\Sample\Platform\IPF\Build>Set EDK_SOURCE=C:\EDK
Build:
C:\EDK\Sample\Platform\IPF\Build>nmake

3.3

Build An EFI Shell Application

Suppose the EDK is located at C:\EDK and the source code of an application named Edit is
located at C:\EDK\Other\Maintained\Application\Shell\Edit. In this instance the
.inf file of Edit is
C:\EDK\Other\Maintained\Application\Shell\Edit\Edit.inf.
To build an IA-32 version of Edit:
Open the description file C:\EDK\Sample\Platform\Nt32\Build\Nt32.dsc
Add:
Other\Maintained\Application\Shell\Library\EfiShellLib.inf
To the [Libraries.Platform] section, like this:
[Libraries.Platform]
Other\Maintained\Application\Shell\Library\EfiShellLib.inf

Add:
Other\Maintained\Application\Shell\Edit\Edit.inf

FV=NULL

To the [Components] section, like this:

[Components]

#Other\Maintained\Application\Shell\Bin\Shell.inf
Other\Maintained\Application\Shell\Shell.inf
Other\Maintained\Application\Shell\Edit\Edit.inf FV=NULL

Type the command:

Cd C:\EDK\Sample\Platform\Nt32\Build
Set the environment variable:
C:\EDK\Sample\Platform\Nt32\Build>Set EDK_SOURCE=C:\EDK
Build:
C:\EDK\Sample\Platform\Nt32\Build>nmake
The applications binary is:
C:\EDK\Sample\Platform\Nt32\Build\IA32\Edit.efi
To build an Itanium architecture version of Edit:
Open the description file C:\EDK\Sample\Platform\Ipf\Build\Ipf.dsc

Version .031

June 29, 2005

13

Add:
Other\Maintained\Application\Shell\Library\EfiShellLib.inf
To the [Libraries.Platform] section, like this:
[Libraries.Platform]
Other\Maintained\Application\Shell\Library\EfiShellLib.inf

Add:
Other\Maintained\Application\Shell\Edit\Edit.inf

FV=NULL

To the [Components] section, like this:

[Components]

#Other\Maintained\Application\Shell\Bin\Shell.inf
Other\Maintained\Application\Shell\Shell.inf
Other\Maintained\Application\Shell\Edit\Edit.inf FV=NULL

Type the command:

Cd C:\EDK\Sample\Platform\Ipf\Build
Set the environment variable:
C:\EDK\Sample\Platform\Ipf\Build>Set EDK_SOURCE=C:\EDK
Build:
C:\EDK\Sample\Platform\Ipf\Build>nmake
The applications binary is:
C:\EDK\Sample\Platform\Ipf\Build\Ipf\Edit.efi

3.4

Add An EFI Shell Application To Shell Binary

Follow the steps below to switch an application to an internal command:
1. Put all the files of your external command (or application) under a sub-directory of the EFI
Shell source root.
For example,
The root directory of the EDK is C:\EDK.
The shell source is C:\EDK\Other\Maintained\Application\Shell.
The application source is C:\EDK\Other\Maintained\Application\Shell\Edit.
2. Add lines into the section sources.common of the shell.inf that is located under the
EFI Shell source root directory to include all of the source files of your external command.
For example:
Open C:\EDK\Other\Maintained\Application\Shell\Shell.inf:
Add code like this:
[sources.common]

Version .031

June 29, 2005

14

...
Edit\EditStrings.uni
Edit\main.c
Edit\libFileBuffer.c
Edit\libEditor.c
Edit\libTitleBar.c
Edit\libStatusBar.c
Edit\libInputBar.c
Edit\libMenuBar.c
Edit\libMisc.c
...

The Edit at the beginning of the above nine lines indicates the path relative to the EFI
Shell source directory.
If your external command (or application) uses any .h files, add lines into the section
includes.common to indicate where the .h files can be found. For example, if file
Editor.h is under C:\EDK\Other\Maintained\Application\Shell\Edit,
then:
[includes.common]
...
$(EDK_SOURCE)\Other\Maintained\Application\Shell\Edit

Macro EDK_SOURCE represents the root directory of the EDK. It should be followed by
the relative path from the root where the .h files can be found.
3. In file source
C:\EDK\Other\Maintained\Application\Shell\shellenv\cmddisp.c,
declare the entry point function and line help function of your external command ahead of the
SEnvInternalCommands table. It should look like this:
...
EFI_STATUS
InitializeEFIEditorGetLineHelp (
OUT CHAR16
**Str
);
EFI_STATUS
InitializeEFIEditor (
IN EFI_HANDLE
IN EFI_SYSTEM_TABLE
);
)
struct {

Version .031

ImageHandle,
*SystemTable

June 29, 2005

15

SHELLENV_INTERNAL_COMMAND Dispatch;
CHAR16
*Cmd;
SHELLCMD_GET_LINE_HELP
GetLineHelp;
}
SEnvInternalCommands[] = {
4. Add an entry for your external command into the SEnvInternalCommands table using the
following values in this order: the entry point function, the internal command name, and the
line help function. You must add the entry inside the #ifdef EFI_MONOSHELL#endif
block. It should look like this:
...
InitializeEFIEditor,
L"edit",
InitializeEFIEditorGetLineHelp,
#endif
{
NULL
}
};
5. After building the EFI Shell, your external command should have been added as an internal
command.

Version .031

June 29, 2005

16

4
Directory Structure of the Shell
4.1

Description of Directory Structure

The top-level directory structure for the Shell is shown below table and described in the follow
column.
Table 4-1 Directory Structure

Shell\ Shell source code.

Library\ Shell Library Source Code.
inc\ Shell Include files.
shellenv\ Shell core code.
newshell\ New shell source code.
attrib\ Command attrib source code.
cls\ Command cls source code.
comp\ Command comp source code.
cp\ Command cp source code.
date\ Command date source code.
dblk\ Command dblk source code.
devices\ Command devices source code.
DeviceTree\ Command devtree source code.
dmem\ Command dmem source code.
dmpstore\ Command dmpstore source code.
drivers\ Command drivers source code.
drvcfg\ Command drvcfg source code.
drvdiag\ Command drvdiag source code.
edit\ Command edit source code.
EfiCompress\ Command eficompress source code.
EfiDecompress\ Command efidecompress source code.
err\ Command err source code.

Version .031

June 29, 2005

17

guid\ Command guid source code.

hexedit\ Command hexedit source code.
IpConfig\ Command ipconfig source code.
load\ Command load source code.
LoadPciRom\ Command loadpcirom source code.
ls\ Command ls source code.
mem\ Command mem source code.
memmap\ Command memmap source code.
mkdir\ Command mkdir source code.
mm\ Command mm source code.
mode\ Command mode source code.
mount\ Command mount source code.
mv\ Command mv source code.
openinfo\ Command openinfo source code.
pci\ Command pci source code.
reset\ Command reset source code.
rm\ Command rm source code.
sermode\ Command sermode source code.
SmbiosView\ Command smbiosview source code.
stall\ Command stall source code.
TelnetMgmt\ Command telnetmgmt source code.
time\ Command time source code.
touch\ Command touch source code.
type\ Command type source code.
tzone\ Command tzone source code.
unload\ Command unload source code.
ver\ Command ver source code.
vol\ Command vol source code.

Version .031

June 29, 2005

18

Version .031

June 29, 2005

19