UEFI Shell

from:https://software.intel.com/en-us/articles/uefi-framwork-course-contents

UEFI Shell

By wolfgang-rosenbergsr (Intel), published on March 21, 2011

Translate

Home >> | Back to Courseware Access page >> | Back to Other Courseware Content page >> |

UEFI Curriculum

About UEFI

UEFI-Framework Course Contents

Introduction to PC Architecture

Beyond BIOS

UEFI Introduction

UEFI Architecture and Technical Overview

UEFI Application

UEFI Shell

UEFI Boot Manager

UEFI Services

UEFI Drivers

Framework Architecture and Technical Overview

Labs

References

Potential research topics

UEFI Shell Users’ Guide

UEFI Shell Overview

• Interactive way to use UEFI code in system

• Has command line prompt and Scripting

–Is similar to DOS and Linux* shell but not EXACTLY - its own unique syntax

• Is UEFI executable in itself

• Knows only about UEFI file systems that are FATxx

• Shell is a Sub-project on EFI Development Kit (EDK) on the EFI and Framework Open source Community Website

- Shell programs

- users’ guide

- EFI Shell Source

• EDK has Binary UEFI Shell for processors IA32, Intel® 64, IA-64

EFI Shell Open Source

• WEB Site: http:www.tianocore.org

• Project: EFI-Shell

• Documents & files : “EFI Shell Getting Started Guide”

Analogy to Old DOS: BIOS

Shell Usage

• Execute preboot programs

– Setup

– operating system install

– Test

– disk utilities

– Driver Diagnostics, Configurations

• Move files around between the hard disk, floppy disk, CD-ROM, USB flash devices, and so on

• Load a preboot EFI driver in the system (has an .efi suffix), examples:

– LAN stack tcpip drivers

– Update old drivers in flash

– New drivers for plugin cards

• Shell.efi verses Shell_full.efi

– Shell.efi smaller to fit in Flash

– Shell_full.efi Richer commands

EFI File System

Can manipulate EFI system fatxx partition only where boot loader and EFI application are

Shell> map
Device mapping table
fs0  : Acpi(PNP0A03,1)/Pci(1F|0)/Pci(2|0)/
 Scsi(Pun0,Lun0)/HD(Part1,Sig8983DFE0-F474-01C2-507B-
9E5F8078F531)
 blk0 : Acpi(PNP0A03,0)/Pci(1F|1)/Ata(Primary,Slave)
 blk1 : Acpi(PNP0A03,0)/Pci(1F|1)/Ata(Primary,Master)
 blk2 : Acpi(PNP0A03,1)/Pci(1F|0)/Pci(2|0)/Scsi(Pun0,
 Lun0)
 blk3 : Acpi(PNP0A03,1)/Pci(1F|0)/Pci(2|0)/
  Scsi(Pun0,Lun0)/HD(Part1,Sig8983DFE0-F474-01C2-507B-
9E5F8078F531)
 blk4 : Acpi(PNP0A03,1)/Pci(1F|0)/Pci(2|0)/
  Scsi(Pun0,Lun0)/HD(Part2,Sig898D07A0-F474-01C2-F1B3-
12714F758821)
 lk5 : Acpi(PNP0A03,1)/Pci(1F|0)/Pci(2|0)/
  Scsi(Pun0,Lun0)/HD(Part3,Sig89919B80-F474-01C2-D931-
F8428177D974)

Device Path

• fs0:

Acpi(PNP0A03,1)/Pci(1F|0)/Pci(2|0)/Scsi(Pun0,Lun0)/HD(Part1, Sig8983DFE0-F474-01C2-507B-9E5F8078F531)

• Fs0:

Acpi(PNP0A03,1)

Pci(1F|0)/Pci(2|0)

Scsi(Pun0,Lun0)

HD(Part1,Sig8983DFE0-F474-01C2-507B-9E5F8078F531)

Executing UEFI Applications

• Enter the application name at the command prompt

• The EFI shell uses “path” environment variable

• The EFI shell automatically adds “.efi”

path = fs0:>efi	ools;fs0:;.
fs0:> test.efi
      fs0:> test
      fs1:> test

If suffix is .nsh, it will execute shell commands inside of the .nsh file similar to .bat in DOS

Execute a UEFI Shell

• nshell

Launches another copy of the EFI shell

Might require shellenv.efi, depending on how the shell was built

• exit

Returns control to the EFI application that launched the EFI shell

– Could be the EFI Boot Manager

– Could be another copy of the EFI shell

Wild Card Expansion

• Syntax is similar to DOS commands

’*’ Matches any string

’?’ Matches any character

[chars] Matches set of characters

Tab will extend to matching files or Directories

