Harnessing the UEFI Shell

Focusing on the use of the UEFI Shell and its recently released formal specification, this book unlocks a wide range of usage models which can help people best utilize the shell solutions. This text also expands on the obvious intended utilization of the shell and explains how it can be used in various areas such as security, networking, configuration, and other anticipated uses such as manufacturing, diagnostics, etc. Among other topics, Harnessing the UEFI Shell demonstrates how to write Shell scripts, how to write a Shell application, how to use provisioning options and more. Since the Shell is also a UEFI component, the book will make clear how the two things interoperate and how both Shell developers as well as UEFI developers can dip into the other's field to further expand the power of their solutions.

Harnessing the UEFI Shell is authored by the three chairs of the UEFI working sub-teams, 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). This book is perfect for any OEMs that ship UEFI-based solutions (which is all of the MNCs such as IBM, Dell, HP, Apple, etc.), software developers who are focused on delivering solutions targeted to manufacturing, diagnostics, hobbyists, or stand-alone kiosk environments.

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