How it Works
Intel
Loading...
Extensible Firmware Interface
User Manual
494 pgs2.85 Mb0
User Manual
1084 pgs7.15 Mb0
Table of contents
Loading...

Intel Extensible Firmware Interface User Manual

Download
Extensible Firmware Interface
Specification
Version 1.10
December 1, 2002
Acknowledgements
The UGA Protocol sections of this specification were developed in close consultation with Microsoft as part of the Universal Graphics Adapter (UGA) initiative. Microsoft has made significant contributions to the interface definitions presented here to ensure that they will work well with video adapters supporting the Microsoft UGA specification. These efforts are gratefully acknowledged.
The EFI Byte Code Virtual Machine sections (Chapter 19) of this specification were developed in close consultation with Microsoft, LSI, Hewlett Packard, Compaq, and Phoenix Technologies. The efforts of all contributors to these sections are gratefully acknowledged.
THIS SPECIFICATION IS PROVIDED "AS IS" WITH NO WARRANTIES WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY, NONINFRINGEMENT, FITNESS FOR ANY PARTICULAR PURPOSE, OR ANY WARRANTY OTHERWISE ARISING OUT OF ANY PROPOSAL, SPECIFICATION OR SAMPLE. Intel disclaims all liability, including liability for infringement of any proprietary rights, relating to use of information in this specification. No license, express or implied, by estoppel or otherwise, to any intellectual property rights is granted herein, except that a license is hereby granted to copy and reproduce this specification for internal use only.
Designers must not rely on the absence or characteristics of any features or instructions marked "reserved" or "undefined." Intel reserves these for future definition and shall have no responsibility whatsoever for conflicts or incompatibilities arising from future changes to them.
This document contains information on products in the design phase of development. Do not finalize a design with this information. Revised information will be published when the product is available. Verify with your local sales office that you have the latest datasheet or specification before finalizing a design.
Intel, the Intel logo, Pentium, Itanium, and MMX are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries.
†
Other names and brands may be claimed as the property of others.
Intel order number: A79614-002
Copyright ¤ 1998–2002 Intel Corporation. All Rights Reserved.
ii 12/01/02 Version 1.10
History

Revision Revision History Date

1.0 Official release of EFI 1.10 Specification, revision 1.0. 12/01/02
Version 1.10 12/01/02 iii
Extensible Firmware Interface Specification
iv 12/01/02 Version 1.10

Contents

