EFI Shell

Release Notes

Version 0.91
June 29, 2005
EFI Shell Release Notes

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 © 1999–2005, Intel Corporation. All Rights Reserved.

ii June 2005 Version 0.91

 Revision History
Revision Revision History Date
0.1.0 Initial version 04/28/04
0.2.0 Beta release updates 06/29/04
0.3.0 Beta release patch updates 11/25/04
0.91.0 Beta release to Open Source 06/29/05

Version 0.91 June 2005 iii

 Contents
1 Introduction ...................................................................................................... 7
1.1 Overview ........................................................................................................................ 7
1.2 Conventions Used in This Document............................................................................. 7
1.2.1 Typographic Conventions................................................................................ 7
1.3 What’s New in the EFI Shell Version 1.0 ....................................................................... 8
1.4 System Requirement...................................................................................................... 8
1.5 Installation Instructions................................................................................................... 8
1.6 Known Issues of the EFI Shell Version 1.0 Beta Release ............................................. 9
2 EFI Shell Features .......................................................................................... 10
2.1 Consistent Mapping ..................................................................................................... 10
2.2 New Substitution Rules of Variable and Alias .............................................................. 12
2.3 Backward Compatibility Support .................................................................................. 13
2.4 Default Location of Startup.nsh Script File................................................................... 13
2.5 Ability to Support Accessing Maximum of 256 Arguments in Batch Scripts................. 13
2.6 Interruption of Execution of Commands, Applications and Scripts .............................. 14
2.7 Output Streaming Control ............................................................................................ 14
2.8 History Screen Support ................................................................................................ 14
2.9 Color Differentiation of Files and Directories................................................................ 14
2.10 New File Operation APIs for the EFI Shell Application Development .......................... 14
3 Known Issues ................................................................................................. 15
3.1 ‘cls’ doesn’t change the background color when changing the color value from 7 to 0 15
3.2 The cursor is not visible if editing a file when the background color is light gray ......... 15
3.3 ‘ipconfig –r’ cannot restart the PXE and DHCP settings .............................................. 15
3.4 ‘.nsh’ is the alias of the file ‘1.nsh’ in the framework .................................................... 15
3.5 ‘reset –s’ does not shutdown the machine as described in the help information ......... 16
3.6 In EFI1.02, the map name for a removed floppy still exists after ‘map –r’ ................... 16

Figures
Figure 2-1 Mapping table Showing Consistent Mapping Names...................................................... 11
Figure 2-2 New Variable & Alias Substitution Flow Chart.................................................................. 12

Tables

Version 0.91 June 2005 v

 1
Introduction
1.1 Overview
This document describes what new features the EFI Shell version 1.0 includes, the system
requirement, installation instructions and known issues of the EFI Shell version 1.0 beta release.

1.2 Conventions Used in This Document

This document uses the typographic and illustrative conventions described below.

1.2.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.
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. In addition, 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).

Version 0.91 June 2005 7

EFI Shell Release Notes

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

1.3 What’s New in the EFI Shell Version 1.0

z Consistent Mapping
z New substitution rules and implementation of variable and alias
z Backward compatibility support
z Default location for startup.nsh script file
z Ability to support accessing maximum of 256 arguments in batch scripts
z Interruption of execution of commands, applications and scripts
z Output streaming control
z History screen support
z Color differentiation of files and directories.
z New file operation APIs for the EFI Shell application development

1.4 System Requirement

IA-32 or Itanium®-based platforms that are powered by the EFI 1.10 Sample Implementation or the
Intel® Platform Innovation Framework for EFI (“the Framework”).

1.5 Installation Instructions

