Intel Extensible Firmware Interface D Status Codes

Version 1.02 12/12/00 345

DStatus 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. Success and warning codes

have their highest bit clear, so all success and warning codes have positive values. The range of

status codes that have both the highest bit clear and the next to highest bit clear are reserved for use

by EFI. The range of status code that have the highest bit clear and the next to highest bit set are

reserved for use by OEMs. Table D-1 lists the status code ranges described above.

Table D-1. EFI_STATUS Codes Ranges

IA-32 Range IA-64 Range Description

0x00000000-

0x3fffffff

0x0000000000000000-

0x3fffffffffffffff

Success and warning codes reserved for use by EFI.

See Tables D-2 and D-4 for valid values in this range.

0x40000000-

0x7fffffff

0x4000000000000000-

0x7fffffffffffffff

Success and warning codes reserved for use by OEMs.

0x80000000-

0xbfffffff

0x8000000000000000-

0xbfffffffffffffff

Error codes reserved for use by EFI. See Table D-3 for

valid values for this range.

0xc0000000-

0xffffffff

0xc000000000000000-

0xffffffffffffffff

Error codes reserved for use by OEMs.

Table D-2. EFI_STATUS Success Codes (High bit clear)

Mnemonic Value Description

EFI_SUCCESS 0 The operation completed successfully.

Table D-3. EFI_STATUS Error Codes (High bit set)

Mnemonic Value Description

EFI_LOAD_ERROR 1 The image failed to load.

EFI_INVALID_PARAMETER 2 A parameter was incorrect.

EFI_UNSUPPORTED 3 The operation is not supported.

EFI_BAD_BUFFER_SIZE 4 The buffer was not the proper size for the request.

EFI_BUFFER_TOO_SMALL 5 The buffer is not large enough to hold the requested data.

The required buffer size is returned in the appropriate

parameter when this error occurs.

continued

Contents