1 Introduction
1.1 EFI Driver Model Extensions............................................................................... 1-2
1.2 Overview............................................................................................................. 1-3
1.3 Goals .................................................................................................................. 1-6
1.4 Target Audience.................................................................................................. 1-8
1.5 EFI Design Overview .......................................................................................... 1-8
1.6 EFI Driver Model ................................................................................................. 1-9
1.6.1 EFI Driver Model Goals............................................................................ 1-10
1.6.2 Legacy Option ROM Issues...................................................................... 1-11
1.7 Migration Requirements .................................................................................... 1-11
1.7.1 Legacy Operating System Support........................................................... 1-11
1.7.2 Supporting the EFI Specification on a Legacy Platform ............................ 1-11
1.8 Conventions Used in This Document ................................................................ 1-12
1.8.1 Data Structure Descriptions...................................................................... 1-12
1.8.2 Protocol Descriptions ............................................................................... 1-12
1.8.3 Procedure Descriptions ............................................................................ 1-13
1.8.4 Instruction Descriptions ............................................................................ 1-13
1.8.5 Pseudo-Code Conventions....................................................................... 1-14
1.8.6 Typographic Conventions......................................................................... 1-14
2 Overview
2.1 Boot Manager ..................................................................................................... 2-2
2.1.1 EFI Images................................................................................................. 2-2
2.1.2 EFI Applications ......................................................................................... 2-3
2.1.3 EFI OS Loaders ......................................................................................... 2-4
2.1.4 EFI Drivers................................................................................................. 2-4
2.2 Firmware Core .................................................................................................... 2-5
2.2.1 EFI Services............................................................................................... 2-5
2.2.2 Runtime Services ....................................................................................... 2-6
2.3 Calling Conventions ............................................................................................ 2-7
2.3.1 Data Types................................................................................................. 2-7
2.3.2 IA-32 Platforms .......................................................................................... 2-9
2.3.2.1 Handoff State .................................................................................. 2-10
2.3.3 Itanium®-Based Platforms ........................................................................ 2-11
2.3.3.1 Handoff State .................................................................................. 2-12
2.4 Protocols........................................................................................................... 2-12
2.5 EFI Driver Model ............................................................................................... 2-15
2.5.1 Legacy Option ROM Issues...................................................................... 2-17
2.5.1.1 IA-32 16-Bit Real Mode Binaries...................................................... 2-17
2.5.1.2 Fixed Resources for Working with Option ROMs............................. 2-18
2.5.1.3 Matching Option ROMs to their Devices .......................................... 2-18
2.5.1.4 Ties to PC-AT System Design......................................................... 2-19
2.5.1.5 Ambiguities in Specification and Workarounds
Born of Experience.......................................................................... 2-19
Version 1.10 12/01/02 v
Extensible Firmware Interface Specification
2.5.2 Driver Initialization.................................................................................... 2-20
2.5.3 Host Bus Controllers ................................................................................ 2-21
2.5.4 Device Drivers.......................................................................................... 2-23
2.5.5 Bus Drivers............................................................................................... 2-24
2.5.6 Platform Components............................................................................... 2-26
2.5.7 Hot-Plug Events ....................................................................................... 2-27
2.6 Requirements ................................................................................................... 2-27
2.6.1 Required Elements................................................................................... 2-28
2.6.2 Platform-Specific Elements ...................................................................... 2-29
2.6.3 Driver-Specific Elements .......................................................................... 2-30
3 Boot Manager
3.1 Firmware Boot Manager...................................................................................... 3-1
3.2 Globally-Defined Variables.................................................................................. 3-5
3.3 Boot Option Variables Default Behavior .............................................................. 3-7
3.4 Boot Mechanisms ............................................................................................... 3-7
3.4.1 Boot via Simple File Protocol...................................................................... 3-7
3.4.1.1 Removable Media Boot Behavior ...................................................... 3-7
3.4.2 Boot via LOAD_FILE Protocol.................................................................... 3-8
3.4.2.1 Network Booting ................................................................................ 3-8
3.4.2.2 Future Boot Media............................................................................. 3-8
4 EFI System Table
4.1 EFI Image Entry Point......................................................................................... 4-1
EFI_IMAGE_ENTRY_POINT........................................................................... 4-1
4.2 EFI Table Header................................................................................................ 4-3
EFI_TABLE_HEADER ..................................................................................... 4-3
4.3 EFI System Table ............................................................................................... 4-4
EFI_SYSTEM_TABLE ..................................................................................... 4-4
4.4 EFI Boot Services Table ..................................................................................... 4-6
EFI_BOOT_SERVICES ................................................................................... 4-6
4.5 EFI Runtime Services Table.............................................................................. 4-11
EFI_RUNTIME_SERVICES ........................................................................... 4-11
4.6 EFI Configuration Table .................................................................................... 4-13
EFI_CONFIGURATION_TABLE .................................................................... 4-13
4.7 EFI Image Entry Point Examples ...................................................................... 4-14
4.7.1 EFI Image Entry Point Examples.............................................................. 4-14
4.7.2 EFI Driver Model Example........................................................................ 4-16
4.7.3 EFI Driver Model Example (Unloadable) .................................................. 4-17
4.7.4 EFI Driver Model Example (Multiple Instances)........................................ 4-18
5 Services — Boot Services
5.1 Event, Timer, and Task Priority Services............................................................. 5-2
CreateEvent() ................................................................................................ 5-5
CloseEvent() .................................................................................................. 5-9
SignalEvent() ............................................................................................... 5-10
WaitForEvent()............................................................................................. 5-11
vi 12/01/02 Version 1.10
Contents
CheckEvent() ............................................................................................... 5-12
SetTimer().................................................................................................... 5-13
RaiseTPL() .................................................................................................. 5-15
RestoreTPL() ............................................................................................... 5-17
5.2 Memory Allocation Services.............................................................................. 5-18
AllocatePages() ........................................................................................... 5-21
FreePages()................................................................................................. 5-24
GetMemoryMap()......................................................................................... 5-25
AllocatePool() .............................................................................................. 5-29
FreePool().................................................................................................... 5-30
5.3 Protocol Handler Services................................................................................. 5-31
5.3.1 Driver Model Boot Services...................................................................... 5-33
InstallProtocolInterface().............................................................................. 5-36
UninstallProtocolInterface().......................................................................... 5-38
ReinstallProtocolInterface().......................................................................... 5-40
RegisterProtocolNotify()............................................................................... 5-42
LocateHandle() ............................................................................................ 5-43
HandleProtocol().......................................................................................... 5-45
LocateDevicePath() ..................................................................................... 5-47
OpenProtocol() ............................................................................................ 5-49
CloseProtocol() ............................................................................................ 5-56
OpenProtocolInformation()........................................................................... 5-59
ConnectController() ..................................................................................... 5-61
DisconnectController() ................................................................................. 5-66
ProtocolsPerHandle()................................................................................... 5-68
LocateHandleBuffer()................................................................................... 5-70
LocateProtocol() .......................................................................................... 5-73
InstallMultipleProtocolInterfaces() ................................................................ 5-74
UninstallMultipleProtocolInterfaces()............................................................ 5-75
5.4 Image Services ................................................................................................. 5-76
LoadImage() ................................................................................................ 5-78
StartImage()................................................................................................. 5-80
UnloadImage() ............................................................................................. 5-81
EFI_IMAGE_ENTRY_POINT....................................................................... 5-82
Exit()............................................................................................................ 5-83
ExitBootServices() ....................................................................................... 5-85
5.5 Miscellaneous Boot Services ............................................................................ 5-86
SetWatchdogTimer().................................................................................... 5-87
Stall()........................................................................................................... 5-88
CopyMem().................................................................................................. 5-89
SetMem()..................................................................................................... 5-90
GetNextMonotonicCount() ........................................................................... 5-91
InstallConfigurationTable()........................................................................... 5-92
CalculateCrc32().......................................................................................... 5-93
Version 1.10 12/01/02 vii
Extensible Firmware Interface Specification
6 Services — Runtime Services
6.1 Variable Services ................................................................................................ 6-2
GetVariable() ................................................................................................. 6-3
GetNextVariableName()................................................................................. 6-5
SetVariable().................................................................................................. 6-7
6.2 Time Services..................................................................................................... 6-9
GetTime() .................................................................................................... 6-10
SetTime()..................................................................................................... 6-13
GetWakeupTime() ....................................................................................... 6-14
SetWakeupTime()........................................................................................ 6-15
6.3 Virtual Memory Services ................................................................................... 6-16
SetVirtualAddressMap()............................................................................... 6-17
ConvertPointer() .......................................................................................... 6-19
6.4 Miscellaneous Runtime Services ...................................................................... 6-20
ResetSystem() ............................................................................................. 6-21
GetNextHighMonotonicCount() .................................................................... 6-23
7 Protocols — EFI Loaded Image
EFI_LOADED_IMAGE Protocol ....................................................................... 7-1
LOADED_IMAGE.Unload()............................................................................ 7-3
8 Protocols — Device Path Protocol
8.1 Device Path Overview......................................................................................... 8-1
8.2 EFI_DEVICE_PATH Protocol.............................................................................. 8-2
EFI_DEVICE_PATH Protocol........................................................................... 8-2
8.3 Device Path Nodes ............................................................................................. 8-3
8.3.1 Generic Device Path Structures ................................................................. 8-3
8.3.2 Hardware Device Path ............................................................................... 8-5
8.3.2.1 PCI Device Path ................................................................................ 8-5
8.3.2.2 PCCARD Device Path ....................................................................... 8-5
8.3.2.3 Memory Mapped Device Path ........................................................... 8-6
8.3.2.4 Vendor Device Path........................................................................... 8-6
8.3.2.5 Controller Device Path....................................................................... 8-6
8.3.3 ACPI Device Path....................................................................................... 8-7
8.3.4 Messaging Device Path.............................................................................. 8-9
8.3.4.1 ATAPI Device Path............................................................................ 8-9
8.3.4.2 SCSI Device Path............................................................................ 8-10
8.3.4.3 Fibre Channel Device Path.............................................................. 8-10
8.3.4.4 1394 Device Path............................................................................ 8-10
8.3.4.5 USB Device Path............................................................................. 8-11
8.3.4.6 USB Class Device Path................................................................... 8-11
8.3.4.7 I2O Device Path............................................................................... 8-12
8.3.4.8 MAC Address Device Path .............................................................. 8-12
8.3.4.9 IPv4 Device Path ............................................................................. 8-12
8.3.4.10 IPv6 Device Path ........................................................................... 8-13
8.3.4.11 InfiniBand Device Path .................................................................. 8-13
8.3.4.12 UART Device Path ........................................................................ 8-14
viii 12/01/02 Version 1.10
Contents
8.3.4.13 Vendor-Defined Messaging Device Path ....................................... 8-14
8.3.4.14 UART Flow Control Messaging Path ............................................. 8-15
8.3.5 Media Device Path ................................................................................... 8-16
8.3.5.1 Hard Drive....................................................................................... 8-16
8.3.5.2 CD-ROM Media Device Path........................................................... 8-17
8.3.5.3 Vendor-Defined Media Device Path................................................. 8-18
8.3.5.4 File Path Media Device Path ........................................................... 8-18
8.3.5.5 Media Protocol Device Path ............................................................ 8-18
8.3.6 BIOS Boot Specification Device Path ....................................................... 8-19
8.4 Device Path Generation Rules.......................................................................... 8-20
8.4.1 Housekeeping Rules ................................................................................ 8-20
8.4.2 Rules with ACPI _HID and _UID .............................................................. 8-20
8.4.3 Rules with ACPI _ADR............................................................................. 8-21
8.4.4 Hardware vs. Messaging Device Path Rules............................................ 8-22
8.4.5 Media Device Path Rules ......................................................................... 8-22
8.4.6 Other Rules.............................................................................................. 8-22
9 Protocols — EFI Driver Model
9.1 EFI Driver Binding Protocol................................................................................. 9-1
EFI_DRIVER_BINDING_PROTOCOL ............................................................. 9-1
EFI_DRIVER_BINDING_PROTOCOL.Supported() ....................................... 9-4
EFI_DRIVER_BINDING_PROTOCOL.Start() .............................................. 9-10
EFI_DRIVER_BINDING_PROTOCOL.Stop() .............................................. 9-18
9.2 EFI Platform Driver Override Protocol ............................................................... 9-23
EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL .................................. 9-23
EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL.GetDriver().............. 9-25
EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL.GetDriverPath() ...... 9-27
EFI_PLATFORM_DRIVER_OVERRIDE_PROTOCOL.DriverLoaded()........ 9-29
9.3 EFI Bus Specific Driver Override Protocol......................................................... 9-31
EFI_BUS_SPECIFIC_DRIVER_OVERRIDE_PROTOCOL ............................ 9-31
EFI_BUS_SPECIFIC_DRIVER_OVERRIDE_PROTOCOL.GetDriver() ....... 9-32
9.4 EFI Driver Configuration Protocol...................................................................... 9-33
EFI_DRIVER_CONFIGURATION_PROTOCOL ............................................ 9-33
EFI_DRIVER_CONFIGURATION_PROTOCOL.SetOptions() ..................... 9-35
EFI_DRIVER_CONFIGURATION_PROTOCOL.OptionsValid()................... 9-38
EFI_DRIVER_CONFIGURATION_PROTOCOL.ForceDefaults()................. 9-40
9.5 EFI Driver Diagnostics Protocol ........................................................................ 9-43
EFI_DRIVER_DIAGNOSTICS_PROTOCOL.................................................. 9-43
EFI_DRIVER_DIAGNOSTICS_PROTOCOL.RunDiagnostics() ................... 9-44
9.6 EFI Component Name Protocol ........................................................................ 9-47
EFI_COMPONENT_NAME_PROTOCOL ...................................................... 9-47
EFI_COMPONENT_NAME_PROTOCOL.GetDriverName() ........................ 9-48
EFI_COMPONENT_NAME_PROTOCOL.GetControllerName() .................. 9-50
Version 1.10 12/01/02 ix
Extensible Firmware Interface Specification
10 Protocols — Console Support
10.1 Console I/O Protocol......................................................................................... 10-1
10.1.1 Overview.................................................................................................. 10-1
10.1.2 ConsoleIn Definition ................................................................................. 10-2
10.2 Simple Input Protocol........................................................................................ 10-4
SIMPLE_INPUT ............................................................................................. 10-4
SIMPLE_INPUT.Reset() .............................................................................. 10-5
SIMPLE_INPUT.ReadKeyStroke()............................................................... 10-6
10.2.1 ConsoleOut or StandardError................................................................... 10-8
10.3 Simple Text Output Protocol ............................................................................. 10-8
SIMPLE_TEXT_OUTPUT Protocol ................................................................ 10-8
SIMPLE_TEXT_OUTPUT.Reset() ............................................................. 10-11
SIMPLE_TEXT_OUTPUT.OutputString()................................................... 10-12
SIMPLE_TEXT_OUTPUT.TestString() ...................................................... 10-16
SIMPLE_TEXT_OUTPUT.QueryMode() .................................................... 10-17
SIMPLE_TEXT_OUTPUT.SetMode() ........................................................ 10-18
SIMPLE_TEXT_OUTPUT.SetAttribute() .................................................... 10-19
SIMPLE_TEXT_OUTPUT.ClearScreen()................................................... 10-21
SIMPLE_TEXT_OUTPUT.SetCursorPosition() .......................................... 10-22
SIMPLE_TEXT_OUTPUT.EnableCursor()................................................. 10-23
10.4 Universal Graphics Adapter Protocols............................................................. 10-24
10.4.1 UGA ROM.............................................................................................. 10-24
10.4.2 UGA Draw Protocol ................................................................................ 10-25
10.4.3 Blt Buffer ................................................................................................ 10-25
10.4.4 UGA I/O Protocol.................................................................................... 10-26
10.4.5 Fallback Mode Driver ............................................................................. 10-26
10.5 UGA Draw Protocol......................................................................................... 10-27
EFI_UGA_DRAW_PROTOCOL................................................................... 10-27
EFI_UGA_DRAW_PROTOCOL.GetMode()............................................... 10-28
EFI_UGA_DRAW_PROTOCOL.SetMode() ............................................... 10-29
EFI_UGA_DRAW_PROTOCOL.Blt() ......................................................... 10-31
10.6 Rules for PCI/AGP Devices ............................................................................ 10-34
10.7 UGA I/O Protocol ............................................................................................ 10-35
EFI_UGA_IO_PROTOCOL.......................................................................... 10-35
EFI_UGA_IO_PROTOCOL.CreateDevice() ............................................... 10-37
EFI_UGA_IO_PROTOCOL.DeleteDevice() ............................................... 10-38
PUGA_FW_SERVICE_DISPATCH.DispatchService()............................... 10-39
10.8 Implementation Rules for an EFI UGA Driver.................................................. 10-42
10.9 UGA Draw Protocol to UGA I/O Protocol Mapping .......................................... 10-43
10.9.1 UGA System Requirements ................................................................... 10-43
10.9.2 System Abstraction Requirements ......................................................... 10-44
10.9.3 Firmware to OS Hand-off........................................................................ 10-44
10.10 Simple Pointer Protocol................................................................................... 10-46
EFI_SIMPLE_POINTER_PROTOCOL......................................................... 10-46
EFI_SIMPLE_POINTER.Reset()................................................................ 10-48
EFI_SIMPLE_POINTER.GetState() ........................................................... 10-49
x 12/01/02 Version 1.10
Contents
10.11 EFI Simple Pointer Device Paths .................................................................... 10-51
10.12 Serial I/O Protocol........................................................................................... 10-55
SERIAL_IO_PROTOCOL............................................................................. 10-55
SERIAL_IO.Reset() ................................................................................... 10-58
SERIAL_IO.SetAttributes() ........................................................................ 10-59
SERIAL_IO.SetControl()............................................................................ 10-61
SERIAL_IO.GetControl()............................................................................ 10-63
SERIAL_IO.Write() .................................................................................... 10-64
SERIAL_IO.Read() .................................................................................... 10-65
11 Protocols — Bootable Image Support
11.1 LOAD_FILE Protocol ........................................................................................ 11-1
LOAD_FILE Protocol...................................................................................... 11-1
LOAD_FILE.LoadFile() ................................................................................ 11-2
11.2 File System Format........................................................................................... 11-4
11.2.1 System Partition ....................................................................................... 11-4
11.2.1.1 File System Format ....................................................................... 11-5
11.2.1.2 File Names.................................................................................... 11-5
11.2.1.3 Directory Structure......................................................................... 11-5
11.2.2 Partition Discovery ................................................................................... 11-7
11.2.2.1 EFI Partition Header ...................................................................... 11-8
11.2.2.2 ISO-9660 and El Torito................................................................ 11-12
11.2.2.3 Legacy Master Boot Record ........................................................ 11-13
11.2.2.4 Legacy Master Boot Record and GPT Partitions ......................... 11-14
11.2.3 Media Formats ....................................................................................... 11-15
11.2.3.1 Removable Media........................................................................ 11-15
11.2.3.2 Diskette ....................................................................................... 11-15
11.2.3.3 Hard Drive................................................................................... 11-16
11.2.3.4 CD-ROM and DVD-ROM............................................................. 11-16
11.2.3.5 Network....................................................................................... 11-16
11.3 File System Protocol ....................................................................................... 11-17
Simple File System Protocol ........................................................................ 11-17
EFI_FILE_IO_INTERFACE.OpenVolume()................................................ 11-19
11.4 EFI_FILE Protocol........................................................................................... 11-20
EFI_FILE Protocol........................................................................................ 11-20
EFI_FILE.Open() ....................................................................................... 11-22
EFI_FILE.Close() ....................................................................................... 11-24
EFI_FILE.Delete()...................................................................................... 11-25
EFI_FILE.Read()........................................................................................ 11-26
EFI_FILE.Write()........................................................................................ 11-27
EFI_FILE.SetPosition() .............................................................................. 11-28
EFI_FILE.GetPosition().............................................................................. 11-29
EFI_FILE.GetInfo() .................................................................................... 11-30
EFI_FILE.SetInfo()..................................................................................... 11-31
EFI_FILE.Flush() ....................................................................................... 11-32
EFI_FILE_INFO ......................................................................................... 11-33
EFI_FILE_SYSTEM_INFO ........................................................................ 11-35
Version 1.10 12/01/02 xi
Extensible Firmware Interface Specification
EFI_FILE_SYSTEM_VOLUME_LABEL ..................................................... 11-36
11.5 DISK_IO Protocol............................................................................................ 11-37
DISK_IO Protocol......................................................................................... 11-37
EFI_DISK_IO.ReadDisk() .......................................................................... 11-39
EFI_DISK_IO.WriteDisk() .......................................................................... 11-40
11.6 BLOCK_IO Protocol........................................................................................ 11-41
BLOCK_IO Protocol ..................................................................................... 11-41
EFI_BLOCK_IO.Reset()............................................................................. 11-44
EFI_BLOCK_IO.ReadBlocks() ................................................................... 11-45
EFI_BLOCK_IO.WriteBlocks() ................................................................... 11-47
EFI_BLOCK_IO.FlushBlocks()................................................................... 11-49
11.7 UNICODE_COLLATION Protocol ................................................................... 11-50
UNICODE_COLLATION Protocol ................................................................ 11-50
UNICODE_COLLATION.StriColl() ............................................................. 11-52
UNICODE_COLLATION.MetaiMatch() ...................................................... 11-53
UNICODE_COLLATION.StrLwr() .............................................................. 11-55
UNICODE_COLLATION.StrUpr() .............................................................. 11-56
UNICODE_COLLATION.FatToStr() ........................................................... 11-57
UNICODE_COLLATION.StrToFat() ........................................................... 11-58
12 Protocols — PCI Bus Support
12.1 PCI Root Bridge I/O Support............................................................................. 12-1
12.1.1 PCI Root Bridge I/O Overview.................................................................. 12-1
12.1.1.1 Sample PCI Architectures.............................................................. 12-4
12.2 PCI Root Bridge I/O Protocol ............................................................................ 12-8
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL .................................................. 12-8
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.PollMem()............................. 12-16
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.PollIo().................................. 12-18
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Mem.Read()
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Mem.Write() ......................... 12-20
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Io.Read()
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Io.Write() .............................. 12-22
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Pci.Read()
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Pci.Write() ............................ 12-24
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.CopyMem() .......................... 12-26
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Map().................................... 12-28
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Unmap() ............................... 12-30
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.AllocateBuffer()..................... 12-31
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.FreeBuffer().......................... 12-33
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Flush().................................. 12-34
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.GetAttributes() ...................... 12-35
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.SetAttributes() ...................... 12-37
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL.Configuration()...................... 12-40
12.2.1 PCI Root Bridge Device Paths................................................................ 12-42
xii 12/01/02 Version 1.10
Contents
12.3 PCI Driver Model............................................................................................. 12-46
12.3.1 PCI Driver Initialization ........................................................................... 12-46
12.3.1.1 Driver Configuration Protocol....................................................... 12-48
12.3.1.2 Driver Diagnostics Protocol ......................................................... 12-48
12.3.1.3 Component Name Protocol ......................................................... 12-48
12.3.2 PCI Bus Drivers...................................................................................... 12-49
12.3.2.1 Driver Binding Protocol for PCI Bus Drivers................................. 12-50
12.3.2.2 PCI Enumeration ......................................................................... 12-53
12.3.3 PCI Device Drivers ................................................................................. 12-53
12.3.3.1 Driver Binding Protocol for PCI Device Drivers............................ 12-53
12.4 EFI PCI I/O Protocol ....................................................................................... 12-55
EFI_PCI_IO_PROTOCOL............................................................................ 12-56
EFI_PCI_IO_PROTOCOL.PollMem() ........................................................ 12-65
EFI_PCI_IO_PROTOCOL.PollIo() ............................................................. 12-67
EFI_PCI_IO_PROTOCOL.Mem.Read() EFI_PCI_IO_PROTOCOL.
Mem.Write()............................................................................................... 12-69
EFI_PCI_IO_PROTOCOL.Io.Read() EFI_PCI_IO_PROTOCOL.
Io.Write().................................................................................................... 12-71
EFI_PCI_IO_PROTOCOL.Pci.Read() EFI_PCI_IO_PROTOCOL.
Pci.Write().................................................................................................. 12-73
EFI_PCI_IO_PROTOCOL.CopyMem() ...................................................... 12-75
EFI_PCI_IO_PROTOCOL.Map() ............................................................... 12-78
EFI_PCI_IO_PROTOCOL.Unmap()........................................................... 12-80
EFI_PCI_IO_PROTOCOL.AllocateBuffer() ................................................ 12-81
EFI_PCI_IO_PROTOCOL.FreeBuffer() ..................................................... 12-83
EFI_PCI_IO_PROTOCOL.Flush() ............................................................. 12-84
EFI_PCI_IO_PROTOCOL.GetLocation() ................................................... 12-85
EFI_PCI_IO_PROTOCOL.Attributes() ....................................................... 12-86
EFI_PCI_IO_PROTOCOL.GetBarAttributes() ............................................ 12-89
EFI_PCI_IO_PROTOCOL.SetBarAttributes() ............................................ 12-92
12.4.1 PCI Device Paths ................................................................................... 12-94
12.4.2 PCI Option ROMs................................................................................... 12-96
12.4.2.1 PCI Bus Driver Responsibilities ................................................... 12-98
12.4.2.2 PCI Device Driver Responsibilities .............................................. 12-99
12.4.3 Nonvolatile Storage .............................................................................. 12-101
12.4.4 PCI Hot-Plug Events ............................................................................ 12-102
13 Protocols — SCSI Bus Support
13.1 SCSI Pass Thru Protocol .................................................................................. 13-1
EFI_SCSI_PASS_THRU Protocol.................................................................. 13-1
EFI_SCSI_PASS_THRU_PROTOCOL.PassThru() ..................................... 13-5
EFI_SCSI_PASS_THRU_PROTOCOL.GetNextDevice()........................... 13-10
EFI_SCSI_PASS_THRU_PROTOCOL.BuildDevicePath() ........................ 13-12
EFI_SCSI_PASS_THRU_PROTOCOL.GetTargetLun()............................. 13-14
EFI_SCSI_PASS_THRU_PROTOCOL.ResetChannel()............................ 13-16
EFI_SCSI_PASS_THRU_PROTOCOL.ResetTarget()............................... 13-17
13.2 SCSI Pass Thru Device Paths ........................................................................ 13-18
Version 1.10 12/01/02 xiii
Extensible Firmware Interface Specification
14 Protocols — USB Support
14.1 USB Host Controller Protocol............................................................................ 14-1
14.1.1 USB Host Controller Protocol Overview ................................................... 14-1
EFI_USB_HC_PROTOCOL ........................................................................... 14-2
EFI_USB_HC_PROTOCOL.Reset()............................................................ 14-4
EFI_USB_HC_PROTOCOL.GetState() ....................................................... 14-6
EFI_USB_HC_PROTOCOL.SetState()........................................................ 14-8
EFI_USB_HC_PROTOCOL.ControlTransfer()........................................... 14-10
EFI_USB_HC_PROTOCOL.BulkTransfer() ............................................... 14-13
EFI_USB_HC_PROTOCOL.AsyncInterruptTransfer() ............................... 14-16
EFI_USB_HC_PROTOCOL.SyncInterruptTransfer() ................................. 14-19
EFI_USB_HC_PROTOCOL.IsochronousTransfer()................................... 14-21
EFI_USB_HC_PROTOCOL.AsyncIsochronousTransfer() ......................... 14-23
EFI_USB_HC_PROTOCOL.GetRootHubPortNumber()............................. 14-25
EFI_USB_HC_PROTOCOL.GetRootHubPortStatus() ............................... 14-26
EFI_USB_HC_PROTOCOL.SetRootHubPortFeature().............................. 14-30
EFI_USB_HC_PROTOCOL.ClearRootHubPortFeature() .......................... 14-32
14.2 USB Driver Model ........................................................................................... 14-34
14.2.1 Scope..................................................................................................... 14-34
14.2.2 USB Driver Model Overview ................................................................... 14-34
14.2.3 USB Bus Driver ...................................................................................... 14-35
14.2.3.1 USB Bus Driver Entry Point......................................................... 14-35
14.2.3.2 Driver Binding Protocol for USB Bus Drivers ............................... 14-35
14.2.3.3 USB Hot-Plug Event .................................................................... 14-36
14.2.3.4 USB Bus Enumeration................................................................. 14-36
14.2.4 USB Device Driver ................................................................................. 14-37
14.2.4.1 USB Device Driver Entry Point .................................................... 14-37
14.2.4.2 Driver Binding Protocol for USB Device Drivers........................... 14-37
14.2.5 EFI USB I/O Protocol Overview.............................................................. 14-37
EFI_USB_IO Protocol .................................................................................. 14-38
EFI_USB_IO_PROTOCOL.UsbControlTransfer()...................................... 14-40
EFI_USB_IO_PROTOCOL.UsbBulkTransfer()........................................... 14-43
EFI_USB_IO_PROTOCOL.UsbAsyncInterruptTransfer()........................... 14-45
EFI_USB_IO_PROTOCOL.UsbSyncInterruptTransfer() ............................ 14-48
EFI_USB_IO_PROTOCOL.UsbIsochronousTransfer() .............................. 14-50
EFI_USB_IO_PROTOCOL.UsbAsyncIsochronousTransfer()..................... 14-52
EFI_USB_IO_PROTOCOL.UsbGetDeviceDescriptor().............................. 14-54
EFI_USB_IO_PROTOCOL.UsbGetConfigDescriptor()............................... 14-56
EFI_USB_IO_PROTOCOL.UsbGetInterfaceDescriptor()........................... 14-57
EFI_USB_IO_PROTOCOL.UsbGetEndpointDescriptor()........................... 14-59
EFI_USB_IO_PROTOCOL.UsbGetStringDescriptor()................................ 14-61
EFI_USB_IO_PROTOCOL.UsbGetSupportedLanguages()....................... 14-62
EFI_USB_IO_PROTOCOL.UsbPortReset()............................................... 14-63
14.2.6 USB Device Paths.................................................................................. 14-64
14.2.6.1 USB Device Path Node ............................................................... 14-64
14.2.6.2 USB Device Path Example.......................................................... 14-65
xiv 12/01/02 Version 1.10
Contents
15 Protocols — Network Support
15.1 EFI_SIMPLE_NETWORK Protocol ................................................................... 15-1
EFI_SIMPLE_NETWORK Protocol ................................................................ 15-1
EFI_SIMPLE_NETWORK.Start()................................................................. 15-6
EFI_SIMPLE_NETWORK.Stop() ................................................................. 15-7
EFI_SIMPLE_NETWORK.Initialize()............................................................ 15-8
EFI_SIMPLE_NETWORK.Reset() ............................................................... 15-9
EFI_SIMPLE_NETWORK.Shutdown()....................................................... 15-10
EFI_SIMPLE_NETWORK.ReceiveFilters() ................................................ 15-11
EFI_SIMPLE_NETWORK.StationAddress()............................................... 15-13
EFI_SIMPLE_NETWORK.Statistics() ........................................................ 15-14
EFI_SIMPLE_NETWORK.MCastIPtoMAC() .............................................. 15-17
EFI_SIMPLE_NETWORK.NvData()........................................................... 15-18
EFI_SIMPLE_NETWORK.GetStatus()....................................................... 15-20
EFI_SIMPLE_NETWORK.Transmit()......................................................... 15-22
EFI_SIMPLE_NETWORK.Receive().......................................................... 15-24
15.2 NETWORK_INTERFACE_IDENTIFIER Protocol............................................ 15-26
EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL.......................... 15-26
15.3 PXE Base Code Protocol................................................................................ 15-29
EFI_PXE_BASE_CODE Protocol................................................................. 15-29
EFI_PXE_BASE_CODE.Start() ................................................................. 15-41
EFI_PXE_BASE_CODE.Stop().................................................................. 15-44
EFI_PXE_BASE_CODE.Dhcp()................................................................. 15-45
EFI_PXE_BASE_CODE.Discover() ........................................................... 15-47
EFI_PXE_BASE_CODE.Mtftp()................................................................. 15-50
EFI_PXE_BASE_CODE.UdpWrite() .......................................................... 15-54
EFI_PXE_BASE_CODE.UdpRead().......................................................... 15-56
EFI_PXE_BASE_CODE.SetIpFilter()......................................................... 15-59
EFI_PXE_BASE_CODE.Arp() ................................................................... 15-60
EFI_PXE_BASE_CODE.SetParameters() ................................................. 15-61
EFI_PXE_BASE_CODE.SetStationIp()...................................................... 15-63
EFI_PXE_BASE_CODE.SetPackets()....................................................... 15-64
15.4 PXE Base Code Callback Protocol ................................................................. 15-66
EFI_PXE_BASE_CODE_CALLBACK Protocol ............................................ 15-66
EFI_PXE_BASE_CODE_CALLBACK.Callback() ....................................... 15-67
15.5 Boot Integrity Services Protocol ...................................................................... 15-69
EFI_BIS_PROTOCOL.................................................................................. 15-69
EFI_BIS.Initialize() ..................................................................................... 15-72
EFI_BIS.Shutdown() .................................................................................. 15-76
EFI_BIS.Free()........................................................................................... 15-78
EFI_BIS.GetBootObjectAuthorizationCertificate() ...................................... 15-79
EFI_BIS.GetBootObjectAuthorizationCheckFlag() ..................................... 15-80
EFI_BIS.GetBootObjectAuthorizationUpdateToken()................................. 15-81
EFI_BIS.GetSignatureInfo()....................................................................... 15-82
Version 1.10 12/01/02 xv
Extensible Firmware Interface Specification
EFI_BIS.UpdateBootObjectAuthorization() ................................................ 15-87
EFI_BIS.VerifyBootObject() ....................................................................... 15-95
EFI_BIS.VerifyObjectWithCredential() ..................................................... 15-102
16 Protocols — Debugger Support
16.1 Overview........................................................................................................... 16-1
16.2 EFI Debug Support Protocol ............................................................................. 16-2
16.2.1 EFI Debug Support Protocol Overview..................................................... 16-2
EFI_DEBUG_SUPPORT_PROTOCOL.......................................................... 16-3
EFI_DEBUG_SUPPORT_PROTOCOL.GetMaximumProcessorIndex()....... 16-5
EFI_DEBUG_SUPPORT_PROTOCOL.RegisterPeriodicCallback()............. 16-6
EFI_DEBUG_SUPPORT_PROTOCOL.RegisterExceptionCallback() ........ 16-10
EFI_DEBUG_SUPPORT_PROTOCOL.InvalidateInstructionCache()......... 16-13
16.3 EFI Debugport Protocol................................................................................... 16-14
16.3.1 EFI Debugport Overview ........................................................................ 16-14
EFI_DEBUGPORT_PROTOCOL................................................................. 16-15
EFI_DEBUGPORT_PROTOCOL.Reset() .................................................. 16-16
EFI_DEBUGPORT_PROTOCOL.Write() ................................................... 16-17
EFI_DEBUGPORT_PROTOCOL.Read() ................................................... 16-18
EFI_DEBUGPORT_PROTOCOL.Poll() ..................................................... 16-19
16.3.2 Debugport Device Path .......................................................................... 16-20
16.3.3 EFI Debugport Variable .......................................................................... 16-21
16.4 EFI Debug Support Table ............................................................................... 16-22
16.4.1 Overview................................................................................................ 16-22
16.4.2 EFI System Table Location .................................................................... 16-24
16.4.3 EFI Image Info........................................................................................ 16-24
17 Protocols — Compression Algorithm Specification
17.1 Algorithm Overview........................................................................................... 17-1
17.2 Data Format...................................................................................................... 17-3
17.2.1 Bit Order................................................................................................... 17-3
17.2.2 Overall Structure ...................................................................................... 17-3
17.2.3 Block Structure......................................................................................... 17-4
17.2.3.1 Block Header................................................................................. 17-4
17.2.3.2 Block Body .................................................................................... 17-7
17.3 Compressor Design .......................................................................................... 17-8
17.3.1 Overall Process........................................................................................ 17-8
17.3.2 String Info Log.......................................................................................... 17-9
17.3.2.1 Data Structures ........................................................................... 17-10
17.3.2.2 Searching the Tree ...................................................................... 17-11
17.3.2.3 Adding String Info........................................................................ 17-11
17.3.2.4 Deleting String Info...................................................................... 17-12
17.3.3 Huffman Code Generation...................................................................... 17-13
17.3.3.1 Huffman Tree Generation ............................................................ 17-13
17.3.3.2 Code Length Adjustment ............................................................. 17-13
17.3.3.3 Code Generation ......................................................................... 17-14
xvi 12/01/02 Version 1.10
Contents
17.4 Decompressor Design..................................................................................... 17-15
17.5 Decompress Protocol...................................................................................... 17-16
EFI_DECOMPRESS_PROTOCOL .............................................................. 17-16
EFI_DECOMPRESS_PROTOCOL.GetInfo() ............................................. 17-17
EFI_DECOMPRESS_PROTOCOL.Decompress()..................................... 17-19
18 Protocols — Device I/O Protocol
18.1 Device I/O Overview ......................................................................................... 18-1
18.2 DEVICE_IO Protocol......................................................................................... 18-2
DEVICE_IO Protocol...................................................................................... 18-2
DEVICE_IO.Mem(), .Io(), and .Pci() ............................................................. 18-5
DEVICE_IO.PciDevicePath() ....................................................................... 18-7
DEVICE_IO.Map() ....................................................................................... 18-8
DEVICE_IO.Unmap()................................................................................. 18-10
DEVICE_IO.AllocateBuffer() ...................................................................... 18-11
DEVICE_IO.Flush() ................................................................................... 18-13
DEVICE_IO.FreeBuffer() ........................................................................... 18-14
19 EFI Byte Code Virtual Machine
19.1 Overview........................................................................................................... 19-1
19.1.1 Processor Architecture Independence...................................................... 19-1
19.1.2 OS Independent ....................................................................................... 19-2
19.1.3 EFI Compliant .......................................................................................... 19-2
19.1.4 Coexistence of Legacy Option ROMs....................................................... 19-2
19.1.5 Relocatable Image ................................................................................... 19-2
19.1.6 Size Restrictions Based on Memory Available.......................................... 19-3
19.2 Memory Ordering .............................................................................................. 19-3
19.3 Virtual Machine Registers ................................................................................. 19-3
19.4 Natural Indexing................................................................................................ 19-5
19.4.1 Sign Bit..................................................................................................... 19-5
19.4.2 Bits Assigned to Natural Units .................................................................. 19-6
19.4.3 Constant................................................................................................... 19-6
19.4.4 Natural Units ............................................................................................ 19-6
19.5 EBC Instruction Operands ................................................................................ 19-7
19.5.1 Direct Operands ....................................................................................... 19-7
19.5.2 Indirect Operands..................................................................................... 19-7
19.5.3 Indirect with Index Operands.................................................................... 19-8
19.5.4 Immediate Operands................................................................................ 19-8
19.6 EBC Instruction Syntax ..................................................................................... 19-9
19.7 Instruction Encoding ......................................................................................... 19-9
19.7.1 Instruction Opcode Byte Encoding ......................................................... 19-10
19.7.2 Instruction Operands Byte Encoding ...................................................... 19-10
19.7.3 Index/Immediate Data Encoding............................................................. 19-11
19.8 EBC Instruction Set......................................................................................... 19-11
ADD........................................................................................................... 19-12
AND........................................................................................................... 19-13
ASHR ........................................................................................................ 19-14
BREAK ...................................................................................................... 19-15
Version 1.10 12/01/02 xvii
Extensible Firmware Interface Specification
CALL ......................................................................................................... 19-17
CMP .......................................................................................................... 19-20
CMPI ......................................................................................................... 19-22
DIV ............................................................................................................ 19-24
DIVU.......................................................................................................... 19-25
EXTNDB.................................................................................................... 19-26
EXTNDD.................................................................................................... 19-27
EXTNDW................................................................................................... 19-28
JMP ........................................................................................................... 19-29
JMP8 ......................................................................................................... 19-31
LOADSP.................................................................................................... 19-32
MOD.......................................................................................................... 19-33
MODU ....................................................................................................... 19-34
MOV .......................................................................................................... 19-35
MOVI ......................................................................................................... 19-37
MOVIn ....................................................................................................... 19-39
MOVn ........................................................................................................ 19-41
MOVREL ................................................................................................... 19-43
MOVsn ...................................................................................................... 19-44
MUL........................................................................................................... 19-46
MULU ........................................................................................................ 19-47
NEG........................................................................................................... 19-48
NOT........................................................................................................... 19-49
OR............................................................................................................. 19-50
POP........................................................................................................... 19-51
POPn......................................................................................................... 19-52
PUSH ........................................................................................................ 19-53
PUSHn ...................................................................................................... 19-54
RET ........................................................................................................... 19-55
SHL ........................................................................................................... 19-56
SHR........................................................................................................... 19-57
STORESP ................................................................................................. 19-58
SUB........................................................................................................... 19-59
XOR........................................................................................................... 19-60
19.9 Runtime and Software Conventions ................................................................ 19-61
19.9.1 Calling Outside VM................................................................................. 19-61
19.9.2 Calling Inside VM ................................................................................... 19-61
19.9.3 Parameter Passing................................................................................. 19-61
19.9.4 Return Values ........................................................................................ 19-61
19.9.5 Binary Format......................................................................................... 19-61
19.10 Architectural Requirements............................................................................. 19-61
19.10.1 EBC Image Requirements...................................................................... 19-62
19.10.2 EBC Execution Interfacing Requirements............................................... 19-62
19.10.3 Interfacing Function Parameters Requirements...................................... 19-62
19.10.4 Function Return Requirements............................................................... 19-62
19.10.5 Function Return Values Requirements................................................... 19-62
xviii 12/01/02 Version 1.10
Contents
19.11 EBC Interpreter Protocol................................................................................. 19-63
EFI_EBC_PROTOCOL ................................................................................ 19-63
EFI_EBC_PROTOCOL.CreateThunk() ...................................................... 19-65
EFI_EBC_PROTOCOL.UnloadImage() ..................................................... 19-66
EFI_EBC_PROTOCOL.RegisterICacheFlush().......................................... 19-67
EFI_EBC_PROTOCOL.GetVersion()......................................................... 19-69
19.12 EBC Tools....................................................................................................... 19-70
19.12.1 EBC C Compiler..................................................................................... 19-70
19.12.2 C Coding Convention ............................................................................. 19-70
19.12.3 EBC Interface Assembly Instructions...................................................... 19-70
19.12.4 Stack Maintenance and Argument Passing ............................................ 19-70
19.12.5 Native to EBC Arguments Calling Convention ........................................ 19-71
19.12.6 EBC to Native Arguments Calling Convention ........................................ 19-71
19.12.7 EBC to EBC Arguments Calling Convention........................................... 19-71
19.12.8 Function Returns.................................................................................... 19-71
19.12.9 Function Return Values .......................................................................... 19-71
19.12.10 Thunking ................................................................................................ 19-72
19.12.10.1 Thunking EBC to Native Code .................................................... 19-72
19.12.10.2 Thunking Native Code to EBC .................................................... 19-73
19.12.10.3 Thunking EBC to EBC ................................................................ 19-73
19.12.11 EBC Linker............................................................................................. 19-74
19.12.12 Image Loader......................................................................................... 19-74
19.12.13 Debug Support....................................................................................... 19-74
19.13 VM Exception Handling................................................................................... 19-75
19.13.1 Divide By 0 Exception ............................................................................ 19-75
19.13.2 Debug Break Exception.......................................................................... 19-75
19.13.3 Invalid Opcode Exception....................................................................... 19-75
19.13.4 Stack Fault Exception............................................................................. 19-75
19.13.5 Alignment Exception............................................................................... 19-75
19.13.6 Instruction Encoding Exception .............................................................. 19-75
19.13.7 Bad Break Exception.............................................................................. 19-76
19.13.8 Undefined Exception .............................................................................. 19-76
19.14 Option ROM Formats...................................................................................... 19-76
19.14.1 EFI Drivers for PCI Add-in Cards............................................................ 19-76
19.14.2 Non-PCI Bus Support ............................................................................. 19-76
Appendix A GUID and Time Formats ............................................................................. A-1
Appendix B Console
B.1 SIMPLE_INPUT .................................................................................................. B-1
B.2 SIMPLE_TEXT_OUTPUT ................................................................................... B-2
Appendix C Device Path Examples
C.1 Example Computer System.................................................................................C-1
C.2 Legacy Floppy ....................................................................................................C-2
C.3 IDE Disk.............................................................................................................. C-3
C.4 Secondary Root PCI Bus with PCI to PCI Bridge ................................................C-5
C.5 ACPI Terms ........................................................................................................ C-6
C.6 EFI Device Path as a Name Space.....................................................................C-7
Version 1.10 12/01/02 xix
Extensible Firmware Interface Specification
Appendix D Status Codes.................................................................................................D-1
Appendix E 32/64-Bit UNDI Specification
E.1 Introduction......................................................................................................... E-1
E.1.1 Definitions .................................................................................................. E-1
E.1.2 Referenced Specifications.......................................................................... E-3
E.1.3 OS Network Stacks .................................................................................... E-5
E.2 Overview............................................................................................................. E-7
E.2.1 32/64-bit UNDI Interface.............................................................................E-7
E.2.2 UNDI Command Format........................................................................... E-13
E.3 UNDI C Definitions............................................................................................ E-15
E.3.1 Portability Macros..................................................................................... E-15
E.3.2 Miscellaneous Macros.............................................................................. E-18
E.3.3 Portability Types....................................................................................... E-18
E.3.4 Simple Types ........................................................................................... E-20
E.3.5 Compound Types..................................................................................... E-33
E.4 UNDI Commands.............................................................................................. E-38
E.4.1 Command Linking and Queuing ............................................................... E-39
E.4.2 Get State.................................................................................................. E-41
E.4.3 Start ......................................................................................................... E-43
E.4.4 Stop .........................................................................................................E-48
E.4.5 Get Init Info............................................................................................... E-49
E.4.6 Get Config Info ......................................................................................... E-53
E.4.7 Initialize.................................................................................................... E-56
E.4.8 Reset........................................................................................................E-60
E.4.9 Shutdown................................................................................................. E-62
E.4.10 Interrupt Enables...................................................................................... E-64
E.4.11 Receive Filters ......................................................................................... E-66
E.4.12 Station Address........................................................................................ E-69
E.4.13 Statistics...................................................................................................E-71
E.4.14 MCast IP To MAC ....................................................................................E-74
E.4.15 NvData..................................................................................................... E-76
E.4.16 Get Status................................................................................................ E-80
E.4.17 Fill Header................................................................................................ E-83
E.4.18 Transmit................................................................................................... E-86
E.4.19 Receive.................................................................................................... E-90
E.5 UNDI as an EFI Runtime Driver ........................................................................ E-93
Appendix F Using the Simple Pointer Protocol ........................................................... F-1
Appendix G Using the EFI SCSI Pass Thru Protocol..................................................G-1
Appendix H Compression Source Code........................................................................H-1
Appendix I Decompression Source Code ...................................................................... I-1
Appendix J EFI Byte Code Virtual Machine Opcode Summary................................J-1
Appendix K Alphabetic Function Lists.....................................................................................K-1
xx 12/01/02 Version 1.10
Contents
References
Related Information.......................................................................................... References-1
Prerequisite Specifications ............................................................................... References-5
ACPI Specification.................................................................................... References-5
WfM Specification..................................................................................... References-5
Additional Considerations for Itanium-Based Platforms ............................ References-6
Glossary
................................................................................................................... Glossary-1
Index................................................................................................................................Index-1
Figures
1-1. EFI Conceptual Overview ...................................................................................... 9
2-1. Booting Sequence.................................................................................................. 1
2-2. Stack after AddressOfEntryPoint Called, IA-32 ..............................................10
2-3. Stack after AddressOfEntryPoint Called, Itanium-based Systems..................12
2-4. Construction of a Protocol.....................................................................................13
2-5. Desktop System....................................................................................................16
2-6. Server System ......................................................................................................16
2-7. Image Handle .......................................................................................................20
2-8. Driver Image Handle .............................................................................................21
2-9. Host Bus Controllers .............................................................................................22
2-10. PCI Root Bridge Device Handle............................................................................22
2-11. Connecting Device Drivers....................................................................................23
2-12. Connecting Bus Drivers ........................................................................................25
2-13. Child Device Handle with a Bus Specific Override ................................................26
5-1. Device Handle to Protocol Handler Mapping.........................................................32
5-2. Handle Database ..................................................................................................34
10-1. Software BLT Buffer..............................................................................................25
10-2. Fallback Mode Driver ............................................................................................26
11-1. Nesting of Legacy MBR Partition Records ............................................................. 7
11-2. GUID Partition Table (GPT) Scheme ..................................................................... 9
12-1. Host Bus Controllers.............................................................................................. 2
12-2. Device Handle for a PCI Root Bridge Controller..................................................... 3
12-3. Desktop System with One PCI Root Bridge ........................................................... 4
12-4. Server System with Four PCI Root Bridges............................................................ 5
12-5. Server System with Two PCI Segments................................................................. 6
12-6. Server System with Two PCI Host Buses............................................................... 7
12-7. Image Handle .......................................................................................................46
12-8. PCI Driver Image Handle ......................................................................................47
12-9. PCI Host Bus Controller ........................................................................................49
12-10. Device Handle for a PCI Host Bus Controller ........................................................49
12-11. Physical PCI Bus Structure ...................................................................................50
Version 1.10 12/01/02 xxi
Extensible Firmware Interface Specification
12-12. Connecting a PCI Bus Driver ................................................................................51
12-13. Child Handle Created by a PCI Bus Driver............................................................51
12-14. Connecting a PCI Device Driver............................................................................54
12-15. Recommended PCI Driver Image Layout ..............................................................99
14-1. Software Triggered State Transitions of a USB Host Controller ............................. 8
14-2. USB Bus Controller Handle...................................................................................34
16-1. Debug Support Table Indirection and Pointer Usage ............................................23
17-1. Bit Sequence of Compressed Data ........................................................................ 3
17-2. Compressed Data Structure................................................................................... 4
17-3. Block Structure ...................................................................................................... 4
17-4. Block Body............................................................................................................. 7
17-5. String Info Log Search Tree ..................................................................................10
17-6. Node Split .............................................................................................................12
C-1. Example Computer System.................................................................................... 1
C-2. Partial ACPI Name Space for Example System ..................................................... 2
C-3. EFI Device Path Displayed As a Name Space ....................................................... 7
E-1. Network Stacks with Three Classes of Drivers....................................................... 5
E-2. !PXE Structures for H/W and S/W UNDI ................................................................ 7
E-3. Issuing UNDI Commands......................................................................................12
E-4. UNDI Command Descriptor Block (CDB) ..............................................................13
E-5. Storage Types ......................................................................................................18
E-6. UNDI States, Transitions & Valid Commands .......................................................38
E-7. Linked CDBs.........................................................................................................39
E-8. Queued CDBs.......................................................................................................40
Tables
1-1. Organization of the EFI Specification ..................................................................... 3
EFI Runtime Services ............................................................................................ 6
2-1.
2-2. Common EFI Data Types....................................................................................... 7
2-3. Modifiers for Common EFI Data Types .................................................................. 8
2-4. EFI Protocols ........................................................................................................14
2-5. Required EFI Implementation Elements................................................................28
Global Variables..................................................................................................... 5
3-1
3-2 EFI Image Types.................................................................................................... 8
Event, Timer, and Task Priority Functions.............................................................. 2
5-1.
5-2. TPL Usage............................................................................................................. 3
5-3. TPL Restrictions..................................................................................................... 4
5-4. Memory Allocation Functions ................................................................................18
5-5. Memory Type Usage before ExitBootServices()...........................................19
xxii 12/01/02 Version 1.10
Contents
5-6. Memory Type Usage after ExitBootServices()..............................................20
5-7. Protocol Interface Functions .................................................................................31
5-8. Image Type Differences Summary........................................................................76
5-9. Image Functions ...................................................................................................77
5-10. Miscellaneous Boot Services Functions ................................................................86
Variable Services Functions................................................................................... 2
6-1.
6-2. Time Services Functions........................................................................................ 9
6-3. Virtual Memory Functions .....................................................................................16
6-4. Miscellaneous Runtime Services ..........................................................................20
Generic Device Path Node Structure ..................................................................... 3
8-1.
8-2. Device Path End Structure..................................................................................... 4
8-3. PCI Device Path..................................................................................................... 5
8-4. PCCARD Device Path............................................................................................ 5
8-5. Memory Mapped Device Path ................................................................................ 6
8-6. Vendor-Defined Device Path.................................................................................. 6
8-7. Controller Device Path ........................................................................................... 6
8-8. ACPI Device Path .................................................................................................. 8
8-9. Expanded ACPI Device Path ................................................................................. 8
8-10. ATAPI Device Path ................................................................................................ 9
8-11. SCSI Device Path .................................................................................................10
8-12. Fibre Channel Device Path ...................................................................................10
8-13. 1394 Device Path..................................................................................................10
8-14. USB Device Path ..................................................................................................11
8-15. USB Class Device Path ........................................................................................11
8-16. I2O Device Path.....................................................................................................12
8-17. MAC Address Device Path....................................................................................12
8-18. IPv4 Device Path ..................................................................................................12
8-19. IPv6 Device Path ..................................................................................................13
8-20. InfiniBand Device Path..........................................................................................13
8-21. UART Device Path................................................................................................14
8-22. Vendor-Defined Messaging Device Path...............................................................14
8-23. UART Flow Control Messaging Device Path.........................................................15
8-24. Hard Drive Media Device Path..............................................................................16
8-25. CD-ROM Media Device Path ................................................................................17
8-26. Vendor-Defined Media Device Path ......................................................................18
8-27. File Path Media Device Path.................................................................................18
8-28. Media Protocol Media Device Path .......................................................................18
8-29. BIOS Boot Specification Device Path....................................................................19
8-30. ACPI _CRS to EFI Device Path Mapping..............................................................20
8-31. ACPI _ADR to EFI Device Path Mapping..............................................................21
9-1.
EFI Driver Configuration Default Type...................................................................41
Supported Unicode Control Characters.................................................................. 2
10-1.
10-2. EFI Scan Codes for SIMPLE_INPUT_INTERFACE ................................................ 3
Version 1.10 12/01/02 xxiii
Extensible Firmware Interface Specification
10-3. EFI Cursor Location/Advance Rules .....................................................................14
10-4. Blt Operation Table ...............................................................................................33
10-5. PS/2 Mouse Device Path ......................................................................................51
10-6. Serial Mouse Device Path.....................................................................................52
10-7. USB Mouse Device Path.......................................................................................54
GUID Partition Table Header ................................................................................. 9
11-1.
11-2. GUID Partition Entry .............................................................................................11
11-3. Defined GUID Partition Entry - Partition Type GUIDs............................................12
11-4. Defined GUID Partition Entry - Attributes ..............................................................12
11-5. Legacy Master Boot Record..................................................................................13
11-6. Legacy Master Boot Record Partition Record .......................................................14
11-7. PMBR Entry to Precede a GUID Partition Table Header.......................................15
PCI Configuration Address....................................................................................25
12-1.
12-2. ACPI 2.0 QWORD Address Space Descriptor ......................................................41
12-3. ACPI 2.0 End Tag .................................................................................................41
12-4. PCI Root Bridge Device Path for a Desktop System .............................................42
12-5. PCI Root Bridge Device Path for Bridge #0 in a Server System ............................43
12-6. PCI Root Bridge Device Path for Bridge #1 in a Server System ............................43
12-7. PCI Root Bridge Device Path for Bridge #2 in a Server System ............................44
12-8. PCI Root Bridge Device Path for Bridge #3 in a Server System ............................44
12-9. PCI Root Bridge Device Path Using Expanded ACPI Device Path........................45
12-10. ACPI 2.0 QWORD Address Space Descriptor ......................................................90
12-11. ACPI 2.0 End Tag.................................................................................................90
12-12. PCI Device 7, Function 0 on PCI Root Bridge 0 ....................................................94
12-13. PCI Device 7, Function 0 behind PCI to PCI bridge ..............................................95
12-14. Standard PCI Expansion ROM Header .................................................................97
12-15. PCIR Data Structure .............................................................................................97
12-16. PCI Expansion ROM Code Types.........................................................................97
12-17. EFI PCI Expansion ROM Header ..........................................................................98
12-18. Recommended PCI Device Driver Layout ...........................................................100
Single Channel PCI SCSI Controller .....................................................................18
13-1.
13-2. Single Channel PCI SCSI Controller behind a PCI Bridge.....................................19
13-3. Channel #3 of a PCI SCSI Controller behind a PCI Bridge....................................20
USB Hub Port Status Bitmap ................................................................................27
14-1.
14-2. Hub Port Change Status Bitmap ...........................................................................28
14-3. USB Port Feature..................................................................................................31
14-4. USB Device Path Examples..................................................................................65
14-5. Another USB Device Path Example ......................................................................66
PXE Tag Definitions for EFI ..................................................................................39
15-1.
15-2. Destination IP Filter Operation ..............................................................................57
15-3. Destination UDP Port Filter Operation...................................................................57
15-4. Source IP Filter Operation.....................................................................................58
15-5. Source UDP Port Filter Operation .........................................................................58
xxiv 12/01/02 Version 1.10
Contents
16-1. Debugport Messaging Device Path ..........................................................................20
Block Header Fields............................................................................................... 5
17-1.
PCI Address........................................................................................................... 6
18-1.
General Purpose VM Registers.............................................................................. 3
19-1.
19-2. Dedicated VM Registers ........................................................................................ 4
19-3. VM Flags Register ................................................................................................. 4
19-4. Index Encoding...................................................................................................... 5
19-5. Index Size in Index Encoding................................................................................. 6
19-6. Opcode Byte Encoding .........................................................................................10
19-7. Operand Byte Encoding........................................................................................10
19-8. ADD Instruction Encoding .....................................................................................12
19-9. AND Instruction Encoding .....................................................................................13
19-10. ASHR Instruction Encoding...................................................................................14
19-11. VM Version format ................................................................................................15
19-12. BREAK Instruction Encoding.................................................................................16
19-13. CALL Instruction Encoding....................................................................................18
19-14. CMP Instruction Encoding.....................................................................................21
19-15. CMPI Instruction Encoding....................................................................................23
19-16. DIV Instruction Encoding.......................................................................................24
19-17. DIVU Instruction Encoding....................................................................................25
19-19. EXTNDD Instruction Encoding ..............................................................................27
19-20. EXTNDW Instruction Encoding .............................................................................28
19-21. JMP Instruction Encoding .....................................................................................30
19-22. JMP8 Instruction Encoding ...................................................................................31
19-23. LOADSP Instruction Encoding ..............................................................................32
19-24. MOD Instruction Encoding ....................................................................................33
19-25. MODU Instruction Encoding..................................................................................34
19-26. MOV Instruction Encoding ....................................................................................36
19-27. MOVI Instruction Encoding ...................................................................................37
19-28. MOVIn Instruction Encoding..................................................................................39
19-29. MOVn Instruction Encoding ..................................................................................41
19-30. MOVREL Instruction Encoding..............................................................................43
19-31. MOVsn Instruction Encoding.................................................................................44
19-32. MUL Instruction Encoding.....................................................................................46
19-33. MULU Instruction Encoding ..................................................................................47
19-34. NEG Instruction Encoding.....................................................................................48
19-35. NOT Instruction Encoding.....................................................................................49
19-36. OR Instruction Encoding.........................................................................................50
19-37. POP Instruction Encoding ......................................................................................51
19-38. POPn Instruction Encoding ....................................................................................52
19-39. PUSH Instruction Encoding ....................................................................................53
19-40. PUSHn Instruction Encoding ..................................................................................54
19-41. RET Instruction Encoding.......................................................................................55
19-42. SHL Instruction Encoding .......................................................................................56
Version 1.10 12/01/02 xxv
Extensible Firmware Interface Specification
19-43. SHR Instruction Encoding ......................................................................................57
19-44. STORESP Instruction Encoding.............................................................................58
19-45. SUB Instruction Encoding.......................................................................................59
19-46. XOR Instruction Encoding ......................................................................................60
EFI GUID Format................................................................................................... 1
A-1.
B-1.
EFI Scan Codes for SIMPLE_INPUT ..................................................................... 1
B-2. Control Sequences That Can Be Used to Implement SIMPLE_TEXT_OUTPUT ...... 2
C-1.
Legacy Floppy Device Path.................................................................................... 3
C-2. IDE Disk Device Path............................................................................................. 4
C-3. Secondary Root PCI Bus with PCI to PCI Bridge Device Path ............................... 5
EFI_STATUS Codes Ranges................................................................................. 1
D-1.
D-2. EFI_STATUS Success Codes (High Bit Clear) ...................................................... 1
D-3. EFI_STATUS Error Codes (High Bit Set)............................................................... 1
D-4. EFI_STATUS Warning Codes (High Bit Clear)....................................................... 2
E-1. Definitions................................................................................................................... 1
E-2. Referenced Specifications .......................................................................................... 3
E-3. Driver Types: Pros and Cons ..................................................................................... 6
E-4. !PXE Structure Field Definitions.................................................................................. 8
E-5. UNDI CDB Field Definitions .......................................................................................13
EBC Virtual Machine Opcode Summary................................................................. 1
J-1.
K-1. Functions Listed in Alphabetic Order .......................................................................... 1
K-2. Functions Listed Alphabetically within a Service or Protocol ......................................19
xxvi 12/01/02 Version 1.10
1

