4. EFI System Table

This section describes the entry point to a UEFI image and the parameters that are passed to that entry point. There are three types of UEFI images that can be loaded and executed by firmware conforming to this specification. These are UEFI applications (UEFI Applications), UEFI boot service drivers (UEFI Drivers ), and UEFI runtime drivers (UEFI Drivers). UEFI applications include UEFI OS loaders (UEFI OS Loaders). There are no differences in the entry point for these three image types.

4.1. UEFI Image Entry Point

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

4.1.1. EFI_IMAGE_ENTRY_POINT

Summary

This is the main entry point for a UEFI Image. This entry point is the same for UEFI applications and UEFI drivers.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_IMAGE_ENTRY_POINT) (
  IN EFI_HANDLE                  ImageHandle,
  IN EFI_SYSTEM_TABLE            *SystemTable
  );

Parameters

ImageHandle

The firmware allocated handle for the UEFI image.

SystemTable

A pointer to the EFI System Table.

Description

This function is the entry point to an EFI image. An EFI image is loaded and relocated in system memory by the EFI Boot Service EFI_BOOT_SERVICES.LoadImage() . An EFI image is invoked through the EFI Boot Service EFI_BOOT_SERVICES.StartImage().

The first argument is the image’s image handle. The second argument is a pointer to the image’s system table. The system table contains the standard output and input handles, plus pointers to the EFI_BOOT_SERVICES and EFI_RUNTIME_SERVICES tables. The service tables contain the entry points in the firmware for accessing the core EFI system functionality. The handles in the system table are used to obtain basic access to the console. In addition, the System Table contains pointers to other standard tables that a loaded image may use if the associated pointers are initialized to nonzero values. Examples of such tables are ACPI, SMBIOS, SAL System Table, etc.

The ImageHandle is a firmware-allocated handle that is used to identify the image on various functions. The handle also supports one or more protocols that the image can use. All images support the EFI_LOADED_IMAGE_PROTOCOL and the EFI_LOADED_IMAGE_DEVICE_PATH_PROTOCOL that returns the source location of the image, the memory location of the image, the load options for the image, etc. The exact EFI_LOADED_IMAGE_PROTOCOL and EFI_LOADED_IMAGE_DEVICE_PATH_PROTOCOL structures are defined in EFI_LOADED_IMAGE_PROTOCOL.Unload() .

If the UEFI image is a UEFI application that is not a UEFI OS loader, then the application executes and either returns or calls the EFI Boot Services EFI_BOOT_SERVICES.Exit() . A UEFI application is always unloaded from memory when it exits, and its return status is returned to the component that started the UEFI application.

If the UEFI image is a UEFI OS Loader, then the UEFI OS Loader executes and either returns, calls the EFI Boot Service Exit() , or calls the EFI Boot Service EFI_BOOT_SERVICES.ExitBootServices() . If the EFI OS Loader returns or calls Exit() , then the load of the OS has failed, and the EFI OS Loader is unloaded from memory and control is returned to the component that attempted to boot the UEFI OS Loader. If ExitBootServices() is called, then the UEFI OS Loader has taken control of the platform, and EFI will not regain control of the system until the platform is reset. One method of resetting the platform is through the EFI Runtime Service ResetSystem() .

If the UEFI image is a UEFI Driver, then the UEFI driver executes and either returns or calls the Boot Service Exit() . If the UEFI driver returns an error, then the driver is unloaded from memory. If the UEFI driver returns EFI_SUCCESS , then it stays resident in memory. If the UEFI driver does not follow the UEFI Driver Model, then it performs any required initialization and installs its protocol services before returning. If the driver does follow the UEFI Driver Model, then the entry point is not allowed to touch any device hardware. Instead, the entry point is required to create and install the EFI Driver Binding Protocol ( EFI Driver Binding Protocol ) on the ImageHandle of the UEFI driver. If this process is completed, then EFI_SUCCESS is returned. If the resources are not available to complete the UEFI driver initialization, then EFI_OUT_OF_RESOURCES is returned.

Status Codes Returned

EFI_SUCCESS

The driver was initialized.

EFI_OUT_OF_RESOURCES

The request could not be completed due to a lack of resources.

4.2. EFI Table Header

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

4.2.1. EFI_TABLE_HEADER

Summary

Data structure that precedes all of the standard EFI table types.

Related Definitions

typedef struct {
  UINT64      Signature;
  UINT32      Revision;
  UINT32      HeaderSize;
  UINT32      CRC32;
  UINT32      Reserved;
 } EFI_TABLE_HEADER;

Parameters

Signature

A 64-bit signature that identifies the type of table that follows. Unique signatures have been generated for the EFI System Table, the EFI Boot Services Table, and the EFI Runtime Services Table.

Revision

The revision of the EFI Specification to which this table conforms. The upper 16 bits of this field contain the major revision value, and the lower 16 bits contain the minor revision value. The minor revision values are binary coded decimals and are limited to the range of 00..99.

When printed or displayed UEFI spec revision is referred as (Major revision).(Minor revision upper decimal).(Minor revision lower decimal) or (Major revision).(Minor revision upper decimal) in case Minor revision lower decimal is set to 0. For example:

Specification with the revision value ((2<<16) | (30)) would be referred as 2.3;

A specification with the revision value ((2<<16) | (31)) would be referred as 2.3.1

HeaderSize

The size, in bytes, of the entire table including the FI_TABLE_HEADER.

CRC32

The 32-bit CRC for the entire table. This value is computed by setting this field to 0, and computing the 32-bit CRC for HeaderSize bytes.

Reserved

Reserved field that must be set to 0.

NOTE: The capabilities found in the EFI system table, runtime table and boot services table may change over time. The first field in each of these tables is an EFI_TABLE_HEADER. This header’s Revision field is incremented when new capabilities and functions are added to the functions in the table. When checking for capabilities, code should verify that Revision is greater than or equal to the revision level of the table at the point when the capabilities were added to the UEFI specification.

