Harnessing the UEFI Shell

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