Introduction

This Extensible Firmware Interface (hereafter known as EFI) Specification describes an interface between the operating system (OS) and the platform firmware. The interface is in the form of data tables that contain platform-related information, and boot and runtime service calls that are available to the OS loader and the OS. Together, these provide a standard environment for bootinganOS.
The EFI specification is designed as a pure interface specification. As such, the specification defines the set of interfaces and structures that platform firmware must implement. Similarly, the specification defines the set of interfaces and structures that the OS may use in booting. How either the firmware developer chooses to implement the required elements or the OS developer chooses to make use of those interfaces and structures is an implementation decision left for the developer.
The intent of this specification is to define a way for the OS and platform firmware to communicate only information necessary to support the OS boot process. This is accomplished through a formal and complete abstract specification of the software-visible interface presented to the OS by the platform and firmware.
®
Using this formal definition, a shrink-wrap OS intended to run on Intel platforms will be able to boot on a variety of system designs without further platform or OS customization. The definition will also allow for platform innovation to introduce new features and functionality that enhance platform capability without requiring new code to be written in the OS boot sequence.
architecture-based
Furthermore, an abstract specification opens a route to replace legacy devices and firmware code over time. New device types and associated code can provide equivalent functionality through the same defined abstract interface, again without impact on the OS boot support code.
The EFI specification is primarily intended for the next generation of 32-bit Intel architecture (IA-32) and Itanium hardware platforms from mobile systems to servers. The specification provides a core set of services along with a selection of protocol interfaces. The selection of protocol interfaces can evolve over time to be optimized for various platform market segments. At the same time the specification allows maximum extensibility and customization abilities for OEMs to allow differentiation. In this, the purpose of EFI is to define an evolutionary path from the traditional “PC-AT”-style boot world into a legacy-API free environment.
®
-based computers. Thus, the specification is applicable to a full range of
Version 1.10 12/01/02 1-1

1.1 EFI Driver Model Extensions

Access to boot devices is provided through a set of protocol interfaces. The EFI 1.02 Specification describes these protocol interfaces in detail. However, it does not describe how these protocol interfaces are produced by the system firmware. The EFI 1.10 Specification includes extensions to the EFI 1.02 Specification that describe the EFI Driver Model along with additional protocol interfaces that provide access to a richer set of boot devices. One purpose of the EFI Driver Model is to provide a replacement for “PC-AT”-style option ROMs. It is important to point out that drivers written to the EFI Driver Model are designed to access boot devices in the preboot environment. They are not designed to replace the high performance OS specific drivers. The EFI 1.10 Specification is designed to be backward compatible with the EFI 1.02 Specification. This means that any EFI applications or drivers written to the EFI 1.02 Specification will continue to function on system firmware that complies with the EFI 1.10 Specification.
The EFI Driver Model is designed to support the execution of modular pieces of code, also known as drivers that run in the preboot environment. These drivers may manage or control hardware buses and devices on the platform or they may provide some software derived platform specific service.
The EFI Driver Model is designed to extend the EFI Specification in a way that supports device drivers and bus drivers. These extensions are provided in the form of new protocols, new boot services, and updated EFI boot services that are backward compatible with their original versions. The EFI Driver Model also contains information required by EFI driver writers to design and implement any combination of bus drivers and device drivers that a platform may need to boot an EFI compliant OS.
The EFI Driver Model is designed to be generic and can be adapted to any type of bus or device. The EFI 1.10 Specification describes how to write PCI bus drivers, PCI device drivers, USB bus drivers, USB device drivers, and SCSI drivers. Additions details are provided that allow EFI drivers to be stored in PCI option ROMs while maintaining compatibility with legacy option ROM images.
One of the design goals in the EFI 1.10 Specification is to keep the driver images as small as possible. However, if a driver is required to support multiple processor architectures, a driver object file would have to be shipped for each supported processor architecture. To address this space issue, the EFI 1.10 Specification also defines the EFI Byte Code Virtual Machine.AnEFI driver can be compiled into a single EFI Byte Code Virtual Machine object file. EFI 1.10 complaint firmware must contain an EFI Byte Code interpreter. This allows a single EFI Byte Code object file to be shipped that supports multiple processor architectures. Another space saving technique is the use of compression. The EFI 1.10 Specification defines compression and decompression algorithms that may be used to reduce the size of EFI drivers, and thus reduce the overhead when EFI drivers are stored in ROM devices.
The information contained in the EFI 1.10 Specification can be used by OSVs, IHVs, OEMs, and firmware vendors to design and implement EFI firmware, EFI drivers that produce standard protocol interfaces, and EFI operating system loaders that can be used to boot EFI compliant operating systems.
1-2 12/01/02 Version 1.10

1.2 Overview

This EFI 1.10 Specification is organized as listed in Table 1-1.
Table 1-1. Organization of the EFI Specification
Chapter/Appendix Description
1. Introduction Introduces the EFI Specification and topics related to using the specification.
2. Overview Describes the major components of EFI, including the boot manager, firmware core, calling conventions, protocols, and requirements.
3. Boot Manager Describes the boot manager, which is used to load EFI drivers and EFI applications.
4. EFI System Table Describes the EFI System Table that is passed to every EFI driver and EFI application.
5. Services — Boot Services Contains the definitions of the fundamental services that are present in an EFI-compliant system before an OS is booted.
6. Services — Runtime Services Contains definitions for the fundamental services that are present in an EFI-compliant system before and after an OS is booted.
7. Protocols — EFI Loaded Image Defines the EFI Loaded Image Protocol that describes an EFI Image that has been loaded into memory.
8. Protocols — Device Path Protocol Defines the device path protocol and provides the information needed to construct and manage device paths in the EFI environment.
9. Protocols — EFI Driver Model Describes a generic driver model for EFI. This includes the set of services and protocols that apply to every bus and device type. These protocols include the Driver Binding Protocol, the Platform Driver Override Protocol, the Bus Specific Driver Override Protocol, the Driver Diagnostics Protocol, the Driver Configuration Protocol, and the Component Name Protocol.
10. Protocols — Console Support Defines the Console I/O protocols, which handle input and output of text-based information intended for the system user while executing in the EFI boot services environment. These protocols include the Simple Input Protocol, the Simple Text Output Protocol, the Universal Graphics Adapter (UGA) Protocol, the Simple Pointer Protocol, and the Serial I/O Protocol.
Introduction
continued
Version 1.10 12/01/02 1-3
Table 1-1. Organization of the EFI Specification (continued)
Chapter/Appendix Description
11. Protocols — Bootable Image
Support
12. Protocols — PCI Bus Support Defines PCI Bus Drivers, PCI Device Drivers, and PCI Option
13. Protocols — SCSI Bus Support Defines the SCSI Pass Thru Protocol that is used to abstract
14. Protocols — USB Support Defines USB Bus Drivers and USB Device Drivers. The
15. Protocols — Network Support Defines the protocols that provide access to network devices
16. Protocols — Debugger Support An optional set of protocols that provide the services required to
17. Protocols — Compression
Algorithm Specification
18. Protocols — Device I/O Protocol Defines the Device I/O protocol, which is used by code running
Defines the protocols that provide access to bootable images while executing in the EFI boot services environment. It also describes the supported disk layouts including MBR, El Torito, and the Guided Partition Table (GPT). These protocols include the Load File Protocol, the Simple File System Protocol, the Disk I/O Protocol, the Block I/O Protocol, and the Unicode Collation Protocol.
ROM layouts. The protocols described include the PCI Root Bridge I/O Protocol and the PCI I/O Protocol.
access to a SCSI channel that is produced by a SCSI host controller.
protocols described include the USB Host Controller Protocol and the USB I/O Protocol.
while executing in the EFI boot services environment. These protocols include the Simple Network Protocol, the PXE Base Code Protocol, and the Boot Integrity services (BIS) Protocol.
implement a source level debugger for the EFI environment. The EFI DebugPort Protocol provides services to communicate with a remote debug host. The Debug Support Protocol provides services to hook processor exceptions, save the processor context, and restore the processor context. These protocols can be used in the implementation of a debug agent on the target system that interacts with the remote debug host.
Describes in detail the EFI compression/decompression algorithm, as well as the EFI Decompress Protocol. The EFI Decompress Protocol provides a standard decompression interface for use at boot time. The EFI Decompress Protocol is used by a PCI Bus Driver to decompress EFI drivers stored in PCI Option ROMs.
in the EFI boot services environment to access memory and I/O.
continued
1-4 12/01/02 Version 1.10
Introduction
Table 1-1. Organization of the EFI Specification (continued)
Chapter/Appendix Description
19. EFI Byte Code Virtual Machine Defines the EFI Byte Code virtual processor and its instruction set. It also defines how EBC object files are loaded into memory, and the mechanism for transitioning from native code to EBC code and back to native code. The information in this document is sufficient to implement an EFI Byte Code interpreter, an EFI Byte Code compiler, and an EFI Byte Code linker.
A. GUID and Time Formats Explains format of EFI GUIDs (Guaranteed Unique Identifiers).
B. Console Describes the requirements for a basic text-based console
required by EFI-conformant systems to provide communication capabilities.
C. Device Path Examples Examples of use of the data structures that defines various
hardware devices to the EFI boot services.
D. Status Codes Lists success, error, and warning codes returned by EFI
interfaces.
E. 32/64-Bit UNDI Specification This appendix defines the 32/64-bit H/W and S/W Universal
Network Driver Interfaces (UNDIs).
F. Using the Simple Pointer Protocol This appendix provides the suggested usage of the Simple
Pointer Protocol.
G. Using the EFI SCSI Pass Thru
Protocol
H. Compression Source Code The C source code to an implementation of the EFI Compression
I. Decompression Source Code The C source code to an implementation of the EFI
J. EFI Byte Code Virtual Machine
Opcode Summary
K. Alphabetic Function List Lists all EFI interface functions alphabetically.
References Lists all necessary and/or useful specifications, web sites, and
Glossary Briefly describes terms defined or referenced by this
Index Provides an index to the key terms and concepts in the
This appendix provides an example on how the SCSI Pass Thru Protocol can be used.
Algorithm.
Decompression Algorithm.
A summary of the opcodes in the instruction set of the EFI Byte Code Virtual Machine.
other documentation that is referenced in this EFI Specification.
specification.
specification.
Version 1.10 12/01/02 1-5