NOTE: Unless otherwise specified, UEFI uses a standard CCITT32 CRC algorithm with a seed polynomial value of 0x04c11db7 for its CRC calculations.

NOTE: The size of the system table, runtime services table, and boot services table may increase over time. It is very important to always use the HeaderSize field of the EFI_TABLE_HEADER to determine the size of these tables.

4.3. EFI System Table

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

4.3.1. EFI_SYSTEM_TABLE

Summary

Contains pointers to the runtime and boot services tables.

Related Definitions

#define EFI_SYSTEM_TABLE_SIGNATURE 0x5453595320494249
#define EFI_2_90_SYSTEM_TABLE_REVISION ((2<<16) | (90))
#define EFI_2_80_SYSTEM_TABLE_REVISION ((2<<16) | (80))
#define EFI_2_70_SYSTEM_TABLE_REVISION ((2<<16) | (70))
#define EFI_2_60_SYSTEM_TABLE_REVISION ((2<<16) | (60))
#define EFI_2_50_SYSTEM_TABLE_REVISION ((2<<16) | (50))
#define EFI_2_40_SYSTEM_TABLE_REVISION ((2<<16) | (40))
#define EFI_2_31_SYSTEM_TABLE_REVISION ((2<<16) | (31))
#define EFI_2_30_SYSTEM_TABLE_REVISION ((2<<16) | (30))
#define EFI_2_20_SYSTEM_TABLE_REVISION ((2<<16) | (20))
#define EFI_2_10_SYSTEM_TABLE_REVISION ((2<<16) | (10))
#define EFI_2_00_SYSTEM_TABLE_REVISION ((2<<16) | (00))
#define EFI_1_10_SYSTEM_TABLE_REVISION ((1<<16) | (10))
#define EFI_1_02_SYSTEM_TABLE_REVISION ((1<<16) | (02))
#define EFI_SPECIFICATION_VERSION    EFI_SYSTEM_TABLE_REVISION
#define EFI_SYSTEM_TABLE_REVISION    EFI_2_90_SYSTEM_TABLE_REVISION

typedef struct {
  EFI_TABLE_HEADER                 Hdr;
  CHAR16                           *FirmwareVendor;
  UINT32                           FirmwareRevision;
  EFI_HANDLE                       ConsoleInHandle;
  EFI_SIMPLE_TEXT_INPUT_PROTOCOL   *ConIn;
  EFI_HANDLE                       ConsoleOutHandle;
  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *ConOut;
  EFI_HANDLE                       StandardErrorHandle;
  EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL  *StdErr;
  EFI_RUNTIME_SERVICES             *RuntimeServices;
  EFI_BOOT_SERVICES                *BootServices;
  UINTN                            NumberOfTableEntries;
  EFI_CONFIGURATION_TABLE          *ConfigurationTable;
} EFI_SYSTEM_TABLE;

Parameters

Hdr

The table header for the EFI System Table. This header contains the EFI_SYSTEM_TABLE_SIGNATURE and EFI_SYSTEM_TABLE_REVISION values along with the size of the EFI_SYSTEM_TABLE structure and a 32-bit CRC to verify that the contents of the EFI System Table are valid.

FirmwareVendor

A pointer to a null terminated string that identifies the vendor that produces the system firmware for the platform.

FirmwareRevision

A firmware vendor specific value that identifies the revision of the system firmware for the platform.

ConsoleInHandle

The handle for the active console input device. This handle must support EFI_SIMPLE_TEXT_INPUT_PROTOCOL and EFI_SIMPLE_TEXT_INPUT_EX_PROTOCOL . If there is no active console, these protocols must still be present.

ConIn

A pointer to the EFI_SIMPLE_TEXT_INPUT_PROTOCOL interface that is associated with ConsoleInHandle.

ConsoleOutHandle

The handle for the active console output device. This handle must support the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL.

If there is no active console, this protocol must still be present.

ConOut

A pointer to the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL interface that is associated with ConsoleOutHandle.

StandardErrorHandle

The handle for the active standard error console device. This handle must support the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL. If there is no active console, this protocol must still be present.

StdErr

A pointer to the EFI_SIMPLE_TEXT_OUTPUT_PROTOCOL interface that is associated with StandardErrorHandle.

RuntimeServices

A pointer to the EFI Runtime Services Table.

BootServices

A pointer to the EFI Boot Services Table. See ref:efi-boot-services-table_efi_system_table.

NumberOfTableEntries

The number of system configuration tables in the buffer ConfigurationTable.

ConfigurationTable

A pointer to the system configuration tables. The number of entries in the table is NumberOfTableEntries.

4.4. EFI Boot Services Table

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

4.4.1. EFI_BOOT_SERVICES

Summary

Contains a table header and pointers to all of the boot services.

Related Definitions

#define EFI_BOOT_SERVICES_SIGNATURE 0x56524553544f4f42
#define EFI_BOOT_SERVICES_REVISION EFI_SPECIFICATION_VERSION