Main Extensible Firmware Interface Specification ii 12/12/00 Version 1.02 Page Page Table of Contents 1 Introduction 2 Overview 3 Services 4 EFI Image Page 6 Device I/O Protocol 7 Console I/O Protocol 8 Block I/O Protocol 9 Disk I/O Protocol 10 File System Protocol 11 Load File Protocol 12 Serial I/O Protocol 13 Unicode Collation Protocol 14 PXE Base Code Protocol35 15 Simple Network Protocol 16 File System Format Page G 32/64-Bit UNDI Specification Index Figures Tables Page Page Page 1 Introduction 1.1 Overview This specification is organized as follows: Table 1-1. Organization of EFI Specification 1.2 Goals Page 1.3 Target Audience 1.4 Related Information Page 1.5 Prerequisite Specifications 1.5.1 ACPI Specification 1.5.2 WfM Specification 1.5.3 Additional Considerations for Itanium-based Platforms 1.6 EFI Design Overview Page 1.7 Migration Requirements 1.7.1 Legacy Operating System Support 1.7.2 Supporting the EFI Specification on a Legacy Platform 1.8 Conventions Used in This Document 1.8.1 Data Structure Descriptions 1.8.2 Typographic Conventions 1.9 Guidelines for Use of the Term Extensible Firmware Interface 2 Overview 2.1 Boot Manager 2.2 Firmware Core 2.2.1 EFI Services 2.2.2 Runtime Services 2.3 Calling Conventions 2.3.1 Data Types Table 2-2. Common EFI Data Types (continued) Table 2-3. Modifiers for Common EFI Data Types 2.3.2 IA-32 Platforms 2.3.3 Itanium-based Platforms 2.4 Protocols Handle The following C code fragment illustrates the use of protocols: Table 2-4 lists the EFI protocols defined by this specification. Table 2-4. EFI Protocols 2.5 Requirements 2.5.1 Required Elements Table 2-5. Required EFI Implementation Elements (continued) 2.5.2 Optional Elements Table 2-6. Optional EFI Implementation Elements Page Page 3 Services 3.1 Event, Timer, and Task Priority Services Page Page 3.1.1 CreateEvent() Page Page Page Page Page 3.1.4 WaitForEvent() Page 3.1.6 SetTimer() Page Page Page Page 3.2 Memory Allocation Services Table 3-5. Memory Type Usage Before ExitBootServices() Page 3.2.1 AllocatePages() Page Page Page 3.2.3 GetMemoryMap() Page Page Page Page Page 3.3 Protocol Handler Services ... 3.3.1 InstallProtocolInterface() Page 3.3.2 UninstallProtocolInterface() 3.3.3 ReinstallProtocolInterface() 3.3.4 RegisterProtocolNotify() 3.3.5 LocateHandle() Page Page 3.3.7 LocateDevicePath() Page Services Version 1.02 12/12/00 67 3.4 Image Services Table 3-8. Image Type Differences Summary EFI Application EFI Boot Services Driver EFI Runtime Services Driver Page 3.4.1 LoadImage() Page Page Page 3.4.4 EFI_IMAGE_ENTRY_POINT 3.4.5 Exit() Page Page 3.5 Variable Services 3.5.1 GetVariable() Page 3.5.2 GetNextVariableName() Page 3.5.3 SetVariable() Page 3.6 Time Services 3.6.1 GetTime() Page Page Page Page 3.6.4 SetWakeupTime() 3.7 Virtual Memory Services 3.7.1 SetVirtualAddressMap() Page Page 3.8 Miscellaneous Services 3.8.1 ResetSystem() Page 3.8.2 SetWatchdogTimer() Page Page Page 3.8.5 GetNextHighMonotonicCount() 3.8.6 InstallConfigurationTable() Page 4 EFI Image 4.1 LOADED_IMAGE Protocol Page Page Page 4.2 EFI Image Header 4.3 EFI Applications 4.4 EFI OS Loaders 4.5 EFI Drivers 4.5.1 EFI Image Handoff State Page Page Page 4.5.1.1 IA-32 Handoff State Figure 4-1. Stack after ImageEntryPoint Called, IA-32 EFI_SYSTEM_TABLE * EFI_HANDLE Stack ESP + 8 ESP + 4 4.5.1.2 Handoff State, Itanium-based Operating Systems Stack Location Register 5 Device Path Protocol 5.1 Device Path Overview 5.2 EFI_DEVICE_PATH Protocol 5.3 Device Path Nodes 5.3.1 Generic Device Path Structures 5.3.2 Hardware Device Path 5.3.2.1 PCI Device Path 5.3.2.2 PCCARD Device Path 5.3.2.3 Memory Mapped Device Path Table 5-5. Memory Mapped Device Path 5.3.2.4 Vendor Device Path Table 5-6. Vendor-Defined Device Path 5.3.2.5 Controller Device Path 5.3.3 ACPI Device Path 5.3.4 Messaging Device Path 5.3.4.1 ATAPI Device Path Table 5-9. ATAPI Device Path 5.3.4.2 SCSI Device Path Table 5-10. SCSI Device Path 5.3.4.3 Fibre Channel Device Path 5.3.4.4 1394 Device Path Table 5-12. 1394 Device Path EFI_GUID type defined in the EFI Specification. 5.3.4.5 USB Device Path Table 5-13. USB Device Path 5.3.4.6 USB Class Device Path Table 5-14. USB Class Device Path 5.3.4.7 I2O Device Path Table 5-15. I2O Device Path 5.3.4.8 MAC Address Device Path 5.3.4.9 IPv4 Device Path Table 5-17. IPv4 Device Path 5.3.4.10 IPv6 Device Path Table 5-18. IPv6 Device Path 5.3.4.11 InfiniBand Device Path Table 5-19. InfiniBand Device Path EFI_GUID type defined in the EFI Specification. 5.3.4.12 UART Device Path Table 5-20. UART Device Path 5.3.4.13 Vendor-Defined Messaging Device Path 5.3.5 Media Device Path 5.3.5.1 Hard Drive Table 5-22. Hard Drive Media Device Path The following structure defines an MBR for EFI: 5.3.5.2 CD-ROM Media Device Path Table 5-23. CD-ROM Media Device Path 5.3.5.3 Vendor-Defined Media Device Path Table 5-24. Vendor-Defined Media Device Path 5.3.5.4 File Path Media Device Path Table 5-25. File Path Media Device Path 5.3.5.5 Media Protocol Device Path Table 5-26. Media Protocol Media Device Path 5.3.6 BIOS Boot Specification Device Path 5.4 Device Path Generation Rules 5.4.1 Housekeeping Rules 5.4.2 Rules with ACPI _HID and _UID 5.4.3 Rules with ACPI _ADR 5.4.4 Hardware vs. Messaging Device Path Rules 5.4.5 Media Device Path Rules 5.4.6 Other Rules 6 Device I/O Protocol 6.1 Device I/O Overview 6.2 DEVICE_IO Protocol Page Page 6.2.1 DEVICE_IO.Mem(), .Io(), and .Pci() Page 6.2.2 DEVICE_IO.PciDevicePath() 6.2.3 DEVICE_IO.Map() Page Page 6.2.5 DEVICE_IO.AllocateBuffer() Page Page Page 7 Console I/O Protocol 7.1 Console I/O Overview 7.2 ConsoleIn Definition Table 7-2. EFI Scan Codes for SIMPLE_INPUT_INTERFACE (continued) 7.3 SIMPLE_INPUT Protocol Page Page 7.4 ConsoleOut or StandardError 7.5 SIMPLE_TEXT_OUTPUT Protocol Page Page Page 7.5.2 SIMPLE_TEXT_OUTPUT.OutputString() Page Page Page Page Page 7.5.6 SIMPLE_TEXT_OUTPUT.SetAttribute() Page Page Page Page Page 8 Block I/O Protocol 8.1 BLOCK_IO Protocol Page Page Page Page Page Page Page Page Page 9 Disk I/O Protocol 9.1 DISK_IO Protocol Page 9.1.1 EFI_DISK_IO.ReadDisk() Page 10 File System Protocol 10.1 Simple File System Protocol Page Page 10.2 EFI_FILE Protocol Page 10.2.1 EFI_FILE.Open() Page Page Page Page 10.2.4 EFI_FILE.Read() 10.2.5 EFI_FILE.Write() Page Page 10.2.8 EFI_FILE.GetInfo() 10.2.9 EFI_FILE.SetInfo() Page 10.2.11 EFI_FILE_INFO Page Page Page Page 11 Load File Protocol 11.1 LOAD_FILE Protocol 11.1.1 LOAD_FILE.LoadFile() Page Page 12 Serial I/O Protocol 12.1 SERIAL_IO Protocol Page Page Page Page 12.1.2 SERIAL_IO.SetAttributes() Page 12.1.3 SERIAL_IO.SetControl() Page Page Page Page 13 Unicode Collation Protocol 13.1 UNICODE_COLLATION Protocol Page Page 13.1.2 UNICODE_COLLATION.MetaiMatch() Page Page Page Page Page Page 14 PXE Base Code Protocol 14.1 EFI_PXE_BASE_CODE Protocol Page Page Page Page Page Page Page Page Page Table 14-1. PXE Tag Definitions for EFI Page 14.1.1 EFI_PXE_BASE_CODE.Start() Page Page Page 14.1.3 EFI_PXE_BASE_CODE.Dhcp() Page 14.1.4 EFI_PXE_BASE_CODE.Discover() Page Page Page 14.1.5 EFI_PXE_BASE_CODE.Mtftp() Page Page Page 14.1.6 EFI_PXE_BASE_CODE.UdpWrite() Page 14.1.7 EFI_PXE_BASE_CODE.UdpRead() Page Page 14.1.8 EFI_PXE_BASE_CODE.SetIpFilter() 14.1.9 EFI_PXE_BASE_CODE.Arp() 14.1.10 EFI_PXE_BASE_CODE.SetParameters() Page Page 14.1.12 EFI_PXE_BASE_CODE.SetPackets() Page 14.2 EFI_PXE_BASE_CODE_CALLBACK Protocol 14.2.1 EFI_PXE_BASE_CODE_CALLBACK.Callback() Page Page 15 Simple Network Protocol 15.1 EFI_SIMPLE_NETWORK Protocol Page Page Page Page Page Page Page Page Page 15.1.6 EFI_SIMPLE_NETWOR K.ReceiveFilters() Page Page 15.1.8 EFI_SIMPLE_NETWOR K.Statistics() Page Page Page 15.1.10 EFI_SIMPLE_NETWOR K.NvData() Page 15.1.11 EFI_SIMPLE_NETWOR K.GetStatus() Page 15.1.12 EFI_SIMPLE_NETWOR K.Transmit() Page 15.1.13 EFI_SIMPLE_NETWOR K.Receive() Page 15.2 NETWORK_INTERFACE_IDENTIFIER Protocol Page Page 16 File System Format 16.1 System Partition 16.1.1 File System Format 16.1.2 File Names 16.1.3 Directory Structure Page 16.2 Partition Discovery DISK PartitionPartition BLOCK_IO Hdl 16.2.1 EFI Partition Header Partition PMBR Partition 1 Table HDR Partition Table HDR Table 16-1. GUID Partition Table Header Page Page 16.2.2 ISO-9660 and El Torito 16.2.3 Legacy Master Boot Record Page 16.2.4 Legacy Master Boot Record and GPT Partitions 16.3 Media Formats 16.3.1 Removable Media 16.3.2 Diskette 16.3.3 Hard Drive 16.3.4 CD-ROM and DVD-ROM 16.3.5 Network 17 Boot Manager 17.1 Firmware Boot Manager Page Descriptor Page 17.2 Globally-Defined Variables Page 17.3 Boot Option Variables Default Behavior 17.4 Boot Mechanisms 17.4.1 Boot via Simple File Protocol 17.4.1.1 Removable Media Boot Behavior 17.4.2 Boot via LOAD_FILE Protocol 17.4.2.1 Network Booting 17.4.2.2 Future Boot Media 18 PCI Expansion ROM 18.1 Standard PCI Expansion ROM Header 18.2 EFI PCI Expansion ROM Header 18.3 Multiple Image Format Support 18.4 EFI PCI Expansion ROM Driver Page A GUID and Time Formats Page B Console B.1 SIMPLE_INPUT Table B-1. EFI Scan Codes for SIMPLE_INPUT (continued) B.2 SIMPLE_TEXT_OUTPUT Table B-2. Control Sequences that Can Be Used to Implement SIMPLE_TEXT_OUTPUT Table B-2. Control Sequences that Can Be Used to Implement SIMPLE_TEXT_OUTPUT (continued) Page C Device Path Examples C.1 Example Computer System C.2 Legacy Floppy C.3 IDE Disk Page C.4 Secondary Root PCI Bus with PCI to PCI Bridge C.5 ACPI Terms Device Path Examples Version 1.02 12/12/00 343 C.6 EFI Device Path as a Name Space Figure C-3. EFI Device Path Displayed As a Name Space Key Page D Status Codes Table D-3. EFI_STATUS Error Codes (High bit set) (continued) Table D-4. EFI_STATUS Warning Codes (High bit clear) E Alphabetic Function Lists Table E-1. Functions Listed in Alphabetic Order Page Page Page Page Page Page Table E-2. Functions Listed Alphabetically Within Service or Protocol Page Page Page Page F Glossary Page Page Page Page Page Page Page Page Page Page Page Page Page G 32/64-Bit UNDI Specification G.1 Introduction G.1.1 Definitions Table G-1. Definitions Table G-1. Definitions (continued) G.1.2 Referenced Specifications Table G-2. Referenced Specification Page Table G-2. Referenced Specification (continued) G.1.3 OS Network Stacks Figure G-1. Network Stacks with Three Classes of Drivers H/W UNDI S/W UNDI Custom Table G-3. Driver Types: Pros and Cons G.2 Overview G.2.1 32/64-bit UNDI Interface !PXE Page Page Page Page 32/64-bit UNDI Specification Version 1.02 12/12/00 383 G.2.1.1 Issuing UNDI Commands Figure G-3. Issuing UNDI Commands G.2.2 UNDI Command Format CDB Table G-5. UNDI CDB Field Definitions (continued) G.3 UNDI C Definitions G.3.1 Portability Macros G.3.1.1 PXE_INTEL_ORDER or PXE_NETWORK_ORDER G.3.1.2 PXE_UINT64_SUPPORT or PXE_NO_UINT64_SUPPORT G.3.1.3 PXE_BUSTYPE G.3.1.4 PXE_SWAP_UINT16 G.3.1.5 PXE_SWAP_UINT32 G.3.1.6 PXE_SWAP_UINT64 Page Page G.3.4 Simple Types G.3.4.1 PXE_BOOL G.3.4.2 PXE_OPCODE Page G.3.4.3 PXE_OPFLAGS Page Page Page Page Page G.3.4.4 PXE_STATFLAGS Page Page Page Page G.3.4.5 PXE_STATCODE G.3.4.6 PXE_IFNUM G.3.4.7 PXE_CONTROL Page G.3.4.12 PXE_IFTYPE G.3.5 Compound Types G.3.5.1 PXE_HW_UNDI Page G.3.5.2 PXE_SW_UNDI G.3.5.3 PXE_UNDI Page G.3.5.4 PXE_CDB G.3.5.5 PXE_IP_ADDR G.3.5.6 PXE_DEVICE G.4 UNDI Commands G.4.1 Command Linking & Queuing Linked CDBs Queued CDBs G.4.2 Get State G.4.2.1 Issuing the Command G.4.2.2 Waiting for the Command to Execute G.4.2.3 Checking Command Execution Results G.4.3 Start G.4.3.1 Issuing the Command To issue a Start command for H/W UNDI, create a CDB and fill it in as shows in the table below: To issue a Start command for S/W UNDI, create a CDB and fill it in as shows in the table below: Page G.4.3.2 Waiting for the Command to Execute G.4.3.3 Checking Command Execution Results G.4.4 Stop G.4.4.1 Issuing the Command G.4.4.2 Waiting for the Command to Execute G.4.4.3 Checking Command Execution Results G.4.5 Get Init Info G.4.5.1 Issuing the Command G.4.5.2 Waiting for the Command to Execute G.4.5.3 Checking Command Execution Results Page Page G.4.6 Get Config Info G.4.6.1 Issuing the Command G.4.6.2 Waiting for the Command to Execute G.4.6.3 Checking Command Execution Results Page G.4.7 Initialize G.4.7.1 Issuing the Command Page G.4.7.2 Waiting for the Command to Execute G.4.7.3 Checking Command Execution Results G.4.8 Reset G.4.8.1 Issuing the Command G.4.8.2 Waiting for the Command to Execute G.4.8.3 Checking Command Execution Results G.4.9 Shutdown G.4.9.1 Issuing the Command G.4.9.2 Waiting for the Command to Execute G.4.9.3 Checking Command Execution Results G.4.10 Interrupt Enables G.4.10.1 Issuing the Command G.4.10.2 Waiting for the Command to Execute G.4.10.3 Checking Command Execution Results G.4.11 Receive Filters G.4.11.1 Issuing the Command G.4.11.2 Waiting for the Command to Execute G.4.11.3 Checking Command Execution Results G.4.12 Station Address G.4.12.1 Issuing the Command G.4.12.2 Waiting for the Command to Execute G.4.12.3 Checking Command Execution Results G.4.13 Statistics G.4.13.1 Issuing the Command G.4.13.2 Waiting for the Command to Execute G.4.13.3 Checking Command Execution Results Page Page G.4.14 MCast IP To MAC G.4.14.1 Issuing the Command G.4.14.2 Waiting for the Command to Execute G.4.14.3 Checking Command Execution Results G.4.15 NvData G.4.15.1 Issuing the Command Sparse NvData CPB Bulk NvData CPB G.4.15.2 Waiting for the Command to Execute G.4.15.3 Checking Command Execution Results G.4.16 Get Status G.4.16.1 Issuing the Command Setting OpFlags G.4.16.2 Waiting for the Command to Execute G.4.16.3 Checking Command Execution Results Using the DB G.4.17 Fill Header G.4.17.1 Issuing the Command Non-Fragmented Frame Fragmented Frame G.4.17.2 Waiting for the Command to Execute G.4.17.3 Checking Command Execution Results G.4.18 Transmit G.4.18.1 Issuing the Command Non-Fragmented Frame Fragmented Frame G.4.18.2 Waiting for the Command to Execute G.4.18.3 Checking Command Execution Results G.4.19 Receive G.4.19.1 Issuing the Command G.4.19.2 Waiting for the Command to Execute G.4.19.3 Checking Command Execution Results Using the DB G.5 UNDI as an EFI Runtime Driver Page Page H Index A B C D E F G H I L M N O P R S T U V W