1.3 Goals

The “PC-AT” boot environment presents significant challenges to innovation within the industry. Each new platform capability or hardware innovation requires firmware developers to craft increasingly complex solutions, and often requires OS developers to make changes to their boot code before customers can benefit from the innovation. This can be a time-consuming process requiring a significant investment of resources.
The primary goal of the EFI specification is to define an alternative boot environment that can alleviate some of these considerations. In this goal, the specification is similar to other existing boot specifications. The main properties of this specification and similar solutions can be summarized by these attributes:
• Coherent, scalable platform environment. The specification defines a complete solution for the firmware to completely describe platform features and surface platform capabilities to the OS during the boot process. The definitions are rich enough to cover the full range of contemporary Intel architecture-based system designs.
• Abstraction of the OS from the firmware. The specification defines interfaces to platform capabilities. Through the use of abstract interfaces, the specification allows the OS loader to be constructed with far less knowledge of the platform and firmware that underlie those interfaces. The interfaces represent a well-defined and stable boundary between the underlying platform and firmware implementation and the OS loader. Such a boundary allows the underlying firmware and the OS loader to change provided both limit their interactions to the defined interfaces.
• Reasonable device abstraction free of legacy interfaces. “PC-AT” BIOS interfaces require the OS loader to have specific knowledge of the workings of certain hardware devices. This specification provides OS loader developers with something different— abstract interfaces that make it possible to build code that works on a range of underlying hardware devices without having explicit knowledge of the specifics for each device in the range.
• Abstraction of Option ROMs from the firmware. This specification defines interfaces to platform capabilities including standard bus types such as PCI, USB, and SCSI. The list of supported bus types may grow over time, so a mechanism to extend to future bus types is included. These defined interfaces and the ability to extend to future bus types are components of the EFI Driver Model. One purpose of the EFI Driver Model is to solve a wide range of issues that are present in existing “PC-AT” option ROMs. Like OS loaders, drivers use the abstract interfaces so device drivers and bus drivers can be constructed with far less knowledge of the platform and firmware that underlie those interfaces.
• Architecturally shareable system partition. Initiatives to expand platform capabilities and add new devices often require software support. In many cases, when these platform innovations are activated before the OS takes control of the platform, they must be supported by code that is specific to the platform rather than to the customer’s choice of OS. The traditional approach to this problem has been to embed code in the platform during manufacturing (for example, in flash memory devices). Demand for such persistent storage is increasing at a rapid rate. This specification defines persistent store on large mass storage media types for use by platform support code extensions to supplement the traditional approach. The definition of how this works is made clear in the
1-6 12/01/02 Version 1.10
Introduction
specification to ensure that firmware developers, OEMs, operating system vendors, and perhaps even third parties can share the space safely while adding to platform capability.
Defining a boot environment that delivers these attributes could be accomplished in many ways. Indeed several alternatives, perhaps viable from an academic point of view, already existed at the time this specification was written. These alternatives, however, typically presented high barriers to entry given the current infrastructure capabilities surrounding Intel architecture platforms. This specification is intended to deliver the attributes listed above while also recognizing the unique needs of an industry that has considerable investment in compatibility and a large installed base of systems that cannot be abandoned summarily. These needs drive the requirements for the additional attributes embodied in this specification:
• Evolutionary, not revolutionary. The interfaces and structures in the specification are designed to reduce the burden of an initial implementation as much as possible. While care has been taken to ensure that appropriate abstractions are maintained in the interfaces themselves, the design also ensures that reuse of BIOS code to implement the interfaces is possible with a minimum of additional coding effort. In other words, on IA-32 platforms the specification can be implemented initially as a thin interface layer over an underlying implementation based on existing code. At the same time, introduction of the abstract interfaces provides for migration away from legacy code in the future. Once the abstraction is established as the means for the firmware and OS loader to interact during boot, developers are free to replace legacy code underneath the abstract interfaces at leisure. A similar migration for hardware legacy is also possible. Since the abstractions hide the specifics of devices, it is possible to remove underlying hardware, and replace it with new hardware that provides improved functionality, reduced cost, or both. Clearly this requires that new platform firmware be written to support the device and present it to the OS loader via the abstract interfaces. However, without the interface abstraction, removal of the legacy device might not be possible at all.
• Compatibility by design. The design of the system partition structures also preserves all the structures that are currently used in the “PC-AT” boot environment. Thus it is a simple matter to construct a single system that is capable of booting a legacy OS or an EFI-aware OS from the same disk.
• Simplifies addition of OS-neutral platform value-add. The specification defines an open extensible interface that lends itself to the creation of platform “drivers.” These may be analogous to OS drivers, providing support for new device types during the boot process, or they may be used to implement enhanced platform capabilities like fault tolerance or security. Furthermore this ability to extend platform capability is designed into the specification from the outset. This is intended to help developers avoid many of the frustrations inherent in trying to squeeze new code into the traditional BIOS environment. As a result of the inclusion of interfaces to add new protocols, OEMs or firmware developers have an infrastructure to add capability to the platform in a modular way. Such drivers may potentially be implemented using high level coding languages because of the calling conventions and environment defined in the specification. This in turn may help to reduce the difficulty and cost of innovation. The option of a system partition provides an alternative to nonvolatile memory storage for such extensions.
• Built on existing investment. Where possible, the specification avoids redefining interfaces and structures in areas where existing industry specifications provide adequate coverage. For example, the ACPI specification provides the OS with all the information
Version 1.10 12/01/02 1-7
necessary to discover and configure platform resources. Again, this philosophical choice for the design of the specification is intended to keep barriers to its adoption as low as possible.

1.4 Target Audience

This document is intended for the following readers:
• IHVs and OEMs who will be implementing EFI drivers.
• OEMs who will be creating Intel architecture-based platforms intended to boot shrink-
wrap operating systems.
• BIOS developers, either those who create general-purpose BIOS and other firmware products or those who modify these products for use in Intel architecture-based products.
• Operating system developers who will be adapting their shrink-wrap operating system products to run on Intel architecture-based platforms.

1.5 EFI Design Overview

The design of EFI is based on the following fundamental elements:
• Reuse of existing table-based interfaces. In order to preserve investment in existing infrastructure support code, both in the OS and firmware, a number of existing specifications that are commonly implemented on Intel architecture platforms must be implemented on platforms wishing to comply with the EFI specification. (See the References appendix for additional information.)
• System partition. The System partition defines a partition and file system that are designed to allow safe sharing between multiple vendors, and for different purposes. The ability to include a separate sharable system partition presents an opportunity to increase platform value-add without significantly growing the need for nonvolatile platform memory.
• Boot services. Boot services provide interfaces for devices and system functionality that can be used during boot time. Device access is abstracted through “handles” and “protocols.” This facilitates reuse of investment in existing BIOS code by keeping underlying implementation requirements out of the specification without burdening the consumer accessing the device.
• Runtime services. A minimal set of runtime services is presented to ensure appropriate abstraction of base platform hardware resources that may be needed by the OS during its normal operations.
1-8 12/01/02 Version 1.10
Introduction
Figure 1-1 shows the principal components of EFI and their relationship to platform hardware and OS software.
OPERATING SYSTEM
EFI OS LOADER
(OTHER)
SMBIOS
ACPI
INTERFACES
FROM
OTHER
REQUIRED
SPECS
EFI BOOT SERVICES
PLATFORM HARDWARE
EFI SYSTEM PARTITION
EFI RUNTIME
SERVICES
EFI OS
LOADER
OM13141
Figure 1-1. EFI Conceptual Overview
This diagram illustrates the interactions of the various components of an EFI specification­compliant system that are used to accomplish platform and OS boot.
The platform firmware is able to retrieve the OS loader image from the EFI System Partition. The specification provides for a variety of mass storage device types including disk, CD-ROM and DVD as well as remote boot via a network. Through the extensible protocol interfaces, it is possible to envision other boot media types being added, although these may require OS loader modifications if they require use of protocols other than those defined in this document
Once started, the OS loader continues to boot the complete operating system. To do so, it may use the EFI boot services and interfaces defined by this or other required specifications to survey, comprehend and initialize the various platform components and the OS software that manages them. EFI runtime services are also available to the OS loader during the boot phase.

1.6 EFI Driver Model

This section describes the goals of a driver model for EFI firmware. The goal is for this driver model to provide a mechanism for implementing bus drivers and device drivers for all types of buses and devices. At the time of writing, the bus types that must be covered include PCI, USB,
†
SCSI, InfiniBand
, and so on.
As hardware architectures continue to evolve, the number and types of buses present in platforms are increasing. This trend is especially true in high-end servers. However, a more diverse set of
Version 1.10 12/01/02 1-9
bus types is being designed into desktop and mobile systems and even some embedded systems. This increasing complexity means that a simple method for describing and managing all the buses and devices in a platform is required in the preboot environment. The EFI Driver Model provides this simple method in the form of protocols services and boot services.

1.6.1 EFI Driver Model Goals

The EFI Driver Model has the following goals:
• Compatible –TheEFI Driver Model must maintain compatibility with the EFI 1.02 Specification. This means that the EFI Driver Model must take advantage of the extensibility mechanisms in the EFI 1.02 Specification to add the required functionality
• Simple – Drivers written to the EFI Driver Model must be simple to implement and simple to maintain. The EFI Driver Model must allow a driver writer to concentrate on the specific device for which the driver is being developed. A driver should not be concerned with platform policy or platform management issues. These considerations should be left to the system firmware.
• Scalable –TheEFI Driver Model must be able to adapt to all types of platforms. These platforms would include embedded systems; mobile and desktop systems, as well as workstations; and servers.
• Flexible –TheEFI Driver Model must support the ability to enumerate all the devices, or to enumerate only those devices required to boot the required OS. The minimum device enumeration provides support for more rapid boot capability, and the full device enumeration provides the ability to perform OS installations, system maintenance, or system diagnostics on any boot device present in the system.
• Extensible –TheEFI Driver Model must be able to extend to future bus types as they are defined.
• Portable – Drivers written to the EFI Driver Model must portable between platforms and between processor architectures. Initially this is limited to platforms with IA-32 family
®
and Itanium
• Interoperable – Drivers must coexist with other drivers and system firmware and must do so without generating resource conflicts.
• Describe Complex Bus Hierarchies –TheEFI Driver Model must be able to describe a variety of bus topologies from very simple single bus platforms to very complex platforms containing many buses of various types.
• Small Driver Footprint – The size of executables produced by the EFI Driver Model must be minimized to reduce the overall platform cost. While flexibility and extensibility are goals, the additional overhead required to support these must be kept to a minimum to prevent the size of firmware components from becoming unmanageable.
• Address Legacy Option ROM Issues –TheEFI Driver Model must directly address and solve the constraints and limitations of legacy option ROMs. Specifically it must be possible to build add-in cards that support both EFI drivers and legacy option ROMs where such cards can execute in both legacy BIOS systems and EFI conforming platforms without modifications to the code carried on the card. The solution must provide an evolutionary path to migrate from legacy option ROMs driver to EFI drivers.
processors, but no processor-specific assumptions are made.
1-10 12/01/02 Version 1.10

1.6.2 Legacy Option ROM Issues

This idea of supporting a driver model came from feedback on the EFI Specification that provided a clear, market-driven requirement for an alternative to the legacy option ROM (sometimes also referred to as an expansion ROM). The perception is that the advent of the EFI Specification represents a chance to escape the limitations implicit to the construction and operation of legacy option ROM images by replacing them with an alternative mechanism that works within the framework of the EFI Specification.

1.7 Migration Requirements

Migration requirements cover the transition period from initial implementation of this specification to a future time when all platforms and operating systems implement to this specification. During this period, two major compatibility considerations are important:
1. The ability to continue booting legacy operating systems; and
2. The ability to implement EFI on existing platforms by reusing as much existing firmware code to keep development resource and time requirements to a minimum.

1.7.1 Legacy Operating System Support

Introduction
The EFI specification represents the preferred means for a shrink-wrap OS and firmware to communicate during the Intel architecture platform boot process. However, choosing to make a platform that complies with this specification in no way precludes a platform from also supporting existing legacy OS binaries that have no knowledge of the EFI specification.
The EFI specification does not restrict a platform designer who chooses to support both the EFI specification and a more traditional “PC-AT” boot infrastructure. If such a legacy infrastructure is to be implemented it should be developed in accordance with existing industry practice that is defined outside the scope of this specification. The choice of legacy operating systems that are supported on any given platform is left to the manufacturer of that platform.

1.7.2 Supporting the EFI Specification on a Legacy Platform

The EFI specification has been carefully designed to allow for existing systems to be extended to support it with a minimum of development effort. In particular, the abstract structures and services defined in the EFI specification can all be supported on legacy platforms.
For example, to accomplish such support on an existing IA-32 platform that uses traditional BIOS to support operating system boot, an additional layer of firmware code would need to be provided. This extra code would be required to translate existing interfaces for services and devices into support for the abstractions defined in this specification.
Version 1.10 12/01/02 1-11

1.8 Conventions Used in This Document

This document uses typographic and illustrative conventions described below.

1.8.1 Data Structure Descriptions

Intel architecture processors of the IA-32 family are “little endian” machines. This distinction means that the low-order byte of a multibyte data item in memory is at the lowest address, while the high-order byte is at the highest address. Intel Itanium processors may be configured for both “little endian” and “big endian” operation. All implementations designed to conform to this specification will use “little endian” operation.
In some memory layout descriptions, certain fields are marked reserved. Software must initialize such fields to zero and ignore them when read. On an update operation, software must preserve any reserved field.

1.8.2 Protocol Descriptions

A protocol description generally has the following format:
Protocol: The formal name of the protocol interface.
Summary: A brief description of the protocol interface. GUID: The 128-bit unique identifier for the protocol interface. Revision Number: The revision of the protocol interface. Protocol Interface Structure:
A “C-style” data structure definition containing the procedures and data fields produced by this protocol interface.
Parameters: A brief description of each field in the protocol interface
structure.
Related Definitions: The type declarations and constants that are used in the
protocol interface structure or any of its procedures.
Description: A description of the functionality provided by the
protocol interface including any limitations and caveats of which the caller should be aware.
1-12 12/01/02 Version 1.10

1.8.3 Procedure Descriptions

A procedure description generally has the following format:
ProcedureName(): The formal name of the procedure.
Summary: A brief description of the procedure. Prototype: A “C-style” procedure header defining the calling
sequence.
Parameters: The parameters defined in the template are described in
further detail.
Related Definitions: The type declarations and constants that are only used by
this procedure.
Description: A description of the functionality provided by the
interface including any limitations and caveats the caller of which should be aware.
Status Codes Returned: A description of the codes returned by the interface.
Any status codes listed in this table are required to be implemented by the procedure. Additional error codes may be returned, but they will not be tested by standard compliance tests, and any software that uses the procedure cannot depend on any of the extended error codes that an implementation may provide.
Introduction

1.8.4 Instruction Descriptions

An instruction description for EBC instructions generally has the following format:
InstructionName The formal name of the EBC Instruction.
SYNTAX: A brief description of the EBC Instruction. DESCRIPTION: A description of the functionality provided by the EBC
Instruction accompanied by a table that details the instruction encoding.
OPERATION: Details the operations performed on operands. BEHAVIORS AND RESTRICTIONS: An item by item description of the behavior
of each operand involved in the instruction and any restrictions that apply to the operands or the instruction.
Version 1.10 12/01/02 1-13

1.8.5 Pseudo-Code Conventions

Pseudo code is presented to describe algorithms in a more concise form. None of the algorithms in this document are intended to be compiled directly. The code is presented at a level corresponding to the surrounding text.
In describing variables, a list is an unordered collection of homogeneous objects. A queue is an ordered list of homogeneous objects. Unless otherwise noted, the ordering is assumed to be FIFO.
Pseudo code is presented in a C-like format, using C conventions where appropriate. The coding style, particularly the indentation style, is used for readability and does not necessarily comply with an implementation of the EFI Specification.

1.8.6 Typographic Conventions

This document uses the typographic and illustrative conventions described below:
Plain text The normal text typeface is used for the vast majority of the
descriptive text in a specification.
Plain text (blue)
Bold In text, a Bold typeface identifies a processor register name. In other
Italic In text, an Italic typeface can be used as emphasis to introduce a new
BOLD Monospace Computer code, example code segments, and all prototype code
BOLD Monospace
NOTE
Due to management and file size considerations, only the first occurrence of the reference on each page is an active link. Subsequent references on the same page will not be actively linked to the definition and will use the standard, nonunderlined BOLD Monospace typeface. Find the first instance of the name (in the underlined BOLD Monospace word to jump to the function or type definition.
In the electronic version of this specification, any plain text underlined and in blue indicates an active link to the cross-reference.
instances, a Bold typeface can be used as a running head within a paragraph.
term or to indicate a manual or specification name.
segments use a BOLD Monospace typeface with a dark red color. These code listings normally appear in one or more separate paragraphs, though words or segments can also be embedded in a normaltextparagraph.
In the electronic version of this specification, words in a BOLD
Monospace typeface that is underlined and in a dark red color
indicate an active hyperlink to the definition for that function or type definition. Click on the word to follow the hyperlink.
typeface) on the page and click on the
Italic Monospace In code or in text, words in Italic Monospace indicate
placeholder names for variable information that must be supplied (i.e., arguments).
1-14 12/01/02 Version 1.10

Overview

EFI allows the extension of platform firmware by loading EFI driver and EFI application images. When EFI drivers and EFI applications are loaded they have access to all EFI defined runtime and boot services. See Figure 2-1.
2
Driver
Platform
Init
Standard firmware platform initilization
EFI
EFI Image
Load
Drivers and applications loaded iteratively
API specified Value add implementation
Boot Manager EFI binaries
EFI
Application
OS Loader
Boot from ordered list of EFIOS loaders
Retry
EFI
Load
EFI
Bootcode
Failure
Operation handed off to OS loader
Boot
Services
Terminate
OS Loader
EFI API
OM13144
Figure 2-1. Booting Sequence
EFI allows the consolidation of boot menus from the OS loader and platform firmware into a single platform firmware menu. These platform firmware menus will allow the selection of any EFI OS loader from any partition on any boot medium that is supported by EFI boot services. An EFI OS loader can support multiple options that can appear on the user interface. It is also possible to include legacy boot options, such as booting from the A: or C: drive in the platform firmware boot menus.
EFI supports booting from media that contain an EFI OS loader or an EFI-defined System Partition. An EFI-defined System Partition is required by EFI to boot from a block device. EFI does not require any change to the first sector of a partition, so it is possible to build media that will boot on both legacy Intel architecture and EFI platforms.
Version 1.10 12/01/02 2-1

2.1 Boot Manager

EFI contains a boot manager that allows the loading of EFI applications (including OS 1st stage loader) or EFI drivers from any file on an EFI defined file system or through the use of an EFI defined image loading service. EFI defines NVRAM variables that are used to point to the file to be loaded. These variables also contain application specific data that are passed directly to the EFI application. The variables also contain a human readable Unicode string that can be displayed to the user in a menu.
The variables defined by EFI allow the system firmware to contain a boot menu that can point to all the operating systems, and even multiple versions of the same operating systems. The design goal of EFI was to have one set of boot menus that could live in platform firmware. EFI only specifies the NVRAM variables used in selecting boot options. EFI leaves the implementation of the menu system as value added implementation space.
EFI greatly extends the boot flexibility of a system over the current state of the art in the PC-AT-class system. The PC-AT-class systems today are restricted to boot from the first floppy, hard drive, CD-ROM, or network card attached to the system. Booting from a common hard drive can cause lots of interoperability problems between operating systems, and different versions of operating systems from the same vendor.

2.1.1 EFI Images

EFI Images are a class of files defined by EFI that contain executable code. The most distinguishing feature of EFI Images is that the first set of bytes in the EFI Image file contains an image header that defines the encoding of the executable image.
EFI uses a subset of the PE32+ image format with a modified header signature. The modification to signature value in the PE32+ image is done to distinguish EFI images from normal PE32 executables. The “+” addition to PE32 provides the 64-bit relocation fix-up extensions to standard PE32 format.
For images with the EFI image signature, the Subsystem values in the PE image header are defined below. The major differences between image types are the memory type that the firmware will load the image into, and the action taken when the image’s entry point exits or returns. An application image is always unloaded when control is returned from the image’s entry point. A driver image is only unloaded if control is passed back with an EFI error code.
// PE32+ Subsystem type for EFI images #define EFI_IMAGE_SUBSYSTEM_EFI_APPLICATION 10 #define EFI_IMAGE_SUBSYSTEM_EFI_BOOT_SERVICE_DRIVER 11 #define EFI_IMAGE_SUBSYSTEM_EFI_RUNTIME_DRIVER 12
2-2 12/01/02 Version 1.10
Overview
The Machine value that is found in the PE image file header is used to indicate the machine code type of the image. The machine code types defined for images with the EFI image signature are defined below. A given platform must implement the image type native to that platform and the image type for EFI Byte Code (EBC). Support for other machine code types are optional to the platform.
// PE32+ Machine type for EFI images #define EFI_IMAGE_MACHINE_IA32 0x014c #define EFI_IMAGE_MACHINE_IA64 0x0200 #define EFI_IMAGE_MACHINE_EBC 0x0EBC
An EFI image is loaded into memory through the LoadImage()
Boot Service. This service loads an image with a PE32+ format into memory. This PE32+ loader is required to load all the sections of the PE32+ image into memory. Once the image is loaded into memory, and the appropriate “fix-ups” have been performed, control is transferred to a loaded image at the
AddressOfEntryPoint reference according to the normal indirect calling conventions of
IA-32 or Itanium-based applications. All other linkage to and from an EFI image is done programmatically.

2.1.2 EFI Applications

EFI Applications are loaded by the EFI Boot Manager or by other EFI applications. To load an application the firmware allocates enough memory to hold the image, copies the sections within the application to the allocated memory and applies the relocation fix-ups needed. Once done, the allocated memory is set to be the proper type for code and data for the image. Control is then transferred to the application’s entry point. When the application returns from its entry point, or when it calls the Boot Service Exit() returned to the EFI component that loaded the application.
When the EFI Boot Manager loads an application, the image handle may be used to locate the “load options” for the application. The load options are stored in nonvolatile storage and are associated with the application being loaded and executed by the EFI Boot Manager.
, the application is unloaded from memory and control is
Version 1.10 12/01/02 2-3

2.1.3 EFI OS Loaders

An EFI OS loader is a special type of EFI application that normally takes over control of the system from the EFI firmware. When loaded, the OS loader behaves like any other EFI application in that it must only use memory it has allocated from the firmware and can only use EFI services and protocols to access the devices that the firmware exposes. If the OS Loader includes any boot service style driver functions, it must use the proper EFI interfaces to obtain access to the bus specific-resources. That is, I/O and memory-mapped device registers must be accessed through the proper bus specific I/O calls like those that an EFI driver would perform.
If the OS loader experiences a problem and cannot load its operating system correctly, it can release all allocated resources and return control back to the firmware via the Boot Service Exit() The Exit() call allows both an error code and ExitData to be returned. The ExitData contains both a Unicode string and OS loader-specific data to be returned.
If the OS loader successfully loads its operating system, it can take control of the system by using the Boot Service ExitBootServices() all boot services in the system are terminated, including memory management, and the OS loader is responsible for the continued operation of the system.
. After successfully calling ExitBootServices(),

2.1.4 EFI Drivers

call.
EFI Drivers are loaded by the EFI Boot Manager, the EFI firmware, or by other EFI applications. To load an EFI Driver the firmware allocates enough memory to hold the image, copies the sections within the driver to the allocated memory and applies the relocation fix-ups needed. Once done, the allocated memory is set to be the proper type for code and data for the image. Control is then transferred to the driver’s entry point. When the driver returns from its entry point, or when it calls the Boot Service Exit(), the driver is optionally unloaded from memory and control is returned to the EFI component that loaded the driver. A driver is not unloaded from memory if it returns a status code of EFI_SUCCESS. If the driver’s return code is an error status code, then the driver is unloaded from memory.
There are two types of EFI Drivers. These are Boot Service Drivers and Runtime Drivers. The only difference between these two driver types is that Runtime Drivers are available after an OS Loader has taken control of the platform with the Boot Service ExitBootServices(). Boot Service Drivers are terminated when ExitBootServices() is called, and all the memory resources consumed by the Boot Service Drivers are released for use in the operating system environment.
2-4 12/01/02 Version 1.10

