EFI Shells and Scripting

Introduction

Extensible firmware interface (EFI) brings new flexibility and opportunities to users by allowing them to work in the layer between their OS and BIOS, without altering either one. This paper explains how to use EFI shell commands, create a script file and set up the boot menu with shells and scripts. In addition, this paper demonstrates dual boot selection for the 64-bit Red Hat Linux* 7.1 and 64-bit Microsoft Windows* XP Professional operating systems.

EFI Shell Commands

Table 1. EFI 0.9912.29 shell commands

CommandsDescriptions
help [-b] [internal command]Displays this help
guid [-b] [sname]Lists known GUID (Global Unique Identifiers)
set [-bdv] [sname] [value]Gets or sets environment variable
alias [-bdv] [sname] [value]Gets or sets alias settings
dh [-b] [-p prot_id] | [handle]Dumps handle information
unload [-nv] HandleIndexUnloads a protocol image
map [-bdvr] [sname[:]] [handle]Maps shortname to device path
mount BlkDevice [sname[:]]Mounts a file system on a block device
cd [path]Updates the current directory
echo [[-on | -off] | [text]Echoes text to stdout or toggle script echo
if [not] condition thenScript-only: IF THEN construct
endifScript-only: Delimiter for IF THEN construct
goto labelScript-only: Jump to label location in script
for var in <set></td>Script-only: Loop construct
endforScript-only: Delimiter for loop construct
pauseScript-only: Prompt to quit or continue
ls [-b] [dir] [dir] ...Obtains directory listing
mkdir dir [dir] ...Makes directory
mode [col row]Gets or sets current text mode
cp [-r] file [file] ... [dest]Copies files/directories
comp file1 file2Compares two files
rm file/dir [file/dir]Remove files/directories
memmap [-b]Dumps memory map
type [-a] [-u] [-b] fileTypes file
dmpstoreDumps variable store
load driver_nameLoads a driver
verDisplays version information
err [level]Sets or displays error level
time [hh:mm:ss]Gets or sets time
date [mm/dd/yyyy]Gets or sets date
stall microsecondsDelay for x microseconds
reset [/warm] [reset string]Cold or warm reset
vol fs [Volume Label]Sets or displays volume label
attrib [-b] [+/- rhs] [file]Sets or displays file attributes
cls [background color]Clears screen
bcfg -?Configures boot driver and load options
edit [file name]Edits a file
Edd30 [On | Off]Enables or disables EDD 3.0 device paths
dblk device [Lba] [Blocks]Hex dump of BlkIo devices
pci [bus dev] [func]Displays PCI device(s) information
mm Address [Width] [;Type]Modifies memory: Mem, MMIO, IO, PCI
mem [Address] [size] [;MMIO]Dumps memory or memory mapped IO
EddDebug [BlockDeviceName]Dumps EDD information from adapter card

This list appears when you type the command "help" at the shell prompt. However, it does not contain all of the EFI shell commands; the commands "attrib" and "exit" are absent. Not all commands can be used in script files. For example, the command "exit" missing from the list cannot be used in a script file. To exit out of a script, simply jump to the end of the file. Conversely, some of the commands like "if...then," "for...in," "goto" can only be used inside the script file.

To execute a command, type it at the shell prompt, which can be as follows:

Shell>

fs0:>

If there is a disk in the floppydrive before the PC is turned on, then the current media defaults to the floppy disk. If not, then the current media is the first hard disk partition.

fs1:>

The first hard disk partition if fs0 is the floppy disk.

fs2:>

Indicates the CD-ROM drive.

This environment is similar to Microsoft DOS* (MS-DOS) in that the user types in commands and presses Enter to execute the commands. As demonstrated below, changing to another drive is easy: type the name of the drive and then press Enter is a carriage return which translates to Press Enter.

Shell> fs0: <cr>
Fs0:> fs2: <cr>
Fs2:>

If the user is unfamiliar with the use of a command, they simply type it at the shell prompt and the computer displays the correct syntax and meaning of each of the switches.

EFI Shell Scripts

In basic terms, a script file is one that contains a sequence of shell commands that the user would like the computer to execute. Rather than entering them at the shell prompt, the user places the appropriate shell commands into a file and names the file filename.nsh to create a script file. This is extremely useful for repetitive tasks.

The script file resembles a batch file in MS-DOS; in EFI, a file called startup.nsh automatically runs every time a shell environment is opened. You can create the script using any ASCII or Unicode text editor. The following are shell commands frequently used in a script:

Echo

Syntax:echo -on |

-off

echo text

The first line in a script is usually echo -off. This prevents subsequent batch file commands from displaying on the screen so that only results display.

For example, in a script file, there are such commands:

    
Batch commands:echo -on


echo This is a test

When you run that script, you see the following lines on the screen:

Result:echo -on

echo This is a test

This is a test
    

The first two lines in bold are batch commands from the script, and the third line is the result of the second batch command. Note the display when the echo command is turned off:

Batch commands:echo -off

echo This is a test

Result:echo -off

This is a test

The batch command echo This is a test no longer displays onscreen because the echo has been turned off. You always see the batch command echo -off because the echo does not disable after this line has been executed.

If

Syntax: if [not] exist filename then...endif if [not] string1 == string2
then
...
endiff

The first form checks for file existence. Type either just the file name or the path and the file name. For example:

set test "startup.nsh" # Assign "startup.nsh" to the

environment

# variable named test

if exist %test% then # Check to see if the file

"startup.nsh"

# exists in the current directory

type %test% # Displays the contents of "startup.nsh"

# if found.

endif # End of if ... then statement

The second form is the comparison between strings:

set env1 "world"

set env2 "map"

if %env1% == %env2% then # Compare the value of 2

variables

echo %env1% is equal to %env2%

endif

Note: Spaces need to be inserted at both ends of the "==" sign. Otherwise, the shell generates an error.

%env1% == %env2% correct
%env1%==%env2% incorrect

For

Syntax:for %index in

group

...

endfor

This is a for loop. The index here is any single character, like a, b, c and so on, but it can't be a digit like 1, 2 or 3 because they can be misinterpreted as argument variables. Groups can be made up of strings or file names separated by the use of spaces. Consider the following examples:

Batch commands:for %b in 1

2 3 4

type %b

**

endfor

Result:1

**

2

**

3

**

4

**

Batch commands:for %m in

*.nsh

type

%m

endfor

Result: The list of all files with extension nsh in the current directory.

Note: Spaces need to be inserted at both ends of the %index. Otherwise, the shell generates an error.

Type %b ** correct

Type %b** incorrect

Dual Boot Selection

Consider the procedure for setting up dual boot on an Intel® Itanium® processor based system. If Windows 9x and Windows NT* or Windows 2000 is installed on an Intel Itanium platform, you can set up a dual boot under Windows NT or Windows 2000. If Windows 9x and Linux* are installed, you can set up a dual boot under Linux.

On the Intel Itanium platform, there is a layer between the firmware and the OS, that layer is the EFI. You can boot to any installed OS from the EFI layer as long as the OS is EFI-compliant.

Below is a demonstration of dual booting 64-bit versions of Red Hat Linux and Windows 2000.

Before starting to build the boot menu:

A) You must disable the file startup.nsh. This script runs automatically when you turn on the system and select the Boot OS option. When you install Windows 2000, it creates the startup.nsh file. This file executes a file called launcher.efi, which boots directly to Windows 2000. Perform the following steps to disable the startup.nsh file:

  1. During the Windows booting process, press any key to interrupt it.
  2. Change the access right of the startup.nsh file to modify or delete it. From the shell prompt, Shell>, go to the main partition:
