The UEFI Shell in Detail

ABSTRACT: With the advent of an environment like UEFI, it would stand to reason
that a common concept like a shell would arise. Conceptually, a shell is built
around some aspect of a rather complex system and provides simplified
abstractions for users to gain access to the underlying infrastructure. These users
could be pieces of software (such as scripts and applications) or they could be
humans interacting with the shell in an interactive manner. A platform running a
BIOS that is UEFI compliant is what might be characterized as the rather
complex item that a UEFI Shell is built around. This article talks about various
concepts such as how the UEFI Shell is abstracting the underlying UEFI
compatible BIOS infrastructure, how certain concepts such as localization are
accomplished within the shell, and the various manners in which a user can
interact with the shell.

Figure 1 The program launching and script support of the UEFI Shell is providing an
alternative to what users of DOS and other shells have been using for a very long time.

The UEFI Shell is unusual in that it is not a shell that is a client of an operating
system, but is actually considered a BIOS extension. This puts the shell on par
with components that traditionally would be launched prior to an operating
system such as an add-in devices option ROM. Where the UEFI Shell is launched
from is largely irrelevant, but for many platform vendors, the underlying feature
set and size are important considerations since in some cases the shell may
actually be contained in the platforms FLASH device.

What Is Contained in the UEFI Shell?

With the consideration that size and features are important to the platform

Copyright 2009 Intel Corporation 1

vendor, the features that are provided by a UEFI Shell are likely even more
important to the users of the shell. With this in mind, the concept of having
varying levels of UEFI Shell support became very important along with the ability
for a client of the UEFI Shell to determine what support was being provided.

What Kind of Shell Do You Have?

The concept that a UEFI Shell can vary its support can be worrisome to some, but
suffice it to say that this support is both predictable and easily dealt with. The
shell is composed of two primary classes of contents:
Programmatic Shell Environment. This environment is guaranteed to remain
available regardless of what underlying Shell level is supported by a
platform that purports to support the UEFI Shell. It is composed of the
calling interfaces that shell applications can use.
Script Shell Environment. This environment is the one that supports the
launching and interpreting of shell scripts. The biggest variation that one
might witness between shell support levels is the enumeration of
commands that are supported in a given support level.

The shell contains an environment variable known as the shellsupport variable.

This variable can be used by shell applications as well as shell scripts to
determine what the underlying UEFI Shells function support is.

In Table 1, the various levels of shell support are listed. This illustrates how at its
simplest, the shell may be used strictly for purposes of shell applications to be
launched (no scripting services). At level 1 basic scripting support is introduced,
while level 2 simply adds a few more commands and functionality as well. In level
3, the concept of being interactive is introduced. For people who are familiar
with the C: prompt from DOS, this interactive mode is similar in concept.
Whereas in level 2 when a script was finished processing, the shell would
terminate, in level 3 the shell provides a mode that allows the user to type at the
UEFI Shell prompt.

Copyright 2009 Intel Corporation 2

Table 1 UEFI Shell Levels of Support

Level Name Execute()/ PATH ALIAS Interactive Commands

Scripting/ ? ? ?
startup.nsh
0 Minimal No No No No None
1 Scripting Yes Yes No No for, endfor, goto, if, else, endif,
shift, exit
2 Basic Yes Yes Yes No attrib, cd, cp, date*, time*, del,
load, ls, map, mkdir, mv, rm,
reset, set, timezone*
3 Interactive Yes Yes Yes Yes alias, date, echo, help, pause,
time, touch, type, ver, cls,
timezone
Note: * Non-interactive form only

Execute()/Scripting/startup.nsh. Support indicates whether the Execute()

function is supported by the EFI_SHELL_PROTOCOL, whether or not batch
scripts are supported and whether the default startup script startup.nsh is
supported.
PATH. Support determines whether the PATH environment variable will be
used to determine the location of executables.
ALIAS. Support determines whether the ALIAS environment variable will be
used to determine alternate names for shell commands.
Interactive. Support determines whether or not an interactive session can
be started.

What!? No Shell? No Problem!

In many usage cases, bootable media is used to launch scripts or other utilities.
Historically, the common components for bootable (removable) media were a
floppy disk with DOS on it, some scripts, and possibly some executable utilities.
DOS itself had some inherent limitations associated with a relatively weak API set
compared to more modern environments, limited access to certain memory
ranges, and other miscellaneous issues with more modern hardware
environments. With the advent of UEFI systems, the same infrastructure can be
launched as was done before (a DOS bootable image), but with relatively no
discernable advantageit simply preserves what was previously working.
However, many users of bootable media (such as manufacturing operations.
diagnostics, and so on) are actively porting their DOS solutions so that they can
leverage the underlying UEFI BIOS environments.

Coupling UEFI-based BIOS with the UEFI Shell, a user can achieve a true
advancement in what was done in prior solutions since any of the prior limitations
associated with the DOS environment have been eliminated. In fact, since the

Copyright 2009 Intel Corporation 3

infrastructure within which the UEFI Shell runs is robust, the utilities that are
launched can fully leverage all of the UEFI BIOS APIs as well as the UEFI Shell
infrastructure APIs in addition to running various sets of UEFI Shell scripts.

In some situations a users shell requirements are not compatible with what the
platform currently supports. For those who are trying to provide solutions
(utilities, scripts, and so on) that leverage the UEFI Shell and its environment,
there are three situations to consider:

