Harnessing the UEFI Shell

Michael Rothman (Intel, chair of the UEFI Configuration and UEFI Shell sub-teams), Vincent Zimmer (Intel, chair of the UEFI networking sub-team and security sub-team), and Tim Lewis (Insyde Software, chair of the UEFI security sub-team).

Preface  vii

Chapter 1 Introduction  1

What is UEFI?  1

What Do We Mean by Shell?  4

A Short History of the UEFI Shell  5

Brief Overview of the UEFI Shell  5

UEFI Shell APIs  6

Command Line Interface Features  6

Why a Shell at all?  7

Chapter 2 Under the UEFI Shell  9

Shell and UEFI  9

Evolution and Revolution  13

Chapter 3 What Is the UEFI Shell?  15

What Is Contained in the UEFI Shell?  16

What Kind of Shell Do You Have?  16

What!? No Shell? No Problem!  17

Programmatic Shell Environment  19

Using UEFI Shell Commands  20

Interactive Shell Environment  22

Scripting  22

Program Launch  24

File-System Abstractions  29

Shell Script Resolves into a UEFI Firmware Action  31

Chapter 4 Why We Need an Execution Environment before the OS  33

Evolution of a Machine  33

The Platform Initialization Flow  34

UEFI Transitions  36

States of a Platform  38

Readiness of UEFI  41

Migration Using the UEFI Shell  44

Going Forward  45

Chapter 5 Manufacturing  47

Throughput  47

Manufacturing Test Tools  49

Hardware Access with Manufacturing Tools  50

Converting Manufacturing Tools  53

Conclusion  54

Chapter 6 Bare Metal Provisionig  55

Provisioning with the UEFI Shell  55

UEFI Networking Stack  56

Securing the Network  58

Speeding Up the Network  62

Example of Putting It Together  62

Summary  68

Chapter 7 Configuration of Provisioned Material  69

Initialization Timeline  69

Configuration Infrastructure Overview  71

Using the Configuration Infrastructure  72

Driver Model Interactions  73

Provisioning the Platform  75

Configuring through the UEFI Shell  76

Basic Configuration  76

Advanced Configuration Abilities  79

Chapter 8 The Use of UEFI for Diagnostics  85

Types of Diagnostics  85

SMBIOS Table Organization  87

SMBIOS Structure Table Entry Point  88

Table Organization Graph  88

Structure Standards  89

Structure Evolution and Usage Guidelines  90

Text Strings  90

Required Structures and Data  91

Features  91

User Interface Design  92

Design Guide  92

Usage  93

Examples  93

Architecture Design  94

Data Structure  95

SMBIOS_STRUCTURE_TABLE  95

SMBIOS_HEADER  97

SMBIOS_STRUCTURE_POINTER  98

STRUCTURE_STATISTICS  99



Source Code for the Utility  100

Summary  105

Chapter 9 UEFI Shell Scripting  107

Hello, World!  108

Echo  108

Echo All Parameters  109

Echo All Parameters (Improved Version)  110

Concatenate Text Files  112

List Only Selected “ls” Information  113

Install Script  115

How to Make a Shell Script Appear as a Boot Option  119

Chapter 10 UEFI Shell Programming  121

A Simple UEFI Shell Application: HelloWorld  121

The Source File: HelloWorld.c  121

The Component Information (.inf) File  123

A Simple Standard Application: HelloWorld2  124

The Source File: HelloWorld2.c  124

The Component Information (.inf) File: HelloWorld2.inf  125

Read Keyboard Input in UEFI Shell Scripts: GetKey  126

The Source File: GetKey.c  127

The Component Information (.inf) File: GetKey.inf  137

The Build Description (.dsc) File  139

Calculate Math Expressions: Math  139

The Source File: Math.c  140

The Component Information (.inf) File: Math.inf  154

Convert ASCII to Unicode and Back: UniCodeDecode  154

The Source File: UniCodeDecode.c  155

The Component Information (.inf) File  163

Chapter 11 Managing UEFI Drivers Using the Shell  165

Testing Specific Protocols  166

Loading and Unloading UEFI Drivers  167

Load  168

LoadPciRom  168

Unload  169

Connecting UEFI Drivers  169

Connect  169

Disconnect  170

Reconnect  170

Driver and Device Information  171



Drivers  171

Devices  172