typedef struct {
  EFI_TABLE_HEADER     Hdr;

  //
  // Task Priority Services
  //
  EFI_RAISE_TPL        RaiseTPL;       // EFI 1.0+
  EFI_RESTORE_TPL      RestoreTPL;     // EFI 1.0+

    //
    // Memory Services
    //
    EFI_ALLOCATE_PAGES   AllocatePages;  // EFI 1.0+
    EFI_FREE_PAGES       FreePages;      // EFI 1.0+
    EFI_GET_MEMORY_MAP   GetMemoryMap;   // EFI 1.0+
    EFI_ALLOCATE_POOL    AllocatePool;   // EFI 1.0+
    EFI_FREE_POOL        FreePool;       // EFI 1.0+

    //
    // Event & Timer Services
    //
    EFI_CREATE_EVENT     CreateEvent;    // EFI 1.0+
    EFI_SET_TIMER        SetTimer;       // EFI 1.0+
    EFI_WAIT_FOR_EVENT   WaitForEvent;   // EFI 1.0+
    EFI_SIGNAL_EVENT     SignalEvent;    // EFI 1.0+
    EFI_CLOSE_EVENT      CloseEvent;     // EFI 1.0+
    EFI_CHECK_EVENT      CheckEvent;     // EFI 1.0+

    //
    // Protocol Handler Services
    //
    EFI_INSTALL_PROTOCOL_INTERFACE     InstallProtocolInterface;            // EFI 1.0+
    EFI_REINSTALL_PROTOCOL_INTERFACE   ReinstallProtocolInterface;          // EFI 1.0+
    EFI_UNINSTALL_PROTOCOL_INTERFACE   UninstallProtocolInterface;          // EFI 1.0+
    EFI_HANDLE_PROTOCOL                HandleProtocol;                      // EFI 1.0+
 VOID*   Reserved;    // EFI 1.0+
    EFI_REGISTER_PROTOCOL_NOTIFY       RegisterProtocolNotify;              // EFI  1.0+
    EFI_LOCATE_HANDLE                  LocateHandle;                        // EFI 1.0+
    EFI_LOCATE_DEVICE_PATH             LocateDevicePath;                    // EFI 1.0+
 EFI_INSTALL_CONFIGURATION_TABLE       InstallConfigurationTable;           // EFI 1.0+

    //
    // Image Services
    //
    EFI_IMAGE_UNLOAD               LoadImage;        // EFI 1.0+
    EFI_IMAGE_START                StartImage;       // EFI 1.0+
    EFI_EXIT                       Exit;             // EFI 1.0+
    EFI_IMAGE_UNLOAD               UnloadImage;      // EFI 1.0+
    EFI_EXIT_BOOT_SERVICES         ExitBootServices; // EFI 1.0+

    //
    // Miscellaneous Services
    //
    EFI_GET_NEXT_MONOTONIC_COUNT   GetNextMonotonicCount; // EFI 1.0+
    EFI_STALL                      Stall;                 // EFI 1.0+
    EFI_SET_WATCHDOG_TIMER         SetWatchdogTimer;      // EFI 1.0+

    //
    // DriverSupport Services
    //
    EFI_CONNECT_CONTROLLER         ConnectController;     // EFI 1.1
    EFI_DISCONNECT_CONTROLLER      DisconnectController;  // EFI 1.1+

    //
    // Open and Close Protocol Services
    //
    EFI_OPEN_PROTOCOL              OpenProtocol;           // EFI 1.1+
    EFI_CLOSE_PROTOCOL             CloseProtocol;          // EFI 1.1+
 EFI_OPEN_PROTOCOL_INFORMATION     OpenProtocolInformation;// EFI 1.1+

    //
    // Library Services
    //
    EFI_PROTOCOLS_PER_HANDLE       ProtocolsPerHandle;     // EFI 1.1+
    EFI_LOCATE_HANDLE_BUFFER       LocateHandleBuffer;     // EFI 1.1+
    EFI_LOCATE_PROTOCOL            LocateProtocol;         // EFI 1.1+
  EFI_UNINSTALL_MULTIPLE_PROTOCOL_INTERFACES  InstallMultipleProtocolInterfaces;    // EFI 1.1+
  EFI_UNINSTALL_MULTIPLE_PROTOCOL_INTERFACES UninstallMultipleProtocolInterfaces;   // EFI 1.1+*

    //
    // 32-bit CRC Services
    //
    EFI_CALCULATE_CRC32    CalculateCrc32;     // EFI 1.1+

    //
    // Miscellaneous Services
    //
    EFI_COPY_MEM           CopyMem;        // EFI 1.1+
    EFI_SET_MEM            SetMem;         // EFI 1.1+
    EFI_CREATE_EVENT_EX    CreateEventEx;  // UEFI 2.0+
  } EFI_BOOT_SERVICES;

Parameters

Hdr

The table header for the EFI Boot Services Table. This header contains the EFI_BOOT_SERVICES_SIGNATURE and EFI_BOOT_SERVICES_REVISION values along with the size of the EFI_BOOT_SERVICES structure and a 32-bit CRC to verify that the contents of the EFI Boot Services Table are valid.

RaiseTPL

Raises the task priority level.

RestoreTPL

Restores/lowers the task priority level.

AllocatePages

Allocates pages of a particular type.

FreePages

Frees allocated pages.

GetMemoryMap

Returns the current boot services memory map and memory map key.

AllocatePool

Allocates a pool of a particular type.

FreePool

Frees allocated pool.

CreateEvent

Creates a general-purpose event structure.

SetTimer

Sets an event to be signaled at a particular time.

WaitForEvent

Stops execution until an event is signaled.

SignalEvent

Signals an event.

CloseEvent

Closes and frees an event structure.

CheckEvent

Checks whether an event is in the signaled state.

InstallProtocolInterface

Installs a protocol interface on a device handle.

ReinstallProtocolInterface

Reinstalls a protocol interface on a device handle.

UninstallProtocolInterface

Removes a protocol interface from a device handle.

HandleProtocol

Queries a handle to determine if it supports a specified protocol.

Reserved

Reserved. Must be NULL.

RegisterProtocolNotify

Registers an event that is to be signaled whenever an interface is installed for a specified protocol.

LocateHandle

Returns an array of handles that support a specified protocol.

LocateDevicePath

Locates all devices on a device path that support a specified protocol and returns the handle to the device that is closest to the path.

InstallConfigurationTable

Adds, updates, or removes a configuration table from the EFI System Table.

LoadImag

Loads an EFI image into memory.

StartImage

Transfers control to a loaded image’s entry point.

Exit

Exits the image’s entry point.

UnloadImage

Unloads an image.

ExitBootServices