2.2 Firmware Core

This section provides an overview of the services defined by EFI. These include boot services and runtime services.

2.2.1 EFI Services

The purpose of the EFI interfaces is to define a common boot environment abstraction for use by loaded EFI images, which include EFI drivers, EFI applications, and EFI OS loaders. The calls are defined with a full 64-bit interface, so that there is headroom for future growth. The goal of this set of abstracted platform calls is to allow the platform and OS to evolve and innovate independently of one another. Also, a standard set of primitive runtime services may be used by operating systems.
Platform interfaces defined in this chapter allow the use of standard Plug and Play Option ROMs as the underlying implementation methodology for the boot services. The PC industry has a huge investment in Intel Architecture Option ROM technology, and the obsolescence of this installed base of technology is not practical in the first generation of EFI-compliant systems. The interfaces have been designed in such as way as to map back into legacy interfaces. These interfaces have in no way been burdened with any restrictions inherent to legacy Option ROMs.
The EFI platform interfaces are intended to provide an abstraction between the platform and the OS that is to boot on the platform. The EFI specification also provides abstraction between diagnostics or utility programs and the platform; however, it does not attempt to implement a full diagnostic OS environment. It is envisioned that a small diagnostic OS-like environment can be easily built on top of an EFI system. Such a diagnostic environment is not described by this specification.
Overview
Interfaces added by this specification are divided into the following categories and are detailed later in this document:
• Runtime services
• Boot services interfaces, with the following subcategories:
Global boot service interfacesDevice handle-based boot service interfacesDevice protocolsProtocol services
Version 1.10 12/01/02 2-5

2.2.2 Runtime Services

This section describes EFI runtime service functions. The primary purpose of the EFI runtime services is to abstract minor parts of the hardware implementation of the platform from the OS. EFI runtime service functions are available during the boot process and also at runtime provided the OS switches into flat physical addressing mode to make the runtime call. However, if the OS loader or OS uses the Runtime Service SetVirtualAddressMap() be able to call EFI runtime services in a virtual addressing mode. All runtime interfaces are nonblocking interfaces and can be called with interrupts disabled if desired.
In all cases memory used by the EFI runtime services must be reserved and not used by the OS. EFI runtime services memory is always available to an EFI function and will never be directly manipulated by the OS or its components. EFI is responsible for defining the hardware resources used by runtime services, so the OS can synchronize with those resources when runtime service calls are made, or guarantee that the OS never uses those resources.
Table 2-1 lists the Runtime Services functions.
Table 2-1. EFI Runtime Services
Name Description
GetTime()
SetTime()
GetWakeupTime()
SetWakeupTime()
GetVariable()
GetNextVariableName()
SetVariable()
SetVirtualAddressMap()
ConvertPointer()
GetNextHighMonotonicCount()
ResetSystem()
Returns the current time, time context, and time keeping capabilities.
Sets the current time and time context.
Returns the current wakeup alarm settings.
Sets the current wakeup alarm settings.
Returns the value of a named variable.
Enumerates variable names.
Sets, and if needed creates, a variable.
Switches all runtime functions from physical to virtual addressing.
Used to convert a pointer from physical to virtual addressing.
Subsumes the platform's monotonic counter functionality.
Resets all processors and devices and reboots the system.
service, the OS will only
2-6 12/01/02 Version 1.10

2.3 Calling Conventions

Unless otherwise stated, all functions defined in the EFI specification are called through pointers in common, architecturally defined, calling conventions found in C compilers. Pointers to the various global EFI functions are found in the EFI_RUNTIME_SERVICES and EFI_BOOT_SERVICES tables that are located via the EFI system table. Pointers to other functions defined in this specification are located dynamically through device handles. In all cases, all pointers to EFI functions are cast with the word EFIAPI. This allows the compiler for each architecture to supply the proper compiler keywords to achieve the needed calling conventions. When passing pointer arguments to Boot Services, Runtime Services, and Protocol Interfaces, the caller has the following responsibilities:
1. It is the caller’s responsibility to pass pointer parameters that reference physical memory
locations. If a pointer is passed that does not point to a physical memory location(i.e. a memory mapped I/O region), the results are unpredictable and the system may halt.
2. It is the caller’s responsibility to pass pointer parameters with correct alignment. If an
unaligned pointer is passed to a function, the results are unpredictable and the system may halt.
3. It is the caller’s responsibility to not pass in a NULL parameter to a function unless it is
explicitly allowed. If a NULL pointer is passed to a function, the results are unpredictable and the system may hang.
Overview
Calling conventions for IA-32 or Itanium-based applications are described in more detail below. Any function or protocol may return any valid return code.

2.3.1 Data Types

Table 2-2 lists the common data types that are used in the interface definitions, and Table 2-3 lists their modifiers. Unless otherwise specified all data types are naturally aligned. Structures are aligned on boundaries equal to the largest internal datum of the structure and internal data are implicitly padded to achieve natural alignment.
Table 2-2. Common EFI Data Types
Mnemonic Description
BOOLEAN
INTN Signed value of native width. (4 bytes on IA-32, 8 bytes on Itanium processor
UINTN Unsigned value of native width. (4 bytes on IA-32, 8 bytes on Itanium processor
INT8 1-byte signed value.
UINT8 1-byte unsigned value.
INT16 2-byte signed value.
UINT16 2-byte unsigned value.
Logical Boolean. 1-byte value containinga0forFALSE or a 1 for TRUE. Other values are undefined.
instructions)
instructions)
continued
Version 1.10 12/01/02 2-7
Table 2-2. Common EFI Data Types (continued)
Mnemonic Description
INT32 4-byte signed value.
UINT32 4-byte unsigned value.
INT64 8-byte signed value.
UINT64 8-byte unsigned value.
CHAR8 1-byte Character.
CHAR16 2-byte Character. Unless otherwise specified all strings are stored in the
UTF-16 encoding format as defined by Unicode 2.1 and ISO/IEC 10646 standards.
VOID Undeclared type.
EFI_GUID 128-bit buffer containing a unique identifier value. Unless otherwise specified,
aligned on a 64-bit boundary.
EFI_STATUS Status code. Type INTN.
EFI_HANDLE A collection of related interfaces. Type VOID *.
EFI_EVENT Handle to an event structure. Type VOID *.
EFI_LBA Logical block address. Type UINT64.
EFI_TPL Task priority level. Type UINTN.
EFI_MAC_ADDRESS 32-byte buffer containing a network Media Access Control address.
EFI_IPv4_ADDRESS 4-byte buffer. An IPv4 internet protocol address.
EFI_IPv6_ADDRESS 16-byte buffer. An IPv6 internet protocol address.
EFI_IP_ADDRESS 16-byte buffer aligned on a 4-byte boundary. An IPv4 or IPv6 internet protocol
address.
<Enumerated Type>
Element of a standard ANSI C enum type declaration. Type INTN.
Table 2-3. Modifiers for Common EFI Data Types
Mnemonic Description
IN Datum is passed to the function.
OUT Datum is returned from the function.
OPTIONAL
EFIAPI Defines the calling convention for EFI interfaces.
2-8 12/01/02 Version 1.10
Passing the datum to the function is optional, and a
passed if the value is not supplied.
NULL may be

2.3.2 IA-32 Platforms

All functions are called with the C language calling convention. The general-purpose registers that are volatile across function calls are eax, ecx,andedx. All other general-purpose registers are nonvolatile and are preserved by the target function. In addition, unless otherwise specified by the function definition, all other registers are preserved. For example, this would include the entire
®
floating point and Intel
During boot services time the processor is in the following execution mode:
• Uniprocessor
• Protected mode
• Paging mode not enabled
• Selectors are set to be flat and are otherwise not used
• Interrupts are enabled–though no interrupt services are supported other than the EFI boot
services timer functions (All loaded device drivers are serviced synchronously by “polling.”)
• DirectionflaginEFLAGsisclear
• Other general purpose flag registers are undefined
• 128 KB, or more, of available stack space
For an operating system to use any EFI runtime services, it must:
• Preserve all memory in the memory map marked as runtime code and runtime data
• Call the runtime service functions, with the following conditions:
Called from the boot processorIn protected modePaging not enabledAll selectors set to be flat with virtual = physical address. If the OS Loader or OS used
SetVirtualAddressMap()
space, then this condition does not have to be met.
DirectionflaginEFLAGsclear4 KB, or more, of available stack spaceInterrupts disabled
• Synchronize processor access to the legacy CMOS registers (if there are multiple processors).
Only one processor can access the registers at any given time.
• ACPI Tables loaded at boot time must be contained in memory of type
EfiACPIReclaimMemory.
• The system firmware must not request a virtual mapping for any memory descriptor of type
EfiACPIReclaimMemory or EfiACPIMemoryNVS.
• EFI memory descriptors of type EfiACPIReclaimMemory and EfiACPIMemoryNVS
must be aligned on a 4 KB boundary and must be a multiple of 4 KB in size.
• Any EFI memory descriptor that requests a virtual mapping via the
EFI_MEMORY_DESCRIPTOR having the EFI_MEMORY_RUNTIME bit set must be aligned
on a 4 KB boundary and must be a multiple of 4 KB in size.
MMX™technology state.
to relocate the runtime services in a virtual address
Overview
Version 1.10 12/01/02 2-9
• An ACPI Memory Op-region must inherit cacheability attributes from the EFI memory map. If
the system memory map does not contain cacheability attributes, the ACPI Memory Op-region must inherit its cacheability attributes from the ACPI name space. If no cacheability attributes exist in the system memory map or the ACPI name space, then the region must be assumed to be noncacheable.
• ACPI tables loaded at runtime must be contained in memory of type EfiACPIMemoryNVS or
EfiFirmareReserved. The cacheability attributes for ACPI tables loaded at runtime (via
ACPI LoadTable) should be defined in the EFI memory map. If no information about the table location exists in the EFI memory map, the table is assumed to be noncached.
2.3.2.1 Handoff State
When an IA-32 EFI OS is loaded, the system firmware hands off control to the OS in flat 32-bit mode. All descriptors are set to their 4 GB limits so that all of memory is accessible from all segments. The address of the IDT is not defined and thus it cannot be manipulated directly during boot services.
Figure 2-2 shows the stack after AddressOfEntryPoint in the image’s PE32+ header has been called on IA-32 systems. All EFI image entry points take two parameters. These are the image handle of the EFI image, and a pointer to the EFI System Table.
Stack Location
EFI_SYSTEM_TABLE *
EFI_HANDLE
<return address>
Figure 2-2. Stack after AddressOfEntryPoint Called, IA-32
ESP + 8
ESP + 4
ESP
OM13145
2-10 12/01/02 Version 1.10

2.3.3 Itanium®-Based Platforms

EFI executes as an extension to the SAL execution environment with the same rules as laid out by the SAL specification.
During boot services time the processor is in the following execution mode:
• Uniprocessor
• Physical mode
• 128 KB, or more, of available stack space
• 16 KB, or more, of available backing store space
• May only use the lower 32 floating point registers
The EFI Image may invoke both SAL and EFI procedures. Once in virtual mode, the EFI OS must switch back to physical mode to call any boot services. If SetVirtualAddressMap() been used, then runtime service calls are made in virtual mode.
• ACPI Tables loaded at boot time must be contained in memory of type
EfiACPIReclaimMemory.
• The system firmware must not request a virtual mapping for any memory descriptor of type
EfiACPIReclaimMemory or EfiACPIMemoryNVS.
• EFI memory descriptors of type EfiACPIReclaimMemory and EfiACPIMemoryNVS
must be aligned on an 8 KB boundary and must be a multiple of 8 KB in size.
• Any EFI memory descriptor that requests a virtual mapping via the
EFI_MEMORY_DESCRIPTOR having the EFI_MEMORY_RUNTIME bit set must be aligned
on a 8 KB boundary and must be a multiple of 8 KB in size.
• An ACPI Memory Op-region must inherit cacheability attributes from the EFI memory map. If
the system memory map does not contain cacheability attributes the ACPI Memory Op-region must inherit its cacheability attributes from the ACPI name space. If no cacheability attributes exist in the system memory map or the ACPI name space, then the region must be assumed to be noncacheable.
• ACPI tables loaded at runtime must be contained in memory of type EfiACPIMemoryNVS or
EfiFirmareReserved. The cacheability attributes for ACPI tables loaded at runtime (via
ACPI LoadTable) should be defined in the EFI memory map. If no information about the table location exists in the EFI memory map, the table is assumed to be noncached.
Overview
has
Refer to the IA-64 System Abstraction Layer Specification (see the References appendix) for details.
EFI procedures are invoked using the P64 C calling conventions defined for Itanium-based applications. Refer to the document 64 Bit Runtime Architecture and Software Conventions for IA-64 (see the References appendix) for more information.
Version 1.10 12/01/02 2-11
2.3.3.1 Handoff State
EFI uses the standard P64 C calling conventions that are defined for Itanium-based operating systems. Figure 2-3 shows the stack after ImageEntryPoint has been called on Itanium-based systems. The arguments are also stored in registers: out0 contains EFI_HANDLE and out1 contains the address of the EFI_SYSTEM_TABLE.Thegp for the EFI Image will have been loaded from the plabel pointed to by the AddressOfEntryPoint in the image’s PE32+ header. All EFI image entry points take two parameters. These are the image handle of the EFI image, and a pointer to the EFI System Table.
Stack Location Register
EFI_SYSTEM_TABLE *
EFI_HANDLE
Figure 2-3. Stack after AddressOfEntryPoint Called, Itanium-based Systems
SP + 8
SP
out1
out0
OM13146
The SAL specification (see the References appendix) defines the state of the system registers at boot handoff. The SAL specification also defines which system registers can only be used after EFI boot services have been properly terminated.

2.4 Protocols

The protocols that a device handle supports are discovered through the HandleProtocol() Boot Service or the OpenProtocol() Boot Service. Each protocol has a specification that includes the following:
• The protocol’s globally unique ID (GUID)
• The Protocol Interface structure
• The Protocol Services
To determine if the handle supports any given protocol, the protocol’s GUID is passed to
HandleProtocol() or OpenProtocol(). If the device supports the requested protocol, a
pointer to the defined Protocol Interface structure is returned. The Protocol Interface structure links the caller to the protocol-specific services to use for this device.
2-12 12/01/02 Version 1.10
Overview
Figure 2-4 shows the construction of a protocol. The EFI driver contains functions specific to one or more protocol implementations, and registers them with the Boot Service
InstallProtocolInterface()
. The firmware returns the Protocol Interface for the protocol that is then used to invoke the protocol specific services. The EFI driver keeps private, device-specific context with protocol interfaces.
HandleProtocol (GUID, ...)
Invoking one of the protocol services
Handle
Protocol Interface
Function Pointer Function Pointer
...
Device specific context
EFI Driver
GUID 1
Protocol specific functions
GUID 2
Protocol specific functions
Device, or next Driver
Figure 2-4. Construction of a Protocol
The following C code fragment illustrates the use of protocols:
// There is a global “EffectsDevice” structure. This // structure contains information pertinent to the device.
// Connect to the ILLUSTRATION_PROTOCOL on the EffectsDevice, // by calling HandleProtocol with the device’s EFI device handle // and the ILLUSTRATION_PROTOCOL GUID.
EffectsDevice.Handle = DeviceHandle; Status = HandleProtocol (
EffectsDevice.EFIHandle, &IllustrationProtocolGuid, &EffectsDevice.IllustrationProtocol );
// Use the EffectsDevice illustration protocol’s “MakeEffects” // service to make flashy and noisy effects.
Status = EffectsDevice.IllustrationProtocol->MakeEffects (
EffectsDevice.IllustrationProtocol, TheFlashyAndNoisyEffect );
O
M
13147
Version 1.10 12/01/02 2-13
Table 2-4 lists the EFI protocols defined by this specification.
Table 2-4. EFI Protocols
Protocol Description
LOADED_IMAGE
DEVICE_PATH
DRIVER_BINDING
PLATFORM_DRIVER_OVERRIDE
BUS_SPECIFIC_DRIVER_OVERRIDE
DRIVER_CONFIGURATION
DRIVER_DIAGNOSTICS
COMPONENT_NAME
SIMPLE_INPUT
SIMPLE_TEXT_OUTPUT
UGA_DRAW
SIMPLE_POINTER
SERIAL_IO
LOAD_FILE
SIMPLE_FILE_SYSTEM
FILE_HANDLE
DISK_IO
BLOCK_IO
UNICODE_COLLATION
PCI_ROOT_BRIDGE_IO
PCI_IO
Provides information on the image.
Provides the location of the device.
Provides services to determine if an EFI driver supports a given controller, and services to start and stop a given controller.
Provide a platform specific override mechanism for the selection of the best driver for a given controller.
Provides a bus specific override mechanism for the selection of the best driver for a given controller.
Provides user configuration options for EFI drivers and the controllers that the EFI drivers are managing.
Provides diagnostics services for the controllers that EFI drivers are managing.
Provides human readable names for EFI Drivers and the controllers that the EFI drivers are managing.
Protocol interfaces for devices that support simple console style text input.
Protocol interfaces for devices that support console style text displaying.
Protocol interfaces for devices that support graphical output.
Protocol interfaces for devices such as mice and trackballs.
Protocol interfaces for devices that support serial character transfer.
Protocol interface for reading a file from an arbitrary device.
Protocol interfaces for opening disk volume containing an EFI file system.
Provides access to supported file systems.
A protocol interface that layers onto any BLOCK_IO interface.
Protocol interfaces for devices that support block I/O style accesses.
Protocol interfaces for Unicode string comparison operations.
Protocol interfaces to abstract memory, I/O, PCI configuration, and DMA accesses to a PCI root bridge controller.
Protocol interfaces to abstract memory, I/O, PCI configuration, and DMA accesses to a PCI controller on a PCI bus.
continued
2-14 12/01/02 Version 1.10
Table 2-4. EFI Protocols (continued)
Protocol Description
SCSI_PASS_THRU
USB_HC
USB_IO
SIMPLE_NETWORK
PXE_BC
BIS
DEBUG_SUPPORT
DEBUG_PORT
DECOMPRESS
DEVICE_IO
EBC
Protocol interfaces for a SCSI channel that allow SCSI Request Packets to be sent to SCSI devices.
Protocol interfaces to abstract access to a USB Host Controller.
Protocol interfaces to abstract access to a USB controller.
Provides interface for devices that support packet based transfers.
Protocol interfaces for devices that support network booting.
Protocol interfaces to validate boot images before they are loaded and invoked.
Protocol interfaces to save and restore processor context and hook processor exceptions.
Protocol interface that abstracts a byte stream connection between a debug host and a debug target system.
Protocol interfaces to decompress an image that was compressed using the EFI Compression Algorithm.
Protocol interfaces for performing device I/O.
Protocols interfaces required to support an EFI Byte Code interpreter.
Overview

2.5 EFI Driver Model

The EFI Driver Model is intended to simplify the design and implementation of device drivers, and produce small executable image sizes. As a result, some complexity has been moved into bus drivers and in a larger part into common firmware services.
A device driver is required to produce a Driver Binding Protocol on the same image handle on which the driver was loaded. It then waits for the system firmware to connect the driver to a controller. When that occurs, the device driver is responsible for producing a protocol on the controller’s device handle that abstracts the I/O operations that the controller supports. A bus driver performs these exact same tasks. In addition, a bus driver is also responsible for discovering any child controllers on the bus, and creating a device handle for each child controller found.
One assumption is that the architecture of a system can be viewed as a set of one or more processors connected to one or more core chipsets. The core chipsets are responsible for producing one or more I/O buses. The EFI Driver Model does not attempt to describe the processors or the core chipsets. Instead, the EFI Driver Model describes the set of I/O buses produced by the core chipsets, and any children of these I/O buses. These children can either be devices or additional I/O buses. This can be viewed as a tree of buses and devices with the core chipsets at the root of that tree.
Version 1.10 12/01/02 2-15
The leaf nodes in this tree structure are peripherals that perform some type of I/O. This could include keyboards, displays, disks, network, etc. The nonleaf nodes are the buses that move data between devices and buses, or between different bus types. Figure 2-5 shows a sample desktop system with four buses and six devices.
CPU
North
Bridge
PCI Bus
USB
IDE
VGA
PCI-ISA
Bridge
USB Bus
IDE Bus
Hard
Drive
CD-ROM
1.44 MB Floppy
Keyboard
Mouse
Bus Controller
Device Controller
Other
ISA Bus
O
M
13142
Figure 2-5. Desktop System
Figure 2-6 is an example of a more complex server system. The idea is to make the EFI Driver Model simple and extensible so more complex systems like the one below can be described and
managed in the preboot environment. This system contains six buses and eight devices.
CPU
North
Bridge
PCI-IBA
Bridge
USB
IBA Bus
USB Bus
IBA-PCI
Bridge
KBD
SCSI
PCI Bus
Hard
Drive
Hard
Drive
CPU
VGA
MOUSE
Hard
Drive
PCI Bus
PCI-ISA
Bridge
ISA Bus
1.44 MB Floppy
Hard
Drive
O
M
13143
Figure 2-6. Server System
2-16 12/01/02 Version 1.10
The combination of firmware services, bus drivers, and device drivers in any given platform is likely to be produced by a wide variety of vendors including OEMs, IBVs, and IHVs. These different components from different vendors are required to work together to produce a protocol for an I/O device than can be used to boot an EFI compliant operating system. As a result, the EFI Driver Model is described in great detail in order to increase the interoperability of these components.
This remainder of this section is a brief overview of the EFI Driver Model. It describes the legacy option ROM issues that the EFI Driver Model is designed to address, the entry point of a driver, host bus controllers, properties of device drivers, properties of bus drivers, and how the EFI Driver Model can accommodate hot-plug events.

2.5.1 Legacy Option ROM Issues

