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