DevTree  172

Dh –d  173

OpenInfo  173

Testing the Driver Configuration and Driver Diagnostics Protocols  174

DrvCfg  174

DrvDiag  174

Debugging Code Statements  175

POST Codes  177

Post Card Debug  178

Text-Mode VGA Frame Buffer  179

Other Options  179

Appendix A Security Considerations  181

UEFI Shell Binary Integrity  181

Overview  181

Signed Executable Overview  182

Digital Signature  183

Signed Executable Processing  185

Signed Executable Generation Application (SignTool)  185

UEFI Load Image  186

SignTool  186

Build Environment  186

Example usage  187

Appendix B Command Reference  189

Command Profiles and Support Levels  189

Command List  189

Standardizing Command Output  192

Command Details  193

alias  193

attrib  194

bcfg  194

cd  196

cls  197

comp  197

connect  198

cp/copy  199

date  199

dblk  200

del  200



devices  200

devtree  201

dh  201

dir/ls  202

disconnect  202

dmem  203

dmpstore  204

drivers  204

drvcfg  205

drvdiag  206

echo  206

edit  207

eficompress  207

efidecompress  207

exit  207

for  208

getmtc  209

goto  209

help  209

hexedit  210

if  210

ifconfig  214

ifconfig6  214

load  215

loadpcirom  216

ls  216

map  217

md  218

mem  218

memmap  218

mkdir  219

mm  219

mode  220

mv  220

openinfo  220

parse  221

pause  221

pci  221

ping  222

ping6  222

reconnect  223

reset  223



rm  224

sermode  224

set  225

setsize  226

setvar  226

shift  227

smbiosview  227

stall  228

time  228

time  229

touch  229

type  230

unload  230

ver  230

vol  230

Appendix C Programming Reference  233

Script-based Programming  233

Parameter Passing  233

Redirection and Piping  234

Return Codes  235

Environment Variables  236

Non-Script-based Programming  237

Shell Protocol  238

Shell Parameters Protocol  240

Appendix D UEFI Shell Library  241

Functions  241

File I/O Functions  241

Miscellaneous Functions  242

Command Line Parsing  243

Text I/O  244

String Functions  244

ShellCloseFile()  245

ShellCloseFileMetaArg()  246

ShellCommandLineCheckDuplicate()  246

ShellCommandLineFreeVarList()  247

ShellCommandLineGetCount()  247

ShellCommandLineGetFlag()  248

ShellCommandLineGetValue()  248

ShellCommandLineGetRawValue()  249

ShellCommandLineParseEx()  250



ShellCopySearchAndReplace()  251

ShellConvertStringToUint64()  252

ShellCreateDirectory()  253

ShellDeleteFile()  254

ShellDeleteFileByName()  254

ShellExecute()  255

ShellFileExists()  257

ShellFileHandleReturnLine()  257

ShellFileHandleReadLine()  258

ShellFindFilePath()  259

ShellFindFilePathEx()  260

ShellFindFirstFile()  260

ShellFindNextFile()  261

ShellFlushFile()  262

SHELL_FREE_NON_NULL()  263

ShellGetCurrentDir()  263

ShellGetEnvironmentVariable()  264

ShellGetExecutionBreakFlag()  265

ShellGetFileInfo()  265

ShellGetFilePosition()  266

ShellGetFileSize()  266

ShellHexStrToUintn()  267

ShellInitialize()  268

ShellIsDecimalDigitCharacter()  268

ShellIsDirectory()  269

ShellIsFile()  269

ShellIsFileInPath()  270

ShellIsHexaDecimalDigitCharacter()  270

ShellIsHexOrDecimalNumber()  271

ShellOpenFileByDevicePath()  271

ShellOpenFileByName()  273

ShellOpenFileMetaArg()  274

ShellPrintEx()  275

ShellPrintHelp()  276

ShellPrintHiiEx()  277

ShellPromptForResponse()  278

ShellPromptForResponseHii()  279

ShellReadFile()  281

ShellSetFileInfo()  282

ShellSetFilePosition()  283

ShellSetEnvironmentVariable()  284

ShellSetPageBreakMode()  285



ShellStrToUintn()  285

ShellWriteFile()  286

StrnCatGrow()  287

Data Structures  288

Format Strings  288

Shell Parameters  289

Index  291