Legacy option ROMs have a number of constraints and limitations that restrict innovation on the part of platform designers and adapter vendors. At the time of writing, both ISA and PCI adapters use legacy option ROMs. For the purposes of this discussion, only PCI option ROMs will be considered; legacy ISA option ROMs are not supported as part of the EFI Specification.
The following is a list of the major constraints and limitations of legacy option ROMs. For each issue, the design considerations that went into the design of the EFI Driver Model are also listed. Thus, the design of the EFI Driver Model directly addresses the requirements for a solution to overcome the limitations implicit to PC-AT-style legacy option ROMs.
Overview
2.5.1.1 IA-32 16-Bit Real Mode Binaries
Legacy option ROMs typically contain 16-bit real mode code for an IA-32 processor. This means that the legacy option ROM on a PCI card cannot be used in platforms that do not support the execution of IA-32 real mode binaries. Also, 16-bit real mode only allows the driver to access directly the lower 1 MB of system memory. It is possible for the driver to switch the processor into modes other than real mode in order to access resources above 1 MB, but this requires a lot of additional code, and causes interoperability issues with other option ROMs and the system BIOS. Also, option ROMs that switch the processor into to alternate execution modes are not compatible with Itanium Processors.
EFI Driver Model design considerations:
• Drivers need flat memory mode with full access to system components.
• Drivers need to be written in C so they are portable between processor architectures.
• Drivers may be compiled into a virtual machine executable, allowing a single binary driver to
work on machines using different processor architectures.
Version 1.10 12/01/02 2-17
2.5.1.2 Fixed Resources for Working with Option ROMs
Since legacy option ROMs can only directly address the lower 1 MB of system memory, this means that the code from the legacy option ROM must exist below 1 MB. In a PC-AT platform, memory from 0x00000-0x9FFFF is system memory. Memory from 0xA0000-0xBFFFF is VGA memory, and memory from 0xF0000-0xFFFFF is reserved for the system BIOS. Also, since system BIOS has become more complex over the years, many platforms also use 0xE0000-0xEFFFF for system BIOS. This leaves 128 KB of memory from 0xC0000-0xDFFFF for legacy option ROMs. This limits how many legacy option ROMs can be run during BIOS POST.
Also, it is not easy for legacy option ROMs to allocate system memory. Their choices are to allocate memory from Extended BIOS Data Area (EBDA), allocate memory through a Post Memory Manager (PMM), or search for free memory based on a heuristic. Of these, only EBDA is standard, and the others are not used consistently between adapters, or between BIOS vendors, which adds complexity and the potential for conflicts.
EFI Driver Model design considerations:
• Drivers need flat memory mode with full access to system components.
• Drivers need to be relocatable, so they can be loaded anywhere in memory (PE/COFF Images)
• Drivers should allocate memory through the EFI boot services. These are well-specified
interfaces, and can be guaranteed to function as expected across a wide variety of platform implementations.
2.5.1.3 Matching Option ROMs to their Devices
It is not clear which controller may be managed by a particular legacy option ROM. Some legacy option ROMs search the entire system for controllers to manage. This can be a lengthy process depending on the size and complexity of the platform. Also, due to limitation in BIOS design, all the legacy option ROMs must be executed, and they must scan for all the peripheral devices before an operating system can be booted. This can also be a lengthy process, especially if SCSI buses must be scanned for SCSI devices. This means that legacy option ROMs are making policy decision about how the platform is being initialized, and which controllers are managed by which legacy option ROMs. This makes it very difficult for a system designer to predict how legacy option ROMs will interact with each other. This can also cause issues with on-board controllers, because a legacy option ROM may incorrectly choose to manage the on-board controller.
EFI Driver Model design considerations:
• Driver to controller matching must be deterministic
• Give OEMs more control through Platform Driver Override Protocol and Driver Configuration
Protocol
• It must be possible to start only the drivers and controllers required to boot an operating system.
2-18 12/01/02 Version 1.10
Overview
2.5.1.4 Ties to PC-AT System Design
Legacy option ROMs assume a PC-AT-like system architecture. Many of them include code that directly touches hardware registers. This can make them incompatible on legacy-free and headless platforms. Legacy option ROMs may also contain setup programs that assume a PC-AT-like system architecture to interact with a keyboard or video display. This makes the setup application incompatible on legacy-free and headless platforms.
EFI Driver Model design considerations:
• Drivers should use well-defined protocols to interact with system hardware, system input devices, and system output devices.
2.5.1.5 Ambiguities in Specification and Workarounds Born of Experience
Many legacy option ROMs and BIOS code contain workarounds because of incompatibilities between legacy option ROMs and system BIOS. These incompatibilities exist in part because there are no clear specifications on how to write a legacy option ROM or write a system BIOS.
Also, interrupt chaining and boot device selection is very complex in legacy option ROMs. It is not always clear which device will be the boot device for the OS.
EFI Driver Model design considerations:
• EFI Drivers and EFI firmware is written to follow the EFI Specification. Since both components have a clearly defined specification, compliance tests can be developed to prove that drivers and system firmware are compliant. This should eliminate the need to build workarounds into either drivers or system firmware (other than those that might be required to address specific hardware issues).
• Give OEMs more control through Platform Driver Override Protocol and Driver Configuration Protocol and other OEM value-add components to manage the boot device selection process.
Version 1.10 12/01/02 2-19

2.5.2 Driver Initialization

The file for a driver image must be loaded from some type of media. This could include ROM, FLASH, hard drives, floppy drives, CD-ROM, or even a network connection. Once a driver image has been found, it can be loaded into system memory with the boot service LoadImage()
LoadImage() loads a PE/COFF formatted image into system memory. A handle is created for
the driver, and a Loaded Image Protocol instance is placed on that handle. A handle that contains a Loaded Image Protocol instance is called an Image Handle. At this point, the driver has not been started. It is just sitting in memory waiting to be started. Figure 2-7 shows the state of an image handle for a driver after LoadImage() has been called.
Image Handle
EFI_LOADED_IMAGE_PROTOCOL
OM13148
Figure 2-7. Image Handle
.
After a driver has been loaded with the boot service LoadImage(), it must be started with the boot service StartImage()
. This is true of all types of EFI Applications and EFI Drivers that can be loaded and started on an EFI-compliant system. The entry point for a driver that follows the EFI Driver Model must follow some strict rules. First, it is not allowed to touch any hardware. Instead, the driver is only allowed to install protocol instances onto its own Image Handle. A driver that follows the EFI Driver Model is required to install an instance of the Driver Binding Protocol onto its own Image Handle. It may optionally install the Driver Configuration Protocol, the Driver Diagnostics Protocol, or the Component Name Protocol. In addition, if a driver wishes to be unloadable it may optionally update the Loaded Image Protocol to provide its own
Unload()
service ExitBootServices()
function. Finally, if a driver needs to perform any special operations when the boot
is called, it may optionally create an event with a notification
function that is triggered when the boot service ExitBootServices() is called. An Image Handle that contains a Driver Binding Protocol instance is known as a Driver Image Handle. Figure 2-8 shows a possible configuration for the Image Handle from Figure 2-7 after the boot service StartImage() has been called.
2-20 12/01/02 Version 1.10
Image Handle
EFI_LOADED_IMAGE_PROTOCOL
EFI_DRIVER_BINDING_PROTOCOL
Overview
Optional
Optional
Optional
EFI_DRIVER_CONFIGURATION_PROTOCOL
EFI_DRIVER_DIAGNOSTICS_PROTOCOL
EFI_COMPONENT_NAME_PROTOCOL
Figure 2-8. Driver Image Handle

2.5.3 Host Bus Controllers

Drivers are not allowed to touch any hardware in the driver’s entry point. As a result, drivers will be loaded and started, but they will all be waiting to be told to manage one or more controllers in the system. A platform component, like the EFI Boot Manager, is responsible for managing the connection of drivers to controllers. However, before even the first connection can be made, there has to be some initial collection of controllers for the drivers to manage. This initial collection of controllers is known as the Host Bus Controllers. The I/O abstractions that the Host Bus
Controllers provide are produced by firmware components that are outside the scope of the EFI Driver Model. The device handles for the Host Bus Controllers and the I/O abstraction for each
one must be produced by the core firmware on the platform, or an EFI Driver that may not follow the EFI Driver Model.SeethePCI Root Bridge I/O Protocol Specification for an example of an I/O abstraction for PCI buses.
OM13149
Version 1.10 12/01/02 2-21
A platform can be viewed as a set of processors and a set of core chipset components that may produce one or more host buses. Figure 2-9 shows a platform with n processors (CPUs), and a set of core chipset components that produce m host bridges.
CPU 1
CPU 2
. . .
CPU
n
Front Side Bus
Core Chipset Components
HB 1
HB 2
Figure 2-9. Host Bus Controllers
. . .
Each host bridge is represented in EFI as a device handle that contains a Device Path Protocol instance, and a protocol instance that abstracts the I/O operations that the host bus can perform. For example, a PCI Host Bus Controller supports one or more PCI Root Bridges that are abstracted by the PCI Root Bridge I/O Protocol. Figure 2-10 shows an example device handle for a PCI Root Bridge.
HB
m
OM13150
Device Handle
EFI_DEVICE_PATH_PROTOCOL
EFI_PCI_ROOT_BRIDGE_IO_PROTOCOL
O
M
15221
Figure 2-10. PCI Root Bridge Device Handle
2-22 12/01/02 Version 1.10
A PCI Bus Driver could connect to this PCI Root Bridge, and create child handles for each of the PCI devices in the system. PCI Device Drivers should then be connected to these child handles, and produce I/O abstractions that may be used to boot an EFI compliant OS. The following section describes the different types of drivers that can be implemented within the EFI Driver Model.The EFI Driver Model is very flexible, so all the possible types of drivers will not be discussed here. Instead, the major types will be covered that can be used as a starting point for designing and implementing additional driver types.

2.5.4 Device Drivers

A device driver is not allowed to create any new device handles. Instead, it installs additional protocol interfaces on an existing device handle. The most common type of device driver will attach an I/O abstraction to a device handle that was created by a bus driver. This I/O abstraction may be used to boot an EFI compliant OS. Some example I/O abstractions would include Simple Text Output, Simple Input, Block I/O, and Simple Network Protocol. Figure 2-11 shows a device handle before and after a device driver is connected to it. In this example, the device handle is a child of the XYZ Bus, so it contains an XYZ I/O Protocol for the I/O services that the XYZ bus supports. It also contains a Device Path Protocol that was placed there by the XYZ Bus Driver. The Device Path Protocol is not required for all device handles. It is only required for device handles that represent physical devices in the system. Handles for virtual devices will not contain a Device Path Protocol.
Overview
Device Handle
EFI_DEVICE_PATH_PROTOCOL
EFI_XYZ_I/O_PROTOCOL
Stop()
Installed by Start()
Uninstalled by Stop()
Start()
Device Handle
EFI_DEVICE_PATH_PROTOCOL
EFI_XYZ_I/O_PROTOCOL
EFI_BLOCK_I/O_PROTOCOL
OM13152
Figure 2-11. Connecting Device Drivers
Version 1.10 12/01/02 2-23
The device driver that connects to the device handle in Figure 2-11 must have installed a Driver Binding Protocol on its own image handle. The Driver Binding Protocol contains three functions called Supported()
, Start(),andStop().TheSupported() function tests to see if the
driver supports a given controller. In this example, the driver will check to see if the device handle supports the Device Path Protocol and the XYZ I/O Protocol. If a driver’s Supported() function passes, then the driver can be connected to the controller by calling the driver’s Start() function. The Start() function is what actually adds the additional I/O protocols to a device handle. In this example, the Block I/O Protocol is being installed. To provide symmetry, the Driver Binding Protocol also has a Stop() function that forces the driver to stop managing a device handle. This will cause the device driver to uninstall any protocol interfaces that were installed in Start().
The Supported(), Start(),andStop() functions of the EFI Driver Binding Protocol are required to make use of the boot service OpenProtocol() boot service CloseProtocol()
to release a protocol interface. OpenProtocol() and
to get a protocol interface and the
CloseProtocol() update the handle database maintained by the system firmware to track
which drivers are consuming protocol interfaces. The information in the handle database can be used to retrieve information about both drivers and controllers. The new boot service
OpenProtocolInformation()
can be used to get the list of components that are currently
consuming a specific protocol interface.

2.5.5 Bus Drivers

Bus drivers and device drivers are virtually identical from the EFI Driver Model’s point of view. The only difference is that a bus driver creates new device handles for the child controllers that the bus driver discovers on its bus. As a result, bus drivers are slightly more complex than device drivers, but this in turn simplifies the design and implementation of device drivers. There are two major types of bus drivers. The first creates handles for all child controllers on the first call to
Start(). The other type allows the handles for the child controllers to be created across multiple
calls to Start(). This second type of bus driver is very useful in supporting a rapid boot capability. It allows a few child handles or even one child handle to be created. On buses that take a long time to enumerate all of their children (e.g. SCSI), this can lead to a very large timesaving in booting a platform. Figure 2-12 shows the tree structure of a bus controller before and after
Start() is called. The dashed line coming into the bus controller node represents a link to the
bus controller’s parent controller. If the bus controller is a Host Bus Controller, then it will not have a parent controller. Nodes A, B, C ,D, and E represent the child controllers of the bus controller.
2-24 12/01/02 Version 1.10
Overview
Bus Controller
Start()
Stop()
Figure 2-12. Connecting Bus Drivers
ABCDE
Bus Controller
OM13153
A bus driver that supports creating one child on each call to Start() might choose to create child C first, and then child E, and then the remaining children A, B, and D. The Supported()
Start(),andStop()
functions of the Driver Binding Protocol are flexible enough to allow this
,
type of behavior.
A bus driver must install protocol interfaces onto every child handle that is creates. At a minimum, it must install a protocol interface that provides an I/O abstraction of the bus’s services to the child controllers. If the bus driver creates a child handle that represents a physical device, then the bus driver must also install a Device Path Protocol instance onto the child handle. A bus driver may optionally install a Bus Specific Driver Override Protocol onto each child handle. This protocol is used when drivers are connected to the child controllers. The boot service
ConnectController()
uses architecturally defined precedence rules to choose the best set of drivers for a given controller. The Bus Specific Driver Override Protocol has higher precedence than a general driver search algorithm, and lower precedence than platform overrides. An example of a bus specific driver selection occurs with PCI. A PCI Bus Driver gives a driver stored in a PCI controller’s option ROM a higher precedence than drivers stored elsewhere in the platform. Figure 2-13 shows an example child device handle that was created by the XYZ Bus Driver that supports a bus specific driver override mechanism.
Version 1.10 12/01/02 2-25
Child Device Handle
EFI_DEVICE_PATH_PROTOCOL
EFI_XYZ_I/O_PROTOCOL
Optional
EFI_BUS_SPECIFIC_DRIVER_OVERRIDE_PROTOCOL
Figure 2-13. Child Device Handle with a Bus Specific Override

2.5.6 Platform Components

Under the EFI Driver Model, the act of connecting and disconnecting drivers from controllers in a platform is under the platform firmware’s control. This will typically be implemented as part of the EFI Boot Manager, but other implementations are possible. The boot services
ConnectController()
firmware to determine which controllers get started and which ones do not. If the platform wishes to perform system diagnostics or install an operating system, then it may choose to connect drivers to all possible boot devices. If a platform wishes to boot a preinstalled operating system, it may choose to only connect drivers to the devices that are required to boot the selected operating system. The EFI Driver Model supports both these modes of operation through the boot services
ConnectController() and DisconnectController(). In addition, since the platform
component that is in charge of booting the platform has to work with device paths for console devices and boot options, all of the services and protocols involved in the EFI Driver Model are optimized with device paths in mind.
and DisconnectController() canbeusedbytheplatform
OM13154
Since the platform firmware may choose to only connect the devices required to produce consoles and gain access to a boot device, the OS present device drivers cannot assume that an EFI driver for a device has been executed. The presence of an EFI driver in the system firmware or in an option ROM does not guarantee that the EFI driver will be loaded, executed, or allowed to manage any devices in a platform. All OS present device drivers must be able to handle devices that have been managed by an EFI driver and devices that have not been managed by an EFI driver.
The platform may also choose to produce a protocol named the Platform Driver Override Protocol. This is similar to the Bus Specific Driver Override Protocol, but it has higher priority. This gives the platform firmware the highest priority when deciding which drivers are connected to which controllers. The Platform Driver Override Protocol is attached to a handle in the system. The boot service ConnectController() will make use of this protocol if it is present in the system.
2-26 12/01/02 Version 1.10

2.5.7 Hot-Plug Events

In the past, system firmware has not had to deal with hot-plug events in the preboot environment. However, with the advent of buses like USB, where the end user can add and remove devices at any time, it is important to make sure that it is possible to describe these types of buses in the EFI Driver Model. It is up to the bus driver of a bus that supports the hot adding and removing of devices to provide support for such events. For these types of buses, some of the platform management is going to have to move into the bus drivers. For example, when a keyboard is hot added to a USB bus on a platform, the end user would expect the keyboard to be active. A USB Bus driver could detect the hot-add event and create a child handle for the keyboard device. However, because drivers are not connected to controllers unless ConnectController() called, the keyboard would not become an active input device. Making the keyboard driver active requires the USB Bus driver to call ConnectController() when a hot-add event occurs. In addition, the USB Bus Driver would have to call DisconnectController() remove event occurs.
Device drivers are also affected by these hot-plug events. In the case of USB, a device can be removed without any notice. This means that the Stop() have to deal with shutting down a driver for a device that is no longer present in the system. As a result, any outstanding I/O requests will have to be flushed without actually being able to touch the device hardware.
functions of USB device drivers will
when a hot-
Overview
is
In general, adding support for hot-plug events greatly increases the complexity of both bus drivers and device drivers. Adding this support is up to the driver writer, so the extra complexity and size of the driver will need to be weighed against the need for the feature in the preboot environment.

2.6 Requirements

This document is an architectural specification. As such, care has been taken to specify architecture in ways that allow maximum flexibility in implementation. However, there are certain requirements on which elements of this specification must be implemented to ensure that operating system loaders and other code designed to run with EFI boot services can rely upon a consistent environment.
For the purposes of describing these requirements, the specification is broken up into required and optional elements. In general, an optional element is completely defined in the section that matches the element name. For required elements however, the definition may in a few cases not be entirely self contained in the section that is named for the particular element. In implementing required elements, care should be taken to cover all the semantics defined in this specification that relate to the particular element.
Version 1.10 12/01/02 2-27

2.6.1 Required Elements

Table 2-5 lists the required elements. Any system that is designed to conform to the EFI specification must provide a complete implementation of all these elements. This means that all the required service functions and protocols must be present and the implementation must deliver the full semantics defined in the specification for all combinations of calls and parameters. Implementers of EFI applications, drivers or operating system loaders that are designed to run on a broad range of systems conforming to the EFI specification may assume that all such systems implement all the required elements.
A system vendor may choose not to implement all the required elements, for example on specialized system configurations that do not support all the services and functionality implied by the required elements. However, since most EFI applications, drivers and operating system loaders are written assuming all the required elements are present on a system that implements the EFI specification; any such code is likely to require explicit customization to run on a less than complete implementation of the required elements in the EFI specification.
Table 2-5. Required EFI Implementation Elements
Element Description
EFI System Table
EFI Boot Services All functions defined as boot services.
EFI Runtime Services All functions defined as runtime services.
LOADED_IMAGE protocol Provides information on the image.
DEVICE_PATH protocol Provides the location of the device.
DECOMPRESS protocol Protocol interfaces to decompress an image that was
EBC Interpreter An EFI Byte Code Interpreter is required so EFI images compiled
Provides access to EFI Boot Services, EFI Runtime Services, consoles, firmware vendor information, and the system configuration tables.
compressed using the EFI Compression Algorithm.
to EFI Byte Code executables are guaranteed to function on all EFI compliant platforms. The EBC Interpreter must also produce the EBC protocol.
2-28 12/01/02 Version 1.10

2.6.2 Platform-Specific Elements

There are a number of EFI elements that can be added or removed depending on the specific features that a platform requires. Platform firmware developers are required to implement EFI elements based upon the features included. The following is a list of potential platform features and the EFI elements that are required for each feature type:
Overview
1. If a platform includes console devices, the Simple Input Protocol
and Simple Text Output
Protocol must be implemented.
2. If a platform includes graphical console devices, then the UGADrawProtocol
and the UGA
I/O Protocol must be implemented. In order to support UGA, a platform must contain a
driver to consume UGA Draw Protocol and produce Simple Text Output Protocol even if the UGA Draw Protocol is produced by an external driver.
3. If a platform includes a pointer device as part of its console support, the Simple Pointer
Protocol must be implemented.
4. If a platform includes the ability to boot from a disk device, then the Block I/O Protocol
Disk I/O Protocol
,theSimple File System Protocol,andtheUnicode Collation Protocol are
,the
required. In addition, partition support for MBR, GPT, and El Torito must be implemented. An external driver may produce the Block I/O Protocol. All other protocols required to boot from a disk device must be carried as part of the platform.
5. If a platform includes the ability to boot from a network device, then the UNDI interface, the
Simple Network Protocol
,andthePXE Base Code Protocol are required. If a platform includes the ability to validate a boot image received through a network device, the Boot
Integrity Services Protocol is also required. An external driver may produce the UNDI
interface. All other protocols required to boot from a network device must be carried by the platform.
6. If a platform includes a byte-stream device such as a UART, then the Serial I/O Protocol must be implemented.
7. If a platform includes PCI bus support, then the PCI Root Bridge I/O Protocol
,thePCI I/O
Protocol,andtheDevice I/O Protocol must be implemented.
8. If a platform includes USB bus support, then the USB Host Controller Protocol
and the USB
I/O Protocol must be implemented. An external device can support USB by producing a
USB Host Controller Protocol.
9. If a platform includes an I/O subsystem that uses SCSI command packets, the SCSI Pass
Thru Protocol must be implemented.
10. If a platform includes debugging capabilities, then the Debug Support Protocol
,theDebug
Port Protocol,andtheDebug Image Info Table must be implemented.
11. If a platform includes the ability to override the default driver to the controller matching algorithm provided by the EFI Driver Model, then the Platform Driver Override Protocol must be implemented.
Version 1.10 12/01/02 2-29

2.6.3 Driver-Specific Elements

There are a number of EFI elements that can be added or removed depending on the features that a specific driver requires. Drivers can be implemented by platform firmware developers to support buses and devices in a specific platform. Drivers can also be implemented by add-in card vendors for devices that might be integrated into the platform hardware or added to a platform through an expansion slot. The following list includes possible driver features, and the EFI elements that are required for each feature type:
1. If a driver follows the EFI 1.10 Driver Model, the EFI Driver Binding Protocol
must be implemented. It is strongly recommended that all drivers that follow the EFI Driver Model also implement the Component Name Protocol
.
2. If a driver requires configuration information, the Driver Configuration Protocol must be implemented. A driver is not allowed to interact with the user unless the Driver
Configuration Protocol is invoked.
3. If a driver requires diagnostics, the Driver Diagnostics Protocol
must be implemented. In order to support low boot times, limit diagnostics during normal boots. Time consuming diagnostics should be deferred until the Driver Diagnostics Protocol
is invoked.
4. If a bus supports devices that are able to provide containers for EFI drivers (e.g. option ROMs), then the bus driver for that bus type must implement the Bus Specific Driver
Override Protocol.
5. If a driver is written for a console output device, then the Simple Text Output Protocol be implemented.
6. If a driver is written for a graphical console output device, then the UGADrawProtocol the UGA I/O Protocol
7. If a driver is written for a console input device, then the Simple Input Protocol
must be implemented.
must be
implemented.
8. If a driver is written for a pointer device, then the Simple Pointer Protocol
must be
implemented.
must
and
9. If a driver is written for a network device, then the UNDI interface
10. If a driver is written for a disk device, then the Block I/O Protocol
must be implemented.
must be implemented.
11. If a driver is written for a device that is not a block oriented device but one that can provide a file system-like interface, then the Simple File System Protocol must be implemented.
12. If a driver is written for a PCI root bridge, then the PCI Root Bridge I/O Protocol
,thePCI I/O
Protocol,andtheDevice I/O Protocol must be implemented.
13. If a driver is written for a USB host controller, then the USB Host Controller Protocol
must
be implemented.
14. If a driver is written for a SCSI controller, then the SCSI Pass Thru Protocol
must be
implemented.
15. If a driver is written for a boot device that is not a block-oriented device, a file system-based device, or a console device, then the Load File Protocol
2-30 12/01/02 Version 1.10
must be implemented.
3

Boot Manager

The EFI boot manager is a firmware policy engine that can be configured by modifying architecturally defined global NVRAM variables. The boot manager will attempt to load EFI drivers and EFI applications (including EFI OS boot loaders) in an order defined by the global NVRAM variables. The platform firmware must use the boot order specified in the global NVRAM variables for normal boot. The platform firmware may add extra boot options or remove invalid boot options from the boot order list.
The platform firmware may also implement value added features in the boot manager if an exceptional condition is discovered in the firmware boot process. One example of a value added feature would be not loading an EFI driver if booting failed the first time the driver was loaded. Another example would be booting to an OEM-defined diagnostic environment if a critical error was discovered in the boot process.
The boot sequence for EFI consists of the following:
• The boot order list is read from a globally defined NVRAM variable. The boot order list defines a list of NVRAM variables that contain information about what is to be booted. Each NVRAM variable defines a Unicode name for the boot option that can be displayed to a user.
• The variable also contains a pointer to the hardware device and to a file on that hardware device that contains the EFI image to be loaded.
• The variable might also contain paths to the OS partition and directory along with other configuration specific directories.
The NVRAM can also contain load options that are passed directly to the EFI image. The platform firmware has no knowledge of what is contained in the load options. The load options are set by higher level software when it writes to a global NVRAM variable to set the platform firmware boot policy. This information could be used to define the location of the OS kernel if it was different than the location of the EFI OS loader.

3.1 Firmware Boot Manager

