Extensible Firmware Interface Specification

ManualsBrandsIntel ManualsNetwork RouterExtensible Firmware Interface

Extensible Firmware Interface

Specification

Version 1.02

December 12, 2000

Summary of content (494 pages)

PAGE 1
Extensible Firmware Interface Specification Version 1.
PAGE 2
Extensible Firmware Interface Specification THIS SPECIFICATION IS PROVIDED "AS IS" WITH NO WARRANTIES WHATSOEVER, INCLUDING ANY WARRANTY OF MERCHANTABILITY, FITNESS FOR ANY PARTICULAR PURPOSE, OR ANY WARRANTY OTHERWISE ARISING OUT OF ANY PROPOSAL, SPECIFICATION OR SAMPLE. A license is hereby granted to copy and reproduce this specification for internal use only. No other license, express or implied, by estoppel or otherwise, to any other intellectual property rights is granted herein.
PAGE 3
Revision History Revision 1.01 1.02 Revision History Original Issue. Update for legal and trademarking requirements. Version 1.
PAGE 4
Extensible Firmware Interface Specification iv 12/12/00 Version 1.
PAGE 5
Table of Contents 1 Introduction 1.1 1.2 1.3 1.4 1.5 Overview.................................................................................................... 2 Goals ......................................................................................................... 3 Target Audience ........................................................................................ 5 Related Information ...................................................................................
PAGE 6
Extensible Firmware Interface Specification 3 Services 3.1 Event, Timer, and Task Priority Services................................................. 26 3.1.1 CreateEvent() .................................................................................. 29 3.1.2 CloseEvent().................................................................................... 33 3.1.3 SignalEvent() ................................................................................... 34 3.1.4 WaitForEvent() ..................
PAGE 7
Contents 3.5 Variable Services..................................................................................... 77 3.5.1 GetVariable() ................................................................................... 78 3.5.2 GetNextVariableName() .................................................................. 80 3.5.3 SetVariable().................................................................................... 82 3.6 Time Services..............................................................
PAGE 8
Extensible Firmware Interface Specification 5.3 Device Path Nodes ................................................................................ 119 5.3.1 Generic Device Path Structures .................................................... 119 5.3.2 Hardware Device Path................................................................... 120 5.3.2.1 PCI Device Path ........................................................................... 121 5.3.2.2 PCCARD Device Path ....................................
PAGE 9
Contents 5.4.4 5.4.5 5.4.6 Hardware vs. Messaging Device Path Rules................................. 135 Media Device Path Rules .............................................................. 136 Other Rules ................................................................................... 136 6 Device I/O Protocol 6.1 6.2 Device I/O Overview .............................................................................. 137 DEVICE_IO Protocol ............................................................
PAGE 10
Extensible Firmware Interface Specification 8 Block I/O Protocol 8.1 BLOCK_IO Protocol............................................................................... 173 8.1.1 EFI_BLOCK_IO.Reset() ................................................................ 176 8.1.2 EFI_BLOCK_IO.ReadBlocks()....................................................... 177 8.1.3 EFI_BLOCK_IO.WriteBlocks()....................................................... 179 8.1.4 BLOCK_IO.FlushBlocks() ................................
PAGE 11
Contents 12 Serial I/O Protocol 12.1 SERIAL_IO Protocol .............................................................................. 213 12.1.1 SERIAL_IO.Reset() ....................................................................... 217 12.1.2 SERIAL_IO.SetAttributes() ............................................................ 218 12.1.3 SERIAL_IO.SetControl()................................................................ 220 12.1.4 SERIAL_IO.GetControl() .............................................
PAGE 12
Extensible Firmware Interface Specification 15 Simple Network Protocol 15.1 EFI_SIMPLE_NETWORK Protocol........................................................ 277 15.1.1 EFI_SIMPLE_NETWORK.Start() ..................................................... 282 15.1.2 EFI_SIMPLE_NETWORK.Stop() ..................................................... 283 15.1.3 EFI_SIMPLE_NETWORK.Initialize()................................................ 284 15.1.4 EFI_SIMPLE_NETWORK.Reset() .......................................
PAGE 13
Contents 17 Boot Manager 17.1 Firmware Boot Manager ........................................................................ 319 17.2 Globally-Defined Variables .................................................................... 323 17.3 Boot Option Variables Default Behavior ................................................ 325 17.4 Boot Mechanisms .................................................................................. 325 17.4.1 Boot via Simple File Protocol....................................
PAGE 14
Extensible Firmware Interface Specification G 32/64-Bit UNDI Specification G.1 Introduction............................................................................................ 373 G.1.1 Definitions...................................................................................... 373 G.1.2 Referenced Specifications ............................................................. 374 G.1.3 OS Network Stacks ....................................................................... 376 G.2 Overview.....
PAGE 15
Contents G.4.18 Transmit......................................................................................... 460 G.4.19 Receive.......................................................................................... 464 G.5 UNDI as an EFI Runtime Driver............................................................. 466 Index .......................................................................................................................... 469 Figures 1-1. 2-1. 2-2. 3-1. 4-1. 4-2. 16-1. 16-2.
PAGE 16
Extensible Firmware Interface Specification 3-3. 3-5. 3-7. 3-9. 3-11. 3-13. 3-15. 3-17. 3-19. 3-21. 3-23. 3-25. 5-1. 5-3. 5-5. 5-6. 5-7. 5-8. 5-9. 5-10. 5-11. 5-12. 5-13. 5-14. 5-15. 5-16. 5-17. 5-18. 5-19. 5-20. TPL Usage............................................................................................... 27 TPL Restrictions ...................................................................................... 28 Memory Allocation Functions.......................................................
PAGE 17
Contents 5-25. 5-26. 5-27. 5-28. 5-29. 5-30. 5-31. 6-1. 7-1. 7-3. 14-1. 14-2. 14-3. 14-4. 14-5. 16-1. 16-2. 16-3. 16-4. 16-5. 16-6. 16-7. 17-1 17-2 18-1. 18-2. 18-3. A-1. B-1. CD-ROM Media Device Path................................................................. 131 Vendor-Defined Media Device Path....................................................... 131 File Path Media Device Path ................................................................. 132 Media Protocol Media Device Path..................
PAGE 18
Extensible Firmware Interface Specification D-1. D-2. D-3. D-4. E-1. E-2. G-1. G-2. G-3. G-4. G-5. xviii EFI_STATUS Codes Ranges ................................................................ 345 EFI_STATUS Success Codes (High bit clear)....................................... 345 EFI_STATUS Error Codes (High bit set) ............................................... 345 EFI_STATUS Warning Codes (High bit clear) ....................................... 346 Functions Listed in Alphabetic Order .............
PAGE 19
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 and its loader. Together, these provide a standard environment for booting an OS. The EFI specification is designed as a pure interface specification.
PAGE 20
Extensible Firmware Interface Specification 1.1 Overview This specification is organized as follows: Table 1-1. Organization of EFI Specification Chapter/Appendix Description 1. Introduction Provides an overview of the EFI Specification. 2. Overview Describes the major components of EFI, including the boot manager, firmware core, calling conventions, protocols, and requirements. 3. Services Contains definitions for the fundamental services that are present in an EFI-compliant system. 4.
PAGE 21
Introduction Table 1-1. 1.2 Organization of EFI Specification (continued) Chapter/Appendix Description 15. Simple Network Protocol Defines the Simple Network Protocol, which provides a packet level interface to a network device. Also defines the Network Interface Identifier Protocol, which is an optional protocol used to describe details about the software layer used to produce the Simple Network Protocol. 16. File System Format Defines the EFI file system. 17.
PAGE 22
Extensible Firmware Interface Specification • • • 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.
PAGE 23
Introduction • • • 1.3 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.
PAGE 24
Extensible Firmware Interface Specification 1.4 Related Information The following publications and sources of information may be useful to you or are referred to by this specification: • ACPI Implementers’ Guide, Intel Corporation, Microsoft Corporation, Toshiba Corporation, version 0.5, 1998, http://www.teleport.com/~acpi • Advanced Configuration and Power Interface Specification, http://www.teleport.com/~acpi • BIOS Boot Specification Version 1.01, Compaq Computer Corporation, Phoenix Technologies Ltd.
PAGE 25
Introduction • • • • • • • • • • • • • • • • • • Microsoft Extensible Firmware Initiative FAT32 File System Specification, Version 1.03, Microsoft Corporation, December 6, 2000 OSTA Universal Disk Format Specification, Revision 2.00, Optical Storage Technology Association, 1998, http://www2.osta.org/osta/html/ostatech.html#udf PCI BIOS Specification, Revision 2.1, PCI Special Interest Group, Hillsboro, OR, http://www.pcisig.com/tech/index.html PCI Local Bus Specification Revision 2.
PAGE 26
Extensible Firmware Interface Specification 1.5 Prerequisite Specifications In general, this specification requires that functionality defined in a number of other existing specifications be present on a system that implements this specification. This specification requires that those specifications be implemented at least to the extent that all the required elements are present. This specification prescribes the use and extension of previously established industry specification tables whenever possible.
PAGE 27
Introduction 1.5.3 Additional Considerations for Itanium™-based Platforms Any information or service that is available via Itanium-based firmware architecture specifications supercedes any requirement in the common IA-32 and Itanium-based specifications listed above.
PAGE 28
Extensible Firmware Interface Specification 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 EFI BOOT SERVICES ACPI INTERFACES FROM OTHER REQUIRED SPECS PLATFORM HARDWARE EFI RUNTIME SERVICES EFI SYSTEM PARTITION EFI OS LOADER Figure 1-1.
PAGE 29
Introduction 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.
PAGE 30
Extensible Firmware Interface Specification 1.8 Conventions Used in This Document This document uses typographic and illustrative conventions described below. 1.8.1 Data Structure Descriptions The Intel architecture processors of the IA-32 family are “little endian” machines. This means that the low-order byte of a multi-byte data item in memory is at the lowest address, while the highorder byte is at the highest address.
PAGE 31
2 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. 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.
PAGE 32
Extensible Firmware Interface Specification 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.
PAGE 33
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 sub-categories:  Global boot service interfaces  Device handle-based boot service interfaces  Device protocols  Protocol services 2.2.2 Runtime Services This section describes EFI runtime service functions.
PAGE 34
Extensible Firmware Interface Specification 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.
PAGE 35
Overview Table 2-2. Common EFI Data Types (continued) Mnemonic Description 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.
PAGE 36
Extensible Firmware Interface Specification 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, and edx. 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.
PAGE 37
Overview 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() has been used, then runtime service calls are made in virtual mode. Refer to the IA-64 System Abstraction Layer Specification for details. EFI procedures are invoked using the P64 C calling conventions defined for Itanium-based applications.
PAGE 38
Extensible Firmware Interface Specification 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.
PAGE 39
Overview 2.5 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.
PAGE 40
Extensible Firmware Interface Specification Table 2-5. Required EFI Implementation Elements (continued) Element Description SIMPLE_INPUT protocol Protocol interfaces for devices that support simple console style text input. SIMPLE_TEXT_OUTPUT protocol Protocol interfaces for devices that support console style text displaying. UNICODE_COLLATION protocol 1 2.5.2 1 Protocol interfaces for Unicode string comparison operations.
PAGE 41
Overview 2.5.3 Appendixes The content of Appendixes B, C, D, E of this specification is largely intended as informational. In other words, semantic information contained in these sections need not be considered part of the formal definition of either required or optional elements of the specification. The content of Appendix A is a set of definitions that are used extensively by other interfaces in the specification. As such, implementations are required to use the time and GUID formats defined therein.
PAGE 42
Extensible Firmware Interface Specification 24 12/01/00 Version 1.
PAGE 43
3 Services This chapter discusses the fundamental 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 pre-boot environment and EFI OS loaders. Two types of services are described here: • Boot Services.
PAGE 44
Extensible Firmware Interface Specification The rest of this chapter discusses individual functions. Global boot services functions fall into these categories: • Event, Timer, and Task Priority Services (Section 3.1) • Memory Allocation Services (Section 3.2) • Protocol Handler Services (Section 3.3) • Image Services (Section 3.4) • Miscellaneous Services (Section 3.8) Runtime Services fall into these categories: • • • • 3.1 Variable Services (Section 3.5) Time Services (Section 3.
PAGE 45
Services 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, the lowest priority level • TPL_CALLBACK, an intermediate priority level • TPL_NOTIFY, the highest priority level Tasks that execute at a higher priority level may interrupt tasks that execute at a lower priority level.
PAGE 46
Extensible Firmware Interface Specification Table 3-2. TPL Usage (continued) Task Priority Level Usage (Firmware Interrupts) This level is internal to the firmware. It is the level at which internal interrupts occur. Code running at this level interrupts code running at the TPL_NOTIFY level (or lower levels). If the interrupt requires extended time to complete, firmware signals another event (or events) to perform the longer term operations so that other interrupts can occur.
PAGE 47
Services 3.1.1 CreateEvent() Summary Creates an event. Prototype EFI_STATUS CreateEvent ( IN UINT32 IN EFI_TPL IN EFI_EVENT_NOTIFY IN VOID OUT EFI_EVENT ); Type, NotifyTpl, NotifyFunction, *NotifyContext, *Event Parameters Type The type of event to create and its mode and attributes. The “#define” statements in “Related Definitions” can be used to specify an event’s mode and attributes. NotifyTpl The task priority level of event notifications. See Section 3.1.7.
PAGE 48
Extensible Firmware Interface Specification Related Definitions //******************************************************* // EFI_EVENT //******************************************************* typedef VOID *EFI_EVENT //******************************************************* // Event Types //******************************************************* // These types can be “ORed” together as needed – for example, // EVT_TIMER might be “Ored” with EVT_NOTIFY_WAIT or // EVT_NOTIFY_SIGNAL.
PAGE 49
Services EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE The event is to be notified by the system when SetVirtualAddressMap() is performed. This type can not be used with any other EVT bit type. See the discussion of EVT_RUNTIME. //******************************************************* // EFI_EVENT_NOTIFY //******************************************************* typedef VOID (EFIAPI *EFI_EVENT_NOTIFY) ( IN EFI_EVENT Event, IN VOID *Context ); Event Event whose notification function is being invoked.
PAGE 50
Extensible Firmware Interface Specification can’t clean up on behalf of drivers that have been loaded into the system. The drivers have to do that themselves by creating an event whose type is EVT_SIGNAL_EXIT_BOOT_SERVICES and whose notification function is a function within the driver itself. Then, when ExitBootServices() has finished its cleanup, it signals each event of type EVT_SIGNAL_EXIT_BOOT_SERVICES.
PAGE 51
Services 3.1.2 CloseEvent() Summary Closes an event. Prototype EFI_STATUS CloseEvent ( IN EFI_EVENT ); Event Parameters Event The event to close. Type EFI_EVENT is defined in Section 3.1.1. Description The CloseEvent() function removes the caller’s reference to the event and closes it. Once the event is closed, the event is no longer valid and may not be used on any subsequent function calls. Status Codes Returned EFI_SUCCESS Version 1.02 The event has been closed.
PAGE 52
Extensible Firmware Interface Specification 3.1.3 SignalEvent() Summary Signals an event. Prototype EFI_STATUS SignalEvent ( IN EFI_EVENT ); Event Parameters Event The event to signal. Type EFI_EVENT is defined in Section 3.1.1. Description The supplied Event is signaled and, if the event has a signal notification function, it is scheduled to be invoked at the event’s notificiation task priority level. SignalEvent() may be invoked from any task priority level.
PAGE 53
Services 3.1.4 WaitForEvent() Summary Stops execution until an event is signaled. Prototype EFI_STATUS WaitForEvent ( IN UINTN IN EFI_EVENT OUT UINTN ); NumberOfEvents, *Event, *Index Parameters NumberOfEvents The number of events in the Event array. Event An array of EFI_EVENT. Type EFI_EVENT is defined in Section 3.1.1. Index Pointer to the index of the event which satisfied the wait condition. Description The WaitForEvent()function waits for any event in the Event array to be signaled.
PAGE 54
Extensible Firmware Interface Specification 3.1.5 CheckEvent() Summary Checks whether an event is in the signaled state. Prototype EFI_STATUS CheckEvent ( IN EFI_EVENT ); Event Parameters Event The event to check. Type EFI_EVENT is defined in Section 3.1.1. Description The CheckEvent() function checks to see whether Event is in the signaled state. If Event is of type EVT_NOTIFY_SIGNAL, then EFI_INVALID_PARAMETER is returned.
PAGE 55
Services 3.1.6 SetTimer() Summary Sets the type of timer and the trigger time for a timer event. Prototype EFI_STATUS SetTimer ( IN EFI_EVENT IN EFI_TIMER_DELAY IN UINT64 ); Event, Type, TriggerTime Parameters Event The timer event that is to be signaled at the specified time. Type EFI_EVENT is defined in Section 3.1.1. Type The type of time that is specified in TriggerTime. See the timer delay types in “Related Definitions”. TriggerTime The number of 100ns units until the timer expires.
PAGE 56
Extensible Firmware Interface Specification Description The SetTimer() function cancels any previous time trigger setting for the event, and sets the new trigger time for the event. This function can only be used on events of type EVT_TIMER. Status Codes Returned 38 EFI_SUCCESS The event has been set to be signaled at the requested time. EFI_INVALID_PARAMETER Event or Type is not valid. 12/12/00 Version 1.
PAGE 57
Services 3.1.7 RaiseTPL() Summary Raises a task’s priority level and returns its previous level. Prototype EFI_TPL RaiseTPL ( IN EFI_TPL NewTpl ); Parameters NewTpl The new task priority level. It must be greater than or equal to the current task priority level. See “Related Definitions”.
PAGE 58
Extensible Firmware Interface Specification Description The RaiseTPL() function raises the priority of the currently executing task and returns its previous priority level. Only three task priority levels are exposed outside of the firmware during EFI boot services execution. The first is TPL_APPLICATION where all normal execution occurs. That level may be interrupted to perform various asynchronous interrupt style notifications, which occur at the TPL_CALLBACK or TPL_NOTIFY level.
PAGE 59
Services 3.1.8 RestoreTPL() Summary Restores a task’s priority level to its previous value. Prototype VOID RestoreTPL ( IN EFI_TPL OldTpl ) Parameters OldTpl The previous task priority level to restore (the value from a previous, matching call to RaiseTPL()). Type EFI_TPL is defined in Section 3.1.7. Description The RestoreTPL() function restores a task’s priority level to its previous value. Calls to RestoreTPL() are matched with calls to RaiseTPL().
PAGE 60
Extensible Firmware Interface Specification 3.2 Memory Allocation Services The functions that make up Memory Allocation Services are used during pre-boot to allocate and free memory, and to obtain the system’s memory map. See Table 3-4. Table 3-4. Memory Allocation Functions Name Type Description AllocatePages Boot Allocates pages of a particular type. FreePages Boot Frees allocated pages. GetMemoryMap Boot Returns the current boot services memory map and memory map key.
PAGE 61
Services Table 3-5. Memory Type Usage Before ExitBootServices() Mnemonic Description EfiReservedMemoryType Not used. EfiLoaderCode The code portions of a loaded EFI application. (Note that EFI OS loaders are EFI applications.) EfiLoaderData The data portions of a loaded EFI application and the default data allocation type used by an EFI application to allocate pool memory. EfiBootServicesCode The code portions of a loaded Boot Services Driver.
PAGE 62
Extensible Firmware Interface Specification Table 3-6. Memory Type Usage After ExitBootServices() Mnemonic Description EfiReservedMemoryType Not used. EfiLoaderCode The Loader and/or OS may use this memory as they see fit. Note: the OS loader that called ExitBootServices() is utilizing one or more EfiLoaderCode ranges. EfiLoaderData The Loader and/or OS may use this memory as they see fit. Note: the OS loader that called ExitBootServices() is utilizing one or more EfiLoaderData ranges.
PAGE 63
Services 3.2.1 AllocatePages() Summary Allocates memory pages from the system. Prototype EFI_STATUS AllocatePages( IN EFI_ALLOCATE_TYPE Type, IN EFI_MEMORY_TYPE MemoryType, IN UINTN Pages, IN OUT EFI_PHYSICAL_ADDRESS *Memory ); Parameters Type The type of allocation to perform. See “Related Definitions”. MemoryType The type of memory to allocate.
PAGE 64
Extensible Firmware Interface Specification Related Definitions //******************************************************* //EFI_ALLOCATE_TYPE //******************************************************* // These types are discussed in the “Description” section below.
PAGE 65
Services Description The AllocatePages() function allocates the requested number of pages and returns a pointer to the base address of the page range in the location referenced by Memory. The function scans the memory map to locate free pages. When it finds a physically contiguous block of pages that is large enough and also satisfies the value of Type, it changes the memory map to indicate that the pages are now of type MemoryType.
PAGE 66
Extensible Firmware Interface Specification 3.2.2 FreePages() Summary Frees memory pages. Prototype EFI_STATUS FreePages ( IN EFI_PHYSICAL_ADDRESS IN UINTN ); Memory, Pages Parameters Memory The base physical address of the pages to be freed. Type EFI_PHYSICAL_ADDRESS is defined in Section 3.2.1. Pages The number of contiguous 4KB pages to free. Description The FreePages() function returns memory allocated by AllocatePages()to the firmware.
PAGE 67
Services 3.2.3 GetMemoryMap() Summary Returns the current memory map. Prototype EFI_STATUS GetMemoryMap ( IN OUT UINTN IN OUT EFI_MEMORY_DESCRIPTOR OUT UINTN OUT UINTN OUT UINT32 ); *MemoryMapSize, *MemoryMap, *MapKey, *DescriptorSize, *DescriptorVersion Parameters MemoryMapSize A pointer to the size, in bytes, of the MemoryMap buffer. On input, this is the size of the buffer allocated by the caller.
PAGE 68
Extensible Firmware Interface Specification Related Definitions //******************************************************* //EFI_MEMORY_DESCRIPTOR //******************************************************* typedef struct { UINT32 Type; EFI_PHYSICAL_ADDRESS PhysicalStart; EFI_VIRTUAL_ADDRESS VirtualStart; UINT64 NumberOfPages; UINT64 Attribute; } EFI_MEMORY_DESCRIPTOR; Type Type of the memory region (EFI_MEMORY_TYPE, see Section 3.2.1). PhysicalStart Physical address of the first byte in the memory region.
PAGE 69
Services EFI_MEMORY_WB Memory cacheability attribute: Memory region is cacheable with “write back” policy. Reads and writes that hit in the cache do not propagate to main memory. Dirty data is written back to main memory when a new cache line is allocated. EFI_MEMORY_UCE Memory cacheability attribute: Memory region is uncacheable,exported, and supports the "fetch and add" semaphore mechanism. EFI_MEMORY_WP Physical memory protection attribute: Memory region is writeprotected by system hardware.
PAGE 70
Extensible Firmware Interface Specification The GetMemoryMap() function also returns the size and revision number of the EFI_MEMORY_DESCRIPTOR. The DescriptorSize represents the size in bytes of an EFI_MEMORY_DESCRIPTOR array element returned in MemoryMap. The size is returned to allow for future expansion of the EFI_MEMORY_DESCRIPTOR in response to hardware innovation.
PAGE 71
Services 3.2.4 AllocatePool() Summary Allocates pool memory. Prototype EFI_STATUS AllocatePool ( IN EFI_MEMORY_TYPE IN UINTN OUT VOID ); PoolType, Size, **Buffer Parameters PoolType The type of pool to allocate. The only supported types are EfiLoaderData, EfiBootServicesData, EfiRuntimeServicesData, EfiACPIReclaimMemory, and EfiACPIMemoryNVS. Type EFI_MEMORY_TYPE is defined in Section 3.2.1. Size The number of bytes to allocate from the pool.
PAGE 72
Extensible Firmware Interface Specification 3.2.5 FreePool() Summary Returns pool memory to the system. Prototype EFI_STATUS FreePool ( IN VOID ); *Buffer Parameters Buffer Pointer to the buffer to free. Description The FreePool() function returns the memory specified by Buffer to the system. On return, the memory’s type is EfiConventionalMemory. The Buffer that is freed must have been allocated by AllocatePool(). Status Codes Returned 54 EFI_SUCCESS The memory was returned to the system.
PAGE 73
Services 3.3 Protocol Handler Services In the abstract, a protocol consists of a 128-bit guaranteed unique identifier (GUID) and a Protocol Interface structure. The structure contains the functions and instance data that are used to access a device. The functions that make up Protocol Handler Services allow applications to install a protocol on a handle, identify the handles that support a given protocol, determine whether a handle supports a given protocol, and so forth. See Table 3-7. Table 3-7.
PAGE 74
Extensible Firmware Interface Specification First Handle Device Handle GUID Interface GUID Interface GUID Interface GUID Interface Protocol Interface Protocol Interface Protocol Interface Protocol Interface Instance Data Instance Data Instance Data Instance Data Device Handle GUID Interface GUID Interface Protocol Interface Protocol Interface Instance Data Instance Data ... Figure 3-1.
PAGE 75
Services 3.3.1 InstallProtocolInterface() Summary Installs a protocol interface on a device handle. If the handle does not exist, it is created and added to the list of handles in the system. Prototype EFI_STATUS InstallProtocolInterface ( IN OUT EFI_HANDLE IN EFI_GUID IN EFI_INTERFACE_TYPE IN VOID ); *Handle, *Protocol, InterfaceType, *Interface Parameters Handle A pointer to the EFI_HANDLE on which the interface is to be installed.
PAGE 76
Extensible Firmware Interface Specification Related Definitions //******************************************************* //EFI_HANDLE //******************************************************* typedef VOID *EFI_HANDLE; //******************************************************* //EFI_GUID //******************************************************* typedef struct { UINT32 Data1; UINT16 Data2; UINT16 Data3; UINT8 Data4[8]; } EFI_GUID; //******************************************************* //EFI_INTERFACE_TYPE
PAGE 77
Services 3.3.2 UninstallProtocolInterface() Summary Removes a protocol interface from a device handle. Prototype EFI_STATUS UninstallProtocolInterface ( IN EFI_HANDLE IN EFI_GUID IN VOID ); Handle, *Protocol, *Interface Parameters Handle The handle on which the interface was installed. Type EFI_HANDLE is defined in Section 3.3.1. If Handle is not a valid handle, then EFI_INVALID_PARAMETER is returned. Protocol The numeric ID of the interface. Type EFI_GUID is defined in Section 3.3.1.
PAGE 78
Extensible Firmware Interface Specification 3.3.3 ReinstallProtocolInterface() Summary Reinstalls a protocol interface on a device handle. Prototype EFI_STATUS ReinstallProtocolInterface IN EFI_HANDLE IN EFI_GUID IN VOID IN VOID ); ( Handle, *Protocol, *OldInterface, *NewInterface Parameters Handle Handle on which the interface is to be reinstalled. Type EFI_HANDLE is defined in Section 3.3.1. If Handle is not a valid handle, then EFI_INVALID_PARAMETER is returned.
PAGE 79
Services 3.3.4 RegisterProtocolNotify() Summary Creates an event that is to be signaled whenever an interface is installed for a specified protocol. Prototype EFI_STATUS RegisterProtocolNotify ( IN EFI_GUID *Protocol, IN EFI_EVENT Event, OUT VOID **Registration ); Parameters Protocol The numeric ID of the protocol for which the event is to be registered. Type EFI_GUID is defined in Section 3.3.1. Event Event that is to be signaled whenever a protocol interface is registered for Protocol.
PAGE 80
Extensible Firmware Interface Specification 3.3.5 LocateHandle() Summary Returns an array of handles that support a specified protocol. Prototype EFI_STATUS LocateHandle ( IN EFI_LOCATE_SEARCH_TYPE IN EFI_GUID IN VOID IN OUT UINTN OUT EFI_HANDLE ); SearchType, *Protocol OPTIONAL, *SearchKey OPTIONAL, *BufferSize, *Buffer Parameters 62 SearchType Specifies which handle(s) are to be returned. Type EFI_LOCATE_SEARCH_TYPE is defined in “Related Definitions”.
PAGE 81
Services Related Definitions //******************************************************* // EFI_LOCATE_SEARCH_TYPE //******************************************************* typedef enum { AllHandles, ByRegisterNotify, ByProtocol } EFI_LOCATE_SEARCH_TYPE; AllHandles Protocol and SearchKey are ignored and the function returns an array of every handle in the system. ByRegisterNotify SearchKey supplies the Registration value returned by RegisterProtocolNotify().
PAGE 82
Extensible Firmware Interface Specification 3.3.6 HandleProtocol() Summary Queries a handle to determine if it supports a specified protocol. Prototype EFI_STATUS HandleProtocol ( IN EFI_HANDLE IN EFI_GUID OUT VOID ); Handle, *Protocol, **Interface Parameters Handle The handle being queried. Type EFI_HANDLE is defined in Section 3.3.1. If Handle is not a valid EFI_HANDLE, then EFI_INVALID_PARAMETER is returned. Protocol The published unique identifier of the protocol.
PAGE 83
Services 3.3.7 LocateDevicePath() Summary Locates the handle to a device on the device path that supports the specified protocol. Prototype EFI_STATUS LocateDevicePath ( IN EFI_GUID IN OUT EFI_DEVICE_PATH OUT EFI_HANDLE ); *Protocol, **DevicePath, *Device Parameters Protocol The protocol to search for. Type EFI_GUID is defined in Section 3.3.1. DevicePath On input, a pointer to a pointer to the device path.
PAGE 84
Extensible Firmware Interface Specification Description The LocateDevicePath() function locates all devices on DevicePath that support Protocol and returns the handle to the device that is closest to DevicePath. DevicePath is advanced over the device path nodes that were matched. This function is useful for locating the proper instance of a protocol interface to use from a logical parent device driver.
PAGE 85
Services 3.4 Image Services Three types of images can be loaded: EFI Applications, EFI Boot Services Drivers, and EFI Runtime Services Drivers. An EFI OS Loader is a type of EFI Application. The most significant difference between these image types is the type of memory into which they are loaded by the firmware’s loader. Table 3-8 summarizes the differences between images. Table 3-8.
PAGE 86
Extensible Firmware Interface Specification Most images are loaded by the boot manager. When an EFI application or driver is installed, the installation procedure registers itself with the boot manager for loading. However, in some cases an application or driver may want to programmatically load and start another EFI image. This can be done with the LoadImage() and StartImage() interfaces. Drivers may only load applications during the driver’s initialization entry point.
PAGE 87
Services 3.4.1 LoadImage() Summary Loads an EFI image into memory. Prototype EFI_STATUS LoadImage ( IN BOOLEAN IN EFI_HANDLE IN EFI_DEVICE_PATH IN VOID IN UINTN OUT EFI_HANDLE ); BootPolicy, ParentImageHandle, *FilePath, *SourceBuffer OPTIONAL, SourceSize, *ImageHandle Parameters BootPolicy If TRUE, indicates that the request originates from the boot manager, and that the boot manager is attempting to load FilePath as a boot selection. Ignored if SourceBuffer is not NULL.
PAGE 88
Extensible Firmware Interface Specification Description The LoadImage() function loads an EFI image into memory and returns a handle to the image. The image is loaded in one of two ways. If SourceBuffer is not NULL, the function is a memory-to-memory load in which SourceBuffer points to the image to be loaded and SourceSize indicates the image’s size in bytes. In this case, the caller has copied the image into SourceBuffer and can free the buffer once loading is complete.
PAGE 89
Services 3.4.2 StartImage() Summary Transfers control to a loaded image’s entry point. Prototype EFI_STATUS StartImage ( IN EFI_HANDLE OUT UINTN OUT CHAR16 ); ImageHandle, *ExitDataSize, **ExitData OPTIONAL Parameters ImageHandle Handle of image to be started. Type EFI_HANDLE is defined in Section 3.3.1. ExitDataSize Pointer to the size, in bytes, of ExitData.
PAGE 90
Extensible Firmware Interface Specification 3.4.3 UnloadImage() Summary Unloads an image. Prototype EFI_STATUS UnloadImage ( IN EFI_HANDLE ); ImageHandle Parameters ImageHandle Handle that identifies the image to be unloaded. Type EFI_HANDLE is defined in Section 3.3.1. Description The UnloadImage() function unloads a previously loaded image. There are three possible scenarios. If the image has not been started, the function unloads the image and returns EFI_SUCCESS.
PAGE 91
Services 3.4.4 EFI_IMAGE_ENTRY_POINT Summary This is the declaration of an EFI image entry point. This can be the entry point to an EFI application, an EFI boot service driver, or an EFI runtime driver. Prototype typedef EFI_STATUS (EFIAPI *EFI_IMAGE_ENTRY_POINT) ( IN EFI_HANDLE ImageHandle, IN EFI_SYSTEM_TABLE *SystemTable ); Parameters ImageHandle Handle that identifies the loaded image. Type EFI_HANDLE is defined in Section 3.3.1. SystemTable System Table for this image.
PAGE 92
Extensible Firmware Interface Specification 3.4.5 Exit() Summary Terminates the currently loaded EFI image and returns control to boot services. Prototype EFI_STATUS Exit ( IN EFI_HANDLE IN EFI_STATUS IN UINTN IN CHAR16 ); ImageHandle, ExitStatus, ExitDataSize, *ExitData OPTIONAL Parameters ImageHandle Handle that identifies the image. This parameter is passed to the image on entry. Type EFI_HANDLE is defined in Section 3.3.1. ExitStatus The image’s exit code.
PAGE 93
Services When an EFI application exits, firmware frees the memory used to hold the image. The firmware also frees its references to the ImageHandle and the handle itself. Before exiting, the application is responsible for freeing any resources it allocated. This includes memory (pages and/or pool), open file system handles, and so forth. The only exception to this rule is the ExitData buffer, which must be freed by the caller of StartImage().
PAGE 94
Extensible Firmware Interface Specification 3.4.6 ExitBootServices() Summary Terminates all boot services. Prototype EFI_STATUS ExitBootServices ( IN EFI_HANDLE IN UINTN ); ImageHandle, MapKey Parameters ImageHandle Handle that identifies the exiting image. Type EFI_HANDLE is defined in Section 3.3.1. MapKey Key to the latest memory map. Description The ExitBootServices() function is called by the currently executing EFI OS loader image to terminate all boot services.
PAGE 95
Services 3.5 Variable Services Variables are defined as key/value pairs that consist of identifying information plus attributes (the key) and arbitrary data (the value). Variables are intended for use as a means to store data that is passed between the EFI environment implemented in the platform and EFI OS loaders and other applications that run in the EFI environment. Although the implementation of variable storage is not defined in this specification, variables must be persistent in most cases.
PAGE 96
Extensible Firmware Interface Specification 3.5.1 GetVariable() Summary Returns the value of a variable. Prototype EFI_STATUS GetVariable ( IN CHAR16 IN EFI_GUID OUT UINT32 IN OUT UINTN OUT VOID ); *VariableName, *VendorGuid, *Attributes OPTIONAL, *DataSize, *Data Parameters VariableName A Null-terminated Unicode string that is the name of the vendor’s variable. VendorGuid A unique identifier for the vendor. Type EFI_GUID is defined in Section 3.3.1.
PAGE 97
Services Description Each vendor may create and manage its own variables without the risk of name conflicts by using a unique VendorGuid. When a variable is set its Attributes are supplied to indicate how the data variable should be stored and maintained by the system. The attributes affect when the variable may be accessed and volatility of the data. Any attempts to access a variable that does not have the attribute set for runtime access will yield the EFI_NOT_FOUND error.
PAGE 98
Extensible Firmware Interface Specification 3.5.2 GetNextVariableName() Summary Enumerates the current variable names. Prototype EFI_STATUS GetNextVariableName ( IN OUT UINTN IN OUT CHAR16 IN OUT EFI_GUID ); *VariableNameSize, *VariableName, *VendorGuid Parameters VariableNameSize The size of the VariableName buffer. VariableName On input, supplies the last VariableName that was returned by GetNextVariableName(). On output, returns the Nullterminated Unicode string of the current variable.
PAGE 99
Services Once ExitBootServices() is performed, variables that are only visible during boot services will no longer be returned. To obtain the data contents or attribute for a variable returned by GetNextVariableName(), the GetVariable() interface is used. Status Codes Returned EFI_SUCCESS The function completed successfully. EFI_NOT_FOUND The next variable was not found. EFI_BUFFER_TOO_SMALL The VariableNameSize is too small for the result.
PAGE 100
Extensible Firmware Interface Specification 3.5.3 SetVariable() Summary Sets the value of a variable. Prototype EFI_STATUS SetVariable ( IN CHAR16 IN EFI_GUID IN UINT32 IN UINTN IN VOID ); *VariableName, *VendorGuid, Attributes, DataSize, *Data Parameters VariableName A Null-terminated Unicode string that is the name of the vendor’s variable. Each VariableName is unique for each VendorGuid. VendorGuid A unique identifier for the vendor. Type EFI_GUID is defined in Section 3.3.1.
PAGE 101
Services EFI_VARIABLE_NON_VOLATILE variables are stored in fixed hardware that has a limited storage capacity; sometimes a severely limited capacity. Software should only use a non-volatile variable when absolutely necessary. In addition, if software uses a non-volatile variable it should use a variable that is only accessible at boot services time if possible. A variable must contain one or more bytes of Data. Using SetVariable() with a DataSize of zero causes the entire variable to be deleted.
PAGE 102
Extensible Firmware Interface Specification 3.6 Time Services This section contains function definitions for time-related functions that are typically needed by operating systems at runtime to access underlying hardware that manages time information and services. The purpose of these interfaces is to provide operating system writers with an abstraction for hardware time devices, thereby relieving the need to access legacy hardware devices directly.
PAGE 103
Services 3.6.1 GetTime() Summary Returns the current time and date information, and the time-keeping capabilities of the hardware platform. Prototype EFI_STATUS GetTime ( OUT EFI_TIME OUT EFI_TIME_CAPABILITIES ); *Time, *Capabilities OPTIONAL Parameters Time A pointer to storage to receive a snapshot of the current time. Type EFI_TIME is defined in “Related Definitions”. Capabilities An optional pointer to a buffer to receive the real time clock device’s capabilities.
PAGE 104
Extensible Firmware Interface Specification //******************************************************* // Bit Definitions for EFI_TIME.Daylight. See below. //******************************************************* #define EFI_TIME_ADJUST_DAYLIGHT 0x01 #define EFI_TIME_IN_DAYLIGHT 0x02 //******************************************************* // Value Definition for EFI_TIME.TimeZone. See below.
PAGE 105
Services //******************************************************* // EFI_TIME_CAPABILITIES //******************************************************* // This provides the capabilities of the // real time clock device as exposed through the EFI interfaces. typedef struct { UINT32 Resolution; UINT32 Accuracy; BOOLEAN SetsToZero; } EFI_TIME_CAPABILITIES; Resolution Provides the reporting resolution of the real-time clock device in counts per second.
PAGE 106
Extensible Firmware Interface Specification 3.6.2 SetTime() Summary Sets the current local time and date information. Prototype EFI_STATUS SetTime ( IN EFI_TIME ); *Time Parameters Time A pointer to the current time. Type EFI_TIME is defined in Section 3.6.1. Full error checking is performed on the different fields of the EFI_TIME structure (refer to the EFI_TIME definition on page 85 for full details), and EFI_INVALID_PARAMETER is returned if any field is out of range.
PAGE 107
Services 3.6.3 GetWakeupTime() Summary Returns the current wakeup alarm clock setting. Prototype EFI_STATUS GetWakeupTime ( OUT BOOLEAN OUT BOOLEAN OUT EFI_TIME ); *Enabled, *Pending, *Time Parameters Enabled Indicates if the alarm is currently enabled or disabled. Pending Indicates if the alarm signal is pending and requires acknowledgement. Time The current alarm setting. Type EFI_TIME is defined in Section 3.6.1.
PAGE 108
Extensible Firmware Interface Specification 3.6.4 SetWakeupTime() Summary Sets the system wakeup alarm clock time. Prototype EFI_STATUS SetWakeupTime ( IN BOOLEAN IN EFI_TIME ); Enable, *Time OPTIONAL Parameters Enable Enable or disable the wakeup alarm. Time If Enable is TRUE, the time to set the wakeup alarm for. Type EFI_TIME is defined in Section 3.6.1. If Enable is FALSE, then this parameter is optional, and may be NULL.
PAGE 109
Services 3.7 Virtual Memory Services This section contains function definitions for the virtual memory support that may be optionally used by an operating system at runtime. If an operating system chooses to make EFI runtime service calls in a virtual addressing mode instead of the flat physical mode, then the operating system must use the services in this section to switch the EFI runtime services from flat physical addressing to virtual addressing.
PAGE 110
Extensible Firmware Interface Specification 3.7.1 SetVirtualAddressMap() Summary Changes the runtime addressing mode of EFI firmware from physical to virtual. Prototype EFI_STATUS SetVirtualAddressMap ( IN UINTN IN UINTN IN UINT32 IN EFI_MEMORY_DESCRIPTOR ); MemoryMapSize, DescriptorSize, DescriptorVersion, *VirtualMap Parameters MemoryMapSize The size in bytes of VirtualMap. DescriptorSize The size in bytes of an entry in the VirtualMap.
PAGE 111
Services A virtual address map may only be applied one time. Once the runtime system is in virtual mode, calls to this function return EFI_UNSUPPORTED. Status Codes Returned EFI_SUCCESS The virtual address map has been applied. EFI_UNSUPPORTED EFI firmware is not at runtime, or the EFI firmware is already in virtual address mapped mode. EFI_INVALID_PARAMETER DescriptorSize or DescriptorVersion is invalid.
PAGE 112
Extensible Firmware Interface Specification 3.7.2 ConvertPointer() Summary Determines the new virtual address that is to be used on subsequent memory accesses. Prototype EFI_STATUS ConvertPointer ( IN UINTN IN VOID ); DebugDisposition, **Address Parameters DebugDisposition Supplies type information for the pointer being converted. See "Related Definitions". Address A pointer to a pointer that is to be fixed to be the value needed for the new virtual address mappings being applied.
PAGE 113
Services 3.8 Miscellaneous Services This section contains the remaining function definitions for services not defined elsewhere but which are required to complete the definition of the EFI environment. Table 3-13 lists the Miscellaneous Services Functions. Table 3-13. Miscellaneous Services Functions Name Type Description ResetSystem Runtime Resets the entire platform. SetWatchDogTimer Boot Resets and sets a watchdog timer used during boot services time. Stall Boot Stalls the processor.
PAGE 114
Extensible Firmware Interface Specification 3.8.1 ResetSystem() Summary Resets the entire platform. Prototype VOID ResetSystem ( IN EFI_RESET_TYPE IN EFI_STATUS IN UINTN IN CHAR16 ); ResetType, ResetStatus, DataSize, *ResetData OPTIONAL Parameters ResetType The type of reset to perform. Type EFI_RESET_TYPE is defined in “Related Definitions”. ResetStatus The status code for the reset. If the system reset is part of a normal operation, the status code would be EFI_SUCCESS.
PAGE 115
Services Description The ResetSystem()function resets the entire platform, including all processors and devices, and reboots the system. Calling this interface with ResetType of EfiResetCold causes a system-wide reset. This sets all circuitry within the system to its initial state. This type of reset is asynchronous to system operation and operates without regard to cycle boundaries. EfiResetCold is tantamount to a system power cycle.
PAGE 116
Extensible Firmware Interface Specification 3.8.2 SetWatchdogTimer() Summary Sets the system’s watchdog timer. Prototype EFI_STATUS SetWatchdogTimer ( IN UINTN IN UINT64 IN UINTN IN CHAR16 ); Timeout, WatchdogCode, DataSize, *WatchdogData OPTIONAL Parameters Timeout The number of seconds to set the watchdog timer to. A value of zero disables the timer. WatchdogCode The numeric code to log on a watchdog timer timeout event. The firmware reserves codes 0x0000 to 0xFFFF.
PAGE 117
Services Status Codes Returned EFI_SUCCESS The timeout has been set. EFI_INVALID_PARAMETER The supplied WatchdogCode is invalid. EFI_UNSUPPORTED The system does not have a watchdog timer. EFI_DEVICE_ERROR The watch dog timer could not be programmed due to a hardware error. Version 1.
PAGE 118
Extensible Firmware Interface Specification 3.8.3 Stall() Summary Induces a fine-grained stall. Prototype EFI_STATUS Stall ( IN UINTN ) Microseconds Parameters Microseconds The number of microseconds to stall execution. Description The Stall() function stalls execution on the processor for at least the requested number of microseconds. Execution of the processor is not yielded for the duration of the stall.
PAGE 119
Services 3.8.4 GetNextMonotonicCount() Summary Returns a monotonically increasing count for the platform. Prototype EFI_STATUS GetNextMonotonicCount ( OUT UINT64 ); *Count Parameters Count Pointer to returned value. Description The GetNextMonotonicCount() function returns a 64 bit value that is numerically larger then the last time the function was called. The platform’s monotonic counter is comprised of two parts: the high 32 bits and the low 32 bits.
PAGE 120
Extensible Firmware Interface Specification 3.8.5 GetNextHighMonotonicCount() Summary Returns the next high 32 bits of the platform’s monotonic counter. Prototype EFI_STATUS GetNextHighMonotonicCount ( OUT UINT32 *HighCount ); Parameters HighCount Pointer to returned value. Description The GetNextHighMonotonicCount() function returns the next high 32 bits of the platform’s monotonic counter. The platform’s monotonic counter is comprised of two 32 bit quantities: the high 32 bits and the low 32 bits.
PAGE 121
Services 3.8.6 InstallConfigurationTable() Summary Adds, updates, or removes a configuration table entry from the EFI System Table. Prototype EFI_STATUS InstallConfigurationTable ( IN EFI_GUID IN VOID ); *Guid, *Table Parameters Guid A pointer to the GUID for the entry to add, update, or remove. Table A pointer to the configuration table for the entry to add, update, or remove. May be NULL.
PAGE 122
Extensible Firmware Interface Specification If an add, modify, or remove operation is completed, then EFI_SUCCESS is returned. Note: If there is not enough memory to perform an add operation, then EFI_OUT_OF_RESOURCES is returned. Status Codes Returned 104 EFI_SUCCESS The (Guid, Table) pair was added, updated, or removed. EFI_INVALID_PARAMETER Guid is not valid. EFI_NOT_FOUND An attempt was made to delete a non-existent entry.
PAGE 123
4 EFI Image This chapter defines EFI images, a class of files that contain executable code. We begin by describing the EFI_LOADED_IMAGE protocol, and then discuss EFI image headers, applications, OS loaders, and drivers. 4.1 LOADED_IMAGE Protocol This section provides a detailed description of the EFI_LOADED_IMAGE protocol. Summary Can be used on any image handle to obtain information about the loaded image.
PAGE 124
Extensible Firmware Interface Specification Protocol Interface Structure typedef struct { UINT32 EFI_HANDLE EFI_SYSTEM_TABLE Revision; ParentHandle; *SystemTable; // Source location of the image EFI_HANDLE DeviceHandle; EFI_DEVICE_PATH *FilePath; VOID *Reserved; // Image’s load options UINT32 VOID LoadOptionsSize; *LoadOptions; // Location where image was loaded VOID *ImageBase; UINT64 ImageSize; EFI_MEMORY_TYPE ImageCodeType; EFI_MEMORY_TYPE ImageDataType; Unload; EFI_IMAGE_UNLOAD } EFI_LOADED_IMAGE;
PAGE 125
EFI Image LoadOptions A pointer to the image’s binary load options. ImageBase The base address at which the image was loaded. ImageSize The size in bytes of the loaded image. ImageCodeType The memory type that the code sections were loaded as. Type EFI_MEMORY_TYPE is defined in Chapter 3. ImageDataType The memory type that the data sections were loaded as. Type EFI_MEMORY_TYPE is defined in Chapter 3. Unload Function that unloads the image. See Section 4.1.1.
PAGE 126
Extensible Firmware Interface Specification 4.1.1 LOADED_IMAGE.Unload() Summary Unloads an image from memory. Prototype typedef EFI_STATUS (EFIAPI *EFI_UNLOAD_IMAGE) ( IN EFI_HANDLE ImageHandle, ); Parameters ImageHandle The handle to the image to unload. Type EFI_HANDLE is defined in Chapter 3. Description The Unload() function unloads an image from memory if ImageHandle is valid. Status Codes Returned 108 EFI_SUCCESS The image was unloaded. EFI_INVALID_PARAMETER The ImageHandle was not valid.
PAGE 127
EFI Image 4.2 EFI Image Header 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.
PAGE 128
Extensible Firmware Interface Specification 4.3 EFI Applications Applications are loaded by the boot manager in the EFI firmware, or by other 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.
PAGE 129
EFI Image When the boot manager loads a driver, the image handle may be used to locate the “load options” for the driver. The load options are those options that were stored in the LoadOptions field of the EFI_LOADED_IMAGE information for the driver. 4.5.1 EFI Image Handoff State Control is transferred to a loaded image at the AddressOfEntryPoint reference according to the normal indirect calling conventions for the image’s Machine type. The entry point is a function of type EFI_IMAGE_ENTRY_POINT.
PAGE 130
Extensible Firmware Interface Specification // // EFI System Table // #define EFI_SYSTEM_TABLE_SIGNATURE #define EFI_SYSTEM_TABLE_REVISION typedef struct _EFI_SYSTEM_TABLE { EFI_TABLE_HEADER 0x5453595320494249 (1<<16) | (99) Hdr; CHAR16 UINT32 *FirmwareVendor; FirmwareRevision; EFI_HANDLE SIMPLE_INPUT_INTERFACE ConsoleInHandle; *ConIn; EFI_HANDLE SIMPLE_TEXT_OUTPUT_INTERFACE ConsoleOutHandle; *ConOut; EFI_HANDLE SIMPLE_TEXT_OUTPUT_INTERFACE StandardErrorHandle; *StdErr; EFI_RUNTIME_SERVICES EFI_
PAGE 131
EFI Image typedef struct_EFI_CONFIGURATION_TABLE { EFI_GUID VendorGuid; VOID *VendorTable; } EFI_CONFIGURATION_TABLE; The EFI system table contains pointers to the runtime and boot services tables. The definitions for these tables are 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 Chapter 3. The GetTime() function is shown as an example.
PAGE 132
Extensible Firmware Interface Specification EFI_GET_VARIABLE EFI_GET_NEXT_VARIABLE_NAME EFI_SET_VARIABLE GetVariable; GetNextVariableName; SetVariable; // // Miscellaneous Services // EFI_GET_NEXT_HIGH_MONO_COUNT EFI_RESET_SYSTEM GetNextHighMonotonicCount; ResetSystem; } EFI_RUNTIME_SERVICES; // // EFI Boot Services Table // #define EFI_BOOT_SERVICES_SIGNATURE #define EFI_BOOT_SERVICES_REVISION 0x56524553544f4f42 (1<<16) | (99) typedef struct _EFI_BOOT_SERVICES { EFI_TABLE_HEADER Hdr; // // Task P
PAGE 133
EFI Image EFI_INSTALL_PROTOCOL_INTERFACE EFI_REINSTALL_PROTOCOL_INTERFACE EFI_UNINSTALL_PROTOCOL_INTERFACE EFI_HANDLE_PROTOCOL EFI_HANDLE_PROTOCOL EFI_REGISTER_PROTOCOL_NOTIFY EFI_LOCATE_HANDLE EFI_LOCATE_DEVICE_PATH EFI_INSTALL_CONFIGURATION_TABLE InstallProtocolInterface; ReinstallProtocolInterface; UninstallProtocolInterface; HandleProtocol; PCHandleProtocol; RegisterProtocolNotify; LocateHandle; LocateDevicePath; InstallConfigurationTable; // // Image Services // EFI_IMAGE_LOAD EFI_IMAGE_START EFI_EX
PAGE 134
Extensible Firmware Interface Specification 4.5.1.2 Handoff State, Itanium-based Operating Systems EFI uses the standard P64 C calling conventions that are defined for Itanium-based operating systems. Figure 4-2 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.
PAGE 135
5 Device Path Protocol This chapter contains the definition of the device path protocol and the information needed to construct and manage device paths in the EFI environment. A device path is constructed and used by the firmware to convey the location of important devices, such as the boot device and console, consistent with the software-visible topology of the system. 5.1 Device Path Overview A Device Path is used to define the programmatic path to a device.
PAGE 136
Extensible Firmware Interface Specification 5.2 EFI_DEVICE_PATH Protocol This section provides a detailed description of the EFI_DEVICE_PATH protocol. Summary Can be used on any device handle to obtain generic path/location information concerning the physical device or logical device. If the handle does not logically map to a physical device, the handle may not necessarily support the device path protocol.
PAGE 137
Device Path Protocol 5.3 Device Path Nodes There are six major types of Device Path nodes: • Hardware Device Path. This Device Path defines how a device is attached to the resource domain of a system, where resource domain is simply the shared memory, memory mapped I/O, and I/O space of the system. • ACPI Device Path. This Device Path is used to describe devices whose enumeration is not described in an industry-standard fashion.
PAGE 138
Extensible Firmware Interface Specification A Device Path is a series of generic Device Path nodes. The first Device Path node starts at byte offset zero of the Device Path. The next Device Path node starts at the end of the previous Device Path node. Therefore all nodes are byte packed data structures that may appear on any byte boundary. All code references to device path notes must assume all fields are UNALIGNED.
PAGE 139
Device Path Protocol 5.3.2.1 PCI Device Path The Device Path for PCI defines the path to the PCI configuration space address for a PCI device. There is one PCI Device Path entry for each device and function number that defines the path from the root PCI bus to the device. Because the PCI bus number of a device may potentially change, a flat encoding of single PCI Device Path entry cannot be used.
PAGE 140
Extensible Firmware Interface Specification 5.3.2.3 Memory Mapped Device Path Table 5-5. Memory Mapped Device Path Mnemonic Byte Offset Byte Length Description Type 0 1 Type 1 – Hardware Device Path Sub-Type 1 1 Sub-Type 3 – Memory Mapped Length 2 2 Length of this structure in bytes. Length is 24 bytes. Memory Type 4 4 EFI_MEMORY_TYPE (See Chapter 3.) Start Address 8 8 Starting Memory Address End Address 16 8 Ending Memory Address 5.3.2.
PAGE 141
Device Path Protocol 5.3.3 ACPI Device Path This Device Path contains ACPI Device IDs that represent a device’s Plug and Play Hardware ID and its corresponding unique persistent ID. The ACPI IDs are stored in the ACPI _HID and _UID device identification objects that are associated with a device. The ACPI Device Path contains values that must match exactly the ACPI name space that is provided by the platform firmware to the operating system.
PAGE 142
Extensible Firmware Interface Specification 5.3.4.1 ATAPI Device Path Table 5-9. ATAPI Device Path Mnemonic Byte Offset Byte Length Description Type 0 1 Type 3 – Messaging Device Path Sub-Type 1 1 Sub-Type 1 – ATAPI Length 2 2 Length of this structure in bytes. Length is 8 bytes. PrimarySecondary 4 1 Set to zero for primary or one for secondary SlaveMaster 5 1 Set to zero for master or one for slave mode Logical Unit Number 6 2 Logical Unit Number 5.3.4.
PAGE 143
Device Path Protocol 5.3.4.4 1394 Device Path Table 5-12. 1394 Device Path Mnemonic Byte Offset Byte Length Description Type 0 1 Type 3 – Messaging Device Path Sub-Type 1 1 Sub-Type 4 – 1394 Length 2 2 Length of this structure in bytes. Length is 16 bytes. Reserved 4 4 Reserved 8 8 1394 Global Unique ID (GUID) 1 GUID 1 1 The usage of the term GUID is per the 1394 specification. This is not the same as the EFI_GUID type defined in the EFI Specification. 5.3.4.
PAGE 144
Extensible Firmware Interface Specification 5.3.4.6 USB Class Device Path Table 5-14. USB Class Device Path Mnemonic Byte Offset Byte Length Description Type 0 1 Type 3 - Messaging Device Path Sub-Type 1 1 Sub-Type 15 - USB Class Length 2 2 Length of this structure in bytes. Length is 11 bytes. Vendor ID 4 2 Vendor ID assigned by USB-IF. A value of 0xFFFF will match any Vendor ID. Product ID 6 2 Product ID assigned by USB-IF. A value of 0xFFFF will match any Product ID.
PAGE 145
Device Path Protocol 5.3.4.9 IPv4 Device Path Table 5-17. IPv4 Device Path Mnemonic Byte Offset Byte Length Description Type 0 1 Type 3 – Messaging Device Path Sub-Type 1 1 Sub-Type 12 – IPv4 Length 2 2 Length of this structure in bytes. Length is 19 bytes. Local IP Address 4 4 The local IPv4 address Remote IP Address 8 4 The remote IPv4 address Local Port 12 2 The local port number Remote Port 14 2 The remote port number Protocol 16 2 The network protocol(i.e. UDP, TCP).
PAGE 146
Extensible Firmware Interface Specification 5.3.4.11 InfiniBand† Device Path † Table 5-19.
PAGE 147
Device Path Protocol 5.3.4.13 Vendor-Defined Messaging Device Path Table 5-21. Vendor-Defined Messaging Device Path Mnemonic Byte Offset Byte Length Description Type 0 1 Type 3 – Messaging Device Path Sub-Type 1 1 Sub-Type 10 – Vendor Length 2 2 Length of this structure in bytes. Length is 20 + n bytes.
PAGE 148
Extensible Firmware Interface Specification Table 5-22. Hard Drive Media Device Path Mnemonic Byte Offset Byte Length Description Type 0 1 Type 4 – Media Device Path Sub-Type 1 1 Sub-Type 1 – Hard Drive Length 2 2 Length of this structure in bytes. Length is 42 bytes. Partition Number 4 4 Partition Number of the hard drive. Partition numbers start at one. Partition number zero represents the entire device.
PAGE 149
Device Path Protocol 5.3.5.2 CD-ROM Media Device Path The CD-ROM Media Device Path is used to define a system partition that exists on a CD-ROM. The CD-ROM is assumed to contain an ISO-9660 file system and follow the CD-ROM “El Torito” format. The Boot Entry number from the Boot Catalog is how the “El Torito” specification defines the existence of bootable entities on a CD-ROM. In EFI the bootable entity is an EFI System Partition that is pointed to by the Boot Entry. Table 5-23.
PAGE 150
Extensible Firmware Interface Specification 5.3.5.4 File Path Media Device Path Table 5-25. File Path Media Device Path Mnemonic Byte Offset Byte Length Description Type 0 1 Type 4 – Media Device Path. Sub-Type 1 1 Sub-Type 4 – File Path. Length 2 2 Length of this structure in bytes. Length is 4 + n bytes. Path Name 4 n Unicode Path string including directory and file names. The length of this string n can be determined by subtracting 4 from the Length entry.
PAGE 151
Device Path Protocol 5.3.6 BIOS Boot Specification Device Path This Device Path is used to describe the booting of non-EFI-aware operating systems. This Device Path is based on the IPL and BCV table entry data structures defined in Appendix A of the BIOS Boot Specification. The BIOS Boot Specification Device Path defines a complete Device Path and is not used with other Device Path entries. This Device Path is only needed to enable platform firmware to select a legacy non-EFI OS as a boot option.
PAGE 152
Extensible Firmware Interface Specification Device Path structure in the stream. Any future additions to the Device Path structure types will always start with the current standard header. The size of a Device Path can be determined by traversing the generic Device Path structures in each header and adding up the total size of the Device Path. This size will include the four bytes of the End of Device Path structure. Multiple hardware devices may be pointed to by a single Device Path.
PAGE 153
Device Path Protocol 5.4.3 Rules with ACPI _ADR If a device in the ACPI name space can be completely described by a _ADR object then it will map to an EFI ACPI, Hardware, or Message Device Path structure. A _ADR method implies a bus with a standard enumeration algorithm. If the ACPI device has a _ADR and a _CRS method, then it should also have a _HID method and follow the rules for using _HID. The following table relates the ACPI _ADR bus definition to the EFI Device Path: Table 5-29.
PAGE 154
Extensible Firmware Interface Specification 5.4.5 Media Device Path Rules The Media Device Path is used to define the location of information on a medium. Hard Drives are subdivided into partitions by the MBR and a Media Device Path is used to define which partition is being used. A CD-ROM has boot partitions that are defined by the “El Torito” specification, and the Media Device Path is used to point to these partitions. A BLOCK_IO protocol is produced for both raw devices and partitions on devices.
PAGE 155
6 Device I/O Protocol This chapter defines the Device I/O protocol. This protocol is used by code, typically drivers, running in the EFI boot services environment to access memory and I/O. In particular, functions for managing PCI buses are defined here although other bus types may be supported in a similar fashion as extensions to this specification. 6.1 Device I/O Overview The interfaces provided in the DEVICE_IO protocol are for performing basic operations to memory, I/O, and PCI configuration space.
PAGE 156
Extensible Firmware Interface Specification 6.2 DEVICE_IO Protocol Summary Provides the basic Memory, I/O, and PCI interfaces that are used to abstract accesses to devices.
PAGE 157
Device I/O Protocol Description The DEVICE_IO protocol provides the basic Memory, I/O, and PCI interfaces that are used to abstract accesses to devices. A driver that controls a physical device obtains the proper DEVICE_IO protocol interface by checking for the supported protocol on the programmatic parent(s) for the device. This is easily done via the LocateDevicePath() function.
PAGE 158
Extensible Firmware Interface Specification Related Definitions //******************************************************* // EFI_IO_WIDTH //******************************************************* typedef enum { IO_UINT8 = IO_UINT16 = IO_UINT32 = IO_UINT64 = } EFI_IO_WIDTH; 0, 1, 2, 3 //******************************************************* // EFI_DEVICE_IO //******************************************************* typedef EFI_STATUS (EFIAPI *EFI_DEVICE_IO) ( IN struct _EFI_DEVICE_IO_INTERFACE IN EFI_IO_W
PAGE 159
Device I/O Protocol 6.2.1 DEVICE_IO.Mem(), .Io(), and .Pci() Summary Enable a driver to access device registers in the appropriate memory or I/O space. Prototype typedef EFI_STATUS (EFIAPI *EFI_DEVICE_IO) ( IN struct EFI_DEVICE_IO_INTERFACE IN EFI_IO_WIDTH IN UINT64 IN UINTN IN OUT VOID ); *This, Width, Address, Count, *Buffer Parameters This A pointer to the EFI_DEVICE_IO_INTERFACE instance. Type EFI_DEVICE_IO_INTERFACE is defined in Section 6.2. Width Signifies the width of the I/O operations.
PAGE 160
Extensible Firmware Interface Specification Table 6-1. PCI Address Mnemonic Byte Offset Byte Length Description Register 0 1 The register number on the function. Function 1 1 The function on the device. Device 2 1 The device on the bus. Bus 3 1 The bus. Segment 4 1 The segment number. Reserved 5 3 Must be zero. Status Codes Returned 142 EFI_SUCCESS The data was read from or written to the device. EFI_UNSUPPORTED The Address is not valid for this system.
PAGE 161
Device I/O Protocol 6.2.2 DEVICE_IO.PciDevicePath() Summary Provides an EFI Device Path for a PCI device with the given PCI configuration space address. Prototype typedef EFI_STATUS (EFIAPI *EFI_PCI_DEVICE_PATH) ( IN EFI_DEVICE_IO_INTERFACE IN UINT64 IN OUT EFI_DEVICE_PATH ); *This, PciAddress, **PciDevicePath Parameters This A pointer to the EFI_DEVICE_IO_INTERFACE. Type EFI_DEVICE_IO_INTERFACE is defined in Section 6.2.
PAGE 162
Extensible Firmware Interface Specification 6.2.3 DEVICE_IO.Map() Summary Provides the device specific addresses needed to access system memory. Prototype typedef EFI_STATUS (EFIAPI *EFI_IO_MAP) ( IN EFI_DEVICE_IO_INTERFACE IN EFI_IO_OPERATION_TYPE IN EFI_PHYSICAL_ADDRESS IN OUT UINTN OUT EFI_PHYSICAL_ADDRESS OUT VOID ); *This, Operation, *HostAddress, *NumberOfBytes, *DeviceAddress, **Mapping Parameters 144 This A pointer to the EFI_DEVICE_IO_INTERFACE instance.
PAGE 163
Device I/O Protocol Related Definitions //******************************************************* // EFI_IO_OPERATION_TYPE //******************************************************* typedef enum { EfiBusMasterRead, EfiBusMasterWrite, EfiBusMasterCommonBuffer } EFI_IO_OPERATION_TYPE; EfiBusMasterRead A read operation from system memory by a bus master. EfiBusMasterWrite A write operation to system memory by a bus master.
PAGE 164
Extensible Firmware Interface Specification 6.2.4 DEVICE_IO.Unmap() Summary Completes the Map() operation and releases any corresponding resources. Prototype typedef EFI_STATUS (EFIAPI *EFI_IO_UNMAP) ( IN EFI_DEVICE_IO_INTERFACE IN VOID ); *This, *Mapping Parameters This A pointer to the EFI_DEVICE_IO_INTERFACE instance. Type EFI_DEVICE_IO_INTERFACE is defined in Section 6.2. Mapping The mapping value returned from Map().
PAGE 165
Device I/O Protocol 6.2.5 DEVICE_IO.AllocateBuffer() Summary Allocates pages that are suitable for an EFIBusMasterCommonBuffer mapping. Prototype typedef EFI_STATUS (EFIAPI *EFI_IO_ALLOCATE_BUFFER) ( IN EFI_DEVICE_IO_INTERFACE IN EFI_ALLOCATE_TYPE IN EFI_MEMORY_TYPE IN UINTN IN OUT EFI_PHYSICAL_ADDRESS ); *This, Type, MemoryType, Pages, *HostAddress Parameters This A pointer to the EFI_DEVICE_IO_INTERFACE. Type EFI_DEVICE_IO_INTERFACE is defined in Section 6.2. Type The type allocation to perform.
PAGE 166
Extensible Firmware Interface Specification Allocation requests of Type AllocateMaxAddress will allocate any available range of pages that satisfies the request that are below or equal to the value pointed to by HostAddress on input. On success, the value pointed to by HostAddress contains the base of the range actually allocated. If there are not enough consecutive available pages below the requested address, an error is returned.
PAGE 167
Device I/O Protocol 6.2.6 DEVICE_IO.Flush() Summary Flushes any posted write data to the device. Prototype typedef EFI_STATUS (EFIAPI *EFI_IO_FLUSH) ( IN EFI_DEVICE_IO_INTERFACE ); *This Parameters This A pointer to the EFI_DEVICE_IO_INTERFACE instance. Type EFI_DEVICE_IO_INTERFACE is defined in Section 6.2. Description The Flush() function flushes any posted write data to the device. Status Codes Returned EFI_SUCCESS The buffers were flushed.
PAGE 168
Extensible Firmware Interface Specification 6.2.7 DEVICE_IO.FreeBuffer() Summary Frees pages that were allocated with AllocateBuffer(). Prototype typedef EFI_STATUS (EFIAPI *EFI_IO_FREE_BUFFER) ( IN EFI_DEVICE_IO_INTERFACE IN UINTN IN EFI_PHYSICAL_ADDRESS ); *This, Pages, HostAddress Parameters This A pointer to the EFI_DEVICE_IO_INTERFACE. Type EFI_DEVICE_IO_INTERFACE is defined in Section 6.2. Pages The number of pages to free. HostAddress The base address of the range to free.
PAGE 169
7 Console I/O Protocol This chapter defines the Console I/O protocol. This protocol is used to handle input and output of text-based information intended for the system user during the operation of code in the EFI boot services environment. Also included here are the definitions of three console devices: one for input and one each for normal output and errors. These interfaces are specified by function call definitions to allow maximum flexibility in implementation.
PAGE 170
Extensible Firmware Interface Specification 7.2 ConsoleIn Definition The SIMPLE_INPUT protocol defines an input stream that contains Unicode characters and required EFI scan codes. Only the control characters defined in Table 7-1 have meaning in the Unicode input or output streams. The control characters are defined to be characters U+0000 through U+001F. The input stream does not support any software flow control. Table 7-1.
PAGE 171
Console I/O Protocol Table 7-2. EFI Scan Codes for SIMPLE_INPUT_INTERFACE (continued) EFI Scan Code Description 0x0b Function 1. 0x0c Function 2. 0x0d Function 3. 0x0e Function 4. 0x0f Function 5. 0x10 Function 6. 0x11 Function 7. 0x12 Function 8. 0x13 Function 9. 0x14 Function 10. 0x17 Escape. Version 1.
PAGE 172
Extensible Firmware Interface Specification 7.3 SIMPLE_INPUT Protocol Summary This protocol is used to obtain input from the ConsoleIn device. GUID #define SIMPLE_INPUT_PROTOCOL \ { 387477c1-69c7-11d2-8e39-00a0c969723b } Protocol Interface Structure typedef struct _SIMPLE_INPUT_INTERFACE { EFI_INPUT_RESET Reset; EFI_INPUT_READ_KEY ReadKeyStroke; EFI_EVENT WaitForKey; } SIMPLE_INPUT_INTERFACE; Parameters Reset Reset the ConsoleIn device. See Section 7.3.1.
PAGE 173
Console I/O Protocol 7.3.1 SIMPLE_INPUT.Reset() Summary Resets the input device hardware. Prototype EFI_STATUS (EFIAPI *EFI_INPUT_RESET) ( IN SIMPLE_INPUT_INTERFACE IN BOOLEAN ); *This, ExtendedVerification Parameters A pointer to the SIMPLE_INPUT_INTERFACE instance. Type SIMPLE_INPUT_INTERFACE is defined in Section 7.3 This ExtendedVerification Indicates that the driver may perform a more exhaustive verification operation of the device during reset.
PAGE 174
Extensible Firmware Interface Specification 7.3.2 SIMPLE_INPUT.ReadKeyStroke Summary Reads the next keystroke from the input device. Prototype EFI_STATUS (EFIAPI *EFI_INPUT_READ_KEY) ( IN SIMPLE_INPUT_INTERFACE OUT EFI_INPUT_KEY ); *This, *Key Parameters This A pointer to the SIMPLE_INPUT_INTERFACE instance. Type SIMPLE_INPUT_INTERFACE is defined in Section 7.3. Key A pointer to a buffer that is filled in with the keystroke information for the key that was pressed.
PAGE 175
Console I/O Protocol 7.4 ConsoleOut or StandardError The SIMPLE_TEXT_OUTPUT protocol must implement the same Unicode code pages as the SIMPLE_INPUT protocol. The protocol must also support the Unicode control characters defined in Table 7-1. The SIMPLE_TEXT_OUTPUT protocol supports special manipulation of the screen by programmatic methods and therefore does not support the EFI scan codes defined in Table 7-2. 7.
PAGE 176
Extensible Firmware Interface Specification SetAttribute Sets the foreground and background color of the text that is output. See Section 7.5.6. ClearScreen Clears the screen with the currently set background color. See Section 7.5.7. SetCursorPosition Sets the current cursor position. See Section 7.5.8. EnableCursor Turns the visibility of the cursor on/off. See Section 7.5.9. Mode Pointer to SIMPLE_TEXT_OUTPUT_MODE data. Type SIMPLE_TEXT_OUTPUT_MODE is defined in “Related Definitions”.
PAGE 177
Console I/O Protocol Description The SIMPLE_TEXT_OUTPUT protocol is used to control text-based output devices. It is the minimum required protocol for any handle supplied as the ConsoleOut or StandardError device. In addition, the minimum supported text mode of such devices is at least 80 x 25 characters. A video device that only supports graphics mode is required to emulate text mode functionality.
PAGE 178
Extensible Firmware Interface Specification 7.5.1 SIMPLE_TEXT_OUTPUT.Reset() Summary Resets the text output device hardware. Prototype EFI_STATUS (EFIAPI *EFI_TEXT_RESET) ( IN SIMPLE_TEXT_OUTPUT_INTERFACE IN BOOLEAN ); *This, ExtendedVerification Parameters This A pointer to the SIMPLE_TEXT_OUTPUT_INTERFACE instance. Type SIMPLE_TEXT_OUTPUT_INTERFACE is defined in Section 7.5.
PAGE 179
Console I/O Protocol 7.5.2 SIMPLE_TEXT_OUTPUT.OutputString() Summary Writes a Unicode string to the output device. Prototype EFI_STATUS (EFIAPI *EFI_TEXT_STRING) ( IN SIMPLE_TEXT_OUTPUT_INTERFACE IN CHAR16 ); *This, *String Parameters This A pointer to the SIMPLE_TEXT_OUTPUT_INTERFACE instance. Type SIMPLE_TEXT_OUTPUT_INTERFACE is defined in Section 7.5. String The Null-terminated Unicode string to be displayed on the output device(s).
PAGE 180
Extensible Firmware Interface Specification #define BOXDRAW_DOWN_LEFT_DOUBLE #define BOXDRAW_DOWN_DOUBLE_LEFT #define BOXDRAW_DOUBLE_DOWN_LEFT 0x2555 0x2556 0x2557 #define BOXDRAW_UP_RIGHT_DOUBLE #define BOXDRAW_UP_DOUBLE_RIGHT #define BOXDRAW_DOUBLE_UP_RIGHT 0x2558 0x2559 0x255a #define BOXDRAW_UP_LEFT_DOUBLE #define BOXDRAW_UP_DOUBLE_LEFT #define BOXDRAW_DOUBLE_UP_LEFT 0x255b 0x255c 0x255d #define BOXDRAW_VERTICAL_RIGHT_DOUBLE #define BOXDRAW_VERTICAL_DOUBLE_RIGHT #define BOXDRAW_DOUBLE_VERTICAL_RI
PAGE 181
Console I/O Protocol //******************************************************* // EFI Required Arrow shapes //******************************************************* #define ARROW_UP #define ARROW_DOWN 0x2191 0x2193 Description The OutputString() function writes a Unicode string to the output device. This is the most basic output mechanism on an output device.
PAGE 182
Extensible Firmware Interface Specification 7.5.3 SIMPLE_TEXT_OUTPUT.TestString() Summary Verifies that all characters in a Unicode string can be output to the target device. Prototype EFI_STATUS (EFIAPI *EFI_TEXT_TEST_STRING) ( IN SIMPLE_TEXT_OUTPUT_INTERFACE IN CHAR16 ); *This, *String Parameters This A pointer to the SIMPLE_TEXT_OUTPUT_INTERFACE instance. Type SIMPLE_TEXT_OUTPUT_INTERFACE is defined in Section 7.5.
PAGE 183
Console I/O Protocol 7.5.4 SIMPLE_TEXT_OUTPUT.QueryMode() Summary Returns information for an available text mode that the output device(s) supports. Prototype EFI_STATUS (EFIAPI *EFI_TEXT_QUERY_MODE) ( IN SIMPLE_TEXT_OUTPUT_INTERFACE IN UINTN OUT UINTN OUT UINTN ); *This, ModeNumber, *Columns, *Rows Parameters This A pointer to the SIMPLE_TEXT_OUTPUT_INTERFACE instance. Type SIMPLE_TEXT_OUTPUT_INTERFACE is defined in Section 7.5. ModeNumber The mode number to return information on.
PAGE 184
Extensible Firmware Interface Specification 7.5.5 SIMPLE_TEXT_OUTPUT.SetMode() Summary Sets the output device(s) to a specified mode. Prototype EFI_STATUS (* EFIAPI EFI_TEXT_SET_MODE) ( IN SIMPLE_TEXT_OUTPUT_INTERFACE IN UINTN ); *This, ModeNumber Parameters This A pointer to the SIMPLE_TEXT_OUTPUT_INTERFACE instance. Type SIMPLE_TEXT_OUTPUT_INTERFACE is defined in Section 7.5. ModeNumber The text mode to set. Description The SetMode() function sets the output device(s) to the requested mode.
PAGE 185
Console I/O Protocol 7.5.6 SIMPLE_TEXT_OUTPUT.SetAttribute() Summary Sets the background and foreground colors for the OutputString() and ClearScreen() functions. Prototype EFI_STATUS (EFIAPI *EFI_TEXT_SET_ATTRIBUTE) ( IN SIMPLE_TEXT_OUTPUT_INTERFACE IN UINTN ); *This, Attribute Parameters This A pointer to the SIMPLE_TEXT_OUTPUT_INTERFACE instance. Type SIMPLE_TEXT_OUTPUT_INTERFACE is defined in Section 7.5. Attribute The attribute to set. Bits 0..3 are the foreground color, and bits 4..
PAGE 186
Extensible Firmware Interface Specification #define #define #define #define #define #define #define #define EFI_BACKGROUND_BLACK EFI_BACKGROUND_BLUE EFI_BACKGROUND_GREEN EFI_BACKGROUND_CYAN EFI_BACKGROUND_RED EFI_BACKGROUND_MAGENTA EFI_BACKGROUND_BROWN EFI_BACKGROUND_LIGHTGRAY 0x00 0x10 0x20 0x30 0x40 0x50 0x60 0x70 #define EFI_TEXT_ATTR(foreground,background) ((foreground) | ((background) << 4)) \ Description The SetAttribute() function sets the background and foreground colors for the OutputString()
PAGE 187
Console I/O Protocol 7.5.7 SIMPLE_TEXT_OUTPUT.ClearScreen() Summary Clears the output device(s) display to the currently selected background color. Prototype EFI_STATUS (EFIAPI *EFI_TEXT_CLEAR_SCREEN) ( IN SIMPLE_TEXT_OUTPUT_INTERFACE ); *This Parameters This A pointer to the SIMPLE_TEXT_OUTPUT_INTERFACE instance. Type SIMPLE_TEXT_OUTPUT_INTERFACE is defined in Section 7.5. Description The ClearScreen() function clears the output device(s) display to the currently selected background color.
PAGE 188
Extensible Firmware Interface Specification 7.5.8 SIMPLE_TEXT_OUTPUT.SetCursorPosition() Summary Sets the current coordinates of the cursor position. Prototype EFI_STATUS (EFIAPI *EFI_TEXT_SET_CURSOR_POSITION) ( IN SIMPLE_TEXT_OUTPUT_INTERFACE *This, IN UINTN Column, IN UINTN Row ); Parameters This A pointer to the SIMPLE_TEXT_OUTPUT_INTERFACE instance. Type SIMPLE_TEXT_OUTPUT_INTERFACE is defined in Section 7.5. Column, Row The position to set the cursor to.
PAGE 189
Console I/O Protocol 7.5.9 SIMPLE_TEXT_OUTPUT.EnableCursor() Summary Makes the cursor visible or invisible. Prototype EFI_STATUS (EFIAPI *EFI_TEXT_ENABLE_CURSOR) ( IN SIMPLE_TEXT_OUTPUT_INTERFACE IN BOOLEAN ); *This, Visible Parameters This A pointer to the SIMPLE_TEXT_OUTPUT_INTERFACE instance. Type SIMPLE_TEXT_OUTPUT_INTERFACE is defined in Section 7.5. Visible If TRUE, the cursor is set to be visible. If FALSE, the cursor is set to be invisible.
PAGE 190
Extensible Firmware Interface Specification 172 12/12/00 Version 1.
PAGE 191
8 Block I/O Protocol This chapter defines the Block I/O protocol. This protocol is used to abstract mass storage devices to allow code running in the EFI boot services environment to access them without specific knowledge of the type of device or controller that manages the device. Functions are defined to read and write data at a block level from mass storage devices as well as to manage such devices in the EFI boot services environment. 8.
PAGE 192
Extensible Firmware Interface Specification Parameters Revision The revision to which the block IO interface adheres. All future revisions must be backwards compatible. If a future version is not back wards compatible it is not the same GUID. Media A pointer to the EFI_BLOCK_IO_MEDIA data for this device. Type EFI_BLOCK_IO_MEDIA is defined in “Related Definitions”. Reset Resets the block device hardware. See Section 8.1.1. ReadBlocks Reads the requested number of blocks from the device.
PAGE 193
Block I/O Protocol Related Definitions //******************************************************* // EFI_BLOCK_IO_MEDIA //******************************************************* typedef struct { UINT32 BOOLEAN BOOLEAN MediaId; RemovableMedia; MediaPresent; BOOLEAN BOOLEAN BOOLEAN LogicalPartition; ReadOnly; WriteCaching; UINT32 UINT32 BlockSize; IoAlign; EFI_LBA } EFI_BLOCK_IO_MEDIA; LastBlock; //******************************************************* // EFI_LBA //***********************************
PAGE 194
Extensible Firmware Interface Specification 8.1.1 EFI_BLOCK_IO.Reset() Summary Resets the block device hardware. Prototype EFI_STATUS (EFIAPI *EFI_BLOCK_RESET) ( IN EFI_BLOCK_IO IN BOOLEAN ); *This, ExtendedVerification Parameters This Indicates a pointer to the calling context. Type EFI_BLOCK_IO is defined in Section 8.1. ExtendedVerification Indicates that the driver may perform a more exhaustive verification operation of the device during reset.
PAGE 195
Block I/O Protocol 8.1.2 EFI_BLOCK_IO.ReadBlocks() Summary Reads the requested number of blocks from the device. Prototype EFI_STATUS (EFIAPI *EFI_BLOCK_READ) ( IN EFI_BLOCK_IO IN UINT32 IN EFI_LBA IN UINTN OUT VOID ); *This, MediaId, LBA, BufferSize, *Buffer Parameters This Indicates a pointer to the calling context. Type EFI_BLOCK_IO is defined in Section 8.1. MediaId The media id that the read request is for. LBA The starting logical block address to read from on the device.
PAGE 196
Extensible Firmware Interface Specification Status Codes Returned 178 EFI_SUCCESS The data was read correctly from the device. EFI_DEVICE_ERROR The device reported an error while attempting to perform the read operation. EFI_NO_MEDIA There is no media in the device. EFI_MEDIA_CHANGED The MediaId is not for the current media. EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the intrinsic block size of the device.
PAGE 197
Block I/O Protocol 8.1.3 EFI_BLOCK_IO.WriteBlocks() Summary Writes a specified number of blocks to the device. Prototype EFI_STATUS (EFIAPI *EFI_BLOCK_WRITE) ( IN EFI_BLOCK_IO IN UINT32 IN EFI_LBA IN UINTN IN VOID ); *This, MediaId, LBA, BufferSize, *Buffer Parameters This Indicates a pointer to the calling context. Type EFI_BLOCK_IO is defined in Section 8.1. MediaId The media id that the write request is for. LBA The starting logical block address to be written.
PAGE 198
Extensible Firmware Interface Specification Status Codes Returned 180 EFI_SUCCESS The data were written correctly to the device. EFI_WRITE_PROTECTED The device cannot be written to. EFI_NO_MEDIA There is no media in the device. EFI_MEDIA_CHANGED The MediaId is not for the current media. EFI_DEVICE_ERROR The device reported an error while attempting to perform the write operation. EFI_BAD_BUFFER_SIZE The BufferSize parameter is not a multiple of the intrinsic block size of the device.
PAGE 199
Block I/O Protocol 8.1.4 BLOCK_IO.FlushBlocks() Summary Flushes all modified data to a physical block device. Prototype EFI_STATUS (EFIAPI *EFI_BLOCK_FLUSH) ( IN EFI_BLOCK_IO ); *This Parameters This Indicates a pointer to the calling context. Type EFI_BLOCK_IO is defined in Section 8.1. Description The FlushBlocks() function flushes all modified data to the physical block device.
PAGE 200
Extensible Firmware Interface Specification 182 12/12/00 Version 1.
PAGE 201
9 Disk I/O Protocol This chapter defines the Disk I/O protocol. This protocol is used to abstract the block accesses of the Block I/O protocol to a more general offset-length protocol. The firmware is responsible for adding this protocol to any Block I/O interface that appears in the system that does not already have a Disk I/O protocol. File systems and other disk access code utilize the Disk I/O protocol. 9.1 DISK_IO Protocol Summary This protocol is used to abstract Block I/O interfaces.
PAGE 202
Extensible Firmware Interface Specification Description The EFI_DISK_IO protocol is used to control block I/O interfaces. The disk I/O functions allow I/O operations that need not be on the underlying device’s block boundaries or alignment requirements. This is done by copying the data to/from internal buffers as needed to provide the proper requests to the block I/O device. Outstanding write buffer data is flushed by using the Flush() function of the EFI_BLOCK_IO protocol on the device handle.
PAGE 203
Disk I/O Protocol 9.1.1 EFI_DISK_IO.ReadDisk() Summary Reads a specified number of bytes from a device. Prototype EFI_STATUS (EFIAPI *EFI_DISK_READ) ( IN EFI_DISK_IO IN UINT32 IN UINT64 IN UINTN OUT VOID ); *This, MediaId, Offset, BufferSize, *Buffer Parameters This Indicates a pointer to the calling context. Type EFI_DISK_IO is defined in Section 9.1. MediaId Id of the medium to be read. Offset The starting byte offset on the logical block I/O device to read from.
PAGE 204
Extensible Firmware Interface Specification 9.1.2 EFI_DISK_IO.WriteDisk() Summary Writes a specified number of bytes to a device. Prototype EFI_STATUS (EFIAPI *EFI_DISK_WRITE) ( IN EFI_DISK_IO IN UINT32 IN UINT64 IN UNITN IN VOID ); *This, MediaId, Offset, BufferSize, *Buffer Parameters This Indicates a pointer to the calling context. Type EFI_DISK_IO is defined in Section 9.1. MediaId Id of the medium to be written. Offset The starting byte offset on the logical block I/O device to write.
PAGE 205
10 File System Protocol This chapter defines the File System protocol. This protocol allows code running in the EFI boot services environment to obtain file based access to a device. The Simple File System protocol is used to open a device volume and return an EFI_FILE that provides interfaces to access files on a device volume. 10.1 Simple File System Protocol Summary Provides a minimal interface for file-type access to a device.
PAGE 206
Extensible Firmware Interface Specification Description The Simple File System protocol provides a minimal interface for file-type access to a device. This protocol is only supported on some devices. Devices that support the Simple File System protocol return an EFI_FILE_IO_INTERFACE. The only function of this interface is to open a handle to the root directory of the file system on the volume.
PAGE 207
File System Protocol 10.1.1 EFI_FILE_IO_INTERFACE.OpenVolume() Summary Opens the root directory on a volume. Prototype typedef EFI_STATUS (EFIAPI *EFI_VOLUME_OPEN) ( IN EFI_FILE_IO_INTERFACE OUT EFI_FILE ); *This, **Root Parameters This A pointer to the volume to open the root directory of. Type EFI_FILE_IO_INTERFACE is defined in Section 10.1. Root A pointer to the location to return the opened file handle for the root directory. Type EFI_FILE is defined in Section 10.2.
PAGE 208
Extensible Firmware Interface Specification 10.2 EFI_FILE Protocol Summary Provides file based access to supported file systems.
PAGE 209
File System Protocol Description The EFI_FILE provides file IO access to supported file systems. An EFI_FILE provides access to a file’s or directory’s contents, and is also a reference to a location in the directory tree of the file system in which the file resides. With any given file handle, other files may be opened relative to this file’s location, yielding new file handles. On requesting the file system protocol on a device, the caller gets the EFI_FILE_IO_INTERFACE to the volume.
PAGE 210
Extensible Firmware Interface Specification 10.2.1 EFI_FILE.Open() Summary Opens a new file relative to the source file’s location. Prototype EFI_STATUS (EFIAPI *EFI_FILE_OPEN) ( IN EFI_FILE OUT EFI_FILE IN CHAR16 IN UINT64 IN UINT64 ); *This, **NewHandle, *FileName, OpenMode, Attributes Parameters 192 This A pointer to the EFI_FILE instance that is the file handle to the source location. This would typically be an open handle to a directory. Type EFI_FILE is defined in Section 10.2.
PAGE 211
File System Protocol Related Definitions //******************************************************* // Open Modes //******************************************************* #define EFI_FILE_MODE_READ 0x0000000000000001 #define EFI_FILE_MODE_WRITE 0x0000000000000002 #define EFI_FILE_MODE_CREATE 0x8000000000000000 //******************************************************* // File Attributes //******************************************************* #define EFI_FILE_READ_ONLY 0x0000000000000001 #define EFI_FILE_H
PAGE 212
Extensible Firmware Interface Specification Status Codes Returned 194 EFI_SUCCESS The file was opened. EFI_NOT_FOUND The specified file could not be found on the device. EFI_NO_MEDIA The device has no medium. EFI_MEDIA_CHANGED The device has a different medium in it or the medium is no longer supported. EFI_DEVICE_ERROR The device reported an error. EFI_VOLUME_CORRUPTED The file system structures are corrupted.
PAGE 213
File System Protocol 10.2.2 EFI_FILE.Close() Summary Closes a specified file handle. Prototype EFI_STATUS (EFIAPI *EFI_FILE_CLOSE) ( IN EFI_FILE *This ); Parameters This A pointer to the EFI_FILE instance that is the file handle to close. Type EFI_FILE is defined in Section 10.2. Description The Close() function closes a specified file handle. All “dirty” cached file data is flushed to the device, and the file is closed. In all cases the handle is closed. Status Codes Returned EFI_SUCCESS Version 1.
PAGE 214
Extensible Firmware Interface Specification 10.2.3 EFI_FILE.Delete() Summary Closes and deletes a file. Prototype EFI_STATUS (EFIAPI *EFI_FILE_DELETE) ( IN EFI_FILE *This ); Parameters This A pointer to the EFI_FILE instance that is the handle to the file to delete. Type EFI_FILE is defined in Section 10.2. Description The Delete() function closes and deletes a file. In all cases the file handle is closed.
PAGE 215
File System Protocol 10.2.4 EFI_FILE.Read() Summary Reads data from a file. Prototype EFI_STATUS (EFIAPI *EFI_FILE_READ) ( IN EFI_FILE IN OUT UINTN OUT VOID ); *This, *BufferSize, *Buffer Parameters This A pointer to the EFI_FILE instance that is the file handle to read data from. Type EFI_FILE is defined in Section 10.2. BufferSize On input, the size of the Buffer. On output, the amount of data returned in Buffer. In both cases, the size is measured in bytes.
PAGE 216
Extensible Firmware Interface Specification 10.2.5 EFI_FILE.Write() Summary Writes data to a file. EFI_STATUS (EFIAPI *EFI_FILE_WRITE) ( IN EFI_FILE *This, IN OUT UINTN *BufferSize, IN VOID *Buffer ); Parameters This A pointer to the EFI_FILE instance that is the file handle to write data to. Type EFI_FILE is defined in Section 10.2. BufferSize On input, the size of the Buffer. On output, the amount of data actually written. In both cases, the size is measured in bytes.
PAGE 217
File System Protocol 10.2.6 EFI_FILE.SetPosition() Summary Sets a file’s current position. Prototype EFI_STATUS (EFIAPI *EFI_FILE_SET_POSITION) ( IN EFI_FILE *This, IN UINT64 Position ); Parameters This A pointer to the EFI_FILE instance that is the he file handle to set the requested position on. Type EFI_FILE is defined in Section 10.2. Position The byte position from the start of the file to set.
PAGE 218
Extensible Firmware Interface Specification 10.2.7 EFI_FILE.GetPosition() Summary Returns a file’s current position. Prototype EFI_STATUS (EFIAPI *EFI_GET_POSITION) ( IN EFI_FILE *This, OUT UINT64 *Position ); Parameters This A pointer to the EFI_FILE instance that is the file handle to get the current position on. Type EFI_FILE is defined in Section 10.2. Position The address to return the file’s current position value.
PAGE 219
File System Protocol 10.2.8 EFI_FILE.GetInfo() Summary Returns information about a file. Prototype EFI_STATUS (EFIAPI *EFI_FILE_GET_INFO) ( IN EFI_FILE *This, IN EFI_GUID *InformationType, IN OUT UINTN *BufferSize, OUT VOID *Buffer ); Parameters This A pointer to the EFI_FILE instance that is the file handle the requested information is for. Type EFI_FILE is defined in Section 10.2. InformationType The type identifier for the information being requested. Type EFI_GUID is defined in Chapter 3.
PAGE 220
Extensible Firmware Interface Specification 10.2.9 EFI_FILE.SetInfo() Summary Sets information about a file. Prototype EFI_STATUS (EFIAPI *EFI_FILE_SET_INFO) ( IN EFI_FILE *This, IN EFI_GUID *InformationType, IN UINTN BufferSize, OUT VOID *Buffer ); Parameters This A pointer to the EFI_FILE instance that is the file handle the information is for. Type EFI_FILE is defined in Section 10.2. InformationType The type identifier for the information being set. Type EFI_GUID is defined in Chapter 3.
PAGE 221
File System Protocol 10.2.10 EFI_FILE.Flush() Summary Flushes all modified data associated with a file to a device. Prototype EFI_STATUS (EFIAPI *EFI_FILE_FLUSH) ( IN EFI_FILE *This ); Parameters This A pointer to the EFI_FILE instance that is the file handle to flush. Type EFI_FILE is defined in Section 10.2. Description The Flush() function flushes all modified data associated with a file to a device. Status Codes Returned EFI_SUCCESS The data was flushed. EFI_NO_MEDIA The device has no medium.
PAGE 222
Extensible Firmware Interface Specification 10.2.11 EFI_FILE_INFO Summary Provides a GUID and a data structure that can be used with EFI_FILE.SetInfo() and EFI_FILE.GetInfo() to set or get generic file information.
PAGE 223
File System Protocol ModificationTime The time when the file’s contents were last modified. Attribute The attribute bits for the file. See “Related Definitions”. FileName The Null-terminated Unicode name of the file. Description The EFI_FILE_INFO data structure supports GetInfo() and SetInfo() requests. In the case of SetInfo()the following additional rules apply: • • • • On directories, the file size is determined by the contents of the directory and cannot be changed by setting FileSize.
PAGE 224
Extensible Firmware Interface Specification 10.2.12 EFI_FILE_SYSTEM_INFO Summary Provides a GUID and a data structure that can be used with EFI_FILE.GetInfo() to get information about the system volume, and EFI_FILE.SetInfo() to set the system volume’s volume label.
PAGE 225
File System Protocol 10.2.13 EFI_FILE_SYSTEM_VOLUME_LABEL Summary Provides a GUID and a data structure that can be used with EFI_FILE.GetInfo() or EFI_FILE.SetInfo()to get or set information about the system’s volume label. GUID #define EFI_FILE_SYSTEM_VOLUME_LABEL_ID \ { DB47D7D3-FE81-11d3-9A35-0090273FC14D } Related Definitions typedef struct { CHAR16 } EFI_FILE_SYSTEM_VOLUME_LABEL; VolumeLabel[]; Parameters VolumeLabel The Null-terminated string that is the volume’s label.
PAGE 226
Extensible Firmware Interface Specification 208 12/12/00 Version 1.
PAGE 227
11 Load File Protocol This chapter defines the Load File protocol. This protocol is designed to allow code running in the EFI boot services environment to find and load other modules of code. 11.1 LOAD_FILE Protocol Summary Is used to obtain files from arbitrary devices.
PAGE 228
Extensible Firmware Interface Specification 11.1.1 LOAD_FILE.LoadFile() Summary Causes the driver to load a specified file. Prototype EFI_STATUS (EFIAPI *EFI_LOAD_FILE) ( IN EFI_LOAD_FILE_INTERFACE IN EFI_DEVICE_PATH IN BOOLEAN IN OUT UINTN IN VOID ); *This, *FilePath, BootPolicy, *BufferSize, *Buffer OPTIONAL Parameters This Indicates a pointer to the calling context. Type EFI_LOAD_FILE_INTERFACE is defined in Section 11.1. FilePath The device specific path of the file to load.
PAGE 229
Load File Protocol If BootPolicy is FALSE the FilePath must match an exact file to be loaded. If no such file exists, EFI_NOT_FOUND is returned. If BootPolicy is FALSE, and an attempt is being made to perform a network boot through the PXE Base Code protocol, EFI_UNSUPPORTED is returned. If BootPolicy is TRUE the firmware’s boot manager is attempting to load an EFI image that is a boot selection. In this case, FilePath contains the file path value in the boot selection option.
PAGE 230
Extensible Firmware Interface Specification 212 12/12/00 Version 1.
PAGE 231
12 Serial I/O Protocol This chapter defines the Serial I/O protocol. This protocol is used to abstract byte stream devices. 12.1 SERIAL_IO Protocol Summary This protocol is used to communicate with any type of character-based I/O device.
PAGE 232
Extensible Firmware Interface Specification SetControl Set the control bits on a serial device. These include Request to Send and Data Terminal Ready. GetControl Read the status of the control bits on a serial device. These include Clear to Send, Data Set Ready, Ring Indicator, and Carrier Detect. Write Send a buffer of characters to a serial device. Read Receive a buffer of characters from a serial device. Mode Pointer to SERIAL_IO_MODE data.
PAGE 233
Serial I/O Protocol Parity If applicable, this is the EFI_PARITY_TYPE that is computed or checked as each character is transmitted or received. If the device does not support parity the value is the default parity value. StopBits If applicable, the EFI_STOP_BITS_TYPE number of stop bits per character. If the device does not support stop bits the value is the default stop bit value.
PAGE 234
Extensible Firmware Interface Specification The default attributes for all UART-style serial device interfaces are: 115,200 baud, a 1 byte receive FIFO, a 1,000,000 microsecond timeout per character, no parity, 8 data bits, and 1 stop bit. Flow control is the responsibility of the software that uses the protocol. Hardware flow control can be implemented through the use of the GetControl() and SetControl() functions (described below) to monitor and assert the flow control signals.
PAGE 235
Serial I/O Protocol 12.1.1 SERIAL_IO.Reset() Summary Resets the serial device. Prototype EFI_STATUS (EFIAPI *EFI_SERIAL_RESET) ( IN SERIAL_IO_INTERFACE ); *This Parameters A pointer to the SERIAL_IO_INTERFACE instance. Type SERIAL_IO_INTERFACE is defined in Section 12.1. This Description The Reset() function resets the hardware of a serial device. Status Codes Returned EFI_SUCCESS The serial device was reset. EFI_DEVICE_ERROR The serial device could not be reset. Version 1.
PAGE 236
Extensible Firmware Interface Specification 12.1.2 SERIAL_IO.SetAttributes() Summary Sets the baud rate, receive FIFO depth, transmit/receive time out, parity, data bits, and stop bits on a serial device. EFI_STATUS (EFIAPI *EFI_SERIAL_SET_ATTRIBUTES) ( IN SERIAL_IO_INTERFACE *This, IN UINT64 BaudRate, IN UINT32 ReceiveFifoDepth, IN UINT32 Timeout IN EFI_PARITY_TYPE Parity, IN UINT8 DataBits, IN EFI_STOP_BITS_TYPE StopBits ); Parameters 218 This A pointer to the SERIAL_IO_INTERFACE instance.
PAGE 237
Serial I/O Protocol Description The SetAttributes() function sets the baud rate, receive-FIFO depth, transmit/receive time out, parity, data bits, and stop bits on a serial device. The controller for a serial device is programmed with the specified attributes. If the Parity, DataBits, or StopBits values are not valid, then an error will be returned. If the specified BaudRate is below the minimum baud rate supported by the serial device, an error will be returned.
PAGE 238
Extensible Firmware Interface Specification 12.1.3 SERIAL_IO.SetControl() Summary Sets the control bits on a serial device. Prototype EFI_STATUS (EFIAPI *EFI_SERIAL_SET_CONTROL) ( IN SERIAL_IO_INTERFACE *This, IN UINT32 Control ); Parameters This A pointer to the SERIAL_IO_INTERFACE instance. Type SERIAL_IO_INTERFACE is defined in Section 12.1. Control Sets the bits of Control that are settable. See “Related Definitions”.
PAGE 239
Serial I/O Protocol Only the REQUEST_TO_SEND, DATA_TERMINAL_READY, HARDWARE_LOOPBACK_ENABLE, SOFTWARE_LOOPBACK_ENABLE, and HARDWARE_FLOW_CONTROL_ENABLE bits can be set with SetControl(). All the bits can be read with GetControl(). Status Codes Returned EFI_SUCCESS The new control bits were set on the serial device. EFI_UNSUPPORTED The serial device does not support this operation. EFI_DEVICE_ERROR The serial device is not functioning correctly. Version 1.
PAGE 240
Extensible Firmware Interface Specification 12.1.4 SERIAL_IO.GetControl() Summary Retrieves the status of the control bits on a serial device. Prototype EFI_STATUS (EFIAPI *EFI_SERIAL_GET_CONTROL) ( IN SERIAL_IO_INTERFACE *This, OUT UINT32 *Control ); Parameters This A pointer to the SERIAL_IO_INTERFACE instance. Type SERIAL_IO_INTERFACE is defined in Section 12.1. Control A pointer to return the current Control signals from the serial device.
PAGE 241
Serial I/O Protocol 12.1.5 SERIAL_IO.Write() Summary Writes data to a serial device. Prototype EFI_STATUS (EFIAPI *EFI_SERIAL_WRITE) ( IN SERIAL_IO_INTERFACE IN OUT UINTN IN VOID ); *This, *BufferSize, *Buffer Parameters This A pointer to the SERIAL_IO_INTERFACE instance. Type SERIAL_IO_INTERFACE is defined in Section 12.1. BufferSize On input, the size of the Buffer. On output, the amount of data actually written. Buffer The buffer of data to write.
PAGE 242
Extensible Firmware Interface Specification 12.1.6 SERIAL_IO.Read() Summary Reads data from a serial device. Prototype EFI_STATUS (EFIAPI *EFI_SERIAL_READ) ( IN SERIAL_IO_INTERFACE IN OUT UINTN OUT VOID ); *This, *BufferSize, *Buffer Parameters This A pointer to the SERIAL_IO_INTERFACE instance. Type SERIAL_IO_INTERFACE is defined in Section 12.1. BufferSize On input, the size of the Buffer. On output, the amount of data returned in Buffer. Buffer The buffer to return the data into.
PAGE 243
13 Unicode Collation Protocol This chapter defines the Unicode Collation protocol. This protocol is used to allow code running in the boot services environment to perform lexical comparison functions on Unicode strings for given languages. 13.1 UNICODE_COLLATION Protocol Summary Is used to perform case-insensitive comparisons of Unicode strings.
PAGE 244
Extensible Firmware Interface Specification StrUpr Converts all the Unicode characters in a Null-terminated Unicode string to upper case Unicode characters. See Section 13.1.4 . FatToStr Converts an 8.3 FAT file name using an OEM character set to a Null-terminated Unicode string. See Section 13.1.5. StrToFat Converts a Null-terminated Unicode string to legal characters in a FAT filename using an OEM character set. See Section 13.1.6.
PAGE 245
Unicode Collation Protocol 13.1.1 UNICODE_COLLATION.StriColl() Summary Performs a case-insensitive comparison of two Null-terminated Unicode strings. Prototype INTN (EFIAPI IN IN IN ); *EFI_UNICODE_COLLATION_STRICOLL) ( UNICODE_COLLATION_INTERFACE *This, CHAR16 *s1, CHAR16 *s2 Parameters This A pointer to the UNICODE_COLLATION instance. Type UNICODE_COLLATION_INTERFACE is defined in Section 13.1. s1 A pointer to a Null-terminated Unicode string. s2 A pointer to a Null-terminated Unicode string.
PAGE 246
Extensible Firmware Interface Specification 13.1.2 UNICODE_COLLATION.MetaiMatch() Summary Performs a case-insensitive comparison of a Null-terminated Unicode pattern string and a Nullterminated Unicode string. Prototype BOOLEAN (EFIAPI IN IN IN ); *EFI_UNICODE_COLLATION_STRICOLL) ( UNICODE_COLLATION_INTERFACE *This, CHAR16 *String, CHAR16 *Pattern Parameters This A pointer to the UNICODE_COLLATION_INTERFACE instance. Type UNICODE_COLLATION_INTERFACE is defined in Section 13.1.
PAGE 247
Unicode Collation Protocol Examples patterns (for English): *.FW Matches all strings that end in “.FW” or “.fw” or “.Fw” or “.fW”. [a-z] Match any letter in the alphabet. [!@#$%^&*()] Match any one of these symbols. z Match the character ‘z’ or ‘Z’. D?.* Match the character ‘D’ or ‘d’ followed by any character followed by a “.” followed by any string. Status Codes Returned TRUE Pattern was found in String. FALSE Pattern was not found in String. Version 1.
PAGE 248
Extensible Firmware Interface Specification 13.1.3 UNICODE_COLLATION.StrLwr() Summary Converts all the Unicode characters in a Null-terminated Unicode string to lower case Unicode characters. Prototype VOID (EFIAPI *EFI_UNICODE_COLLATION_STRLWR) ( IN UNICODE_COLLATION_INTERFACE *This, IN OUT CHAR16 *String ); Parameters This A pointer to the UNICODE_COLLATION_INTERFACE instance. Type UNICODE_COLLATION_INTERFACE is defined in Section 13.1. String A pointer to a Null-terminated Unicode string.
PAGE 249
Unicode Collation Protocol 13.1.4 UNICODE_COLLATION.StrUpr() Summary Converts all the Unicode characters in a Null-terminated Unicode string to upper case Unicode characters. Prototype VOID (EFIAPI *EFI_UNICODE_COLLATION_STRUPR) ( IN UNICODE_COLLATION_INTERFACE *This, IN OUT CHAR16 *String ); Parameters This A pointer to the UNICODE_COLLATION_INTERFACE instance. Type UNICODE_COLLATION_INTERFACE is defined in Section 13.1. String A pointer to a Null-terminated Unicode string.
PAGE 250
Extensible Firmware Interface Specification 13.1.5 UNICODE_COLLATION.FatToStr() Summary Converts an 8.3 FAT file name in an OEM character set to a Null-terminated Unicode string. Prototype VOID (EFIAPI *EFI_UNICODE_COLLATION_FATTOSTR) ( IN UNICODE_COLLATION_INTERFACE *This, IN UINTN FatSize, IN CHAR8 *Fat, OUT CHAR16 *String ); Parameters This A pointer to the UNICODE_COLLATION_INTERFACE instance. Type UNICODE_COLLATION_INTERFACE is defined in Section 13.1. FatSize The size of the string Fat in bytes.
PAGE 251
Unicode Collation Protocol 13.1.6 UNICODE_COLLATION.StrToFat() Summary Converts a Null-terminated Unicode string to legal characters in a FAT filename using an OEM character set. Prototype BOOLEAN (EFIAPI *EFI_UNICODE_COLLATION_STRTOFAT) ( IN UNICODE_COLLATION_INTERFACE *This, IN CHAR16 *String, IN UINTN FatSize, OUT CHAR8 *Fat ); Parameters This A pointer to the UNICODE_COLLATION_INTERFACE instance. Type UNICODE_COLLATION_INTERFACE is defined in Section 13.1.
PAGE 252
Extensible Firmware Interface Specification 234 12/12/00 Version 1.
PAGE 253
14 PXE Base Code Protocol This chapter defines the Preboot Execution Environment (PXE) Base Code protocol, which is used to access PXE-compatible devices for network access and network booting. More information about PXE can be found in the Preboot Execution Environment (PXE) Specification at: ftp://download.intel.com/ial/wfm/pxespec.pdf. 14.1 EFI_PXE_BASE_CODE Protocol Summary The EFI_PXE_BASE_CODE protocol is used to control PXE-compatible devices.
PAGE 254
Extensible Firmware Interface Specification Parameters 236 Revision The revision of the EFI_PXE_BASE_CODE Protocol. All future revisions must be backwards compatible. If a future version is not backwards compatible it is not the same GUID. Start Starts the PXE Base Code Protocol. Mode structure information is not valid and no other Base Code Protocol functions will operate until the Base Code is started. Stop Stops the PXE Base Code Protocol. Mode structure information is unchanged by this function.
PAGE 255
PXE Base Code Protocol Related Definitions //******************************************************* // Maximum ARP and Route Entries //******************************************************* #define EFI_PXE_BASE_CODE_MAX_ARP_ENTRIES 8 #define EFI_PXE_BASE_CODE_MAX_ROUTE_ENTRIES 8 //******************************************************* // EFI_PXE_BASE_CODE_MODE // // The data values in this structure are read-only and // are updated by the code that produces the EFI_PXE_BASE_CODE // protocol functions.
PAGE 256
Extensible Firmware Interface Specification EFI_PXE_BASE_CODE_ARP_ENTRY ArpCache[EFI_PXE_BASE_CODE_MAX_ARP_ENTRIES]; UINT32 RouteTableEntries; EFI_PXE_BASE_CODE_ROUTE_ENTRY RouteTable[EFI_PXE_BASE_CODE_MAX_ROUTE_ENTRIES]; EFI_PXE_BASE_CODE_ICMP_ERROR IcmpError; EFI_PXE_BASE_CODE_TFTP_ERROR TftpError; } EFI_PXE_BASE_CODE_MODE; 238 Started TRUE if this device has been started by calling Start(). This field is set to TRUE by the Start() function and to FALSE by the Stop() function.
PAGE 257
PXE Base Code Protocol ProxyOfferReceived This field is initialized to FALSE by the Start() function and set to TRUE when the Dhcp() function completes successfully and a proxy DHCP offer packet was received. When TRUE, the ProxyOffer packet field is valid. This field can also be changed by the SetPackets() function. PxeDiscoverValid When TRUE, the PxeDiscover packet field is valid.
PAGE 258
Extensible Firmware Interface Specification 240 StationIp The device’s current IP address. This field is initialized to a zero address by Start(). This field is set when the Dhcp()function completes successfully. This field can also be set by the SetStationIp() function. SubnetMask The device’s current subnet mask. This field is initialized to a zero address by the Start() function. This field is set when the Dhcp()function completes successfully.
PAGE 259
PXE Base Code Protocol RouteTableEntries The number of valid entries in the current route table. This field is reset to zero by the Start() function. RouteTable Array of route table entries. IcmpError ICMP error packet. This field is updated when an ICMP error is received and is undefined until the first ICMP error is received. This field is zero-filled by the Start() function. TftpError TFTP error packet.
PAGE 260
Extensible Firmware Interface Specification //******************************************************* // This section defines the data types for DHCP packets, ICMP // error packets, and TFTP error packets. All of these are byte // packed data structures. //******************************************************* //******************************************************* // NOTE: ALL THE MULTIBYTE FIELDS IN THESE STRUCTURES ARE // STORED IN NETWORK ORDER.
PAGE 261
PXE Base Code Protocol //******************************************************* // EFI_PXE_BASE_CODE_ICMP_ERROR //******************************************************* typedef struct { UINT8 Type; UINT8 Code; UINT16 Checksum; union { UINT32 reserved; UINT32 Mtu; UINT32 Pointer; struct { UINT16 Identifier; UINT16 Sequence; } Echo; } u; UINT8 Data[494]; } EFI_PXE_BASE_CODE_ICMP_ERROR; //******************************************************* // EFI_PXE_BASE_CODE_TFTP_ERROR //******************************
PAGE 262
Extensible Firmware Interface Specification //******************************************************* // This section defines the data types for ARP cache entries, // and route table entries.
PAGE 263
PXE Base Code Protocol //******************************************************* // The following table defines values for the PXE DHCP and // Bootserver Discover packet tags that are specific to the EFI // environment. Complete definitions of all PXE tags are defined // in Table 2-1 PXE DHCP Options (Full List), in the PXE // Specification. //******************************************************* Table 14-1.
PAGE 264
Extensible Firmware Interface Specification Description The basic mechanisms and flow for remote booting in EFI are identical to the remote boot functionality described in detail in the PXE Specification. However, the actual execution environment, linkage, and calling conventions are replaced and enhanced for the EFI environment. The DHCP Option for the Client System Architecture is used to inform the DHCP server if the client is an IA-32 or Itanium-based EFI environment.
PAGE 265
PXE Base Code Protocol 14.1.1 EFI_PXE_BASE_CODE.Start() Summary Enables the use of the PXE Base Code Protocol functions. Prototype EFI_STATUS (EFIAPI *EFI_PXE_BASE_CODE_START) ( IN EFI_PXE_BASE_CODE *This, IN BOOLEAN UseIpv6 ); Parameters This Pointer to the EFI_PXE_BASE_CODE instance. UseIpv6 Specifies the type of IP addresses that are to be used during the session that is being started. Set to TRUE for IPv6 addresses, and FALSE for IPv4 addresses.
PAGE 266
Extensible Firmware Interface Specification 248 ToS Set to DEFAULT_ToS. DhcpCompleted Set to FALSE. ProxyOfferReceived Set to FALSE. StationIp Set to an address of all zeros. SubnetMask Set to a subnet mask of all zeros. DhcpDiscover Zero-filled. DhcpAck Zero-filled. ProxyOffer Zero-filled. PxeDiscoverValid Set to FALSE. PxeDiscover Zero-filled. PxeReplyValid Set to FALSE. PxeReply Zero-filled. PxeBisReplyValid Set to FALSE. PxeBisReply Zero-filled.
PAGE 267
PXE Base Code Protocol Status Codes Returned EFI_SUCCESS The PXE Base Code Protocol was started. EFI_INVALID_PARAMETER One of the parameters is not valid. EFI_UNSUPPORTED UseIpv6 is TRUE, but the Ipv6Supported field of the EFI_BASE_CODE_MODE structure is FALSE. EFI_ALREADY_STARTED The PXE Base Code Protocol is already in the started state. EFI_DEVICE_ERROR The network device encountered an error during this operation.
PAGE 268
Extensible Firmware Interface Specification 14.1.2 EFI_PXE_BASE_CODE.Stop() Summary Disables the use of the PXE Base Code Protocol functions. Prototype EFI_STATUS (EFIAPI *EFI_PXE_BASE_CODE_STOP) ( IN EFI_PXE_BASE_CODE *This ); Parameters This Pointer to the EFI_PXE_BASE_CODE instance. Description This function stops all activity on the network device.
PAGE 269
PXE Base Code Protocol 14.1.3 EFI_PXE_BASE_CODE.Dhcp() Summary Attempts to complete a DHCPv4 D.O.R.A. (discover / offer / request / acknowledge) or DHCPv6 S.A.R.R (solicit / advertise / request / reply) sequence. Prototype EFI_STATUS (EFIAPI *EFI_PXE_BASE_CODE_DHCP) ( IN EFI_PXE_BASE_CODE *This, IN BOOLEAN SortOffers ); Parameters This Pointer to the EFI_PXE_BASE_CODE instance. SortOffers TRUE if the offers received should be sorted. Set to FALSE to try the offers in the order that they are received.
PAGE 270
Extensible Firmware Interface Specification Status Codes Returned 252 EFI_SUCCESS Valid DHCP has completed. EFI_NOT_STARTED The PXE Base Code Protocol is in the stopped state. EFI_INVALID_PARAMETER One of the parameters is not valid. EFI_DEVICE_ERROR The network device encountered an error during this operation. EFI_OUT_OF_RESOURCES Could not allocate enough memory to complete the DHCP Protocol. EFI_ABORTED The callback function aborted the DHCP Protocol.
PAGE 271
PXE Base Code Protocol 14.1.4 EFI_PXE_BASE_CODE.Discover() Summary Attempts to complete the PXE Boot Server and/or boot image discovery sequence. Prototype EFI_STATUS (EFIAPI *EFI_PXE_BASE_CODE_DISCOVER) ( IN EFI_PXE_BASE_CODE IN UINT16 IN UINT16 IN BOOLEAN IN EFI_PXE_BASE_CODE_DISCOVER_INFO ); *This, Type, *Layer, UseBis, *Info OPTIONAL Parameters This Pointer to the EFI_PXE_BASE_CODE instance. Type The type of bootstrap to perform. See “Related Definitions”.
PAGE 272
Extensible Firmware Interface Specification Related Definitions //******************************************************* // Bootstrap Types //******************************************************* #define EFI_PXE_BASE_CODE_BOOT_TYPE_BOOTSTRAP 0 #define EFI_PXE_BASE_CODE_BOOT_TYPE_MS_WINNT_RIS 1 #define EFI_PXE_BASE_CODE_BOOT_TYPE_INTEL_LCM 2 #define EFI_PXE_BASE_CODE_BOOT_TYPE_DOSUNDI 3 #define EFI_PXE_BASE_CODE_BOOT_TYPE_NEC_ESMPRO 4 #define EFI_PXE_BASE_CODE_BOOT_TYPE_IBM_WSoD 5 #define EFI_PXE_BASE_CO
PAGE 273
PXE Base Code Protocol //******************************************************* // EFI_PXE_BASE_CODE_DISCOVER_INFO //******************************************************* typedef struct { BOOLEAN UseMCast; BOOLEAN UseBCast; BOOLEAN UseUCast; BOOLEAN MustUseList; EFI_IP_ADDRESS ServerMCastIp; UINT16 IpCnt; EFI_PXE_BASE_CODE_SRVLIST SrvList[IpCnt]; } EFI_PXE_BASE_CODE_DISCOVER_INFO; //******************************************************* // EFI_PXE_BASE_CODE_SRVLIST //***********************************
PAGE 274
Extensible Firmware Interface Specification Description This function attempts to complete the PXE Boot Server and/or boot image discovery sequence. If this sequence is completed, then EFI_SUCCESS is returned, and the PxeDiscoverValid, PxeDiscover, PxeReplyReceived, and PxeReply fields of the EFI_PXE_BASE_CODE_MODE structure are filled in. If UseBis is TRUE, then the PxeBisReplyReceived and PxeBisReply fields of the EFI_PXE_BASE_CODE_MODE structure will also be filled in.
PAGE 275
PXE Base Code Protocol 14.1.5 EFI_PXE_BASE_CODE.Mtftp() Summary Used to perform TFTP and MTFTP services.
PAGE 276
Extensible Firmware Interface Specification Info Pointer to the MTFTP information. This information is required to start or join a multicast TFTP session. It is also required to perform the “get file size” and “read directory” operations of MTFTP. See "Related Definitions" for the description of this data structure. DontUseBuffer Set to FALSE for normal TFTP and MTFTP read file operation.
PAGE 277
PXE Base Code Protocol MCastIp File multicast IP address. This is the IP address to which the server will send the requested file. CPort Client multicast listening port. This is the UDP port to which the server will send the requested file. SPort Server multicast listening port. This is the UDP port on which the server listens for multicast open requests and data acks.
PAGE 278
Extensible Firmware Interface Specification The format of the data returned from a TFTP read directory operation is a null-terminated filename followed by a null-terminated information string, of the form “size year-month-day hour:minute:second” (i.e. %d %d-%d-%d %d:%d:%f - note that the seconds field can be a decimal number), where the date and time are UTC. For an MTFTP read directory command, there is additionally a null-terminated multicast IP address preceding the filename of the form %d.%d.%d.
PAGE 279
PXE Base Code Protocol 14.1.6 EFI_PXE_BASE_CODE.UdpWrite() Summary Writes a UDP packet to the network interface.
PAGE 280
Extensible Firmware Interface Specification HeaderPtr If HeaderSize is not NULL, a pointer to a header to be prepended to the data at BufferPtr. BufferSize A pointer to the size of the data at BufferPtr. BufferPtr A pointer to the data to be written. Description This function writes a UDP packet specified by the (optional HeaderPtr and) BufferPtr parameters to the network interface. The UDP header is automatically built by this routine.
PAGE 281
PXE Base Code Protocol 14.1.7 EFI_PXE_BASE_CODE.UdpRead() Summary Reads a UDP packet from the network interface.
PAGE 282
Extensible Firmware Interface Specification Description This function reads a UDP packet from a network interface. The data contents are returned in (the optional HeaderPtr and) BufferPtr, and the size of the buffer received is returned in BufferSize . If the input BufferSize is smaller than the UDP packet received (less optional HeaderSize), it will be set to the required size, and EFI_BUFFER_TOO_SMALL will be returned. In this case, the contents of BufferPtr are undefined, and the packet is lost.
PAGE 283
PXE Base Code Protocol Table 14-4. Source IP Filter Operation OpFlags ANY_SRC_IP SrcIp Action 0 NULL Return EFI_INVALID_PARAMETER. 1 NULL Receive a packet sent from any IP address. 0 not NULL Receive a packet whose source IP address matches SrcIp. 1 not NULL Receive a packet sent from any IP address, and return the source IP address in SrcIp. Table 14-5. Source UDP Port Filter Operation OpFlags ANY_SRC_PORT SrcPort Action 0 NULL Return EFI_INVALID_PARAMETER.
PAGE 284
Extensible Firmware Interface Specification 14.1.8 EFI_PXE_BASE_CODE.SetIpFilter() Summary Updates the IP receive filters of a network device and enables software filtering. Prototype EFI_STATUS (EFIAPI *EFI_PXE_BASE_CODE_SET_IP_FILTER) ( IN EFI_PXE_BASE_CODE *This, IN EFI_PXE_BASE_CODE_IP_FILTER *NewFilter ); Parameters This Pointer to the EFI_PXE_BASE_CODE instance. NewFilter Pointer to the new set of IP receive filters.
PAGE 285
PXE Base Code Protocol 14.1.9 EFI_PXE_BASE_CODE.Arp() Summary Uses the ARP protocol to resolve a MAC address. Prototype EFI_STATUS (EFIAPI *EFI_PXE_BASE_CODE_ARP) ( IN EFI_PXE_BASE_CODE IN EFI_IP_ADDRESS IN EFI_MAC_ADDRESS ); *This, *IpAddr, *MacAddr OPTIONAL Parameters This Pointer to the EFI_PXE_BASE_CODE instance. IpAddr Pointer to the IP address that is used to resolve a MAC address.
PAGE 286
Extensible Firmware Interface Specification 14.1.10 EFI_PXE_BASE_CODE.SetParameters() Summary Updates the parameters that affect the operation of the PXE Base Code Protocol. Prototype EFI_STATUS (EFIAPI *EFI_PXE_BASE_CODE_SET_PARAMETERS) ( IN EFI_PXE_BASE_CODE *This, IN BOOLEAN *NewAutoArp, IN BOOLEAN *NewSendGUID, IN UINT8 *NewTTL, IN UINT8 *NewToS, IN BOOLEAN *NewMakeCallback ); OPTIONAL OPTIONAL OPTIONAL OPTIONAL OPTIONAL Parameters This Pointer to the EFI_PXE_BASE_CODE instance.
PAGE 287
PXE Base Code Protocol Description This function sets parameters that affect the operation of the PXE Base Code Protocol. The parameter specified by NewAutoArp is used to control the generation of ARP protocol packets. If NewAutoArp is TRUE, then ARP Protocol packets will be generated as required by the PXE Base Code Protocol. If NewAutoArp is FALSE, then no ARP Protocol packets will be generated.
PAGE 288
Extensible Firmware Interface Specification 14.1.11 EFI_PXE_BASE_CODE.SetStationIp() Summary Updates the station IP address and/or subnet mask values of a network device. Prototype EFI_STATUS (EFIAPI *EFI_PXE_BASE_CODE_SET_STATION_IP) ( IN EFI_PXE_BASE_CODE *This, IN EFI_IP_ADDRESS *NewStationIp, IN EFI_IP_ADDRESS *NewSubnetMask ); OPTIONAL OPTIONAL Parameters This Pointer to the EFI_PXE_BASE_CODE instance. NewStationIp Pointer to the new IP address to be used by the network device.
PAGE 289
PXE Base Code Protocol 14.1.12 EFI_PXE_BASE_CODE.SetPackets() Summary Updates the contents of the cached DHCP and Discover packets.
PAGE 290
Extensible Firmware Interface Specification NewPxeBisReplyReceived If not NULL, a pointer to a value that specifies whether to replace the current value of PxeBisReplyReceived field. If NULL, this parameter is ignored. NewDhcpDiscover Pointer to the new cached DHCP Discover packet. NewDhcpAck Pointer to the new cached DHCP Ack packet. NewProxyOffer Pointer to the new cached Proxy Offer packet. NewPxeDiscover Pointer to the new cached PXE Discover packet.
PAGE 291
PXE Base Code Protocol 14.2 EFI_PXE_BASE_CODE_CALLBACK Protocol Summary This is a specific instance of the PXE Base Code Callback Protocol that is invoked when the PXE Base Code Protocol is about to transmit, has received, or is waiting to receive a packet. The PXE Base Code Callback Protocol must be on the same handle as the PXE Base Code Protocol.
PAGE 292
Extensible Firmware Interface Specification 14.2.1 EFI_PXE_BASE_CODE_CALLBACK.Callback() Summary Callback function that is invoked when the PXE Base Code Protocol is about to transmit, has received, or is waiting to receive a packet.
PAGE 293
PXE Base Code Protocol Related Definitions //******************************************************* // EFI_PXE_BASE_CODE_CALLBACK_STATUS //******************************************************* typedef enum { EFI_PXE_BASE_CODE_CALLBACK_STATUS_FIRST, EFI_PXE_BASE_CODE_CALLBACK_STATUS_CONTINUE, EFI_PXE_BASE_CODE_CALLBACK_STATUS_ABORT, EFI_PXE_BASE_CODE_CALLBACK_STATUS_LAST } EFI_PXE_BASE_CODE_CALLBACK_STATUS; //******************************************************* // EFI_PXE_BASE_CODE_FUNCTION //********
PAGE 294
Extensible Firmware Interface Specification 276 12/12/00 Version 1.
PAGE 295
15 Simple Network Protocol This chapter defines the Simple Network Protocol. This protocol provides a packet level interface to a network adapter. 15.1 EFI_SIMPLE_NETWORK Protocol Summary The EFI_SIMPLE_NETWORK protocol provides services to initialize a network interface, transmit packets, receive packets, and close a network interface.
PAGE 296
Extensible Firmware Interface Specification Parameters 278 Revision Revision of the EFI_SIMPLE_NETWORK Protocol. All future revisions must be backwards compatible. If a future version is not backwards compatible it is not the same GUID. Start Prepares the network interface for further command operations. No other EFI_SIMPLE_NETWORK interface functions will operate until this call is made. Stop Stops further network interface command processing.
PAGE 297
SIMPLE_NETWORK Protocol Related Definitions //******************************************************* // EFI_SIMPLE_NETWORK_MODE // // Note that the fields in this data structure are read-only and // are updated by the code that produces the EFI_SIMPLE_NETWORK // protocol functions. All these fields must be discovered // during driver initialization.
PAGE 298
Extensible Firmware Interface Specification 280 State Reports the current state of the network interface (see EFI_SIMPLE_NETWORK_STATE below). When an EFI_SIMPLE_NETWORK driver has initialized a network interface, it is left in the EfiSimpleNetworkStopped state. HwAddressSize The size, in bytes, of the network interface’s HW address. MediaHeaderSize The size, in bytes, of the network interface’s media header.
PAGE 299
SIMPLE_NETWORK Protocol MediaPresentSupported TRUE if the presence of media can be determined; otherwise FALSE. If FALSE, MediaPresent cannot be used. MediaPresent TRUE if media are connected to the network interface;otherwise FALSE. This field is only valid immediately after calling Initialize().
PAGE 300
Extensible Firmware Interface Specification 15.1.1 EFI_SIMPLE_NETWO RK.Start() Summary Changes the state of a network interface from “stopped” “started”. Prototype EFI_STATUS (EFIAPI *EFI_SIMPLE_NETWORK_START) ( IN EFI_SIMPLE_NETWORK *This ); Parameters A pointer to the EFI_SIMPLE_NETWORK instance. This Description This function starts a network interface. If the network interface was successfully started, then EFI_SUCCESS will be returned.
PAGE 301
SIMPLE_NETWORK Protocol 15.1.2 EFI_SIMPLE_NETWO RK.Stop() Summary Changes the state of a network interface from “started” to “stopped”. Prototype EFI_STATUS (EFIAPI *EFI_SIMPLE_NETWORK_STOP) ( IN EFI_SIMPLE_NETWORK *This ); Parameters A pointer to the EFI_SIMPLE_NETWORK instance. This Description This function stops an network interface. This call is only valid if the network interface is in the started state. If the network interface was successfully stopped, then EFI_SUCCESS will be returned.
PAGE 302
Extensible Firmware Interface Specification 15.1.3 EFI_SIMPLE_NETWO RK.Initialize() Summary Resets a network adapter and allocates the transmit and receive buffers required by the network interface; optionally, also requests allocation of additional transmit and receive buffers.
PAGE 303
SIMPLE_NETWORK Protocol 15.1.4 EFI_SIMPLE_NETW ORK.Reset() Summary Resets a network adapter and re-initializes it with the parameters that were provided in the previous call to Initialize(). Prototype EFI_STATUS (EFIAPI *EFI_SIMPLE_NETWORK_RESET) ( IN EFI_SIMPLE_NETWORK *This, IN BOOLEAN ExtendedVerification ); Parameters This A pointer to the EFI_SIMPLE_NETWORK instance. ExtendedVerification Indicates that the driver may perform a more exhaustive verification operation of the device during reset.
PAGE 304
Extensible Firmware Interface Specification 15.1.5 EFI_SIMPLE_NETWO RK.Shutdown() Summary Resets a network adapter and leaves it in a state that is safe for another driver to initialize. Prototype EFI_STATUS (EFIAPI *EFI_SIMPLE_NETWORK_SHUTDOWN) ( IN EFI_SIMPLE_NETWORK *This ); Parameters A pointer to the EFI_SIMPLE_NETWORK instance. This Description This function releases the memory buffers assigned in the Initialize() call.
PAGE 305
SIMPLE_NETWORK Protocol 15.1.6 EFI_SIMPLE_NETWO RK.ReceiveFilters() Summary Manages the multicast receive filters of a network interface. Prototype EFI_STATUS (EFIAPI *EFI_SIMPLE_NETWORK_RECEIVE_FILTERS) ( IN EFI_SIMPLE_NETWORK *This, IN UINT32 Enable, IN UINT32 Disable, IN BOOLEAN ResetMCastFilter, IN UINTN McastFilterCnt OPTIONAL, IN EFI_MAC_ADDRESS *MCastFilter OPTIONAL, ); Parameters This A pointer to the EFI_SIMPLE_NETWORK instance.
PAGE 306
Extensible Firmware Interface Specification If ResetMCastFilter is TRUE, then the multicast receive filter list on the network interface will be reset to the default multicast receive filter list. If ResetMCastFilter is FALSE, and this network interface allows the multicast receive filter list to be modified, then the MCastFilterCnt and MCastFilter are used to update the current multicast receive filter list.
PAGE 307
SIMPLE_NETWORK Protocol 15.1.7 EFI_SIMPLE_NETWO RK.StationAddress() Summary Modifies or resets the current station address, if supported. Prototype EFI_STATUS (EFIAPI *EFI_SIMPLE_NETWORK_STATION_ADDRESS) ( IN EFI_SIMPLE_NETWORK *This, IN BOOLEAN Reset, IN EFI_MAC_ADDRESS *New OPTIONAL ); Parameters This A pointer to the EFI_SIMPLE_NETWORK instance. Reset Flag used to reset the station address to the network interface’s permanent address. New New station address to be used for the network interface.
PAGE 308
Extensible Firmware Interface Specification 15.1.8 EFI_SIMPLE_NETWO RK.Statistics() Summary Resets or collects the statistics on a network interface. Prototype EFI_STATUS (EFIAPI *EFI_SIMPLE_NETWORK_STATISTICS) ( IN EFI_SIMPLE_NETWORK *This, IN BOOLEAN Reset, IN OUT UINTN *StatisticsSize OUT EFI_NETWORK_STATISTICS *StatisticsTable ); OPTIONAL, OPTIONAL Parameters This A pointer to the EFI_SIMPLE_NETWORK instance. Reset Set to TRUE to reset the statistics for the network interface.
PAGE 309
SIMPLE_NETWORK Protocol UINT64 UINT64 UINT64 UINT64 UINT64 UINT64 UINT64 UINT64 UINT64 UINT64 UINT64 UINT64 UINT64 UINT64 UINT64 UINT64 UINT64 UINT64 } EFI_NETWORK_STATISTICS; RxDroppedFrames; RxUnicastFrames; RxBroadcastFrames; RxMulticastFrames; RxCrcErrorFrames; RxTotalBytes; TxTotalFrames; TxGoodFrames; TxUndersizeFrames; TxOversizeFrames; TxDroppedFrames; TxUnicastFrames; TxBroadcastFrames; TxMulticastFrames; TxCrcErrorFrames; TxTotalBytes; Collisions; UnsupportedProtocol; RxTotalFrames Total numbe
PAGE 310
Extensible Firmware Interface Specification TxOversizeFrames Number of frames longer than the maxminum length for the media. This would be greater than 1500 for ethernet. TxDroppedFrames Valid frames that were dropped because receive buffers were full. TxUnicastFrames Number of valid unicast frames transmitted and not dropped. TxBroadcastFrames Number of valid broadcast frames transmitted and not dropped. TxMulticastFrames Number of valid mutlicast frames transmitted and not dropped.
PAGE 311
SIMPLE_NETWORK Protocol 15.1.9 EFI_SIMPLE_NETWO RK.MCastIPtoMAC() Summary Converts a multicast IP address to a multicast HW MAC address. Prototype EFI_STATUS (EFIAPI *EFI_SIMPLE_NETWORK_MCAST_IP_TO_MAC) ( IN EFI_SIMPLE_NETWORK *This, IN BOOLEAN IPv6, IN EFI_IP_ADDRESS *IP, OUT EFI_MAC_ADDRESS *MAC ); Parameters This A pointer to the EFI_SIMPLE_NETWORK instance. IPv6 Set to TRUE if the multicast IP address is IPv6 [RFC 2460]. Set to FALSE if the multicast IP address is IPv4 [RFC 791].
PAGE 312
Extensible Firmware Interface Specification 15.1.10 EFI_SIMPLE_NETWO RK.NvData() Summary Performs read and write operations on the NVRAM device attached to a network interface. Prototype EFI_STATUS (EFIAPI *EFI_SIMPLE_NETWORK_NVDATA) ( IN EFI_SIMPLE_NETWORK *This IN BOOLEAN ReadWrite, IN UINTN Offset, IN UINTN BufferSize, IN OUT VOID *Buffer ); Parameters This A pointer to the EFI_SIMPLE_NETWORK instance. ReadWrite TRUE for read operations, FALSE for write operations.
PAGE 313
SIMPLE_NETWORK Protocol Status Codes Returned EFI_SUCCESS The NVRAM access was performed. EFI_NOT_STARTED The network interface has not been started. EFI_INVALID_PARAMETER One or more of the parameters has an unsupported value. EFI_DEVICE_ERROR The command could not be sent to the network interface. EFI_UNSUPPORTED This function is not supported by the network interface. Version 1.
PAGE 314
Extensible Firmware Interface Specification 15.1.11 EFI_SIMPLE_NETWO RK.GetStatus() Summary Reads the current interrupt status and recycled transmit buffer status from a network interface. Prototype EFI_STATUS (EFIAPI *EFI_SIMPLE_NETWORK_GET_STATUS) ( IN EFI_SIMPLE_NETWORK *This, OUT UINT32 *InterruptStatus OUT VOID **TxBuf ); OPTIONAL, OPTIONAL Parameters This A pointer to the EFI_SIMPLE_NETWORK instance.
PAGE 315
SIMPLE_NETWORK Protocol Description This function gets the current interrupt and recycled transmit buffer status from the network interface. The interrupt status is returned as a bit mask in InterruptStatus. If InterruptStatus is NULL, the interrupt status will not be read. If TxBuf is not NULL, a recycled transmit buffer address will be retrieved. If a recycled transmit buffer address is returned in TxBuf, then the buffer has been successfully transmitted, and the status for that buffer is cleared.
PAGE 316
Extensible Firmware Interface Specification 15.1.12 EFI_SIMPLE_NETWO RK.Transmit() Summary Places a packet in the transmit queue of a network interface. Prototype EFI_STATUS (EFIAPI *EFI_SIMPLE_NETWORK_TRANSMIT) IN EFI_SIMPLE_NETWORK IN UINTN IN UINTN IN VOID IN EFI_MAC_ADDRESS IN EFI_MAC_ADDRESS IN UINT16 ); ( *This HeaderSize, BufferSize, *Buffer, *SrcAddr *DestAddr *Protocol OPTIONAL, OPTIONAL, OPTIONAL, Parameters 298 This A pointer to the EFI_SIMPLE_NETWORK instance.
PAGE 317
SIMPLE_NETWORK Protocol Description This function places the packet specified by Header and Buffer on the transmit queue. If HeaderSize is non-zero and HeaderSize is not equal to This->Mode>MediaHeaderSize, then EFI_INVALID_PARAMETER will be returned. If BufferSize is less than This->Mode->MediaHeaderSize, then EFI_BUFFER_TOO_SMALL will be returned. If Buffer is NULL, then EFI_INVALID_PARAMETER will be returned.
PAGE 318
Extensible Firmware Interface Specification 15.1.13 EFI_SIMPLE_NETWO RK.Receive() Summary Receives a packet from a network interface. Prototype EFI_STATUS (EFIAPI *EFI_SIMPLE_NETWORK_RECEIVE) ( IN EFI_SIMPLE_NETWORK *This OUT UINTN *HeaderSize IN OUT UINTN *BufferSize, OUT VOID *Buffer, OUT EFI_MAC_ADDRESS *SrcAddr OUT EFI_MAC_ADDRESS *DestAddr OUT UINT16 *Protocol ); OPTIONAL, OPTIONAL, OPTIONAL, OPTIONAL Parameters 300 This A pointer to the EFI_SIMPLE_NETWORK instance.
PAGE 319
SIMPLE_NETWORK Protocol Description This function retrieves one packet from the receive queue of a network interface. If there are no packets on the receive queue, then EFI_NOT_READY will be returned. If there is a packet on the receive queue, and the size of the packet is smaller than BufferSize, then the contents of the packet will be placed in Buffer, and BufferSize will be updated with the actual size of the packet.
PAGE 320
Extensible Firmware Interface Specification 15.2 NETWORK_INTERFACE_IDENTIFIER Protocol Summary This is an optional protocol that is used to describe details about the software layer that is used to produce the Simple Network Protocol. This protocol is only required if the underlying network interface is 16-bit UNDI, 32/64-bit S/W UNDI, or H/W UNDI. It is used to obtain type and revision information about the underlying network interface.
PAGE 321
SIMPLE_NETWORK Protocol 16-bit UNDI and 32/64-bit S/W UNDI: Id contains the address of the first byte of the copy of the !PXE structure in the relocated UNDI code segment. See the Preboot Execution Environment (PXE) Specification and Appendix G. H/W UNDI: Id contains the address of the !PXE structure. ImageAddr Address of the un-relocated network interface image. 16-bit UNDI: ImageAddr is the address of the PXE option ROM image in upper memory.
PAGE 322
Extensible Firmware Interface Specification MajorVer Major version number. 16-bit UNDI: MajorVer comes from the third byte of the UNDIRev field in the UNDI ROM ID structure. Refer to the Preboot Execution Environment (PXE) Specification. 32/64-bit S/W UNDI and H/W UNDI: MajorVer comes from the Major field in the !PXE structure. See Appendix G. MinorVer Minor version number. 16-bit UNDI: MinorVer comes from the second byte of the UNDIRev field in the UNDI ROM ID structure.
PAGE 323
16 File System Format The file system supported by the Extensible Firmware Interface is based on the FAT file system. EFI defines a specific version of FAT that is explicitly documented and testable. Conformance to the EFI specification and its associate reference documents is the only definition of FAT that needs to be implemented to support EFI. To differentiate the EFI file system from pure FAT, a new partition file system type has been defined.
PAGE 324
Extensible Firmware Interface Specification 16.1.1 File System Format The first block (sector) of a partition contains a data structure called the BIOS Parameter Block, BPB, that defines the type and location of FAT file system on the drive. The BPB contains a data structure that defines the size of the media, the size of reserved space, the number of FAT tables, and the location and size of the root directory (not used in FAT-32).
PAGE 325
File System Format This directory contains EFI images that aide in recovery if the boot selections for the software installed on the EFI system partition are ever lost. Any additional EFI executables must be in sub directories below the vendor sub directory. The following is a sample directory structure for an EFI system partition present on a hard disk. \EFI \ \ . . .
PAGE 326
Extensible Firmware Interface Specification 16.2 Partition Discovery EFI requires the firmware to be able to parse legacy master boot records, the new GUID Partition Table (GPT), and El Torito logical device volumes. The EFI firmware produces a logical BLOCK_IO device for each EFI Partition Entry, El Torito logical device volume, and if no EFI Partition Table is present any partitions found in the partition tables.
PAGE 327
File System Format EFI supports the nesting of legacy MBR partitions, by allowing any legacy MBR partition to contain more legacy MBR partitions. This is accomplished by supporting the same partition discovery algorithm on every logical block device. It should be noted that the GUID Partition Table does not allow nesting of GUID Partition Table Headers.
PAGE 328
Extensible Firmware Interface Specification Partition Entry array is the PartitionEntrySize multiplied by NumberOfPartitionEntries. When a GUID Partition Entry is updated the PartitionEntryArrayCRC must be updated. When the PartitionEntryArrayCRC is updated the GUID Partition Table Header CRC must also be updated, since the PartitionEntryArrayCRC is stored in the GUID Partition Table Header. First useable block Start partition LBA0 LBA1 End partition LBAn Partition 1 0 1 ...
PAGE 329
File System Format Table 16-1. GUID Partition Table Header Mnemonic Byte Offset Byte Length Signature 0 8 Identifies EFI-compatible partition table header. This value must contain the string “EFI PART”, 0x5452415020494645. Revision 8 4 The specification revision number that this header complies to. For version 1.0 of the specification the correct value is 0x00010000. HeaderSize 12 4 Size in bytes of the GUID Partition Table Header.
PAGE 330
Extensible Firmware Interface Specification If the GUID Partition Table is the primary table, stored at LBA 1: • Check the AlternateLBA to see if it is a valid GUID Partition Table If the primary GUID Partition Table is corrupt: • Check the last LBA of the device to see if it has a valid GUID Partition Table. • If valid backup GUID Partition Table found, restore primary GUID Partition Table.
PAGE 331
File System Format The SizeOfPartitionEntry variable in the GUID Partition Table Header defines the size of a GUID Partition Entry. The GUID Partition Entry starts in the first byte of the GUID Partition Entry and any unused space at the end of the defined partition entry is reserved space and must be set to zero. Each partition record contains a Unique Partition GUID variable that uniquely identifies every partition that will ever be created.
PAGE 332
Extensible Firmware Interface Specification 16.2.2 ISO-9660 and El Torito IS0-9660 is the industry standard low level format used on CD-ROM and DVD-ROM. CD-ROM format is completely described by the “El Torito” Bootable CD-ROM Format Specification Version 1.0. To boot from a CD-ROM or DVD-ROM in the boot services environment, an EFI System partition is stored in a “no emulation” mode as defined by the “El Torito” specification. A Platform ID of 0xEF hex indicates an EFI System Partition.
PAGE 333
File System Format Table 16-5. Legacy Master Boot Record Mnemonic Byte Offset Byte Length BootCode 0 440 Code used on legacy Intel architecture system to select a partition record and load the first block (sector) of the partition pointed to by the partition record. This code is not executed on EFI systems. UniqueMBRSignature 440 4 Unique Disk Signature, this is an optional feature and not on all hard drives. This value is always written by the OS and is never written by EFI firmware.
PAGE 334
Extensible Firmware Interface Specification Table 16-6. Legacy Master Boot Record Partition Record (continued) Mnemonic Byte Offset Byte Length Description End Track 7 1 End of partition in CHS address, not used by EFI firmware. Starting LBA 8 4 Starting LBA address of the partition on the disk. Used by EFI firmware to define the start of the partition. Size In LBA 12 4 Size of partition in LBA. Used by EFI firmware to determine the size of the partition.
PAGE 335
File System Format 16.3 Media Formats This section describes how booting from different types of removable media is handled. In general the rules are consistent regardless of a media’s physical type and whether it is removable or not. 16.3.1 Removable Media Removable media may contain a standard FAT-12, FAT-16, or FAT-32 file system. Legacy 1.44 MB floppy devices typically support a FAT-12 file system. Booting from a removable media device can be accomplished the same way as any other boot.
PAGE 336
Extensible Firmware Interface Specification 16.3.4 CD-ROM and DVD-ROM A CD-ROM or DVD-ROM may contain multiple partitions as defined Sections 16.1 and 16.2 and in the “El Torito” specification. EFI code does not assume a fixed block size. Since the EFI file system definition does not use the same Initial/Default entry as a legacy CD-ROM, it is possible to boot Intel architecture personal computers using an EFI CD-ROM or DVD-ROM.
PAGE 337
17 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.
PAGE 338
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.
PAGE 339
Boot Manager 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 325. 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.
PAGE 340
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.
PAGE 341
Boot Manager 17.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 non-volatile. This means that their values are persistent across resets and power cycles.
PAGE 342
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 non-volatile memory. This value is considered read-only.
PAGE 343
Boot Manager DriverOrder list is used by the firmware’s boot manager as the default load order for EFI drivers that it should explicitly load. 17.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.
PAGE 344
Extensible Firmware Interface Specification 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. 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.
PAGE 345
18 PCI Expansion ROM The PCI Local Bus Specification defines how to discover expansion ROM code that comes from a ROM on a PCI Card. The expansion ROM can be executed to initialize a specific device or, possibly, to boot a system. PCI allows the ROM to contain several different images to accommodate different machine and processor architectures. This chapter explains how EFI images can be discovered and executed from a PCI expansion ROM.
PAGE 346
Extensible Firmware Interface Specification EFI will coordinate with a future revision of the PCI specification to allocate the code type of 0x03 to represent EFI images. This code type will signify that EFI extensions are present in the standard PCI expansion ROM header. Table 18-2.
PAGE 347
PCI Expansion ROM Table 18-3 defines the layout of an EFI PCI expansion ROM. Missing values will be supplied in a later version of the specification. Table 18-3. EFI PCI Expansion ROM Header Offset Byte Length Value Description 0x00 1 0x55 ROM Signature, byte 1 0x01 1 0xAA ROM Signature, byte 2 0x02 2 XXXX Initialization Size – size of this image in units of 512 bytes. The size includes this header.
PAGE 348
Extensible Firmware Interface Specification 330 12/01/00 Version 1.
PAGE 349
A GUID and Time Formats All EFI GUIDs (Globally Unique Identifiers) have the format described in Appendix J of the Wired for Management Baseline Specification. This document references the format of the GUID, but implementers must reference the Wired for Management specifications for algorithms to generate GUIDs. The following table defines the format of an EFI GUID (128 bits). Table A-1. EFI GUID Format Byte Offset Byte Length TimeLow 0 4 The low field of the timestamp.
PAGE 350
Extensible Firmware Interface Specification 332 12/12/00 Version 1.
PAGE 351
B Console The EFI console was designed so that it could map to common console devices. This appendix explains how an EFI console could map to a VGA with PC AT 101/102, PCANSI, or ANSI X3.64 consoles. B.1 SIMPLE_INPUT Table B-1 gives examples of how an EFI scan code can be mapped to ANSI X3.64 terminal, PCANSI terminal, or an AT 101/102 keyboard. PC ANSI terminals support an escape sequence that begins with the ASCII character 0x1b and is followed by the ASCII character 0x5B, “ [ ”.
PAGE 352
Extensible Firmware Interface Specification Table B-1. B.2 EFI Scan Codes for SIMPLE_INPUT (continued) EFI Scan Code Description ANSI X3.
PAGE 353
Console Table B-2. Control Sequences that Can Be Used to Implement SIMPLE_TEXT_OUTPUT (continued) PCANSI Codes ANSI X3.64 Codes Description ESC [ 41 m CSI 41 m Red background, compliant with ISO Standard 6429. ESC [ 42 m CSI 42 m Green background, compliant with ISO Standard 6429. ESC [ 43 m CSI 43 m Yellow background, compliant with ISO Standard 6429. ESC [ 44 m CSI 44 m Blue background, compliant with ISO Standard 6429.
PAGE 354
Extensible Firmware Interface Specification 336 12/12/00 Version 1.
PAGE 355
C Device Path Examples This appendix presents an example EFI Device Path and explains its relationship to the ACPI name space. An example system design is presented along with its corresponding ACPI name space. These physical examples are mapped back to EFI Device Paths. C.1 Example Computer System Figure C-1 represents a hypothetical computer system architecture that will be used to discuss the construction of EFI Device Paths.
PAGE 356
Extensible Firmware Interface Specification The remainder of this appendix describes how to construct a device path for three example devices from the system in Figure C-1. The following is a list of the examples used: • Legacy floppy • IDE Disk • Secondary root PCI bus with PCI to PCI bridge Figure C-2 is a partial ACPI name space for the system in Figure C-1. Figure C-2 is based on Figure 5-3 in the Advanced Configuration and Power Interface Specification.
PAGE 357
Device Path Examples Table C-1.
PAGE 358
Extensible Firmware Interface Specification The EFI Device Path for the PCI IDE controller would contain entries for the following things: • Root PCI Bridge. ACPI Device Path _HID PNP0A03, _UID 0. ACPI name space \_SB\PCI0 • PCI IDE controller. PCI Device Path with device and function of the IDE controller. ACPI name space \_SB\PCI0\IDE0 • ATA Address. ATA Messaging Device Path for Primary bus and Master device. ACPI name space \_SB\PCI0\IDE0\PRIM\MAST • End Device Path Table C-2.
PAGE 359
Device Path Examples C.4 Secondary Root PCI Bus with PCI to PCI Bridge The secondary PCI host bridge materializes a second set of PCI buses into the system. The PCI buses on the secondary PCI host bridge are totally independent of the PCI buses on the root PCI host bridge. The only relationship between the two is they must be configured to not consume the same resources. The primary PCI bus of the secondary PCI host bridge also contains a PCI to PCI bridge.
PAGE 360
Extensible Firmware Interface Specification C.5 ACPI Terms Names in the ACPI name space that start with an underscore (“_”) are reserved by the ACPI specification and have architectural meaning. All ACPI names in the name space are four characters in length. The following four ACPI names are used in this specification. _ADR. The Address on a bus that has standard enumeration. An example would be PCI, where the enumeration method is described in the PCI Local Bus specification. _CRS.
PAGE 361
Device Path Examples C.6 EFI Device Path as a Name Space Figure C-3 shows the EFI Device Path for the example system represented as a name space. The Device Path can be represented as a name space, but EFI does support manipulating the Device Path as a name space. You can only access Device Path information by locating the DEVICE_PATH_INTERFACE from a handle. Not all the nodes in a Device Path will have a handle.
PAGE 362
Extensible Firmware Interface Specification 344 12/12/00 Version 1.
PAGE 363
D Status Codes EFI interfaces return an EFI_STATUS code. Tables D-2, D-3, and D-4 list these codes for success, errors, and warnings, respectively. Error codes also have their highest bit set, so all error codes have negative values. The range of status codes that have the highest bit set and the next to highest bit clear are reserved for use by EFI. The range of status codes that have both the highest bit set and the next to highest bit set are reserved for use by OEMs.
PAGE 364
Extensible Firmware Interface Specification Table D-3. Mnemonic Value Description EFI_NOT_READY 6 There is no data pending upon return. EFI_DEVICE_ERROR 7 The physical device reported an error while attempting the operation. EFI_WRITE_PROTECTED 8 The device cannot be written to. EFI_OUT_OF_RESOURCES 9 A resource has run out. EFI_VOLUME_CORRUPTED 10 An inconstancy was detected on the file system causing the operating to fail. EFI_VOLUME_FULL 11 There is no more space on the file system.
PAGE 365
E Alphabetic Function Lists This appendix contains two tables that list all EFI functions alphabetically. Table E-1 lists the functions in pure alphabetic order. Functions that have the same name can be distinguished by the associated service or protocol (column 2). For example, there are two “Flush” functions, one from the Device I/O Protocol and one from the File System Protocol. Table E-2 orders the functions alphabetically within a service or protocol.
PAGE 366
Extensible Firmware Interface Specification Table E-1. Functions Listed in Alphabetic Order (continued) Function Name Service or Protocol Sub-Service EFI_PXE_BASE_CODE_CAL PXE Base Code LBACK Protocol Function Description Callback function that is invoked when the PXE Base Code Protocol is waiting for an event. EFI_IMAGE_ENTRY_POINT Boot Services Image Services Prototype of an EFI Image’s entry point.
PAGE 367
Alphabetic Function Lists Table E-1. Functions Listed in Alphabetic Order (continued) Function Name Service or Protocol Sub-Service Function Description GetTime Runtime Services Time Services Returns the current time and date, and the time-keeping capabilities of the platform. GetVariable Runtime Services Variable Services Returns the value of the specific variable. GetWakeupTime Runtime Services Time Services Returns the current wakeup alarm clock setting.
PAGE 368
Extensible Firmware Interface Specification Table E-1. Functions Listed in Alphabetic Order (continued) Function Name Service or Protocol Sub-Service Function Description MetaiMatch Unicode Collation Protocol Performs a case insensitive comparison between a Unicode pattern string and a Unicode string. Mtftp PXE Base Code Protocol Is used to perform TFTP and MTFTP services. NVData Simple Network Protocol Allows read and writes to the NVRAM device attached to a network interface.
PAGE 369
Alphabetic Function Lists Table E-1. Functions Listed in Alphabetic Order (continued) Function Name Service or Protocol Sub-Service Function Description ReinstallProtocolInterface Boot Services Replaces a protocol interface. Reset Block I/O Protocol Resets the block device hardware. Reset Serial I/O Protocol Resets the hardware device. Reset Simple Input Protocol Resets a simple input device.
PAGE 370
Extensible Firmware Interface Specification Table E-1. Functions Listed in Alphabetic Order (continued) Function Name Service or Protocol Sub-Service Function Description SetTime Runtime Services Time Services Sets the current local time and date information. SetTimer Boot Services Event Services Sets an event to be signaled at a particular time. SetVariable Runtime Services Variable Services Sets the value of the specified variable.
PAGE 371
Alphabetic Function Lists Table E-1. Functions Listed in Alphabetic Order (continued) Function Name Service or Protocol Sub-Service Function Description StrLwr Unicode Collation Protocol Converts all the Unicode characters in a Null-terminated Unicode string to lower case Unicode characters. StrToFat Unicode Collation Protocol Converts a Null-terminated Unicode string to legal characters in a FAT filename using an OEM character set.
PAGE 372
Extensible Firmware Interface Specification Table E-2. Functions Listed Alphabetically Within Service or Protocol Service or Protocol Function Function Description Block I/O Protocol FlushBlocks Flushes any cached blocks. ReadBlocks Reads the requested number of blocks from the device. Reset Resets the block device hardware. WriteBlocks Writes the requested number of blocks to the device. AllocatePages Allocates memory pages of a particular type.
PAGE 373
Alphabetic Function Lists Table E-2. Functions Listed Alphabetically Within Service or Protocol (continued) Service or Protocol Function Function Description Boot Services (cont.) Stall Stalls the processor. StartImage Function to transfer control to the Image’s entry point. UninstallProtocolInterface Removes a protocol interface from a device handle. Device I/O Protocol Disk I/O Protocol File System Protocol Load File Protocol UnloadImage Unloads an image.
PAGE 374
Extensible Firmware Interface Specification Table E-2. Functions Listed Alphabetically Within Service or Protocol (continued) Service or Protocol Function Function Description PXE Base Code Protocol Arp Uses the ARP protocol to resolve a MAC address. Dhcp Attempts to complete a DHCPv4 D.O.R.A. (discover / offer / request / acknowledge) or DHCPv6 S.A.R.R (solicit / advertise / request / reply) sequence. Discover Attempts to complete the PXE Boot Server and/or boot image discovery sequence.
PAGE 375
Alphabetic Function Lists Table E-2. Functions Listed Alphabetically Within Service or Protocol (continued) Service or Protocol Function Function Description Serial I/O Protocol GetControl Reads the status of the control bits on a serial device. Read Receives a buffer of characters from a serial device. Reset Resets the hardware device. SetAttributes Sets communication parameters for a serial device. SetControl Sets the control bits on a serial device.
PAGE 376
Extensible Firmware Interface Specification Table E-2. Functions Listed Alphabetically Within Service or Protocol (continued) Service or Protocol Function Function Description Simple Text Output Protocol ClearScreen Clears the screen with the currently set background color. EnableCursor Turns the visibility of the cursor on/off. OutputString Displays the Unicode string on the device at the current cursor location.
PAGE 377
F Glossary _ADR A reserved name in ACPI name space. It refers to an address on a bus that has standard enumeration. An example would be PCI, where the enumeration method is described in the PCI Local Bus specification. _CRS A reserved name in ACPI name space. It refers to the current resource setting of a device. A _CRS is required for devices that are not enumerated in a standard fashion. _CRS is how ACPI converts non standard devices into plug and play devices. _HID A reserved name in ACPI name space.
PAGE 378
Extensible Firmware Interface Specification BIOS Boot Specification Device Path A Device Path that is used to point to boot legacy operating systems; it is based on the BIOS Boot Specification, Version 1.01. BIOS Parameter Block (BPB) The first block (sector) of a partition. It defines the type and location of the FAT File System on a drive. Block I/O Protocol A protocol that is used during boot services to abstract mass storage devices.
PAGE 379
Glossary Boot Services Time The period of time between platform initialization and the call to ExitBootServices(). During this time, EFI drivers and applications are loaded iteratively and the system boots from an ordered list of EFI OS loaders. BPB See BIOS Parameter Block. CIM See Common Information Model. Cluster A collection of disk sectors. Clusters are the basic storage units for disk files. See File Allocation Table.
PAGE 380
Extensible Firmware Interface Specification Desktop Management Task Force (DMTF) The DMTF is a standards organization comprised of companies from all areas of the computer industry. Its purpose is to create the standards and infrastructure for costeffective management of PC systems. Device Handle A handle points to a list of one or more protocols that can respond to requests for services for a given device referred to by the handle.
PAGE 381
Glossary DMTF See Desktop Management Task Force. Dynamic Host Configuration Protocol (DHCP) A protocol that is used to get information from a configuration server. DHCP is defined by the Desktop Management Task Force, not EFI. EFI Application Modular code that may be loaded in the boot services environment to accomplish platform specific tasks within that environment.
PAGE 382
Extensible Firmware Interface Specification Event An EFI data structure that describes an “event” — for example, the expiration of a timer. Event Services The set of functions used to manage events. Includes CheckEvent(), CreateEvent(), CloseEvent(), SignalEvent(), and WaitForEvent(). FAT See File Allocation Table. FAT File System The file system on which the EFI file system is based. See File Allocation Table and System Partition.
PAGE 383
Glossary GUID Partition Table Header The header in a GUID Partition Table. Among other things, it contains the number of partition entries in the table and the first and last blocks that can be used for the entries. GUID Partition Entry A data structure that characterizes a GUID Partition. Among other things, it specifies the starting and ending LBA of the partition. Handle See Device Handle.
PAGE 384
Extensible Firmware Interface Specification Intel Itanium Architecture A new Intel architecture that has 64-bit instruction capabilities, new performanceenhancing features, and support for the IA-32 instruction set. This architecture is described in the IA-64 Architecture Software Developer’s Manual. Intel Architecture Platform Architecture A collective term for PC-AT-class computers and other systems based on Intel Architecture processors of all families.
PAGE 385
Glossary MCA See Machine Check Abort. Media Device Path A Device Path that is used to describe the portion of a medium that is being abstracted by a boot service. For example, a Media Device Path could define which partition on a hard drive was being used. Memory Allocation Services The set of functions used to allocate and free memory, and to retrieve the memory map. Includes AllocatePages(), FreePages(), AllocatePool(), FreePool(), and GetMemoryMap().
PAGE 386
Extensible Firmware Interface Specification NBP See Network Boot Program. Network Boot Program A remote boot image downloaded by a PXE client using the Trivial File Transfer Protocol or the Multicast Trivial File Transfer Protocol. Page Memory A set of contiguous pages. Page memory is allocated by AllocatePages() and returned by FreePages(). Partition See System Partition. Partition Discovery The process of scanning a block device to determine whether it contains a Partition.
PAGE 387
Glossary Protocol Handler Services The set of functions used to manipulate handles, protocols, and protocol interfaces. Includes InstallProtocolInterface(), UninstallProtocolInterface(), ReInstallProtocolInterface(), HandleProtocol(), RegisterProtocolNotify(), LocateHandle(),and LocateDevicePath(). Protocol Interface Structure The set of data definitions and functions used to access a particular type of device.
PAGE 388
Extensible Firmware Interface Specification Simple File System Protocol A component of the File System Protocol. It provides a minimal interface for file-type access to a device. Simple Input Protocol A protocol that is used to obtain input from the ConsoleIn device. It is one of two protocols that make up the Console I/O Protocol. Simple Network Protocol A protocol that is used to provide a packet-level interface to a network adapter. Also called the EFI Simple Network Protocol.
PAGE 389
Glossary System Partition A section of a block device that is treated as a logical whole. For a hard disk with a legacy partitioning scheme, it is a contiguous grouping of sectors whose starting sector and size are defined by the Master Boot Record. For an EFI Hard Disk, it is a contiguous grouping of sectors whose starting sector and size are defined by the GUID Partition Table Header and the associated GUID Partition Entries. For “El Torito” devices, it is a logical device volume.
PAGE 390
Extensible Firmware Interface Specification Trivial File Transport Protocol (TFTP) A protocol used to download a Network Boot Program from a TFTP server. Unicode An industry standard internationalized character set used for human readable message display. Unicode Collation Protocol A protocol that is used during boot services to perform case-insensitive comparisons of Unicode strings.
PAGE 391
G 32/64-Bit UNDI Specification G.1 Introduction This appendix defines the 32/64-bit H/W and S/W Universal Network Driver Interfaces (UNDIs). These interfaces provide one method for writing a network driver; other implementations are possible. NOTE This is the Beta-1 version of the 32/64-bit UNDI Specification. G.1.1 Definitions Table G-1.
PAGE 392
Extensible Firmware Interface Specification Table G-1. Definitions (continued) Term Definition PXE Preboot Execution Environment The complete PXE specification covers three areas; the client, the network and the server. Client • Makes network devices into bootable devices. • Provides APIs for PXE protocol modules in EFI and for universal drivers in the OS. Network • Uses existing technology: DHCP, TFTP, etc. • Adds “vendor specific” tags to DHCP to define PXE specific operation within DHCP.
PAGE 393
32/64-bit UNDI Specification Table G-2. Referenced Specification (continued) Acronym Protocol/Specification BOOTP Bootstrap Protocol – http://www.ietf.org/rfc/rfc0951.txt - This reference is included for backward compatibility. BC protocol supports DHCP and BOOTP. Required reading for those implementing the BC protocol or PXE Bootservers. DHCP Dynamic Host Configuration Protocol DHCP for Ipv4 (protocol: http://www.ietf.org/rfc/rfc2131.txt, options: http://www.ietf.org/rfc/rfc2132.
PAGE 394
Extensible Firmware Interface Specification Table G-2. Referenced Specification (continued) Acronym Protocol/Specification TCP Transmission Control Protocol TCPv4: http://www.ietf.org/rfc/rfc0793.txt TCPv6: ftp://ftp.ipv6.org/pub/rfc/rfc2147.txt Required reading for those implementing the BC protocol. TFTP Trivial File Transfer Protocol TFTP over IPv4 (protocol: http://www.ietf.org/rfc/rfc1350.txt, options: http://www.ietf.org/rfc/rfc2347.txt, http://www.ietf.org/rfc/rfc2348.txt and http://www.ietf.
PAGE 395
32/64-bit UNDI Specification Table G-3. Driver Types: Pros and Cons Driver Pro Con Custom • Can be very fast and efficient. NIC vendor tunes driver to OS & device. • New driver for each OS/architecture must be maintained by NIC vendor. • OS vendor does not have to write NIC driver. • OS vendor cannot test all possible driver/NIC versions. • OS vendor must trust code supplied by third-party. • Driver must be installed before NIC can be used.
PAGE 396
Extensible Firmware Interface Specification G.2 Overview There are three major design changes between this specification and the 16-bit UNDI in version 2.1 of the PXE Specification: • A new architectural hardware interface has been added. • All UNDI commands use the same command format. • BC is no longer part of the UNDI ROM. G.2.1 32/64-bit UNDI Interface The !PXE structures are used locate and identify the type of 32/64-bit UNDI interface (H/W or S/W).
PAGE 397
32/64-bit UNDI Specification The !PXE structure for S/W UNDI can be loaded into system memory from one of three places; ROM on a NIC, system non-volatile storage, or external storage. Since there are no direct memory or I/O ports available in the S/W UNDI !PXE structure, an indirect callable entry point is provided. S/W UNDI developers are free to make their internal designs as simple or complex as they desire, as long as all of the UNDI commands in this specification are implemented.
PAGE 398
Extensible Firmware Interface Specification Table G-4. !PXE Structure Field Definitions (continued) Identifier Value Description Implementation Varies Identifies type of UNDI (S/W or H/W, 32 bit or 64 bit) and what features have been implemented. The implementation bits are defined below. Undefined bits must be set to zero by UNDI implementors. Applications/drivers must not rely on the contents of undefined bits (they may change later revisions).
PAGE 399
32/64-bit UNDI Specification Table G-4. !PXE Structure Field Definitions (continued) Identifier Value Description Status Varies UNDI operation, command and interrupt status flags. This is a read-only port. Undefined status bits must be set to zero. Reading this port does NOT clear the status.
PAGE 400
Extensible Firmware Interface Specification Table G-4. !PXE Structure Field Definitions (continued) Identifier Value Description EntryPoint Varies S/W UNDI API entry point address. This is either a virtual address or an offset from the start of the !PXE structure. Protocol drivers will push the 64-bit virtual address of a CDB on the stack and then call the UNDI API entry point. When control is returned to the protocol driver, the protocol driver must remove the address of the CDB from the stack.
PAGE 401
32/64-bit UNDI Specification G.2.1.1 Issuing UNDI Commands How commands are written and status is checked varies a little depending on the type of UNDI (H/W or S/W) implementation being used. The command flowchart below is a high level diagram on how commands are written to both H/W and S/W UNDI. Step 1. Fill in CDB(s). Commands may be linked if supported by UNDI. CDB CDB CDB CDB CDB Step 2 (H/W UNDI) Write physical address of first CDB to CDBaddr register.
PAGE 402
Extensible Firmware Interface Specification G.2.2 UNDI Command Format The format of the CDB is the same for all UNDI commands. Some of the commands do not use or always require the use of all of the fields in the CDB. When fields are not used they must be initialized to zero or the UNDI will return an error. The StatCode and StatFlags fields must always be initialized to zero or the UNDI will return an error.
PAGE 403
32/64-bit UNDI Specification Table G-5. UNDI CDB Field Definitions (continued) Identifier Description CPBsize Command Parameter Block Size This field should be set to a number that is equal to the number of bytes that will be read from CPB structure during command execution. Setting this field to a number that is too small will cause the command to not be executed and a StatCode of PXE_STATCODE_INVALID_CDB will be returned. The contents of the CPB structure will not be modified.
PAGE 404
Extensible Firmware Interface Specification Table G-5. UNDI CDB Field Definitions (continued) Identifier Description IFnum Interface Number This field is used to identify which network adapter (S/W UNDI) or network connector (H/W UNDI) this command is being sent to. If an invalid interface number is given, the command will not execute and a StatCode of PXE_STATCODE_INVALID_CDB will be returned. Control Process Control This bit field is used to control command UNDI inter-command processing.
PAGE 405
32/64-bit UNDI Specification G.3.1.3 PXE_BUSTYPE Used to convert a 4-character ASCII identifier to a 32-bit unsigned integer.
PAGE 406
Extensible Firmware Interface Specification G.3.1.4 PXE_SWAP_UINT16 This macro swaps bytes in a 16-bit word. #ifdef PXE_INTEL_ORDER # define PXE_SWAP_UINT16(n) \ ((((PXE_UINT16)(n) & 0x00FF) << 8) | \ (((PXE_UINT16)(n) & 0xFF00) >> 8)) #else # define PXE_SWAP_UINT16(n) (n) #endif G.3.1.5 PXE_SWAP_UINT32 This macro swaps bytes in a 32-bit word.
PAGE 407
32/64-bit UNDI Specification G.3.1.6 PXE_SWAP_UINT64 This macro swaps bytes in a 64-bit word for compilers that support 64-bit words.
PAGE 408
Extensible Firmware Interface Specification G.3.2 G.3.2.1 Miscellaneous Macros Miscellaneous #define PXE_CPBSIZE_NOT_USED 0 // zero #define PXE_DBSIZE_NOT_USED 0 // zero #define PXE_CPBADDR_NOT_USED (PXE_UINT64)0 // zero #define PXE_DBADDR_NOT_USED (PXE_UINT64)0 // zero G.3.3 Portability Types The examples given below are just that, examples. The actual typedef instructions used in a new implementation may vary depending on the compiler and processor architecture.
PAGE 409
32/64-bit UNDI Specification G.3.3.3 PXE_VOID The void type does not allocate storage. This type is used only to prototype functions that do not return any information and/or do not take any parameters. typedef void PXE_VOID; G.3.3.4 PXE_UINT8 Unsigned 8-bit integer. typedef unsigned char PXE_UINT8; G.3.3.5 PXE_UINT16 Unsigned 16-bit integer. typedef unsigned short PXE_UINT16; G.3.3.6 PXE_UINT32 Unsigned 32-bit integer. typedef unsigned PXE_UINT32; G.3.3.7 PXE_UINT64 Unsigned 64-bit integer.
PAGE 410
Extensible Firmware Interface Specification G.3.4 Simple Types The PXE simple types are defined using one of the portability types from the previous section. G.3.4.1 PXE_BOOL Boolean (true/false) data type. For PXE zero is always false and non-zero is always true. typedef PXE_UINT8 PXE_BOOL; #define PXE_FALSE 0 #define PXE_TRUE (!PXE_FALSE) G.3.4.2 // zero PXE_OPCODE UNDI OpCode (command) descriptions are given in the next chapter.
PAGE 411
32/64-bit UNDI Specification // Change the UNDI operational state from Initialized to Started. #define PXE_OPCODE_SHUTDOWN 0x0007 // Read & change state of external interrupt enables. #define PXE_OPCODE_INTERRUPT_ENABLES 0x0008 // Read & change state of packet receive filters. #define PXE_OPCODE_RECEIVE_FILTERS 0x0009 // Read & change station MAC address. #define PXE_OPCODE_STATION_ADDRESS 0x000A // Read traffic statistics.
PAGE 412
Extensible Firmware Interface Specification G.3.4.
PAGE 413
32/64-bit UNDI Specification //******************************************************* // UNDI Initialize //******************************************************* #define PXE_OPFLAGS_INITIALIZE_CABLE_DETECT_MASK 0x0001 #define PXE_OPFLAGS_INITIALIZE_DETECT_CABLE 0x0000 #define PXE_OPFLAGS_INITIALIZE_DO_NOT_DETECT_CABLE 0x0001 //******************************************************* // UNDI Reset //******************************************************* #define PXE_OPFLAGS_RESET_DISABLE_INTERRUPTS
PAGE 414
Extensible Firmware Interface Specification // Enable receive interrupts. An external interrupt will be // generated after a complete non-error packet has been received. #define PXE_OPFLAGS_INTERRUPT_RECEIVE 0x0001 // Enable transmit interrupts. An external interrupt will be // generated after a complete non-error packet has been // transmitted. #define PXE_OPFLAGS_INTERRUPT_TRANSMIT 0x0002 // Enable command interrupts. An external interrupt will be // generated when command execution stops.
PAGE 415
32/64-bit UNDI Specification #define PXE_OPFLAGS_RECEIVE_FILTER_OPMASK 0xC000 #define PXE_OPFLAGS_RECEIVE_FILTER_ENABLE 0x8000 #define PXE_OPFLAGS_RECEIVE_FILTER_DISABLE 0x4000 #define PXE_OPFLAGS_RECEIVE_FILTER_READ 0x0000 // To reset the contents of the multicast MAC address filter list, // set this OpFlag: #define PXE_OPFLAGS_RECEIVE_FILTERS_RESET_MCAST_LIST 0x2000 // Enable unicast packet receiving. Packets sent to the current // station MAC address will be received.
PAGE 416
Extensible Firmware Interface Specification // Enable promiscuous packet receiving. // received. All packets will be #define PXE_OPFLAGS_RECEIVE_FILTER_PROMISCUOUS // Enable promiscuous multicast packet receiving. // packets will be received.
PAGE 417
32/64-bit UNDI Specification // UNDI NvData //******************************************************* // Select the type of non-volatile data operation. #define PXE_OPFLAGS_NVDATA_OPMASK 0x0001 #define PXE_OPFLAGS_NVDATA_READ 0x0000 #define PXE_OPFLAGS_NVDATA_WRITE 0x0001 //******************************************************* // UNDI Get Status //******************************************************* // // // // Return current interrupt status.
PAGE 418
Extensible Firmware Interface Specification // UNDI Transmit //******************************************************* // S/W UNDI only. Return after the packet has been transmitted. // A transmit complete interrupt will still be generated and the // transmit buffer will have to be recycled.
PAGE 419
32/64-bit UNDI Specification #define PXE_STATFLAGS_COMMAND_QUEUED 0x4000 //******************************************************* // UNDI Get State //******************************************************* #define PXE_STATFLAGS_GET_STATE_MASK 0x0003 #define PXE_STATFLAGS_GET_STATE_INITIALIZED 0x0002 #define PXE_STATFLAGS_GET_STATE_STARTED 0x0001 #define PXE_STATFLAGS_GET_STATE_STOPPED 0x0000 //******************************************************* // UNDI Start //*******************************
PAGE 420
Extensible Firmware Interface Specification //******************************************************* // UNDI Shutdown //******************************************************* // No additional StatFlags //******************************************************* // UNDI Interrupt Enables //******************************************************* // If set, receive interrupts are enabled. #define PXE_STATFLAGS_INTERRUPT_RECEIVE 0x0001 // If set, transmit interrupts are enabled.
PAGE 421
32/64-bit UNDI Specification // If set, all multicast packets will be received.
PAGE 422
Extensible Firmware Interface Specification // If set, at least one receive interrupt occurred. #define PXE_STATFLAGS_GET_STATUS_RECEIVE 0x0001 // If set, at least one transmit interrupt occurred. #define PXE_STATFLAGS_GET_STATUS_TRANSMIT 0x0002 // If set, at least one command interrupt occurred. #define PXE_STATFLAGS_GET_STATUS_COMMAND 0x0004 // If set, at least one software interrupt occurred.
PAGE 423
32/64-bit UNDI Specification G.3.4.5 PXE_STATCODE typedef PXE_UINT16 PXE_STATCODE; #define PXE_STATCODE_INITIALIZE 0x0000 //******************************************************* // Common StatCodes returned by all UNDI commands, UNDI protocol // functions and BC protocol functions.
PAGE 424
Extensible Firmware Interface Specification G.3.4.6 PXE_IFNUM typedef PXE_UINT16 PXE_IFNUM; // This interface number must be passed to the S/W UNDI Start // command. #define PXE_IFNUM_START 0x0000 // This interface number is returned by the S/W UNDI Get State and // Start commands if information in the CDB, CPB or DB is invalid. #define PXE_IFNUM_INVALID G.3.4.
PAGE 425
32/64-bit UNDI Specification G.3.4.8 PXE_FRAME_TYPE typedef PXE_UINT8 PXE_FRAME_TYPE; #define PXE_FRAME_TYPE_NONE 0x00 #define PXE_FRAME_TYPE_UNICAST 0x01 #define PXE_FRAME_TYPE_BROADCAST 0x02 #define PXE_FRAME_TYPE_FILTERED_MULTICAST 0x03 #define PXE_FRAME_TYPE_PROMISCUOUS 0x04 #define PXE_FRAME_TYPE_PROMISCUOUS_MULTICAST 0x05 G.3.4.9 PXE_IPV4 This storage type is always big endian (network order) not little endian (Intel order). typedef PXE_UINT32 PXE_IPV4; G.3.4.
PAGE 426
Extensible Firmware Interface Specification G.3.4.12 PXE_IFTYPE The interface type is returned by the Get Initialization Information command and is used by the BC DHCP protocol function. This field is also used for the low order 8-bits of the H/W type field in ARP packets. The high order 8-bits of the H/W type field in ARP packets will always be set to 0x00 by the BC. typedef PXE_UINT8 PXE_IFTYPE; // This information is from the ARP section of RFC 1700.
PAGE 427
32/64-bit UNDI Specification G.3.5 Compound Types All PXE structures must be byte packed. G.3.5.1 PXE_HW_UNDI This section defines the C structures and #defines for the !PXE H/W UNDI interface.
PAGE 428
Extensible Firmware Interface Specification // If set, last command failed #define PXE_HWSTAT_COMMAND_FAILED 0x20000000 // If set, identifies enabled receive filters #define PXE_HWSTAT_PROMISCUOUS_MULTICAST_RX_ENABLED 0x00001000 #define PXE_HWSTAT_PROMISCUOUS_RX_ENABLED 0x00000800 #define PXE_HWSTAT_BROADCAST_RX_ENABLED 0x00000400 #define PXE_HWSTAT_MULTICAST_RX_ENABLED 0x00000200 #define PXE_HWSTAT_UNICAST_RX_ENABLED 0x00000100 // If set, identifies enabled external interrupts #define PXE_HWST
PAGE 429
32/64-bit UNDI Specification // Use these to enable/disable receive filters.
PAGE 430
Extensible Firmware Interface Specification PXE_UINT64 EntryPoint; // API entry point PXE_UINT8 reserved2[3]; // zero, not used PXE_UINT8 BusCnt; // number of bustypes supported PXE_UINT32 BusType[1]; // list of supported bustypes } PXE_SW_UNDI; #pragma pack() G.3.5.3 PXE_UNDI PXE_UNDI combines both the H/W and S/W UNDI types into one typedef and has #defines for common fields in both H/W and S/W UNDI types.
PAGE 431
32/64-bit UNDI Specification #define PXE_ROMID_IMP_64BIT_DEVICE 0x00010000 #define PXE_ROMID_IMP_FRAG_SUPPORTED 0x00008000 #define PXE_ROMID_IMP_CMD_LINK_SUPPORTED 0x00004000 #define PXE_ROMID_IMP_CMD_QUEUE_SUPPORTED 0x00002000 #define PXE_ROMID_IMP_MULTI_FRAME_SUPPORTED 0x00001000 #define PXE_ROMID_IMP_NVDATA_SUPPORT_MASK 0x00000C00 #define PXE_ROMID_IMP_NVDATA_BULK_WRITABLE 0x00000C00 #define PXE_ROMID_IMP_NVDATA_SPARSE_WRITABLE 0x00000800 #define PXE_ROMID_IMP_NVDATA_READ_ONLY 0x0000040
PAGE 432
Extensible Firmware Interface Specification G.3.5.4 PXE_CDB PXE UNDI command descriptor block. #pragma pack(1) typedef struct s_pxe_cdb { PXE_OPCODE OpCode; PXE_OPFLAGS OpFlags; PXE_UINT16 CPBsize; PXE_UINT16 DBsize; PXE_UINT64 CPBaddr; PXE_UINT64 DBaddr; PXE_STATCODE StatCode; PXE_STATFLAGS StatFlags; PXE_UINT16 IFnum; PXE_CONTROL Control; } PXE_CDB; #pragma pack() G.3.5.5 PXE_IP_ADDR This storage type is always big endian (network order) not little endian (Intel order).
PAGE 433
32/64-bit UNDI Specification G.3.5.6 PXE_DEVICE This typedef is used to identify the network device that is being used by the UNDI. This information is returned by the Get Config Info command. #pragma pack(1) typedef union pxe_device { // PCI and PC Card NICs are both identified using bus, device // and function numbers. For PC Card, this may require PC // Card services to be loaded in the BIOS or preboot // environment.
PAGE 434
Extensible Firmware Interface Specification G.4 UNDI Commands All 32/64-bit UNDI commands use the same basic command format, the CDB (Command Descriptor Block). CDB fields that are not used by a particular command must be initialized to zero by the application/driver that is issuing the command. All UNDI implementations must set the command completion status (PXE_STATFLAGS_COMMAND_COMPLETE) after command execution completes.
PAGE 435
32/64-bit UNDI Specification G.4.1 Command Linking & Queuing When linking commands, the CDBs must be stored consecutively in system memory without any gaps in between. Do not set the Link bit in the last CDB in the list. The Link bit must be set in all other CDBs in the list. Linked CDBs CDB 0x00 0x1F 0x20 Set Link bit. 0x3F 0x40 Set Link bit. 0x5F CDB CDB Do not set Link bit. Figure G-7.
PAGE 436
Extensible Firmware Interface Specification Queued CDBs CDB 0x00 0x1F 0x20 0x3F 0x40 0x5F Set Queue bit. Set Link bit. CDB Do not set Queue bit. Set Link bit. CDB Do not set Queue bit. Do not set Link bit. Figure G-8. Queued CDBs When a command is queued a StatFlag of PXE_STATFLAG_COMMAND_QUEUED is set (if linked commands are queued only the StatFlag of the first CDB gets set). This signals that the command was added to the queue. Commands in the queue will be run on a first-in, first-out, basis.
PAGE 437
32/64-bit UNDI Specification G.4.2.
PAGE 438
Extensible Firmware Interface Specification G.4.3 Start This command is used to change the UNDI operational state from stopped to started. No other operational checks are made by this command. If this is a S/W UNDI, the Delay() and Virt2Phys() functions will not be called by this command. G.4.3.
PAGE 439
32/64-bit UNDI Specification Preparing the CPB The CPB for the S/W UNDI Start command (shown below) must be filled in and the size and address of the CPB must be given in the CDB. #pragma pack(1) typedef struct s_pxe_cpb_start { // PXE_VOID Delay(PXE_UINT64 microseconds); // // // // // UNDI will never request a delay smaller than 10 microseconds and will always request delays in increments of 10 microseconds.
PAGE 440
Extensible Firmware Interface Specification // This field can be set to zero if virtual and physical // addresses are equal. PXE_UINT64 Virt2Phys; PXE_UINT64 Mem_IO; } PXE_CPB_START; #pragma pack() #define PXE_DELAY_MILLISECOND 1000 #define PXE_DELAY_SECOND 1000000 #define PXE_IO_READ 0 #define PXE_IO_WRITE 1 #define PXE_MEM_READ 2 #define PXE_MEM_WRITE 4 G.4.3.2 Waiting for the Command to Execute Monitor the upper two bits (14 & 15) in the CDB.StatFlags field.
PAGE 441
32/64-bit UNDI Specification G.4.4.1 Issuing the Command To issue a Stop command, create a CDB and fill it in as shows in the table below: CDB Field How to initialize the CDB structure for a Stop command OpCode PXE_OPCODE_STOP OpFlags PXE_OPFLAGS_NOT_USED CPBsize PXE_CPBSIZE_NOT_USED DBsize PXE_DBSIZE_NOT_USED CPBaddr PXE_CPBADDR_NOT_USED DBaddr PXE_DBADDR_NOT_USED StatCode PXE_STATCODE_INITIALIZE StatFlags PXE_STATFLAGS_INITIALIZE IFnum A valid interface number from zero to !PXE.
PAGE 442
Extensible Firmware Interface Specification G.4.5.1 Issuing the Command To issue a Get Init Info command, create a CDB and fill it in as shows in the table below: CDB Field How to initialize the CDB structure for a Get Init Info command OpCode PXE_OPCODE_GET_INIT_INFO OpFlags PXE_OPFLAGS_NOT_USED CPBsize PXE_CPBSIZE_NOT_USED DBsize sizeof(PXE_DB_INIT_INFO) CPBaddr PXE_CPBADDR_NOT_USED DBaddr Address of a PXE_DB_INIT_INFO structure.
PAGE 443
32/64-bit UNDI Specification DB #pragma pack(1) typedef struct s_pxe_db_get_init_info { // Minimum length of locked memory buffer that must be given to // the Initialize command. Giving UNDI more memory will // generally give better performance. // If MemoryRequired is zero, the UNDI does not need and will not // use system memory to receive and transmit packets. PXE_UINT32 MemoryRequired; // Maximum frame data length for Tx/Rx excluding the media // header.
PAGE 444
Extensible Firmware Interface Specification // Number of bytes in the NIC hardware (MAC) address. PXE_UINT16 HWaddrLen; // Maximum number of multicast MAC addresses in the multicast // MAC address filter list. PXE_UINT16 MCastFilterCnt; // // // // // Default number and size of transmit and receive buffers that will be allocated by the UNDI. If MemoryRequired is non-zero, this allocation will come out of the memory buffer given to the Initialize command.
PAGE 445
32/64-bit UNDI Specification #define PXE_MAX_TXRX_UNIT_ETHER 1500 #define PXE_HWADDR_LEN_ETHER 0x0006 #define PXE_DUPLEX_ENABLE_FULL_SUPPORTED 1 #define PXE_DUPLEX_FORCE_FULL_SUPPORTED 2 #define PXE_LOOPBACK_INTERNAL_SUPPORTED 1 #define PXE_LOOPBACK_EXTERNAL_SUPPORTED 2 G.4.6 Get Config Info This command is used to retrieve configuration information about the NIC being controlled by the UNDI. G.4.6.
PAGE 446
Extensible Firmware Interface Specification G.4.6.3 Checking Command Execution Results After command execution completes, either successfully or not, the CDB.StatCode field contains the result of the command execution. StatCode Reason SUCCESS Command completed successfully. DB has been written. INVALID_CDB One of the CDB fields was not set correctly. BUSY UNDI is already processing commands. Try again later. QUEUE_FULL Command queue is full. Try again later.
PAGE 447
32/64-bit UNDI Specification typedef struct s_pxe_pcc_config_info { // This is the flag field for the PXE_DB_GET_CONFIG_INFO union. // For PCC bus devices, this field is set to PXE_BUSTYPE_PCC. PXE_UINT32 BusType; // This identifies the PCC network device that this UNDI // interface is bound to. PXE_UINT16 Bus; PXE_UINT8 Device; PXE_UINT8 Function; // This is a copy of the PCC configuration space for this // network device.
PAGE 448
Extensible Firmware Interface Specification G.4.7 Initialize This command resets the network adapter and initializes UNDI using the parameters supplied in the CPB. The Initialize command must be issued before the network adapter can be setup to transmit and receive packets. This command will not enable the receive unit or external interrupts. Once the memory requirements of the UNDI are obtained by using the Get Init Info command, a block of kernel (non-swappable) memory may need to be allocated.
PAGE 449
32/64-bit UNDI Specification Preparing the CPB If the MemoryRequired field returned in the PXE_DB_GET_INIT_INFO structure is zero, the Initialize command does not need to be given a memory buffer or even a CPB structure. If the MemoryRequired field is non-zero, the Initialize command does need a memory buffer. #pragma pack(1) typedef struct s_pxe_cpb_initialize { // // // // Address of first (lowest) byte of the memory buffer. This buffer must be in contiguous physical memory and cannot be swapped out.
PAGE 450
Extensible Firmware Interface Specification // The following configuration parameters are optional and must // be zero to use the default values. PXE_UINT8 Duplex; PXE_UINT8 LoopBack; } PXE_CPB_INITIALIZE; #pragma pack() #define PXE_DUPLEX_DEFAULT 0x00 #define PXE_FORCE_FULL_DUPLEX 0x01 #define PXE_ENABLE_FULL_DUPLEX 0x02 #define LOOPBACK_NORMAL 0 #define LOOPBACK_INTERNAL 1 #define LOOPBACK_EXTERNAL 2 G.4.7.2 Waiting for the Command to Execute Monitor the upper two bits (14 & 15) in the CDB.
PAGE 451
32/64-bit UNDI Specification G.4.7.3 Checking Command Execution Results After command execution completes, either successfully or not, the CDB.StatCode field contains the result of the command execution. StatCode Reason SUCCESS Command completed successfully. UNDI and network device is now initialized. DB has been written. Check StatFlags. INVALID_CDB One of the CDB fields was not set correctly. INVALID_CPB One of the CPB fields was not set correctly. BUSY UNDI is already processing commands.
PAGE 452
Extensible Firmware Interface Specification G.4.8 Reset This command resets the network adapter and re-initializes the UNDI with the same parameters provided in the Initialize command. The transmit and receive queues are emptied and any pending interrupts are cleared. Depending on the state of the OpFlags, the receive filters and external interrupt enables may also be reset. Resetting the network device may take up to four seconds and in some extreme cases (usually poor cables) up to twenty seconds. G.
PAGE 453
32/64-bit UNDI Specification G.4.8.3 Checking Command Execution Results After command execution completes, either successfully or not, the CDB.StatCode field contains the result of the command execution. StatCode Reason SUCCESS Command completed successfully. UNDI and network device have been reset. Check StatFlags. INVALID_CDB One of the CDB fields was not set correctly. BUSY UNDI is already processing commands. Try again later. QUEUE_FULL Command queue is full. Try again later.
PAGE 454
Extensible Firmware Interface Specification G.4.9.
PAGE 455
32/64-bit UNDI Specification G.4.10 Interrupt Enables The Interrupt Enables command can be used to read and/or change the current external interrupt enable settings. Disabling an external interrupt enable prevents an external (hardware) interrupt from being signaled by the network device, internally the interrupt events can still be polled by using the Get Status command. G.4.10.
PAGE 456
Extensible Firmware Interface Specification G.4.10.2 Waiting for the Command to Execute Monitor the upper two bits (14 & 15) in the CDB.StatFlags field. Until these bits change to report PXE_STATFLAGS_COMMAND_COMPLETE or PXE_STATFLAGS_COMMAND_FAILED, the command has not been executed by the UNDI. StatFlags Reason COMMAND_COMPLETE Command completed successfully. Check StatFlags. COMMAND_FAILED Command failed. StatCode field contains error code. COMMAND_QUEUED Command has been queued.
PAGE 457
32/64-bit UNDI Specification G.4.11 Receive Filters This command is used to read and change receive filters and, if supported, read and change the multicast MAC address filter list. G.4.11.1 Issuing the Command To issue a Receive Filters command, create a CDB and fill it in as shows in the table below: CDB Field How to initialize the CDB structure for a Receive Filters command OpCode PXE_OPCODE_RECEIVE_FILTERS OpFlags Set as needed.
PAGE 458
Extensible Firmware Interface Specification Preparing the CPB The receive filter CPB is used to change the contents multicast MAC address filter list. To leave the multicast MAC address filter list unchanged, set the CDB.CPBsize field to PXE_CPBSIZE_NOT_USED and CDB.CPBaddr to PXE_CPBADDR_NOT_USED. To change the multicast MAC address filter list, set CDB.CPBsize to the size, in bytes, of the multicast MAC address filter list and set CDB.
PAGE 459
32/64-bit UNDI Specification G.4.11.3 Checking Command Execution Results After command execution completes, either successfully or not, the CDB.StatCode field contains the result of the command execution. StatCode Reason SUCCESS Command completed successfully. Check StatFlags. DB is written. INVALID_CDB One of the CDB fields was not set correctly. INVALID_CPB One of the CPB fields was not set correctly. BUSY UNDI is already processing commands. Try again later.
PAGE 460
Extensible Firmware Interface Specification G.4.12 Station Address This command is used to get current station and broadcast MAC addresses and, if supported, to change the current station MAC address. G.4.12.1 Issuing the Command To issue a Station Address command, create a CDB and fill it in as shows in the table below: CDB Field How to initialize the CDB structure for a Station Address command OpCode PXE_OPCODE_STATION_ADDRESS OpFlags Set as needed.
PAGE 461
32/64-bit UNDI Specification G.4.12.2 Waiting for the Command to Execute Monitor the upper two bits (14 & 15) in the CDB.StatFlags field. Until these bits change to report PXE_STATFLAGS_COMMAND_COMPLETE or PXE_STATFLAGS_COMMAND_FAILED, the command has not been executed by the UNDI. StatFlags Reason COMMAND_COMPLETE Command completed successfully. DB is written. COMMAND_FAILED Command failed. StatCode field contains error code. COMMAND_QUEUED Command has been queued.
PAGE 462
Extensible Firmware Interface Specification G.4.13 Statistics This command is used to read and clear the NIC traffic statistics. Before using this command check to see if statistics is supported in the !PXE.Implementation flags. G.4.13.1 Issuing the Command To issue a Statistics command, create a CDB and fill it in as shows in the table below: CDB Field How to initialize the CDB structure for a Statistics command OpCode PXE_OPCODE_STATISTICS OpFlags Set as needed.
PAGE 463
32/64-bit UNDI Specification G.4.13.2 Waiting for the Command to Execute Monitor the upper two bits (14 & 15) in the CDB.StatFlags field. Until these bits change to report PXE_STATFLAGS_COMMAND_COMPLETE or PXE_STATFLAGS_COMMAND_FAILED, the command has not been executed by the UNDI. StatFlags Reason COMMAND_COMPLETE Command completed successfully. DB is written. COMMAND_FAILED Command failed. StatCode field contains error code. COMMAND_QUEUED Command has been queued.
PAGE 464
Extensible Firmware Interface Specification PXE_UINT64 Data[64]; } PXE_DB_STATISTICS; // Total number of frames received. // and dropped frames. Includes frames with errors #define PXE_STATISTICS_RX_TOTAL_FRAMES 0x00 // Number of valid frames received and copied into receive // buffers. #define PXE_STATISTICS_RX_GOOD_FRAMES 0x01 // Number of frames below the minimum length for the media. // This would be <64 for ethernet.
PAGE 465
32/64-bit UNDI Specification // Transmit statistics.
PAGE 466
Extensible Firmware Interface Specification G.4.14 MCast IP To MAC Translate a multicast IPv4 or IPv6 address to a multicast MAC address. G.4.14.1 Issuing the Command To issue a MCast IP To MAC command, create a CDB and fill it in as shows in the table below: CDB Field How to initialize the CDB structure for a MCast IP To MAC command OpCode PXE_OPCODE_MCAST_IP_TO_MAC OpFlags Set as needed.
PAGE 467
32/64-bit UNDI Specification G.4.14.2 Waiting for the Command to Execute Monitor the upper two bits (14 & 15) in the CDB.StatFlags field. Until these bits change to report PXE_STATFLAGS_COMMAND_COMPLETE or PXE_STATFLAGS_COMMAND_FAILED, the command has not been executed by the UNDI. StatFlags Reason COMMAND_COMPLETE Command completed successfully. DB is written. COMMAND_FAILED Command failed. StatCode field contains error code. COMMAND_QUEUED Command has been queued.
PAGE 468
Extensible Firmware Interface Specification G.4.15.1 Issuing the Command To issue a NvData command, create a CDB and fill it in as shows in the table below: CDB Field How to initialize the CDB structure for a NvData command OpCode PXE_OPCODE_NVDATA OpFlags Set as needed. CPBsize sizeof(PXE_CPB_NVDATA) DBsize sizeof(PXE_DB_NVDATA) CPBaddr Address of PXE_CPB_NVDATA structure. Dbaddr Address of PXE_DB_NVDATA structure.
PAGE 469
32/64-bit UNDI Specification Sparse NvData CPB typedef struct s_pxe_cpb_nvdata_sparse { // NvData item list. Only items in this list will be updated. struct { // Non-volatile storage address to be changed. PXE_UINT32 Addr; // Data item to write into above storage address. union { PXE_UINT8 Byte; PXE_UINT16 Word; PXE_UINT32 Dword; } Data; } Item[n]; } PXE_CPB_NVDATA_SPARSE; Version 1.
PAGE 470
Extensible Firmware Interface Specification Bulk NvData CPB // When using bulk update, the size of the CPB structure must be // the same size as the non-volatile NIC storage. typedef union u_pxe_cpb_nvdata_bulk { // Array of byte-wide data items. PXE_UINT8 Byte[n]; // Array of word-wide data items. PXE_UINT16 Word[n]; // Array of dword-wide data items. PXE_UINT32 Dword[n]; } PXE_CPB_NVDATA_BULK; G.4.15.2 Waiting for the Command to Execute Monitor the upper two bits (14 & 15) in the CDB.StatFlags field.
PAGE 471
32/64-bit UNDI Specification G.4.15.3 Checking Command Execution Results After command execution completes, either successfully or not, the CDB.StatCode field contains the result of the command execution. StatCode Reason SUCCESS Command completed successfully. Non-volatile data is updated from CPB and/or written to DB. INVALID_CDB One of the CDB fields was not set correctly. INVALID_CPB One of the CPB fields was not set correctly. BUSY UNDI is already processing commands. Try again later.
PAGE 472
Extensible Firmware Interface Specification G.4.16 Get Status This command returns the current interrupt status and/or the transmitted buffer addresses. If the current interrupt status is returned, pending interrupts will be acknowledged by this command. Transmitted buffer addresses that are written to the DB are removed from the transmitted buffer queue. This command may be used in a polled fashion with external interrupts disabled. G.4.16.
PAGE 473
32/64-bit UNDI Specification G.4.16.3 Checking Command Execution Results After command execution completes, either successfully or not, the CDB.StatCode field contains the result of the command execution. StatCode Reason SUCCESS Command completed successfully. StatFlags and/or DB are updated. INVALID_CDB One of the CDB fields was not set correctly. BUSY UNDI is already processing commands. Try again later. QUEUE_FULL Command queue is full. Try again later. NOT_STARTED The UNDI is not started.
PAGE 474
Extensible Firmware Interface Specification Using the DB When reading the transmitted buffer addresses there should be room for at least one 64-bit address in the DB. Once a complete transmitted buffer address is written into the DB, the address is removed from the transmitted buffer queue. If the transmitted buffer queue is full, attempts to use the Transmit command will fail. #pragma pack(1) typedef struct s_pxe_db_get_status { // Length of next receive frame (header + data).
PAGE 475
32/64-bit UNDI Specification G.4.17.1 Issuing the Command To issue a Fill Header command, create a CDB and fill it in as shows in the table below: CDB Field How to initialize the CDB structure for a Fill Header command OpCode PXE_OPCODE_FILL_HEADER OpFlags Set as needed. CPBsize PXE_CPB_FILL_HEADER DBsize PXE_DBSIZE_NOT_USED CPBaddr Address of a PXE_CPB_FILL_HEADER structure.
PAGE 476
Extensible Firmware Interface Specification // Length of packet data in bytes (not including the media // header). PXE_UINT32 PacketLen; // Protocol type. This will be copied into the media header // without doing byte swapping. Protocol type numbers can be // obtained from the Assigned Numbers RFC 1700. PXE_UINT16 Protocol; // Length of the media header in bytes.
PAGE 477
32/64-bit UNDI Specification // Number of packet fragment descriptors. PXE_UINT16 FragCnt; // Reserved, must be set to zero. PXE_UINT16 reserved; // Array of packet fragment descriptors. The first byte of the // media header is the first byte of the first fragment. struct { // Address of this packet fragment. PXE_UINT64 FragAddr; // Length of this packet fragment. PXE_UINT32 FragLen; // Reserved, must be set to zero. PXE_UINT32 reserved; } FragDesc[n]; } PXE_CPB_FILL_HEADER_FRAGMENTED; #pragma pack() G.4.
PAGE 478
Extensible Firmware Interface Specification G.4.17.3 Checking Command Execution Results After command execution completes, either successfully or not, the CDB.StatCode field contains the result of the command execution. StatCode Reason SUCCESS Command completed successfully. Frame is ready to transmit. INVALID_CDB One of the CDB fields was not set correctly. INVALID_CPB One of the CPB fields was not set correctly. BUSY UNDI is already processing commands. Try again later.
PAGE 479
32/64-bit UNDI Specification OpFlags Check the !PXE.Implementation flags to see if the network device support fragmented packets. Select one of the OpFlags below so the UNDI knows what type of CPB is being used. • PXE_OPFLAGS_TRANSMIT_WHOLE • PXE_OPFLAGS_TRANSMIT_FRAGMENTED In addition to selecting whether or not fragmented packets are being given, S/W UNDI needs to know if it should block until the packets are transmitted.
PAGE 480
Extensible Firmware Interface Specification Fragmented Frame #pragma pack(1) typedef struct s_pxe_cpb_transmit_fragments { // Length of packet data in bytes (not including the media // header). PXE_UINT32 FrameLen; // Length of the media header in bytes. PXE_UINT16 MediaheaderLen; // Number of packet fragment descriptors. PXE_UINT16 FragCnt; // Array of frame fragment descriptors. The first byte of the // first fragment is also the first byte of the media header. struct { // Address of this frame fragment.
PAGE 481
32/64-bit UNDI Specification G.4.18.2 Waiting for the Command to Execute Monitor the upper two bits (14 & 15) in the CDB.StatFlags field. Until these bits change to report PXE_STATFLAGS_COMMAND_COMPLETE or PXE_STATFLAGS_COMMAND_FAILED, the command has not been executed by the UNDI. StatFlags Reason COMMAND_COMPLETE Command completed successfully. Use the Get Status command to see when frame buffers can be re-used. COMMAND_FAILED Command failed. StatCode field contains error code.
PAGE 482
Extensible Firmware Interface Specification G.4.19 Receive When the network adapter has received a frame, this command is used to copy the frame into driver/application storage. Once a frame has been copied, it is removed from the receive queue. G.4.19.1 Issuing the Command To issue a Receive command, create a CDB and fill it in as shows in the table below: CDB Field How to initialize the CDB structure for a Receive command OpCode PXE_OPCODE_RECEIVE OpFlags Set as needed.
PAGE 483
32/64-bit UNDI Specification G.4.19.2 Waiting for the Command to Execute Monitor the upper two bits (14 & 15) in the CDB.StatFlags field. Until these bits change to report PXE_STATFLAGS_COMMAND_COMPLETE or PXE_STATFLAGS_COMMAND_FAILED, the command has not been executed by the UNDI. StatFlags Reason COMMAND_COMPLETE Command completed successfully. Frames received and DB is written. COMMAND_FAILED Command failed. StatCode field contains error code. COMMAND_QUEUED Command has been queued.
PAGE 484
Extensible Firmware Interface Specification // Protocol type from media header. PXE_PROTOCOL Protocol; // Length of media header in received frame. PXE_UINT16 MediaHeaderLen; // Type of receive frame. PXE_FRAME_TYPE Type; // Reserved, must be zero. PXE_UINT8 reserved[7]; } PXE_DB_RECEIVE; #pragma pack() G.5 UNDI as an EFI Runtime Driver This section defines the interface between UNDI and EFI and how UNDI must be initialized as an EFI runtime driver.
PAGE 485
32/64-bit UNDI Specification } NII_entry[n]; // the length of this array is given in the NumberOfInterfaces field } UNDI_CONFIG_TABLE; Since there can only be one configuration table associated with any GUID and there can be more than one UNDI loaded, every instance of UNDI must check for any previous installations of the configuration tables and if there are any, it must traverse though the list of all UNDI configuration tables using the nextlink and install itself as the nextlink of the last table in
PAGE 486
Extensible Firmware Interface Specification 468 12/12/00 Version 1.
PAGE 487
H Index _HID, 123 _UID, 123 boot sequence, 319 Boot Services, 25 global functions, 25 handle-based functions, 25 Boot Services Table, EFI, 111 Boot Services, definition of, 360 booting future boot media, 326 via a network device, 326 via Load File Protocol, 326 via Simple File Protocol, 325 booting from CD-ROM and DVD-ROM, 318 diskettes, 317 hard drives, 317 network devices, 318 removable media, 317 BPB.
PAGE 488
Extensible Firmware Interface Specification Device I/O Protocol, 137 Functions AllocateBuffer (), 147, 150 Flush(), 149 Io(), 141 Map(), 144 Mem(), 141 Pci(), 141 PciDevicePath (), 143 Unmap(), 146 GUID, 138 Interface Structure, 138 Device I/O, overview, 137 Device Path for IDE disk, 339 for legacy floppy, 338 for Secondary Root PCI Bus with PCI to PCI Bridge, 341 Device Path Generation, Rules, 133 Hardware vs.
PAGE 489
Index EFI Directory Structure, 306 EFI Driver, 110, 305 EFI Driver, definition of, 363 EFI File, definition of, 363 EFI Image, 105, 109, 305 EFI Image handoff state IA-32, 115 Itanium-based, 116 overview, 111 EFI Image Header, 109 PE32+ image format, 109 EFI Image, definition of, 365 EFI OS Loader, 110, 305 EFI OS loader, definition of, 363 EFI Partition Header, 309 EFI partitioning scheme, 309 EFI Runtime Services Table, 111 EFI System Table, 111 El Torito, 305, 308, 314 error codes, 345, 346 Event Servic
PAGE 490
Extensible Firmware Interface Specification Image Services (cont.) StartImage(), 71 UnloadImage(), 72 overview, 67 images, loading, 13 implementation requirements general, 21 optional elements, 22 required elements, 21, 23 information, resources, 6 Intel Architecture Platform Architecture, definition of, 366 interfaces general categories, 15 purpose, 14 ISO-9660, 314 Itanium architecture firmware specifications, 9 requirements, related to this specification, 9 L LBA.
PAGE 491
Index PCANSI terminals, and SIMPLE_TEXT_OUTPUT, 334 PCI Expansion ROM, 327 driver for EFI, 329 image types, 329 PCI Expansion ROM Header EFI, 328 standard, 327 PE32+ image format, 109 plug and play option ROMs and boot services, 14 PMBR.
PAGE 492
Extensible Firmware Interface Specification Simple File System Protocol, 187 functions OpenVolume(), 189 GUID, 187 Interface Structure, 187 Revision Number, 187 Simple Input Protocol, 152, 154 Functions ReadDisk(), 155 ReadKeyStroke(), 156 GUID, 154 Interface Structure, 154 Scan Codes for, 152 Simple Network Protocol, 235, 246, 277 Functions GetStatus(), 296 Initialize(), 284 MCastIPtoMAC(), 293 NVData(), 294 Receive(), 300 ReceiveFilters(), 287 Reset(), 285 Shutdown(), 286 Start(), 282 StationAddress(), 2
PAGE 493
Index variables global, 323 non-volatile, 323 Virtual Memory Services function list, 91 functions ConvertPointer(), 94 SetVirtualAddressMap (), 92 overview, 91 U UNDI Specification, 32/64-Bit, 373 Unicode Collation Protocol, 225 Functions FatToStr(), 232 MetaiMatch(), 228 StriColl(), 227 StrLwr(), 230 StrToFat(), 233 StrUpr(), 231 GUID, 225 Interface Structure, 225 Unicode control characters, supported, 152 Unicode, definition of, 372 W warning codes, 346 Watchdog timer, definition of, 372 web sites, 6 W
PAGE 494
Extensible Firmware Interface Specification 476 12/12/00 Version 1.