fs0:> dir *.efi

fs0:> dir test?.efi

Output Redirection

Redirect standard output to a Unicode file

             memmap 1> Foo.txt
                memmap > Foo.txt

Redirect standard output to an ASCII file

             memmap 1>a Foo.txt
                memmap >a Foo.txt

Append a file using redirection of standard output

             memmap 1>>a Foo.txt
                memmap >>a Foo.txt

Redirect standard error to a Unicode file

             memmap 2> Foo.txt

Redirect standard error to an ASCII file

             memmap 2>a Foo.txt

EFI Shell Commands

              dmem         drivers
dh            dmpstore     devtree
help ?        err          devices
map           guid         connect
mount     
    pci          disconnect
load          mm           openinfo
unload        reset        reconnect
loadbmp       stall        drvcfg
nshell        getmtc       drvdiag
ver           hexedit      loadpcirom
memmap        Setsize
bcfg          Set
Dblk
alias

Internal EFI Shell Commands

Commands that are built intothe shell environment and are not .efi applications that are loaded

Chosen by the system integrator who builds the shell or by the applications person who delivers nshell.efi

Can be integrated into flash with core EFI, SAL, BIOS and so on or be supplied separately with the other .efi applications

Examples

help
dh
map
guid
alias
set
exit
Cd
type

External Shell Commands

• Applications that rely on the shell library

• For example, Edit, hexdump and other tools that are supplied with the application toolkit

• Some shells integrate these applications as a value add or differentiator or the applications are necessary for their systems

• Flash space is a determining factor

EFI Shell Commands

• DOS like

attrib
date
edit 
time
break
cls
mode
vol

• Batch Commands

(*.nsh files)
echo
exit
for
goto
if
Pause
Equivalent to *.bat files
Note: startup.nsh = autoexec.bat

Unix-like Shell Commands

ls 
rm 
cp 
mv
mkdir 
type
alias
set
touch

• Warning: syntax is not exactly the same as bash or csh

• Use ? or help to look up the syntax

• Use Alias to translate the commands to something familiar

• For example:

– Alias dir ls

– Alias del rm

– Alias copy cp

Script File Example

echo Loading TCP/IP stack...
load efi	ools	cpipv4.efi
if not %lasterror% == 0 then
   echo Error starting network stack
   goto Done

echo loaded tcpipv4
ifconfig lo0 inet 127.0.0.1 up
ifconfig sni0 inet 134.134.31.175 netmask 55.255.255.0 up
route add default 134.134.31.251 
cd 
:Done

Help or ?: Command List in Shell

alias        Displays, creates, or deletes aliases in the EFI
               shell

attrib          Displays or changes the attributes of files or
               directories

bcfg            Dislplays/modifies the driver/boot configuration

break           Executes a break point

cd              Displays or changes the current directory

cls             Clears the standard output with an optional
               background color

Comp            Compares the contents of two files

cp              Copies one or more files/directories to another
               location

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

dblk            Displays the contents of blocks from a block
               device

dh              Displays the handles in the EFI environment

dm
em           Displays the contents of memory

echo            Displays messages or turns command echoing on or
               off

err             Displays or changes the error level

exit            Exits the EFI Shell

for             Executes commands for each item in a set of items

goto            Makes batch file execution jump to another
               location

guid            Displays all the GUIDs in the EFI environment

if              Executes commands in specified conditions

load            Loads and optionally connects EFI drivers

ls              Displays a list of files and subdirectories in a
               directory

map             Displays or defines mappings

memmap         Displays the memory map

mkdir           Creates one or more directories
 
mm              Displays or modifies MEM/IO/PCI
 
mode           Displays or changes the mode of the console
               output device

mount          Mounts a file system on a block device

mv              Moves one or more files/directories to destination

pause      Prints a message and suspends for keyboard input

pci             Displays PCI devices or PCI function
               configuration space
reset           Resets the system

rm              Deletes one or more files or directories

set             Displays, creates, changes or deletes EFI 
               environment variables

stall           Stalls the processor for some microseconds

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

type            Displays the contents of a file

unload         Unloads a protocol image

ver             Displays the version information

vol             Displays volume information of the file system

DH – Dump Handle

All devices and images are in a database called the handle database

Devices are located in the system by their device paths

DH [-b] [-d] [-lXXX] [-v] [handle]|[-p prot_id]
Displays the handles in the EFI environment
-b           - Displays one screen at a time
handle       - Dumps information of a certain handle
-p prot_id   - Dumps all handles of a certain protocol
-d           - Dumps EFI Driver Model related information
-lXXX        - Dumps information using the ISO 639-2 language 
               specified by XXX
-v           - Dumps information on all handles