The boot manager is a component in the EFI firmware that determines which EFI drivers and EFI applications should be explicitly loaded and when. Once the EFI firmware is initialized, it passes control to the boot manager. The boot manager is then responsible for determining what to load and any interactions with the user that may be required to make such a decision. Much of the behavior of the boot manager is left up to the firmware developer to decide, and details of boot manager implementation are outside the scope of this specification. In particular, likely implementation options might include any console interface concerning boot, integrated platform management of boot selections, possible knowledge of other internal applications or recovery drivers that may be integrated into the system through the boot manager.
Version 1.10 12/01/02 3-1
Extensible Firmware Interface Specification
Programmatic interaction with the boot manager is accomplished through globally defined variables. On initialization the boot manager reads the values which comprise all of the published load options among the EFI environment variables. By using the SetVariable()
function the
data that contain these environment variables can be modified.
Each load option entry resides in a Boot#### variable or a Driver#### variable where the
#### is replaced by a unique option number in printable hexadecimal representation using the
digits 0–9, and the upper case versions of the characters A–F (0000–FFFF). The #### must always be four digits, so small numbers must use leading zeros. The load options are then logically ordered by an array of option numbers listed in the desired order. There are two such option ordering lists. The first is DriverOrder that orders the Driver#### load option variables into their load order. The second is BootOrder that orders the Boot#### load options variables into their load order.
For example, to add a new boot option, a new Boot#### variable would be added. Then the option number of the new Boot#### variable would be added to the BootOrder ordered list and the BootOrder variable would be rewritten. To change boot option on an existing Boot####, only the Boot#### variable would need to be rewritten. A similar operation would be done to add, remove, or modify the driver load list.
If the boot via Boot#### returns with a status of EFI_SUCCESS the boot manager will stop processing the BootOrder variable and present a boot manager menu to the user. If a boot via
Boot#### returns a status other than EFI_SUCCESS, the boot has failed and the next Boot#### in the BootOrder variable will be tried until all possibilities are exhausted.
The boot manager may perform automatic maintenance of the database variables. For example, it may remove unreferenced load option variables, any unparseable or unloadable load option variables, and rewrite any ordered list to remove any load options that do not have corresponding load option variables. In addition, the boot manager may automatically update any ordered list to place any of its own load options where it desires. The boot manager can also, at its own discretion, provide for manual maintenance operations as well. Examples include choosing the order of any or all load options, activating or deactivating load options, etc.
The boot manager is required to process the Driver load option entries before the Boot load option entries. The boot manager is also required to initiate a boot of the boot option specified by the
BootNext variable as the first boot option on the next boot, and only on the next boot. The boot
manager removes the BootNext variable before transferring control to the BootNext boot option. If the boot from the BootNext boot option fails the boot sequence continues utilizing the BootOrder variable. If the boot from the BootNext boot option succeeds by returning
EFI_SUCCESS the boot manager will not continue to boot utilizing the BootOrder variable.
The boot manager must call LoadImage() and LOAD_FILE_PROTOCOL
for resolving load options. If LoadImage() succeeds, the boot manager must enable the watchdog timer for 5 minutes by using the SetWatchdogTimer() boot service prior to calling StartImage()
which supports at least SIMPLE_FILE_PROTOCOL
. If a boot option returns control to the boot manager,
the boot manager must disable the watchdog timer with an additional call to the
SetWatchdogTimer() boot service.
3-2 12/01/02 Version 1.10
Boot Manager
If the boot image is not loaded via LoadImage() the boot manager is required to check for a default application to boot. Searching for a default application to boot happens on both removable and fixed media types. This search occurs when the device path of the boot image listed in any boot
option points directly to a SIMPLE_FILE_SYSTEM device and does not specify the exact file to
load. The file discovery method is explained in “Boot Option Variables Default Behavior” starting on page 2-7 of this chapter. The default media boot case of a protocol other than
SIMPLE_FILE_SYSTEM is handled by the LOAD_FILE_PROTOCOL
for the target device path
and does not need to be handled by the boot manager.
The boot manager must also support booting from a short-form device path that starts with the first element being a hard drive media device path (see Table 8-24, “Hard Drive Media Device Path” in Chapter 8). The boot manager must use the GUID or signature and partition number in the hard drive device path to match it to a device in the system. If the drive supports the GPT partitioning scheme the GUID in the hard drive media device path is compared with the
UniquePartitionGuid field of the GUID Partition Entry (see Table 11-2 in Chapter 11). If
the drive supports the PC-AT MBR scheme the signature in the hard drive media device path is compared with the UniqueMBRSignature in the Legacy Master Boot Record (see Table 11-5 in Chapter 11). If a signature match is made, then the partition number must also be matched. The hard drive device path can be appended to the matching hardware device path and normal boot behavior can then be used. If more than one device matches the hard drive device path, the boot manager will pick one arbitrarily. Thus the operating system must ensure the uniqueness of the signatures on hard drives to guarantee deterministic boot behavior.
Each load option variable contains an EFI_LOAD_OPTION descriptor that is a byte packed buffer of variable length fields. Since some of the fields are variable length, an EFI_LOAD_OPTION cannot be described as a standard C data structure. Instead, the fields are listed below in the order that they appear in an EFI_LOAD_OPTION descriptor:
Descriptor
UINT32 Attributes; UINT16 FilePathListLength; CHAR16 Description[]; EFI_DEVICE_PATH FilePathList[]; UINT8 OptionalData[];
Parameters
Attributes The attributes for this load option entry. All unused bits must be
zero and are reserved by the EFI specification for future growth. See “Related Definitions.”
FilePathListLength Length in bytes of the FilePathList. OptionalData
starts at offset sizeof(UINT32) + sizeof(UINT16) +
StrSize(Description) + FilePathListLength of
the EFI_LOAD_OPTION descriptor.
Description The user readable description for the load option. This field ends
with a Null Unicode character.
Version 1.10 12/01/02 3-3
Extensible Firmware Interface Specification
FilePathList A packed array of EFI device paths. The first element of the
array is an EFI device path that describes the device and location of the Image for this load option. The FilePathList[0] is specific to the device type. Other device paths may optionally exist in the FilePathList, but their usage is OSV specific. Each element in the array is variable length, and ends at the device path end structure. Because the size of Description is arbitrary, this data structure is not guaranteed to be aligned on a natural boundary. This data structure may have to be copied to an aligned natural boundary before it is used.
OptionalData The remaining bytes in the load option descriptor are a binary
data buffer that is passed to the loaded image. If the field is zero bytes long, a Null pointer is passed to the loaded image. The number of bytes in OptionalData can be computed by subtracting the starting offset of OptionalData from total size in bytes of the EFI_LOAD_OPTION.
Related Definitions
//******************************************************* // Attributes //******************************************************* #define LOAD_OPTION_ACTIVE 0x00000001 #define LOAD_OPTION_FORCE_RECONNECT 0x00000002
Description
Calling SetVariable() creates a load option. The size of the load option is the same as the size of the DataSize argument to the SetVariable() call that created the variable. When creating a new load option, all undefined attribute bits must be written as zero. When updating a load option, all undefined attribute bits must be preserved. If a load option is not marked as
LOAD_OPTION_ACTIVE, the boot manager will not automatically load the option. This
provides an easy way to disable or enable load options without needing to delete and re-add them. If any Driver#### load option is marked as LOAD_OPTION_FORCE_RECONNECT, then all of
the EFI drivers in the system will be disconnected and reconnected after the last Driver#### load option is processed. This allows an EFI driver loaded with a Driver#### load option to override an EFI driver that was loaded prior to the execution of the EFI Boot Manager.
3-4 12/01/02 Version 1.10
Boot Manager

3.2 Globally-Defined Variables

This section defines a set of variables that have architecturally defined meanings. In addition to the defined data content, each such variable has an architecturally defined attribute that indicates when the data variable may be accessed. The variables with an attribute of NV are nonvolatile. This means that their values are persistent across resets and power cycles. The value of any environment variable that does not have this attribute will be lost when power is removed from the system and the state of firmware reserved memory is not otherwise preserved. The variables with an attribute of BS are only available before ExitBootServices() environment variables can only be retrieved or modified in the preboot environment. They are not visible to an operating system. Environment variables with an attribute of RT are available before and after ExitBootServices() is called. Environment variables of this type can be retrieved and modified in the preboot environment, and from an operating system. All architecturally defined variables use the EFI_GLOBAL_VARIABLE VendorGuid:
#define EFI_GLOBAL_VARIABLE \
{8BE4DF61-93CA-11d2-AA0D-00E098032B8C}
To prevent name collisions with possible future globally defined variables, other internal firmware data variables that are not defined here must be saved with a unique VendorGuid other than
EFI_GLOBAL_VARIABLE. Table 3-1 lists the global variables.
is called. This means that these
Table 3-1 Global Variables
Variable Name Attribute Description
LangCodes BS, RT The language codes that the firmware supports.
Lang NV, BS, RT The language code that the system is configured for.
Timeout NV, BS, RT The firmware’s boot managers timeout, in seconds,
ConIn NV, BS, RT The device path of the default input console.
ConOut NV, BS, RT The device path of the default output console.
ErrOut NV, BS, RT The device path of the default error output device.
ConInDev BS, RT The device path of all possible console input devices.
ConOutDev BS, RT The device path of all possible console output devices.
ErrOutDev BS, RT The device path of all possible error output devices.
Boot#### NV, BS, RT A boot load option. #### is a printed hex value. No 0x
BootOrder NV, BS, RT The ordered boot option load list.
BootNext NV, BS, RT The boot option for the next boot only.
BootCurrent BS, RT The boot option that was selected for the current boot.
Driver#### NV, BS, RT A driver load option. #### is a printed hex value.
DriverOrder NV, BS, RT The ordered driver load option list.
before initiating the default boot selection.
or h is included in the hex value.
Version 1.10 12/01/02 3-5
Extensible Firmware Interface Specification
The LangCodes variable contains an array of 3-character (8-bit ASCII characters) ISO-639-2 language codes that the firmware can support. At initialization time the firmware computes the supported languages and creates this data variable. Since the firmware creates this value on each initialization, its contents are not stored in nonvolatile memory. This value is considered read-only.
The Lang variable contains the 3-character (8-bit ASCII characters) ISO-639-2 language code that the machine has been configured for. This value may be changed to any value supported by
LangCodes; however, the change does not take effect until the next boot. If the language code is
set to an unsupported value, the firmware will choose a supported default at initialization and set
Lang to a supported value.
The Timeout variable contains a binary UINT16 that supplies the number of seconds that the firmware will wait before initiating the original default boot selection. A value of 0 indicates that the default boot selection is to be initiated immediately on boot. If the value is not present, or contains the value of 0xFFFF then firmware will wait for user input before booting. This means the
default boot selection is not automatically started by the firmware.
The ConIn, ConOut, and ErrOut variables each contain an EFI_DEVICE_PATH
descriptor that defines the default device to use on boot. Changes to these values do not take effect until the next boot. If the firmware cannot resolve the device path, it is allowed to automatically replace the value(s) as needed to provide a console for the system.
The ConInDev, ConOutDev, and ErrOutDev variables each contain an EFI_DEVICE_PATH descriptor that defines all the possible default devices to use on boot. These variables are volatile, and are set dynamically on every boot. ConIn, ConOut, and ErrOut are always proper subsets of ConInDev, ConOutDev, and ErrOutDev.
Each Boot#### variable contains an EFI_LOAD_OPTION. Each Boot#### variable is the name “Boot” appended with a unique four digit hexadecimal number. For example, Boot0001,
Boot0002, Boot0A02, etc.
The BootOrder variable contains an array of UINT16’s that make up an ordered list of the
Boot#### options. The first element in the array is the value for the first logical boot option, the
second element is the value for the second logical boot option, etc. The BootOrder order list is used by the firmware’s boot manager as the default boot order.
The BootNext variable is a single UINT16 that defines the Boot#### option that is to be tried first on the next boot. After the BootNext boot option is tried the normal BootOrder list is used. To prevent loops, the boot manager deletes this variable before transferring control to the
preselected boot option.
The BootCurrent variable is a single UINT16 that defines the Boot#### option that was selected on the current boot.
Each Driver#### variable contains an EFI_LOAD_OPTION. Each load option variable is appended with a unique number, for example Driver0001, Driver0002, etc.
The DriverOrder variable contains an array of UINT16’s that make up an ordered list of the
Driver#### variable. The first element in the array is the value for the first logical driver load
option, the second element is the value for the second logical driver load option, etc. The
DriverOrder list is used by the firmware’s boot manager as the default load order for EFI
drivers that it should explicitly load.
3-6 12/01/02 Version 1.10
Boot Manager

3.3 Boot Option Variables Default Behavior

The default state of globally-defined variables is firmware vendor specific. However the boot options require a standard default behavior in the exceptional case that valid boot options are not present on a platform. The default behavior must be invoked any time the BootOrder variable does not exist or only points to nonexistent boot options.
If no valid boot options exist, the boot manager will enumerate all removable EFI media devices followed by all fixed EFI media devices. The order within each group is undefined. These new default boot options are not saved to non volatile storage. The boot manger will then attempt to boot from each boot option. If the device supports the SIMPLE_FILE_SYSTEM the removable media boot behavior (see section 3.4.1.1) is executed. Otherwise the firmware will attempt to boot the device via the LOAD_FILE
It is expected that this default boot will load an operating system or a maintenance utility. If this is an operating system setup program it is then responsible for setting the requisite environment variables for subsequent boots. The platform firmware may also decide to recover or set to a known set of boot options.
protocol .
protocol then

3.4 Boot Mechanisms

EFI can boot from a device using the SIMPLE_FILE_SYSTEM protocol or the LOAD_FILE protocol. A device that supports the SIMPLE_FILE_SYSTEM protocol must materialize a file system protocol for that device to be bootable. If a device does not wish to support a complete file system it may produce a LOAD_FILE protocol which allows it to materialize an image directly. The Boot Manager will attempt to boot using the SIMPLE_FILE_SYSTEM protocol first. If that fails, then the LOAD_FILE protocol will be used.

3.4.1 Boot via Simple File Protocol

When booting via the SIMPLE_FILE_SYSTEM protocol, the FilePath will start with a device path that points to the device that “speaks” the SIMPLE_FILE_SYSTEM protocol. The next part of the FilePath will point to the file name, including sub directories that contain the bootable image. If the file name is a null device path, the file name must be discovered on the media using the rules defined for removable media devices with ambiguous file names (see section 3.4.1.1 below).
The format of the file system specified by EFI is contained in Chapter 11. While the firmware must produce a SIMPLE_FILE_SYSTEM protocol that understands the EFI file system, any file system can be abstracted with the SIMPLE_FILE_SYSTEM protocol interface.
3.4.1.1 Removable Media Boot Behavior
On a removable media device it is not possible for the FilePath to contain a file name, including sub directories. The FilePath is stored in non volatile memory in the platform and cannot possibly be kept in sync with a media that can change at any time. A FilePath for a removable media device will point to a device that “speaks” the SIMPLE_FILE_SYSTEM protocol. The
FilePath will not contain a file name or sub directories.
Version 1.10 12/01/02 3-7
Extensible Firmware Interface Specification
The system firmware will attempt to boot from a removable media FilePath by adding a default file name in the form \EFI\BOOT\BOOT{machine type short-name}.EFI. Where machine type short-name defines a PE32+ image format architecture. Each file only contains one EFI image type, and a system may support booting from one or more images types. Table 3-2 lists the EFI image types.
Table 3-2 EFI Image Types
Architecture File name convention PE Executable machine type *
IA-32 BOOTIA32.EFI 0x14c
Itanium architecture BOOTIA64.EFI 0x200
Note: * The PE Executable machine type is contained in the machine field of the COFF file header as
defined in the Microsoft Portable Executable and Common Object File Format Specification, Revision 6.0
A media may support multiple architectures by simply having a \EFI\BOOT\BOOT{machine type short-name}.EFI file of each possible machine type.

3.4.2 Boot via LOAD_FILE Protocol

When booting via the LOAD_FILE protocol, the FilePath is a device path that points to a device that “speaks” the LOAD_FILE protocol. The image is loaded directly from the device that supports the LOAD_FILE protocol. The remainder of the FilePath will contain information that is specific to the device. EFI firmware passes this device-specific data to the loaded image, but does not use it to load the image. If the remainder of the FilePath is a null device path it is the loaded image's responsibility to implement a policy to find the correct boot device.
The LOAD_FILE protocol is used for devices that do not directly support file systems. Network devices commonly boot in this model where the image is materialized without the need of a file system.
3.4.2.1 Network Booting
Network booting is described by the Preboot eXecution Environment (PXE) BIOS Support Specification that is part of the Wired for Management Baseline specification. PXE specifies UDP,
DHCP, and TFTP network protocols that a booting platform can use to interact with an intelligent system load server. EFI defines special interfaces that are used to implement PXE. These interfaces are contained in the PXE_BASE_CODE protocol (Chapter 15).
3.4.2.2 Future Boot Media
Since EFI defines an abstraction between the platform and the OS and its loader it should be possible to add new types of boot media as technology evolves. The OS loader will not necessarily have to change to support new types of boot. The implementation of the EFI platform services may change, but the interface will remain constant. The OS will require a driver to support the new type of boot media so that it can make the transition from EFI boot services to OS control of the boot media.
3-8 12/01/02 Version 1.10

EFI System Table

This chapter describes the entry point to an EFI image and the parameters that are passed to that entry point. There are three types of EFI images that can be loaded and executed by EFI firmware. These are EFI Applications, EFI OS Loaders, and EFI Drivers. There are no differences in the entry point for these three image types.

4.1 EFI Image Entry Point

The most significant parameter that is passed to an EFI image is a pointer to the EFI System Table. This pointer is EFI_IMAGE_ENTRY_POINT (see definition immediately below), the main entry
point for an EFI Image. The EFI System Table contains pointers to the active console devices, a pointer to the EFI Boot Services Table, a pointer to the EFI Runtime Services Table, and a pointer to the list of system configuration tables such as ACPI, SMBIOS, and the SAL System Table. This chapter describes the EFI System Table in detail.
4

EFI_IMAGE_ENTRY_POINT

Summary
This is the main entry point for an EFI Image. This entry point is the same for EFI Applications, EFI OS Loaders, and EFI Drivers including both device drivers and bus drivers.
Prototype
typedef EFI_STATUS (EFIAPI *EFI_IMAGE_ENTRY_POINT) ( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable );
Parameters
ImageHandle The firmware allocated handle for the EFI image.
SystemTable A pointer to the EFI System Table.
Description
This function is the entry point to an EFI image. An EFI image is loaded and relocated in system memory by the EFI Boot Service LoadImage() Service StartImage()
Version 1.10 12/01/02 4-1
.
. An EFI image is invoked through the EFI Boot
Extensible Firmware Interface Specification
The first argument is the image’s image handle. The second argument is a pointer to the image’s system table. The system table contains the standard output and input handles, plus pointers to the
EFI_BOOT_SERVICES
and EFI_RUNTIME_SERVICES tables. The service tables contain the
entry points in the firmware for accessing the core EFI system functionality. The handles in the system table are used to obtain basic access to the console. In addition, the EFI system table contains pointers to other standard tables that a loaded image may use if the associated pointers are initialized to nonzero values. Examples of such tables are ACPI, SMBIOS, SAL System Table, etc.
The ImageHandle is a firmware-allocated handle that is used to identify the image on various functions. The handle also supports one or more protocols that the image can use. All images
support the EFI_LOADED_IMAGE
protocol that returns the source location of the image, the
memory location of the image, the load options for the image, etc. The exact
EFI_LOADED_IMAGE structure is defined in Chapter 7.
If the EFI image is an EFI Application, then the EFI Application executes and either returns or calls the EFI Boot Services Exit()
. An EFI Application is always unloaded from memory when it
exits, and its return status is returned to the component that started the EFI Application.
If the EFI image is an EFI OS Loader, then the EFI OS Loader executes and either returns, calls the EFI Boot Service Exit(), or calls the EFI Boot Service ExitBootServices()
. If the EFI OS Loader returns or calls Exit(), then the load of the OS has failed, and the EFI OS Loader is unloaded from memory and control is returned to the component that attempted to boot the EFI OS Loader. If ExitBootServices() is called, then the OS Loader has taken control of the platform, and EFI will not regain control of the system until the platform is reset. One method of resetting the platform is through the EFI Runtime Service ResetSystem()
.
If the EFI image is an EFI Driver, then the EFI Driver executes and either returns or calls the EFI Boot Service Exit(). If an EFI driver returns an error, then the driver is unloaded from memory. If the EFI driver returns EFI_SUCCESS, then it stays resident in memory. If the EFI Driver does
not follow the EFI Driver Model, then it performs any required initialization and installs its protocol services before returning. If the EFI driver does
follow the EFI Driver Model, then the
entry point is not allowed to touch any device hardware. Instead, the entry point is required to create and install the EFI_DRIVER_BINDING_PROTOCOL
(Chapter 9) on the ImageHandle
of the EFI Driver. If this process is completed, then EFI_SUCCESS is returned. If the resources are not available to complete the driver initialization, then EFI_OUT_OF_RESOURCES is returned.
Status Codes Returned
EFI_SUCCESS
EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
The driver was initialized
.
4-2 12/01/02 Version 1.10
EFI System Table

4.2 EFI Table Header

The data type EFI_TABLE_HEADER is the data structure that precedes all of the standard EFI table types. It includes a signature that is unique for each table type, a revision of the table that may be updated as extensions are added to the EFI table types, and a 32-bit CRC so a consumer of an EFI table type can validate the contents of the EFI table.

EFI_TABLE_HEADER

Summary
Data structure that precedes all of the standard EFI table types.
Related Definitions
typedef struct { UINT64 Signature; UINT32 Revision; UINT32 HeaderSize; UINT32 CRC32; UINT32 Reserved; } EFI_TABLE_HEADER;
Parameters
Signature A 64-bit signature that identifies the type of table that follows.
Unique signatures have been generated for the EFI System Table, the EFI Boot Services Table, and the EFI Runtime Services Table.
Revision The revision of the EFI Specification to which this table conforms.
The upper 16 bits of this field contain the major revision value, and the lower 16 bits contain the minor revision value. The minor revision values are limited to the range of 00..99.
HeaderSize The size, in bytes, of the entire table including the
EFI_TABLE_HEADER.
CRC32 The 32-bit CRC for the entire table. This value is computed by
setting this field to 0, and computing the 32-bit CRC for
HeaderSize bytes.
Reserved Reserved field that must be set to 0.
NOTE
The size of the EFI system table, runtime services table, and boot services table may increase over time. It is very important to always use the HeaderSize field of the EFI_TABLE_HEADER to
determine the size of these tables.
Version 1.10 12/01/02 4-3
Extensible Firmware Interface Specification

4.3 EFI System Table

The EFI System Table contains pointers to the runtime and boot services tables. The definition for this table is shown in the following code fragments. Except for the table header, all elements in the service tables are prototypes of function pointers to functions as defined in Chapters 5 and 6. Prior to a call to ExitBootServices() operating system has taken control of the platform with a call to ExitBootServices(), only the Hdr, FirmwareVendor, FirmwareRevision, RuntimeServices,
NumberOfTableEntries, and ConfigurationTable fields are valid.
, all of the fields of the EFI System Table are valid. After an

EFI_SYSTEM_TABLE

Summary
Contains pointers to the runtime and boot services tables.
Related Definitions
#define EFI_SYSTEM_TABLE_SIGNATURE 0x5453595320494249 #define EFI_SYSTEM_TABLE_REVISION ((1<<16) | (10)) #define EFI_1_10_SYSTEM_TABLE_REVISION ((1<<16) | (10)) #define EFI_1_02_SYSTEM_TABLE_REVISION ((1<<16) | (02))
typedef struct { EFI_TABLE_HEADER Hdr; CHAR16 *FirmwareVendor; UINT32 FirmwareRevision; EFI_HANDLE ConsoleInHandle; SIMPLE_INPUT_INTERFACE *ConIn; EFI_HANDLE ConsoleOutHandle; SIMPLE_TEXT_OUTPUT_INTERFACE *ConOut; EFI_HANDLE StandardErrorHandle; SIMPLE_TEXT_OUTPUT_INTERFACE *StdErr; EFI_RUNTIME_SERVICES *RuntimeServices; EFI_BOOT_SERVICES *BootServices; UINTN NumberOfTableEntries; EFI_CONFIGURATION_TABLE *ConfigurationTable; } EFI_SYSTEM_TABLE;
4-4 12/01/02 Version 1.10
EFI System Table
Parameters
Hdr The table header for the EFI System Table. This header contains
the EFI_SYSTEM_TABLE_SIGNATURE and
EFI_SYSTEM_TABLE_REVISION values along with the size
of the EFI_SYSTEM_TABLE structure and a 32-bit CRC to verify that the contents of the EFI System Table are valid.
FirmwareVendor A pointer to a null terminated Unicode string that identifies the
vendor that produces the system firmware for the platform.
FirmwareRevision A firmware vendor specific value that identifies the revision of
the system firmware for the platform.
ConsoleInHandle The handle for the active console input device. This handle must
support the SIMPLE_INPUT_PROTOCOL
ConIn A pointer to the SIMPLE_INPUT_PROTOCOL interface that is
associated with ConsoleInHandle.
ConsoleOutHandle The handle for the active console output device. This handle
must support the SIMPLE_TEXT_OUTPUT_PROTOCOL
.
.
ConOut A pointer to the SIMPLE_TEXT_OUTPUT_PROTOCOL
interface that is associated with ConsoleOutHandle.
StandardErrorHandle The handle for the active standard error console device. This
handle must support the
SIMPLE_TEXT_OUTPUT_PROTOCOL.
StdErr A pointer to the SIMPLE_TEXT_OUTPUT_PROTOCOL
interface that is associated with StandardErrorHandle.
RuntimeServices A pointer to the EFI Runtime Services Table. See Section 4.5.
BootServices A pointer to the EFI Boot Services Table. See Section 4.4.
NumberOfTableEntries The number of system configuration tables in the buffer
ConfigurationTable.
ConfigurationTable A pointer to the system configuration tables. The number of
entries in the table is NumberOfTableEntries.
Version 1.10 12/01/02 4-5
Extensible Firmware Interface Specification