Terminates boot services.

GetNextMonotonicCount

Returns a monotonically increasing count for the platform.

Stall

Stalls the processor.

SetWatchdogTimer

Resets and sets a watchdog timer used during boot services time.

ConnectController

Uses a set of precedence rules to find the best set of drivers to manage a controller.

DisconnectController

Informs a set of drivers to stop managing a controller.

OpenProtocol

Adds elements to the list of agents consuming a protocol interface.

CloseProtocol

Removes elements from the list of agents consuming a protocol interface.

OpenProtocolInformtion

Retrieve the list of agents that are currently consuming a protocol interface.

ProtocolsPerHandle

Retrieves the list of protocols installed on a handle. The return buffer is automatically allocated.

LocateHandleBuffer

Retrieves the list of handles from the handle database that meet the search criteria. The return buffer is automatically allocated.

LocateProtocol

Finds the first handle in the handle database the supports the requested protocol.

InstallMultipleProtocolInterfaces

Installs one or more protocol interfaces onto a handle.

UninstallMultipleProtocolInterfaces

Uninstalls one or more protocol interfaces from a handle.

CalculateCrc32

Computes and returns a 32-bit CRC for a data buffer.

CopyMem

Copies the contents of one buffer to another buffer.

SetMem

Fills a buffer with a specified value.

CreateEventEx

Creates an event structure as part of an event group.

4.5. EFI Runtime Services Table

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

4.5.1. EFI_RUNTIME_SERVICES

Summary

Contains a table header and pointers to all of the runtime services.

Related Definitions

#define EFI_RUNTIME_SERVICES_SIGNATURE 0x56524553544e5552
#define EFI_RUNTIME_SERVICES_REVISION EFI_SPECIFICATION_VERSION
typedef struct {
    EFI_TABLE_HEADER                 Hdr;

    //
    // Time Services
    //
    EFI_GET_TIME                     GetTime;
    EFI_SET_TIME                     SetTime;
    EFI_GET_WAKEUP_TIME              GetWakeupTime;
    EFI_SET_WAKEUP_TIME              SetWakeupTime;

    //
    // Virtual Memory Services
    //
    EFI_SET_VIRTUAL_ADDRESS_MAP      SetVirtualAddressMap;
  EFI_CONVERT_POINTER                ConvertPointer;

    //
    // Variable Services
    //
    EFI_GET_VARIABLE                 GetVariable;
    EFI_GET_NEXT_VARIABLE_NAME       GetNextVariableName;
    EFI_SET_VARIABLE                 SetVariable;


    //
    // Miscellaneous Services
    //
    EFI_GET_NEXT_HIGH_MONO_COUNT     GetNextHighMonotonicCount;
    EFI_RESET_SYSTEM                 ResetSystem;

   //
   // UEFI 2.0 Capsule Services
   //
   EFI_UPDATE_CAPSULE               UpdateCapsule;
   EFI_QUERY_CAPSULE_CAPABILITIES   QueryCapsuleCapabilities;


 //
 // Miscellaneous UEFI 2.0 Service
 //
  EFI_QUERY_VARIABLE_INFO          QueryVariableInfo;
} EFI_RUNTIME_SERVICES;

Parameters

Hdr

The table header for the EFI Runtime Services Table. This header contains the EFI_RUNTIME_SERVICES_SIGNATURE and EFI_RUNTIME_SERVICES_REVISION values along with the size of the EFI_RUNTIME_SERVICES structure and a 32-bit CRC to verify that the contents of the EFI Runtime Services Table are valid.

GetTime

Returns the current time and date, and the time-keeping capabilities of the platform.

SetTime

Sets the current local time and date information.

GetWakeupTime

Returns the current wakeup alarm clock setting.

SetWakeupTime

Sets the system wakeup alarm clock time.

SetVirtualAddressMap

Used by a UEFI OS loader to convert from physical addressing to virtual addressing.

ConvertPointer

Used by EFI components to convert internal pointers when switching to virtual addressing.

GetVariable

Returns the value of a variable.

GetNextVariableName

Enumerates the current variable names.

SetVariable

Sets the value of a variable.

GetNextHighMonotonicCount

Returns the next high 32 bits of the platform’s monotonic counter.

ResetSyste

Resets the entire platform.

UpdateCapsule

Passes capsules to the firmware with both virtual and physical mapping.

QueryCapsuleCapabilities

nReturns if the capsule can be supported via UpdateCapsule() .

QueryVariableInfo

Returns information about the EFI variable store.

4.6. EFI Configuration Table & Properties Table

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

4.6.1. EFI_CONFIGURATION_TABLE

Summary

Contains a set of GUID/pointer pairs comprised of ConfigurationTable field in the EFI System Table.

Related Definitions

typedef struct{
  EFI_GUID           VendorGuid;
  VOID               *VendorTable;
}   EFI_CONFIGURATION_TABLE;

Parameters

VendorGuid

The 128-bit GUID value that uniquely identifies the system configuration table.

VendorTable

A pointer to the table associated with VendorGuid. Type of the memory that is used to store the table as well as whether this pointer is a physical address or a virtual address during runtime (whether or not a particular address reported in the table gets fixed up when a call to SetVirtualAddressMap() is made) is determined by the VendorGuid. Unless otherwise specified, memory type of the table buffer is defined by the guidelines set forth in the Calling Conventions section in Chapter 2. It is the responsibility of the specification defining the VendorTable to specify additional memory type requirements (if any) and whether to convert the addresses reported in the table. Any required address conversion is a responsibility of the driver that publishes corresponding configuration table.

A pointer to the table associated with VendorGuid. Whether this pointer is a physical address or a virtual address during runtime is determined by the VendorGuid. The VendorGuid associated with a given VendorTable pointer defines whether or not a particular address reported in the table gets fixed up when a call to SetVirtualAddressMap() is made. It is the responsibility of the specification defining the VendorTable to specify whether to convert the addresses reported in the table.