Shell> fs0:

or

Shell> fs1:

The choice between fs0 and fs1 depends on whether a disk is in the floppy drive.

Note: To use the floppy drive, a floppy disk must be inserted. Otherwise, the floppy drive is not recognized; the same caution applies to the CD-ROM drive.

fs0:> attrib -r startup.nsh fs0:> edit startup.nsh

In edit mode, type a # sign at the beginning of the line containing the word launcher to comment it out.

B) Make sure the BIOS build 89B is flashed. One way to establish the correct build number is to look at the EFI version when you first turn on the PC; if it's correct, you see something like:

EFI Version 0.9912.31...

There are instances in which an incorrect BIOS version has been preloaded to the Software Development Vehicle (SDV). If you see "EFI Version 1.012.25..." displayed on the screen, reflash the BIOS with build 89B or 99.

Assume you want the following multiple boot menu:

  • Windows XP Professional
  • Red Hat Linux
  • EFI Shell

You can create it using any of these methods:

  • boot maintenance menu
  • BCFG command
  • script

Using Boot Maintenance Menu

Follow these steps to create a boot menu:

  1. Turn on the system.
  2. Select Boot OS
  3. At the shell prompt, type exit and press Enter.
Shell> exit
  1. The screen displays a boot menu similar to the following:
EFI Boot Manager ver. 0.9912.29