4.4 EFI Boot Services Table

The EFI Boot Services Table contains a table header and pointers to all of the boot services. The definition for this table is shown in the following code fragments. Except for the table header, all elements in the EFI Boot Services Tables are prototypes of function pointers to functions as defined in Chapters 5. The function pointers in this table are not valid after the operating system has taken control of the platform with a call to ExitBootServices()
.

EFI_BOOT_SERVICES

Summary
Contains a table header and pointers to all of the boot services.
Related Definitions
#define EFI_BOOT_SERVICES_SIGNATURE 0x56524553544f4f42 #define EFI_BOOT_SERVICES_REVISION ((1<<16) | (10))
typedef struct { EFI_TABLE_HEADER Hdr;
// // Task Priority Services // EFI_RAISE_TPL RaiseTPL; EFI_RESTORE_TPL RestoreTPL;
// // Memory Services // EFI_ALLOCATE_PAGES AllocatePages; EFI_FREE_PAGES FreePages; EFI_GET_MEMORY_MAP GetMemoryMap; EFI_ALLOCATE_POOL AllocatePool; EFI_FREE_POOL FreePool;
// // Event & Timer Services // EFI_CREATE_EVENT CreateEvent; EFI_SET_TIMER SetTimer; EFI_WAIT_FOR_EVENT WaitForEvent; EFI_SIGNAL_EVENT SignalEvent; EFI_CLOSE_EVENT CloseEvent; EFI_CHECK_EVENT CheckEvent;
4-6 12/01/02 Version 1.10
EFI System Table
// // Protocol Handler Services // EFI_INSTALL_PROTOCOL_INTERFACE InstallProtocolInterface; EFI_REINSTALL_PROTOCOL_INTERFACE ReinstallProtocolInterface; EFI_UNINSTALL_PROTOCOL_INTERFACE UninstallProtocolInterface; EFI_HANDLE_PROTOCOL HandleProtocol; VOID *Reserved; EFI_REGISTER_PROTOCOL_NOTIFY RegisterProtocolNotify; EFI_LOCATE_HANDLE LocateHandle; EFI_LOCATE_DEVICE_PATH LocateDevicePath; EFI_INSTALL_CONFIGURATION_TABLE InstallConfigurationTable;
// // Image Services // EFI_IMAGE_LOAD LoadImage; EFI_IMAGE_START StartImage; EFI_EXIT Exit; EFI_IMAGE_UNLOAD UnloadImage; EFI_EXIT_BOOT_SERVICES ExitBootServices;
// // Miscellaneous Services // EFI_GET_NEXT_MONOTONIC_COUNT GetNextMonotonicCount; EFI_STALL Stall; EFI_SET_WATCHDOG_TIMER SetWatchdogTimer;
// // DriverSupport Services // EFI_CONNECT_CONTROLLER ConnectController; EFI_DISCONNECT_CONTROLLER DisconnectController;
// // Open and Close Protocol Services // EFI_OPEN_PROTOCOL OpenProtocol; EFI_CLOSE_PROTOCOL CloseProtocol; EFI_OPEN_PROTOCOL_INFORMATION OpenProtocolInformation;
// // Library Services // EFI_PROTOCOLS_PER_HANDLE ProtocolsPerHandle; EFI_LOCATE_HANDLE_BUFFER LocateHandleBuffer; EFI_LOCATE_PROTOCOL LocateProtocol;
Version 1.10 12/01/02 4-7
Extensible Firmware Interface Specification
EFI_INSTALL_MULTIPLE_PROTOCOL_INTERFACES
InstallMultipleProtocolInterfaces;
EFI_UNINSTALL_MULTIPLE_PROTOCOL_INTERFACES
IninstallMultipleProtocolInterfaces;
// // 32-bit CRC Services // EFI_CALCULATE_CRC32 CalculateCrc32;
// // Memory Utility Services // EFI_COPY_MEM CopyMem; EFI_SET_MEM SetMem;
} EFI_BOOT_SERVICES;
Parameters
Hdr The table header for the EFI Boot Services Table. This
header contains the EFI_BOOT_SERVICES_
SIGNATURE and EFI_BOOT_SERVICES_ REVISION values along with the size of the EFI_BOOT_SERVICES_TABLE structure and a 32-bit
CRC to verify that the contents of the EFI Boot Services Table are valid.
RaiseTPL Raises the task priority level.
RestoreTPL Restores/lowers the task priority level.
AllocatePages Allocates pages of a particular type.
FreePages Frees allocated pages.
GetMemoryMap Returns the current boot services memory map and
memory map key.
AllocatePool Allocates a pool of a particular type.
FreePool Frees allocated pool.
CreateEvent Creates a general-purpose event structure.
SetTimer Sets an event to be signaled at a particular time.
WaitForEvent Stops execution until an event is signaled.
SignalEvent Signals an event.
CloseEvent Closes and frees an event structure.
4-8 12/01/02 Version 1.10
EFI System Table
CheckEvent Checks whether an event is in the signaled state.
InstallProtocolInterface Installs a protocol interface on a device handle.
ReinstallProtocolInterface Reinstalls a protocol interface on a device handle.
UninstallProtocolInterface Removes a protocol interface from a device handle.
HandleProtocol Queries a handle to determine if it supports a specified
protocol.
Reserved Reserved. Must be NULL.
RegisterProtocolNotify Registers an event that is to be signaled whenever an
interface is installed for a specified protocol.
LocateHandle Returns an array of handles that support a specified
protocol.
LocateDevicePath Locates all devices on a device path that support a
specified protocol and returns the handle to the device that is closest to the path.
InstallConfigurationTable Adds, updates, or removes a configuration table from the
EFI System Table.
LoadImage Loads an EFI image into memory.
StartImage Transfers control to a loaded image’s entry point.
Exit Exits the image’s entry point.
UnloadImage Unloads an image.
ExitBootServices Terminates boot services.
GetNextMonotonicCount Returns a monotonically increasing count for the
platform.
Stall Stalls the processor.
SetWatchdogTimer Resets and sets a watchdog timer used during boot
services time.
ConnectController Uses a set of precedence rules to find the best set of
drivers to manage a controller.
DisconnectController Informs a set of drivers to stop managing a controller.
OpenProtocol Adds elements to the list of agents consuming a protocol
interface.
CloseProtocol Removes elements from the list of agents consuming a
protocol interface.
Version 1.10 12/01/02 4-9
Extensible Firmware Interface Specification
OpenProtocolInformation Retrieve the list of agents that are currently consuming a
protocol interface.
ProtocolsPerHandle Retrieves the list of protocols installed on a handle. The
return buffer is automatically allocated.
LocateHandleBuffer Retrieves the list of handles from the handle database
that meet the search criteria. The return buffer is automatically allocated.
LocateProtocol Finds the first handle in the handle database the supports
the requested protocol.
InstallMultipleProtocolInterfaces
Installs one or more protocol interfaces onto a handle.
UninstallMultipleProtocolInterfaces
Uninstalls one or more protocol interfaces from a
handle.
CalculateCrc32 Computes and returns a 32-bit CRC for a data buffer.
CopyMem Copies the contents of one buffer to another buffer.
SetMem Fills a buffer with a specified value.
4-10 12/01/02 Version 1.10
EFI System Table

4.5 EFI Runtime Services Table

The EFI Runtime Services Table contains a table header and pointers to all of the runtime services. The definition for this table is shown in the following code fragments. Except for the table header, all elements in the EFI Runtime Services Tables are prototypes of function pointers to functions as defined in Chapters 6. Unlike the EFI Boot Services Table, this table, and the function pointers it contains are valid after the operating system has taken control of the platform with a call to
ExitBootServices()
the function pointers in this table are fixed up to point to the new virtually mapped entry points.
. If a call to SetVirtualAddressMap() is made by the OS, then

EFI_RUNTIME_SERVICES

Summary
Contains a table header and pointers to all of the runtime services.
Related Definitions
#define EFI_RUNTIME_SERVICES_SIGNATURE 0x56524553544e5552 #define EFI_RUNTIME_SERVICES_REVISION ((1<<16) | (10))
typedef struct { EFI_TABLE_HEADER Hdr;
// // Time Services // EFI_GET_TIME GetTime; EFI_SET_TIME SetTime; EFI_GET_WAKEUP_TIME GetWakeupTime; EFI_SET_WAKEUP_TIME SetWakeupTime;
// // Virtual Memory Services // EFI_SET_VIRTUAL_ADDRESS_MAP SetVirtualAddressMap; EFI_CONVERT_POINTER ConvertPointer;
// // Variable Services // EFI_GET_VARIABLE GetVariable; EFI_GET_NEXT_VARIABLE_NAME GetNextVariableName; EFI_SET_VARIABLE SetVariable;
Version 1.10 12/01/02 4-11
Extensible Firmware Interface Specification
// // Miscellaneous Services // EFI_GET_NEXT_HIGH_MONO_COUNT GetNextHighMonotonicCount; EFI_RESET_SYSTEM ResetSystem; } EFI_RUNTIME_SERVICES;
Parameters
Hdr The table header for the EFI Runtime Services Table.
This header contains the EFI_RUNTIME_SERVICES_
SIGNATURE and EFI_RUNTIME_SERVICES_ REVISION values along with the size of the EFI_RUNTIME_SERVICES_TABLE structure and a
32-bit CRC to verify that the contents of the EFI Runtime Services Table are valid.
GetTime Returns the current time and date, and the time-keeping
capabilities of the platform.
SetTime Sets the current local time and date information.
GetWakeupTime Returns the current wakeup alarm clock setting.
SetWakeupTime Sets the system wakeup alarm clock time.
SetVirtualAddressMap Used by an OS loader to convert from physical
addressing to virtual addressing.
ConvertPointer Used by EFI components to convert internal pointers
when switching to virtual addressing.
GetVariable Returns the value of a variable.
GetNextVariableName Enumerates the current variable names.
SetVariable Sets the value of a variable.
GetNextHighMonotonicCount Returns the next high 32 bits of the platform’s
monotonic counter.
ResetSystem Resets the entire platform.
4-12 12/01/02 Version 1.10
EFI System Table

4.6 EFI Configuration Table

The EFI Configuration Table is the ConfigurationTable field in the EFI System Table. This table contains a set of GUID/pointer pairs. Each element of this table is described by the
EFI_CONFIGURATION_TABLE structure below. The number of types of configuration tables is
expected to grow over time. This is why a GUID is used to identify the configuration table type. The EFI Configuration Table may contain at most once instance of each table type. The list of current configuration table types is also listed below.

EFI_CONFIGURATION_TABLE

Summary
Contains a set of GUID/pointer pairs comprised of the ConfigurationTable field in the EFI System Table.
Related Definitions
typedef struct{ EFI_GUID VendorGuid; VOID *VendorTable; } EFI_CONFIGURATION_TABLE;
Parameters
VendorGuid The 128-bit GUID value that uniquely identifies the system
configuration table.
VendorTable A pointer to the table associated with VendorGuid.
#define ACPI_20_TABLE_GUID \ {0x8868e871,0xe4f1,0x11d3,0xbc,0x22,0x0,0x80,0xc7,0x3c,0x88,0x81}
#define ACPI_TABLE_GUID \ {0xeb9d2d30,0x2d88,0x11d3,0x9a,0x16,0x0,0x90,0x27,0x3f,0xc1,0x4d}
#define SAL_SYSTEM_TABLE_GUID \ {0xeb9d2d32,0x2d88,0x11d3,0x9a,0x16,0x0,0x90,0x27,0x3f,0xc1,0x4d}
#define SMBIOS_TABLE_GUID \ {0xeb9d2d31,0x2d88,0x11d3,0x9a,0x16,0x0,0x90,0x27,0x3f,0xc1,0x4d}
#define MPS_TABLE_GUID \ {0xeb9d2d2f,0x2d88,0x11d3,0x9a,0x16,0x0,0x90,0x27,0x3f,0xc1,0x4d}
Version 1.10 12/01/02 4-13
Extensible Firmware Interface Specification

4.7 EFI Image Entry Point Examples

The examples in the following sections show how the various table examples are presented in the EFI environment.

4.7.1 EFI Image Entry Point Examples

The following example shows the EFI image entry point for an EFI Application. This application makes use of the EFI System Table, the EFI Boot Services Table, and the EFI Runtime Services Table.
EFI_SYSTEM_TABLE *gST; EFI_BOOT_SERVICES_TABLE *gBS; EFI_RUNTIME_SERVICES_TABLE *gRT;
EfiApplicationEntryPoint( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable )
{ EFI_STATUS Status; EFI_TIME *Time;
gST = SystemTable; gBS = gST->BootServices; gRT = gST->RuntimeServices;
// // Use EFI System Table to print “Hello World” to the active console output // device. // Status = gST->ConOut->OutputString (gST->ConOut, L”Hello World\n\r”); if (EFI_ERROR (Status)) { return Status; }
// // Use EFI Boot Services Table to allocate a buffer to store the current time // and date. // Status = gBS->AllocatePool ( EfiBootServicesData, sizeof (EFI_TIME), (VOID **)&Time ); if (EFI_ERROR (Status)) { return Status; }
4-14 12/01/02 Version 1.10
EFI System Table
// // Use the EFI Runtime Services Table to get the current time and date. // Status = gRT->GetTime (&Time, NULL) if (EFI_ERROR (Status)) { return Status; }
return Status; }
The following example shows the EFI image entry point for an EFI Driver that does not follow the EFI Driver Model. Since this driver returns EFI_SUCCESS, it will stay resident in memory after
it exits.
EFI_SYSTEM_TABLE *gST; EFI_BOOT_SERVICES_TABLE *gBS; EFI_RUNTIME_SERVICES_TABLE *gRT;
EfiDriverEntryPoint( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable )
{ gST = SystemTable; gBS = gST->BootServices; gRT = gST->RuntimeServices;
// // Implement driver initialization here. //
return EFI_SUCCESS; }
The following example shows the EFI image entry point for an EFI Driver that also does not follow the EFI Driver Model. Since this driver returns EFI_DEVICE_ERROR, it will not stay resident in
memory after it exits.
EFI_SYSTEM_TABLE *gST; EFI_BOOT_SERVICES_TABLE *gBS; EFI_RUNTIME_SERVICES_TABLE *gRT;
EfiDriverEntryPoint( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable )
{ gST = SystemTable; gBS = gST->BootServices; gRT = gST->RuntimeServices;
Version 1.10 12/01/02 4-15
Extensible Firmware Interface Specification
// // Implement driver initialization here. //
return EFI_DEVICE_ERROR; }

4.7.2 EFI Driver Model Example

The following is an EFI Driver Model example that shows the driver initialization routine for the ABC device controller that is on the XYZ bus. The EFI_DRIVER_BINDING_PROTOCOL defined in Chapter 9. The function prototypes for the AbcSupported()
AbcStop()
functions are defined in Section 9.1. This function saves the driver’s image handle
, AbcStart(), and
and a pointer to the EFI boot services table in global variables, so the other functions in the same driver can have access to these values. It then creates an instance of the
EFI_DRIVER_BINDING_PROTOCOL and installs it onto the driver's image handle.
extern EFI_GUID gEfiDriverBindingProtocolGuid; EFI_BOOT_SERVICES_TABLE *gBS; static EFI_DRIVER_BINDING_PROTOCOL mAbcDriverBinding = { AbcSupported, AbcStart, AbcStop, 1, NULL, NULL };
AbcEntryPoint( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable )
{ EFI_STATUS Status;
gBS = SystemTable->BootServices;
mAbcDriverBinding->ImageHandle = ImageHandle; mAbcDriverBinding->DriverBindingHandle = ImageHandle;
Status = gBS->InstallMultipleProtocolInterfaces( &mAbcDriverBinding->DriverBindingHandle, &gEfiDriverBindingProtocolGuid, &mAbcDriverBinding, NULL ); return Status; }
is
4-16 12/01/02 Version 1.10
EFI System Table

4.7.3 EFI Driver Model Example (Unloadable)

The following is the same EFI Driver Model example as above, except it also includes the code required to allow the driver to be unloaded through the boot service Unload() installed or memory allocated in AbcEntryPoint() must be uninstalled or freed in the
AbcUnload().
extern EFI_GUID gEfiLoadedImageProtocolGuid; extern EFI_GUID gEfiDriverBindingProtocolGuid; EFI_BOOT_SERVICES_TABLE *gBS; static EFI_DRIVER_BINDING_PROTOCOL mAbcDriverBinding = { AbcSupported, AbcStart, AbcStop, 1, NULL, NULL };
EFI_STATUS AbcUnload ( IN EFI_HANDLE ImageHandle );
AbcEntryPoint( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable )
{ EFI_STATUS Status; EFI_LOADED_IMAGE_PROTOCOL *LoadedImage;
gBS = SystemTable->BootServices;
Status = gBS->OpenProtocol ( ImageHandle, &gEfiLoadedImageProtocolGuid, &LoadedImage, ImageHandle, NULL, EFI_OPEN_PROTOCOL_GET_PROTOCOL ); if (EFI_ERROR (Status)) { return Status; } LoadedImage->Unload = AbcUnload;
mAbcDriverBinding->ImageHandle = ImageHandle; mAbcDriverBinding->DriverBindingHandle = ImageHandle;
Status = gBS->InstallMultipleProtocolInterfaces( &mAbcDriverBinding->DriverBindingHandle, &gEfiDriverBindingProtocolGuid, &mAbcDriverBinding, NULL );
return Status; }
. Any protocols
Version 1.10 12/01/02 4-17
Extensible Firmware Interface Specification
EFI_STATUS AbcUnload ( IN EFI_HANDLE ImageHandle )
{ EFI_STATUS Status;
Status = gBS->UninstallMultipleProtocolInterfaces ( ImageHandle, &gEfiDriverBindingProtocolGuid, &mAbcDriverBinding, NULL ); return Status; }

4.7.4 EFI Driver Model Example (Multiple Instances)

The following is the same as the first EFI Driver Model example, except it produces three
EFI_DRIVER_BINDING_PROTOCOL
image handle. The other two are installed onto newly created handles.
extern EFI_GUID gEfiDriverBindingProtocolGuid; EFI_BOOT_SERVICES_TABLE *gBS;
static EFI_DRIVER_BINDING_PROTOCOL mAbcDriverBindingA = { AbcSupportedA, AbcStartA, AbcStopA, 1, NULL, NULL };
static EFI_DRIVER_BINDING_PROTOCOL mAbcDriverBindingB = { AbcSupportedB, AbcStartB, AbcStopB, 1, NULL, NULL };
static EFI_DRIVER_BINDING_PROTOCOL mAbcDriverBindingC = { AbcSupportedC, AbcStartC, AbcStopC, 1, NULL, NULL };
instances. The first one is installed onto the driver’s
4-18 12/01/02 Version 1.10
EFI System Table
AbcEntryPoint( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable )
{ EFI_STATUS Status;
gBS = SystemTable->BootServices;
// // Install mAbcDriverBindingA onto ImageHandle // mAbcDriverBindingA->ImageHandle = ImageHandle; mAbcDriverBindingA->DriverBindingHandle = ImageHandle;
Status = gBS->InstallMultipleProtocolInterfaces( &mAbcDriverBindingA->DriverBindingHandle, &gEfiDriverBindingProtocolGuid, &mAbcDriverBindingA, NULL ); if (EFI_ERROR (Status)) { return Status; }
// // Install mAbcDriverBindingB onto a newly created handle // mAbcDriverBindingB->ImageHandle = ImageHandle; mAbcDriverBindingB->DriverBindingHandle = NULL;
Status = gBS->InstallMultipleProtocolInterfaces( &mAbcDriverBindingB->DriverBindingHandle, &gEfiDriverBindingProtocolGuid, &mAbcDriverBindingB, NULL ); if (EFI_ERROR (Status)) { return Status; }
// // Install mAbcDriverBindingC onto a newly created handle // mAbcDriverBindingC->ImageHandle = ImageHandle; mAbcDriverBindingC->DriverBindingHandle = NULL;
Status = gBS->InstallMultipleProtocolInterfaces( &mAbcDriverBindingC->DriverBindingHandle, &gEfiDriverBindingProtocolGuid, &mAbcDriverBindingC, NULL );
return Status; }
Version 1.10 12/01/02 4-19
Version 1.10 12/01/02 4-20
5
Services — Boot Services
This chapter discusses the fundamental boot services that are present in an EFI-compliant system. The services are defined by interface functions that may be used by code running in the EFI environment. Such code may include protocols that manage device access or extend platform capability, as well as EFI applications running in the preboot environment and EFI OS loaders.
TwotypesofservicesapplyinanEFI-compliantsystem:
• Boot Services. Functions that are available before a successful call to
ExitBootServices()
• Runtime Services. Functions that are available before and after any call to
ExitBootServices(). These functions are described in Chapter 6.
During boot, system resources are owned by the firmware and are controlled through boot services interface functions. These functions can be characterized as “global” or “handle-based.” The term “global” simply means that a function accesses system services and is available on all platforms (since all platforms support all system services). The term “handle-based” means that the function accesses a specific device or device functionality and may not be available on some platforms (since some devices are not available on some platforms). Protocols are created dynamically. This chapter discusses the “global” functions and runtime functions; subsequent chapters discuss the “handle-based.”
EFI applications (including OS loaders) must use boot services functions to access devices and allocate memory. On entry, an EFI Image is provided a pointer to an EFI system table which contains the Boot Services dispatch table and the default handles for accessing the console. All boot services functionality is available until an EFI OS loader loads enough of its own environment to take control of the system’s continued operation and then terminates boot services with a call to
ExitBootServices().
. These functions are described in this chapter.
In principle, the ExitBootServices() call is intended for use by the operating system to indicate that its loader is ready to assume control of the platform and all platform resource management. Thus boot services are available up to this point to assist the OS loader in preparing to boot the operating system. Once the OS loader takes control of the system and completes the operating system boot process, only runtime services may be called. Code other than the OS
loader, however, may or may not choose to call ExitBootServices(). This choice may in part depend upon whether or not such code is designed to make continued use of EFI boot services or the boot services environment.
Version 1.10 12/01/02 5-1
The rest of this chapter discusses individual functions. Global boot services functions fall into these categories:
• Event, Timer, and Task Priority Services (Section 5.1)
• Memory Allocation Services (Section 5.2)
• Protocol Handler Services (Section 5.3)
• Image Services (Section 5.4)
• Miscellaneous Services (Section 5.5)

5.1 Event, Timer, and Task Priority Services

The functions that make up the Event, Timer, and Task Priority Services are used during preboot to create, close, signal, and wait for events; to set timers; and to raise and restore task priority levels. See Table 5-1.
Table 5-1. Event, Timer, and Task Priority Functions
Name Type Description
CreateEvent Boot Creates a general-purpose event structure.
CloseEvent Boot Closes and frees an event structure.
SignalEvent Boot Signals an event.
WaitForEvent Boot Stops execution until an event is signaled.
CheckEvent Boot Checks whether an event is in the signaled state.
SetTimer Boot Sets an event to be signaled at a particular time.
RaiseTPL Boot Raises the task priority level.
RestoreTPL Boot Restores/lowers the task priority level.
Execution in the boot services environment occurs at different task priority levels, or TPLs. The boot services environment exposes only three of these levels to EFI applications and drivers:
• TPL_APPLICATION
• TPL_CALLBACK
• TPL_NOTIFY
, the highest priority level
, the lowest priority level
, an intermediate priority level
Tasks that execute at a higher priority level may interrupt tasks that execute at a lower priority level. For example, tasks that run at the TPL_NOTIFY level may interrupt tasks that run at the
TPL_APPLICATION or TPL_CALLBACK level. While TPL_NOTIFY is the highest level
exposed to the boot services applications, the firmware may have higher task priority items it deals with. For example, the firmware may have to deal with tasks of higher priority like timer ticks and internal devices. Consequently, there is a fourth TPL, TPL_HIGH_LEVEL
, designed for use
exclusively by the firmware.
5-2 12/01/02 Version 1.10
Loading...
Buy Points How it Works FAQ Contact Us Questions and Suggestions Privacy Policy Cookie Policy Terms of Use