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.

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.

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