Select boot option

EFI Shell built in

Boot option maintenance menu
  1. Select the boot option maintenance menu.
  2. Select Add a boot option.
  3. Select the partition containing the OS loader. In this case, it is the first hard disk partition. Something similar to the following appears on-screen:
NO VOLUME LABEL VenHw(Unknown D evice:80)/HD(Part1, Sig948939)
Removable Media VenHw(Unknown Device:FF)
Load File Acpi(PNP0A03,0)/Pci(4|0)/mac(009027E4A0F4)
Load File EFI Shell Built-in
Legacy Boot A:
Legacy Boot C:
Exit
  1. Select the first item, NO VOLUME LABEL...
  2. The screen displays the files of the directory of the selected partition. Select the file eli.efi. This is the Linux loader file.
  3. Type the title you wish to display on the boot menu when asked for the description: Red Hat Linux
  4. When prompted with: New boot option data: ASCII/Unicode string only Enter Boot option Data typeA- SCII U- Unicode N- No BootOption, select N
  5. Next, select the option Save Changes to NVRAM Y-yes N-No: and type Y
  6. When you have no other OS to set, select exit to return to the previous menu
  7. Select Cold Reset to reboot the system.
  8. To create an EFI shell prompt, select option EFI Shell[built in] from step 7 and type EFI Shell at step 10.
  9. Type exit at the shell prompt Shell> to go to the boot menu.

Using the BCFG Command

The Bcfg is the boot configuration shell command. Assuming that fs0 is the main partition, type the following statement to create the boot menu:

fs0:> bcfg boot add 2 eli.efi Red Hat Linux

Note: You cannot create an EFI shell prompt using this method; you must use the previous method.

Using Script

Since there is no user-prompt command under the EFI shell to accept users' selected input, you must use an alternative method:

a) If the file startup.nsh does not exist, create it or modify it to contain strictly the following line:

Menu

b) Create a file and name it menu.nsh with the following:

Echo -off

Dblk3:

Echo 2- Red Hat Linux

Echo Enter choice and press Enter

Note: There is no option for the shell prompt since the command nshell is not on the list.
The current partition is set to dblk3 instead of fs0 or fs1. This is because if there is a floppy disk in the floppy drive, then fs0 is the floppy disk and fs1 is the first hard disk partition. Otherwise, fs0 is the first hard disk partition

c) Create a file and name it "2.nsh" with the following contents:

eli

Note: The 2.nsh script is used to boot to Red Hat Linux.

Conclusion

This represents only the beginning of the uses and benefits of EFI shell commands and scripts. Not only can EFI be used similarly to a MS-DOS device driver, its capabilities also remove the hassle of modifying the OS. Disk utility vendors can use EFI to craft powerful tools like platform-independent disk partitioning. Another of EFI's benefits is that the same device drivers can be used by many EFI-compliant platforms, thus providing a good return on investment. EFI allows users to create device drivers to access hardware directly without having to go through the OS, making the process both simpler and faster.

For more complete information about compiler optimizations, see our Optimization Notice.

5 comments

Top

Hi,
I have a question, if I want to count how many "warm reset" are executed in one day, for example I changed boot order in bios and set UEFI shell as first option, I edited startup.nsh and write "reset"
platform reset correctly every boot to efishell but I want to know how many resets are performed 

This is first time learning about EFI Shel. So, I was wondering how can I create a bootable EFI shell USB key?

Hi,

I need small help,

I want to run following content using EFI shell script file like script.nsh.

MyApp.efi "BootOption #"

But when i run script.nsh it is treating as like below,

MyApp.efi "BootOption 

Please help me how to pass # also ,

 

thanks,

It would be most helpful if there's a link to further describe/expand on the commands in the table at the end of this page here. Or where/how to access the user manuals of EFI shell itself. All in all this documentation does provide basic functionality of EFI shell. Thanks.

Add a Comment

Have a technical question? Visit our forums. Have site or software product issues? Contact support.