4.6.1.1. Industry Standard Configuration Tables

The following list shows the GUIDs for tables defined in some of the industry standards. These industry standards define tables accessed as UEFI Configuration Tables on UEFI-based systems. All the addresses reported in these table entries will be referenced as physical and will not be fixed up when transition from preboot to runtime phase. This list is not exhaustive and does not show GUIDs for all possible UEFI Configuration tables.

#define EFI_ACPI_20_TABLE_GUID \
  {0x8868e871,0xe4f1,0x11d3,\
    {0xbc,0x22,0x00,0x80,0xc7,0x3c,0x88,0x81}}

#define ACPI_TABLE_GUID \
  {0xeb9d2d30,0x2d88,0x11d3,\
    {0x9a,0x16,0x00,0x90,0x27,0x3f,0xc1,0x4d}}

#define SAL_SYSTEM_TABLE_GUID \
  {0xeb9d2d32,0x2d88,0x11d3,\
   {0x9a,0x16,0x00,0x90,0x27,0x3f,0xc1,0x4d}}

#define SMBIOS_TABLE_GUID \
  {0xeb9d2d31,0x2d88,0x11d3,\
   {0x9a,0x16,0x00,0x90,0x27,0x3f,0xc1,0x4d}}

#define SMBIOS3_TABLE_GUID \
  {0xf2fd1544, 0x9794, 0x4a2c,\
   {0x99,0x2e,0xe5,0xbb,0xcf,0x20,0xe3,0x94})

#define MPS_TABLE_GUID \
  {0xeb9d2d2f,0x2d88,0x11d3,\
   {0x9a,0x16,0x00,0x90,0x27,0x3f,0xc1,0x4d}}
//
// ACPI 2.0 or newer tables should use EFI_ACPI_TABLE_GUID
//
#define EFI_ACPI_TABLE_GUID \
{0x8868e871,0xe4f1,0x11d3,\
{0xbc,0x22,0x00,0x80,0xc7,0x3c,0x88,0x81}}

#define EFI_ACPI_20_TABLE_GUID EFI_ACPI_TABLE_GUID

#define ACPI_TABLE_GUID \
{0xeb9d2d30,0x2d88,0x11d3,\
{0x9a,0x16,0x00,0x90,0x27,0x3f,0xc1,0x4d}}

#define ACPI_10_TABLE_GUID ACPI_TABLE_GUID*

4.6.1.2. JSON Configuration Tables

The following list shows the GUIDs for tables defined for reporting firmware configuration data to EFI Configuration Tables and also for processing JSON payload capsule as defined in Section 23.5. The address reported in the table entry identified by EFI_JSON_CAPSULE_DATA_TABLE_GUID will be referenced as physical and will not be fixed up when transition from preboot to runtime phase. The addresses reported in these table entries identified by EFI_JSON_CONFIG_DATA_TABLE_GUID and EFI_JSON_CAPSULE_RESULT_TABLE_GUID will be referenced as virtual and will be fixed up when transition from preboot to runtime phase.

#define EFI_JSON_CONFIG_DATA_TABLE_GUID \
{0x87367f87, 0x1119, 0x41ce, \
{0xaa, 0xec, 0x8b, 0xe0, 0x11, 0x1f, 0x55, 0x8a }}

#define EFI_JSON_CAPSULE_DATA_TABLE_GUID \
{0x35e7a725, 0x8dd2, 0x4cac, \
{ 0x80, 0x11, 0x33, 0xcd, 0xa8, 0x10, 0x90, 0x56 }}

#define EFI_JSON_CAPSULE_RESULT_TABLE_GUID \
{0xdbc461c3, 0xb3de, 0x422a,\
{0xb9, 0xb4, 0x98, 0x86, 0xfd, 0x49, 0xa1, 0xe5 }}

4.6.1.3. Devicetree Tables