Installing the EFI Shell project is simple; copy the whole directory under the EDK's subdirectory
Sample. (Example: If the EDK is C:\EDK, then copy the Shell project to
C:\EDK\Other\Maintained\Application. To use this shell, you need to install Microsoft* tools.

8 June 2005 Version 0.91

 EFI Shell Features

Please refer to EFI Shell Developer’s Guide for the detailed instructions for the installation of
Microsoft* tools.

1.6 Known Issues of the EFI Shell Version 1.0 Beta Release
z ‘cls’ doesn't change the background color when changing the color value from 7 to 0
z The cursor is not visible if editing a file when the background color is light gray
z ‘ipconfig –r’ cannot restart the PXE and DHCP settings
z ‘.nsh’ is the alias of the file ‘1.nsh’ in framework
z 'reset -s' does not shutdown machine as described in the help information
z In EFI1.02, the map name for a removed floppy still exists after ‘map –r’

Version .91 June 2005 9

EFI Shell Release Notes

2
EFI Shell Features
2.1 Consistent Mapping
Conventional file system map names using the format ‘fsx’ retain the backward compatible
behavior of the shell command prompt. Examples of conventional mapping names are fs0, fs1, fs2,
fs3, etc. Conventional mapping names allow for easy typing at the shell command prompt, but
without consistent mapping.
Each mapped file system has two mapping names. One is the consistent mapping name—a new
feature—and the other is the conventional mapping name. Whenever the mapping name must
remain the same, a consistent mapping name must be used. There is no direct mapping relationship
between consistent mapping names and conventional mapping names.
Consistent mapping guarantees that file systems discovered during pre-boot will map to file system
names which remain consistent as long as the hardware configuration does not change. The
following are considered hardware configuration changes:
z Physical connection and/or number of controllers changes
z Changes of physical interface which the devices are connected to
In general, if a change of hardware is capable of producing child hardware devices, that
change should be considered a hardware configuration change. Examples include changes of
SCSI controllers, IDE controllers, USE hubs, etc. However, changing a USB flash storage disk
does not constitute a hardware configuration change, even though the consistent mapping name for
the file systems produced from this device may change. This is because the USB flash storage disk
change is unable to produce any child devices. It is a hardware configuration change of the USB
device that does not affect other USB devices.
Consistent mapping guarantees that platforms with exactly the same hardware configurations will
have exactly the same mapping names. This feature greatly helps in writing scripts used during
manufacturing processes.

10 June 2005 Version 0.91

 EFI Shell Features

Figure 2-1 shows a screen snapshot of a mapping table with consistent mapping names:

Figure 2-1 Mapping table Showing Consistent Mapping Names

In figure 2-1, f6 and f7 are consistent mapping names. Consistent mapping names may seem
strange and difficult to read, but they guarantee consistent mapping. Conventional mapping names
allow for easy typing at the shell command prompt, but without consistent mapping.
No functional difference exists between a file or directory referred by either the consistent mapping
name or the conventional mapping name. It is one item, but with two names which refer to the
same file or directory.
Please refer to the EFI Shell User’s Guide for the detailed usage of command ‘map’.

Version .91 June 2005 11

EFI Shell Release Notes

2.2 New Substitution Rules of Variable and Alias

The EFI Shell version 1.0 beta release has a re-designed substitution process of variables and
aliases. Figure 2-2 illustrates the new processing flow:

Figure 2-2 New Variable & Alias Substitution Flow Chart

In previous versions, the shell attempted to translate the variable as a positional argument at first.
One major change is that now the shell attempts to translate the variable as an environment variable
at first. This change allows for support of those environment variables whose leading characters
are numbers.
Users can define the way in which a variable is interpreted because of a change in the processing of
quotation marks.
Suppose an environment variable named ‘123abc’ whose content is “hello”, and script ‘a.nsh’ like
this
echo %123abc%.
The result of execution of ‘a.nsh 123’ will be:
hello.
Suppose the use of a pair of quotation marks to define the boundary inside the substitution is
performed:
echo “%1”23abc%.
The result of execution of ‘a.nsh 123’ will be:
12323abc.

12 June 2005 Version 0.91

 EFI Shell Features

In general, a pair of quotation marks defines the boundary of the unit inside which variable
substitution is performed. The substitution will not be performed across the boundary.
The new shell has a stricter rule of variables names, please refer to EFI Shell User’s Guide for
detailed information.

2.3 Backward Compatibility Support

The new shell has some significant changes in command line processing and variable substitution.
A backward-compatible running mode provides to be compatibility with the old shell
environments. The new shell uses a shell-reserved environment variable to control and switch the
running mode. The default running mode of the new shell is the enhanced shell mode, in which all
the new shell features will function. Users can change the running mode by using command ‘set’ to
change the value of shell-reserved variable ‘efishellmode’ to preferred mode. This release supports
mode 1.1.1 (backward-compatible mode) and mode s1.1.2 (enhanced shell mode). For example:
- To set the running mode to backward-compatible mode:
Shell> set –v efishellmode 1.1.1
- To set the running mode to enhanced shell mode:
Shell> set –v efishellmode 1.1.2

The default running mode at the beginning of the execution of a script is the backward-compatible
mode. In backward-compatible mode, all the syntaxes of commands and their behavior remain the
same as those of previous EFI Shells. This allows smooth execution of old shell scripts without any
modifications. It also forces a requirement upon the composition of new scripts, which must place
the command ‘set –v efishellmode 1.1.x’ at the very beginning of scripts to set the running mode
preference. The modification of running mode in child scripts does not affect the running mode of
parent scripts.
Backward compatibility for external commands and applications is not guaranteed because of the
diversity of external commands and applications across several different EFI conformant
implementations (EFI 1.1, EFI 1.02, etc). However, most external commands and applications
should run smoothly in backward compatible mode without any modification.

2.4 Default Location of Startup.nsh Script File

A new shell launched by loading a shell image file on a file system looks for the startup.nsh script
file in the directory where it was launched. If startup.nsh is found it then executes. If startup.nsh is
not found, then search continues in the paths specified by variable path. This feature does not cover
instances in which the shell launches from FV storage.

2.5 Ability to Support Accessing Maximum of 256 Arguments in

Batch Scripts
The script command ‘shift’ is a new addition to the shell. Users can access a maximum of 10
simultaneous arguments in scripts, but users can rotate the arguments with the command ‘shift’. A
total of 256 arguments are supported for scripts.

Version .91 June 2005 13

EFI Shell Release Notes

2.6 Interruption of Execution of Commands, Applications and

Scripts
By pressing ‘ESC’ key, users can terminate the execution of internal commands, external
commands, and scripts. Applications delivered by Intel should have the ability to be interrupted
during execution but this functionality is not guaranteed for applications developed by third-parties.

2.7 Output Streaming Control

By pressing ‘TAB’ key, users can pause and resume the on-going output in console.

2.8 History Screen Support

By using ‘PageUp’ and ‘PageDown’ keys, users can browse the history screen information at most
by 3 screens.

2.9 Color Differentiation of Files and Directories

In the EFI Shell’s enhanced shell mode, executable files (with suffix .nsh or .efi) are displayed in
bright-green and directories are displayed in blue. This color coding helps users to distinguish
executable files and directories. This feature only functions in enhanced shell mode.

2.10 New File Operation APIs for the EFI Shell Application
Development
. EFI Shell application developers can manipulate files and directories in programs more efficiently
and easily than before using new APIs. These have an easy-to-use interface definition, similar to
that in Microsoft Windows*.

14 June 2005 Version 0.91

 3
Known Issues
3.1 ‘cls’ doesn’t change the background color when changing the
color value from 7 to 0
Description:
First, change the background color by executing command ‘cls 7’. Then change the background
color by executing command ‘cls 0’. As a result, the background color is not changed to black.
Notes:
This only happens on the EFI1.1 sample implementation. An investigation discovered that this is
not a bug in the EFI Shell. It is a bug in the Console module of EFI1.1 sample implementation.

3.2 The cursor is not visible if editing a file when the background
color is light gray
Description:
When running the command ‘edit’ with the background color set to light gray, the cursor in ‘edit’ is
not visible because the color of the cursor is the same as the background color.
Notes:
This is not a bug of the EFI Shell. An investigation discovered that this is a bug in the Graphic
Console module in the framework.

3.3 ‘ipconfig –r’ cannot restart the PXE and DHCP settings
Description:
On Itanium® based platforms initially executing ‘ipconfig –r’ starts the PXE base code for the first
time. A second execution fails with the error message ‘ipconfig: DHCP start error – Already
Started’.
Notes:
This is not a bug of the EFI Shell. An investigation discovered that this caused by defects in the
PXE base code of the framework for Itanium® based platforms.

3.4 ‘.nsh’ is the alias of the file ‘1.nsh’ in the framework

Description:
If a user creates a script file named ‘.nsh’, then tries to execute ‘1.nsh’ the file ‘.nsh’ will execute
successfully.
Notes:
This is not a bug of the EFI Shell. An investigation found that the root cause is inside the FAT
module of the underlying system.

Version 0.91 June 2005 15

EFI Shell Release Notes

3.5 ‘reset –s’ does not shutdown the machine as described in the
help information
Description:
During execution of the command ‘reset –s’ the system will reboot on the EFI1.1 sample
implementation. However, the help information says that the system should be shutdown.
Notes:
This is not a bug of the EFI Shell. The ‘reset’ command calls the underlying system service to
perform the shutdown operation, so this is a defect in the EFI1.1 sample implementation.

3.6 In EFI1.02, the map name for a removed floppy still exists after
‘map –r’
Description:
On an IA-32 server platform running EFI1.02, the map name for a floppy will still exist after the
floppy is removed and the command ‘map –r’ is executed.
Notes:
This is not a bug of the EFI Shell. An investigation discovered that this is a platform specific defect
of the IA-32 server platform.

16 June 2005 Version 0.91