When the built-in UEFI Shell does not meet the solutions requirements. If
the UEFI Shells shellsupport level is insufficient for the solution providers
needs, a copy of a UEFI Shell might need to be carried with the solution
itself.
When there is no built-in UEFI Shell. There may be cases where the
platform does not have a UEFI Shell built in as part of its feature set. With
this in mind, the solution provider will want to carry a copy of a UEFI Shell
along with its solutions carried on the providers media.
When the platform is not compatible with UEFI. Even though UEFI BIOS is
being adopted in a rapid manner in the industry, some platforms will have
no underlying UEFI support. To address this situation, Intel has provided to
the open source community something known as the Developers UEFI
Emulation (DUET). DUET is designed to provide a UEFI environment on a
non-UEFI pre-boot system. This is achieved by creating an UEFI file image
for a bootable device, and then booting that image as a legacy boot. On
this same bootable device/media a solution provider can, in addition to
providing UEFI emulation, provide a copy of the shell environment as well
as any other material the solution provider desires.
c This DUET infrastructure is made available for download on the
companion Web site associated with the book Harnessing the UEFI Shell
(Intel Press) as well as being made available on the open source Web
site www.tianocore.org.

Figure 2 illustrates three common usage scenarios for the UEFI Shell. The first is
when the platform contains all the needed support for the script/utility solution,
the second is when the underlying platform shell support is insufficient, and the
third is when the platform is not UEFI compatible.

Copyright 2009 Intel Corporation 4

Figure 2 Different UEFI Shell usage models. One built within the platform, and the others
provided by a bootable target.

Programmatic Shell Environment

Interfaces that are callable from binary programs are what form the UEFI Shell
services. These services are what provide simplified access to various shell
features and also simplify the interactions that shell clients would have with the
underlying UEFI infrastructure. Figure 3 provides a high level view of what the
interactions would be between the UEFI infrastructure, Shell interfaces, and Shell
clients.

Copyright 2009 Intel Corporation 5

Figure 3 The architectural view of the UEFI Shell and the underlying platform infrastructure.

Using UEFI Shell Commands

Two classes of operations occur within the UEFI Shell environment. One class of
operations runs a script file that uses built-in shell commands (such as DIR and
COPY) and the other class of operations are binary programs that when launched
can use a variety of underlying services.

An example of this interaction would be when a script executes a DIR shell

command. When doing this, the following steps occur:
DIR command in a script file is interpreted by the Shell Interpreter.
Shell Interpreter then calls a Shell Protocol function such as OpenRoot().
The Shell Protocol would then call a UEFI service such as the UEFI Simple
File System Protocols OpenVolume() routine.
The UEFI Simple File System Protocol would then call other routines, which
would ultimately interact directly with the hardware and return the
requested information.

Copyright 2009 Intel Corporation 6

Figure 4 shows how a script that uses a UEFI Shell command will in turn interact
with both the UEFI Shell interfaces and UEFI BIOS interfaces to achieve what is
requested. It also shows that Shell applications would also interact with the
underlying UEFI Shell and UEFI BIOS interfaces.

Figure 4 UEFI Shell interpreter processing a script file

For more information about the UEFI Shell, please refer to the book Harnessing
the UEFI Shell by Michael Rothman, Tim Lewis, Vincent Zimmer and Robert Hale.

About the Authors

Michael Rothman is a Senior Staff Engineer in the Software and Services Group
at Intel and has nearly 20 years of operating system and embedded software
development experience. His career has spanned the gamut of being the
development lead for the PC DOS product, development on retail and embedded

Copyright 2009 Intel Corporation 7

versions of DOS and OS/2, and working on both legacy and UEFI BIOS
codebases.

Tim Lewis is the Chief Architect at Phoenix Technologies Ltd. for all UEFI-based
products, with over 20 years experience in BIOS development. He currently
serves on the UEFI board of directors.

Vincent Zimmer is a Principal Engineer in the Software and Services Group at

Intel. Vincent has over 17 years experience in embedded software spanning real-
time control, RAID, and BIOS/boot firmware. In addition to contributing to UEFI
implementations on Tianocore.org, Vincent has written specifications in the UEFI
Forum, Intel Framework, the Internet Engineering Task Force (IETF) and the
Trusted Computing Group.

Robert Hale is a Principal Engineer in the Software and Services Group at Intel.
After stints doing real-time operating systems and networking, he has been a
BIOS developer since 1986. Robert was one of the original Framework (now PI)
architects, leading a firmware team that deployed the first Framework-based
product for EFI.

Copyright 2009 Intel Corporation. All rights reserved.

This article is based on material found in book Harnessing the UEFI Shell by
Michael Rothman, Tim Lewis, Vincent Zimmer and Robert Hale. Visit the Intel
Press web site to learn more about this book:
http://www.intel.com/intelpress/sum_eshl.htm

No part of this publication may be reproduced, stored in a retrieval system

or transmitted in any form or by any means, electronic, mechanical,
photocopying, recording, scanning or otherwise, except as permitted under
Sections 107 or 108 of the 1976 United States Copyright Act, without either
the prior written permission of the Publisher, or authorization through
payment of the appropriate per-copy fee to the Copyright Clearance Center,
222 Rosewood Drive, Danvers, MA 01923, (978) 750-8400, fax (978) 750-
4744. Requests to the Publisher for permission should be addressed to the
Publisher, Intel Press, Intel Corporation, 2111 NE 25 Avenue, JF3-330,
Hillsboro, OR 97124-5961. E-mail: intelpress@intel.com .

Copyright 2009 Intel Corporation 8