The following list shows the GUIDs for the Devicetree table (DTB). For more information, see “Links to UEFI-Related Documents” ( http://uefi.org/uefi ) under the headings “Devicetree Specification”. The DTB must be contained in memory of type EfiACPIReclaimMemory. The address reported in this table entry will be referenced as physical and will not be fixed up when transition from preboot to runtime phase. Firmware must have the DTB resident in memory and installed in the EFI system table before executing any UEFI applications or drivers that are not part of the system firmware image. Once the DTB is installed as a configuration table, the system firmware must not make any modification to it or reference any data contained within the DTB.

UEFI applications are permitted to modify or replace the loaded DTB. System firmware must not depend on any data contained within the DTB. If system firmware makes use of a DTB for its own configuration, it should use a separate private copy that is not installed in the EFI System Table or otherwise be exposed to EFI applications.

//
// Devicetree table, in Flattened Devicetree Blob (DTB) format
//
#define EFI_DTB_TABLE_GUID \
{0xb1b621d5, 0xf19c, 0x41a5, \
{0x83, 0x0b, 0xd9, 0x15, 0x2c, 0x69, 0xaa, 0xe0}}

4.6.2. EFI_RT_PROPERTIES_TABLE

This table should be published by a platform if it no longer supports all EFI runtime services once ExitBootServices() has been called by the OS. Note that this is merely a hint to the OS, which it is free to ignore, and so the platform is still required to provide callable implementations of unsupported runtime services that simply return EFI_UNSUPPORTED.

#define EFI_RT_PROPERTIES_TABLE_GUID \\
  { 0xeb66918a, 0x7eef, 0x402a, \\
    { 0x84, 0x2e, 0x93, 0x1d, 0x21, 0xc3, 0x8a, 0xe9 }}

      typedef struct {
        UINT16 Version;
        UINT16 Length;
        UINT32 RuntimeServicesSupported;
    } EFI_RT_PROPERTIES_TABLE;
Version

Version of the table, must be 0x1

#define EFI_RT_PROPERTIES_TABLE_VERSION 0x1
Length

Size in bytes of the entire EFI_RT_PROPERTIES_TABLE, must be 8.

RuntimeServicesSupported

Bitmask of which calls are or are not supported, where a bit set to 1 indicates that the call is supported, and 0 indicates that it is not.

#define EFI_RT_SUPPORTED_GET_TIME                        0x0001
#define EFI_RT_SUPPORTED_SET_TIME                        0x0002
#define EFI_RT_SUPPORTED_GET_WAKEUP_TIME                 0x0004
#define EFI_RT_SUPPORTED_SET_WAKEUP_TIME                 0x0008
#define EFI_RT_SUPPORTED_GET_VARIABLE                    0x0010
#define EFI_RT_SUPPORTED_GET_NEXT_VARIABLE_NAME          0x0020
#define EFI_RT_SUPPORTED_SET_VARIABLE                    0x0040
#define EFI_RT_SUPPORTED_SET_VIRTUAL_ADDRESS_MAP         0x0080
#define EFI_RT_SUPPORTED_CONVERT_POINTER                 0x0100
#define EFI_RT_SUPPORTED_GET_NEXT_HIGH_MONOTONIC_COUNT   0x0200
#define EFI_RT_SUPPORTED_RESET_SYSTEM                    0x0400
#define EFI_RT_SUPPORTED_UPDATE_CAPSULE                  0x0800
#define EFI_RT_SUPPORTED_QUERY_CAPSULE_CAPABILITIES      0x1000
#define EFI_RT_SUPPORTED_QUERY_VARIABLE_INFO             0x2000

The address reported in the EFI configuration table entry of this type will be referenced as physical and will not be fixed up when transitioning from preboot to runtime phase.

4.6.3. EFI_PROPERTIES_TABLE (deprecated)

Note

This table is deprecated and should no longer be used! It will be removed from future versions of the specification. EFI_MEMORY_ATTRIBUTES_TABLE described below provides alternative mechanism to implement runtime memory protection.

This table is published if the platform meets some of the construction requirements listed in the MemoryProtectionAttributes .

typedef struct {
  UINT32         Version;
  UINT32         Length;
  UINT64         MemoryProtectionAttribute;
}   EFI_PROPERTIES_TABLE;
Version

This is revision of the table. Successive version may populate additional bits and growth the table length. In the case of the latter, the Length field will be adjusted appropriately

#define EFI_PROPERTIES_TABLE_VERSION 0x00010000
Length

This is the size of the entire EFI_PROPERTIES_TABLE structure, including the version. The initial version will be of length 16.

MemoryProtectionAttribute

This field is a bit mask. Any bits not defined shall be considered reserved. A set bit means that the underlying firmware has been constructed responsive to the given property.

//
// Memory attribute (Not defined bits are reserved)
//
#define EFI_PROPERTIES_RUNTIME_MEMORY_PROTECTION_NON_EXECUTABLE_PE_DATA     0x1
\
  // BIT 0 - description - implies the runtime data is separated     from the code

This bit implies that the UEFI runtime code and data sections of the executable image are separate and must be aligned as specified in Calling Conventions . This bit also implies that the data pages do not have any executable code.

It is recommended not to use this attribute, especially for implementations that broke the runtime code memory map descriptors into the underlying code and data sections within UEFI modules. This splitting causes interoperability issues with operating systems that invoke SetVirtualAddress() without realizing that there is a relationship between these runtime descriptors.

4.6.4. EFI_MEMORY_ATTRIBUTES_TABLE

Summary

When published by the system firmware, the EFI_MEMORY_ATTRIBUTES_TABLE provides additional information about regions within the run-time memory blocks defined in the EFI_MEMORY_DESCRIPTOR entries returned from EFI_BOOT_SERVICES . GetMemoryMap() function. The Memory Attributes Table is currently used to describe memory protections that may be applied to the EFI Runtime code and data by an operating system or hypervisor. Consumers of this table must currently ignore entries containing any values for Type except for EfiRuntimeServicesData and EfiRuntimeServicesCode to ensure compatibility with future uses of this table. The Memory Attributes Table may define multiple entries to describe sub-regions that comprise a single entry returned by GetMemoryMap() however the sub-regions must total to completely describe the larger region and may not cross boundaries between entries reported by GetMemoryMap() . If a run-time region returned in GetMemoryMap() entry is not described within the Memory Attributes Table, this region is assumed to not be compatible with any memory protections.

Only entire EFI_MEMORY_DESCRIPTOR entries as returned by GetMemoryMap() may be passed to SetVirtualAddressMap() .

The address reported in the EFI configuration table entry of this type will be referenced as physical and will not be fixed up when transition from preboot to runtime phase.

Prototype

#define EFI_MEMORY_ATTRIBUTES_TABLE_GUID \
  {0xdcfa911d, 0x26eb, 0x469f, \
    {0xa2, 0x20, 0x38, 0xb7, 0xdc, 0x46, 0x12, 0x20}}

With the following data structure

/**********************************************
/* EFI_MEMORY_ATTRIBUTES_TABLE
/**********************************************
typedef struct {
  UINT32                       Version ;
  UINT32                       NumberOfEntries ;
  UINT32                       DescriptorSize ;
  UINT32                       Reserved ;
  // EFI_MEMORY_DESCRIPTOR     Entry [1] ;
  }  EFI_MEMORY_ATTRIBUTES_TABLE;
Version

The version of this table. Present version is 0x00000001

NumberOfEntries

Count of EFI_MEMORY_DESCRIPTOR entries provided. This is typically the total number of PE/COFF sections within all UEFI modules that comprise the UEFI Runtime and all UEFI Data regions (e.g. runtime heap).

Entry

Array of Entries of type EFI_MEMORY_DESCRIPTOR.

DescriptorSize

Size of the memory descriptor.

Reserved

Reserved bytes.

Description

For each array entry, the EFI_MEMORY_DESCRIPTOR . Attribute field can inform a runtime agency, such as operating system or hypervisor, as to what class of protection settings can be made in the memory management unit for the memory defined by this entry. The only valid bits for Attribute field currently are EFI_MEMORY_RO , EFI_MEMORY_XP , plus EFI_MEMORY_RUNTIME . Irrespective of the memory protections implied by Attribute , the EFI_MEMORY_DESCRIPTOR . Type field should match the type of the memory in enclosing SetMemoryMap() entry. PhysicalStart must be aligned as specified in Calling Conventions . The list must be sorted by physical start address in ascending order. VirtualStart field must be zero and ignored by the OS since it has no purpose for this table. NumPages must cover the entire memory region for the protection mapping. Each Descriptor in the EFI_MEMORY_ATTRIBUTES_TABLE with attribute EFI_MEMORY_RUNTIME must not overlap any other Descriptor in the EFI_MEMORY_ATTRIBUTES_TABLE with attribute EFI_MEMORY_RUNTIME . Additionally, every memory region described by a Descriptor in EFI_MEMORY_ATTRIBUTES_TABLE must be a sub-region of, or equal to, a descriptor in the table produced by GetMemoryMap().

Table 4.1 Usage of Memory Attribute Definitions

EFI_MEMORY_RO

EFI_MEMORY_XP

EFI _MEMORY_RUNTIME

No memory access protection is possible for Entry

0

0

1

Write-protected Code

1

0

1

Read/Write Data

0

1

1

Read-only Data

1

1

1

Other Configuration Tables

The following list shows additional configuration tables defined in this specification:

  • EFI_MEMORY_RANGE_CAPSULE_GUID

  • EFI_DEBUG_IMAGE_INFO_TABLE (Section 18.4.3)

  • EFI_SYSTEM_RESOURCE_TABLE (Section 23.4)

  • EFI_IMAGE_EXECUTION_INFO_TABLE (Section 32.5.3.1)

  • User Information Table (Section 36.5)

  • HII Database export buffer (Section 33.2.11.1, OS Runtime Utilization)

4.7. Image Entry Point Examples

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

4.7.1. Image Entry Point Examples

The following example shows the image entry point for a UEFI Application. This application makes use of the EFI System Table, the EFI Boot Services Table, and the EFI Runtime Services Table.

 EFI_SYSTEM_TABLE                *gST;
 EFI_BOOT_SERVICES               *gBS;
 EFI_RUNTIME_SERVICES            *gRT;

 EfiApplicationEntryPoint(
   IN EFI_HANDLE                 ImageHandle,
   IN EFI_SYSTEM_TABLE           *SystemTable
   )

  {
   EFI_STATUS Status;
   EFI_TIME                       *Time;

   gST = SystemTable;
   gBS = gST->BootServices;
   gRT = gST->RuntimeServices;

   //
   // Use EFI System Table to print "Hello World" to the active console output
   // device.
   //
   Status = gST->ConOut->OutputString (gST->ConOut, L"Hello world\n\r"); if (EFI_ERROR (Status)) {
    return Status;
   }

   //
   // Use EFI Boot Services Table to allocate a buffer to store the current time
   // and date.
   //
   Status = gBS->AllocatePool (
        EfiBootServicesData,
        sizeof (EFI_TIME),
        (VOID \**)&Time
        );
   if (EFI_ERROR (Status)) {
    return Status;
   }

   //
   // Use the EFI Runtime Services Table to get the current time and date.
   //
   Status = gRT->GetTime (Time, NULL)
   if (EFI_ERROR (Status)) {
    return Status;
   }

   return Status;
}

The following example shows the UEFI image entry point for a driver that does not follow the UEFI Driver Model . Since this driver returns EFI_SUCCESS , it will stay resident in memory after it exits.

EFI_SYSTEM_TABLE         *gST;
EFI_BOOT_SERVICES        *gBS;
EFI_RUNTIME_SERVICES     *gRT;

EfiDriverEntryPoint(
  IN EFI_HANDLE           ImageHandle,
  IN EFI_SYSTEM_TABLE     *SystemTable
  )

{
  gST = SystemTable;
  gBS = gST->BootServices;
  gRT = gST->RuntimeServices;

  //
  // Implement driver initialization here.
  //

   return EFI_SUCCESS;
}

The following example shows the UEFI image entry point for a driver that also does not follow the UEFI Driver Model . Since this driver returns EFI_DEVICE_ERROR, it will not stay resident in memory after it exits.

EFI_SYSTEM_TABLE          *gST;
EFI_BOOT_SERVICES         *gBS;
EFI_RUNTIME_SERVICES      *gRT;

EfiDriverEntryPoint(
  IN EFI_HANDLE           ImageHandle,
  IN EFI_SYSTEM_TABLE     *SystemTable
  )

{
  gST = SystemTable;
  gBS = gST->BootServices;
  gRT = gST->RuntimeServices;

  //
  // Implement driver initialization here.
  //

  return EFI_DEVICE_ERROR;
}

4.7.2. UEFI Driver Model Example

The following is an UEFI Driver Model example that shows the driver initialization routine for the ABC device controller that is on the XYZ bus. The EFI_DRIVER_BINDING_PROTOCOL and the function prototypes for AbcSupported(), AbcStart(), and AbcStop() are defined in EFI Driver Binding Protocol This function saves the driver’s image handle and a pointer to the EFI boot services table in global variables, so the other functions in the same driver can have access to these values. It then creates an instance of the EFI_DRIVER_BINDING_PROTOCOL and installs it onto the driver’s image handle.

extern EFI_GUID              gEfiLoadedImageProtocolGuid;
extern EFI_GUID              gEfiDriverBindingProtocolGuid;
EFI_BOOT_SERVICES            *gBS;
static EFI_DRIVER_BINDING_PROTOCOL  mAbcDriverBinding = {
  AbcSupported,
  AbcStart,
  AbcStop,
  1,
  NULL,
  NULL
};

AbcEntryPoint(
  IN EFI_HANDLE                ImageHandle,
  IN EFI_SYSTEM_TABLE          *SystemTable
  )

{
  EFI_STATUS Status;

  gBS = SystemTable->BootServices;

  mAbcDriverBinding->ImageHandle      = ImageHandle;
  mAbcDriverBinding->DriverBindingHandle = ImageHandle;

  Status = gBS->InstallMultipleProtocolInterfaces(
           &mAbcDriverBinding->DriverBindingHandle,
           &gEfiDriverBindingProtocolGuid, &mAbcDriverBinding,
            NULL
            );
  return Status;
}

4.7.3. UEFI Driver Model Example (Unloadable)

The following is the same UEFI Driver Model example as above, except it also includes the code required to allow the driver to be unloaded through the boot service Unload() EFI_LOADED_IMAGE_PROTOCOL.Unload() . Any protocols installed or memory allocated in AbcEntryPoint() must be uninstalled or freed in the AbcUnload().

 extern EFI_GUID                        gEfiLoadedImageProtocolGuid;
 extern EFI_GUID                        gEfiDriverBindingProtocolGuid;
 EFI_BOOT_SERVICES                      *gBS;
 static EFI_DRIVER_BINDING_PROTOCOL     mAbcDriverBinding = {
   AbcSupported,
   AbcStart,
   AbcStop,
   1,
   NULL,
   NULL
 };

 EFI_STATUS
 AbcUnload (
   IN EFI_HANDLE                        ImageHandle
   );
 AbcEntryPoint(
   IN EFI_HANDLE                        ImageHandle,
   IN EFI_SYSTEM_TABLE                  *SystemTable
   )

 {
   EFI_STATUS                           Status;
   EFI_LOADED_IMAGE_PROTOCOL            *LoadedImage;

   gBS = SystemTable->BootServices;

   Status = gBS->OpenProtocol (
            ImageHandle,
            &gEfiLoadedImageProtocolGuid,
            &LoadedImage,
            ImageHandle,
            NULL,
            EFI_OPEN_PROTOCOL_GET_PROTOCOL
            );
   if (EFI_ERROR (Status)) {
     return Status;
 }
 LoadedImage->Unload = AbcUnload;

 mAbcDriverBinding->ImageHandle         = ImageHandle;
 mAbcDriverBinding->DriverBindingHandle = ImageHandle;

 Status =  gBS->InstallMultipleProtocolInterfaces(
           &mAbcDriverBinding->DriverBindingHandle,
           &gEfiDriverBindingProtocolGuid, &mAbcDriverBinding,
           NULL
           );

   return Status;
 }

 EFI_STATUS Status
 AbcUnload (
   IN EFI_HANDLE ImageHandle
   )

{
 EFI_STATUS Status;

 Status =  gBS->UninstallMultipleProtocolInterfaces (
           ImageHandle,
           &gEfiDriverBindingProtocolGuid, &mAbcDriverBinding,
           NULL
           );
      return Status;
    }

4.7.4. EFI Driver Model Example (Multiple Instances)

The following is the same as the first UEFI Driver Model example, except it produces three EFI Driver Binding Protocol instances. The first one is installed onto the driver’s image handle. The other two are installed onto newly created handles.

extern EFI_GUID             gEfiDriverBindingProtocolGuid;
EFI_BOOT_SERVICES           *gBS;

static EFI_DRIVER_BINDING_PROTOCOL   mAbcDriverBindingA = {
  AbcSupportedA,
  AbcStartA,
  AbcStopA,
  1,
  NULL,
  NULL
};

static EFI_DRIVER_BINDING_PROTOCOL   mAbcDriverBindingB = {
  AbcSupportedB,
  AbcStartB,
  AbcStopB,
  1,
  NULL,
  NULL
};

static EFI_DRIVER_BINDING_PROTOCOL   mAbcDriverBindingC = {
  AbcSupportedC,
  AbcStartC,
  AbcStopC,
  1,
  NULL,
  NULL
};

AbcEntryPoint(
  IN EFI_HANDLE ImageHandle,
  IN EFI_SYSTEM_TABLE *SystemTable
  )

{
  EFI_STATUS Status;

  gBS = SystemTable->BootServices;

  //
  // Install mAbcDriverBindingA onto ImageHandle
  //
  mAbcDriverBindingA->ImageHandle            = ImageHandle;
  mAbcDriverBindingA->DriverBindingHandle    = ImageHandle;

  Status =  gBS->InstallMultipleProtocolInterfaces(
            &mAbcDriverBindingA->DriverBindingHandle,
            &gEfiDriverBindingProtocolGuid, &mAbcDriverBindingA,
            NULL
            );
  if (EFI_ERROR (Status)) {
     return Status;
  }

  //
  // Install mAbcDriverBindingB onto a newly created handle
  //
  mAbcDriverBindingB->ImageHandle      = ImageHandle;
  mAbcDriverBindingB->DriverBindingHandle      = NULL;

  Status =  gBS->InstallMultipleProtocolInterfaces(
            &mAbcDriverBindingB->DriverBindingHandle,
            &gEfiDriverBindingProtocolGuid, &mAbcDriverBindingB,
            NULL
            );
  if (EFI_ERROR (Status)) {
     return Status;
  }

  //
  // Install mAbcDriverBindingC onto a newly created handle
  //
  mAbcDriverBindingC->ImageHandle = ImageHandle;
  mAbcDriverBindingC->DriverBindingHandle = NULL;

  Status =  gBS->InstallMultipleProtocolInterfaces(
            &mAbcDriverBindingC->DriverBindingHandle,
            &gEfiDriverBindingProtocolGuid, &mAbcDriverBindingC,
            NULL
            );

  return Status;
  }