EFI BOOT SERVICES

From PhoenixWiki

Jump to: navigation, search

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

Contents

Prototype

typedef struct {
  EFI_TABLE_HEADER                           Hdr;
  EFI_RAISE_TPL                              RaiseTPL;
  EFI_RESTORE_TPL                            RestoreTPL; 
  EFI_ALLOCATE_PAGES                         AllocatePages; 
  EFI_FREE_PAGES                             FreePages; 
  EFI_GET_MEMORY_MAP                         GetMemoryMap; 
  EFI_ALLOCATE_POOL                          AllocatePool; 
  EFI_FREE_POOL                              FreePool; 
  EFI_CREATE_EVENT                           CreateEvent; 
  EFI_SET_TIMER                              SetTimer; 
  EFI_WAIT_FOR_EVENT                         WaitForEvent; 
  EFI_SIGNAL_EVENT                           SignalEvent; 
  EFI_CLOSE_EVENT                            CloseEvent; 
  EFI_CHECK_EVENT                            CheckEvent; 
  EFI_INSTALL_PROTOCOL_INTERFACE             InstallProtocolInterface; 
  EFI_REINSTALL_PROTOCOL_INTERFACE           ReinstallProtocolInterface; 
  EFI_UNINSTALL_PROTOCOL_INTERFACE           UninstallProtocolInterface; 
  EFI_HANDLE_PROTOCOL                        HandleProtocol; 
  VOID*                                      Reserved; 
  EFI_REGISTER_PROTOCOL_NOTIFY               RegisterProtocolNotify; 
  EFI_LOCATE_HANDLE                          LocateHandle; 
  EFI_LOCATE_DEVICE_PATH                     LocateDevicePath; 
  EFI_INSTALL_CONFIGURATION_TABLE            InstallConfigurationTable; 
  EFI_IMAGE_LOAD                             LoadImage; 
  EFI_IMAGE_START                            StartImage; 
  EFI_EXIT                                   Exit; 
  EFI_IMAGE_UNLOAD                           UnloadImage; 
  EFI_EXIT_BOOT_SERVICES                     ExitBootServices; 
  EFI_GET_NEXT_MONOTONIC_COUNT               GetNextMonotonicCount; 
  EFI_STALL                                  Stall; 
  EFI_SET_WATCHDOG_TIMER                     SetWatchdogTimer; 
  EFI_CONNECT_CONTROLLER                     ConnectController; 
  EFI_DISCONNECT_CONTROLLER                  DisconnectController;
  EFI_OPEN_PROTOCOL                          OpenProtocol; 
  EFI_CLOSE_PROTOCOL                         CloseProtocol; 
  EFI_OPEN_PROTOCOL_INFORMATION              OpenProtocolInformation; 
  EFI_PROTOCOLS_PER_HANDLE                   ProtocolsPerHandle; 
  EFI_LOCATE_HANDLE_BUFFER                   LocateHandleBuffer; 
  EFI_LOCATE_PROTOCOL                        LocateProtocol; 
  EFI_INSTALL_MULTIPLE_PROTOCOL_INTERFACES   InstallMultipleProtocolInterfaces; 
  EFI_UNINSTALL_MULTIPLE_PROTOCOL_INTERFACES UninstallMultipleProtocolInterfaces; 
  EFI_CALCULATE_CRC32                        CalculateCrc32; 
  EFI_COPY_MEM                               CopyMem; 
  EFI_SET_MEM                                SetMem;
  EFI_CREATE_EVENT_EX                        CreateEventEx;
} EFI_BOOT_SERVICES;

Parameters

Parameter Description
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.
LoadImage Loads an EFI image into memory.
StartImage Transfers control to a loaded image’s entry point.
Exit Exits the image’s entry point.
UnloadImage Unloads an image.
ExitBootServices Terminates boot services.
GetNextMonotonicCount Returns a monotonically increasing count for the platform.
Stall Stalls the processor.
SetWatchdogTimer Resets and sets a watchdog timer used during boot services time.
ConnectController Uses a set of precedence rules to find the best set of drivers to manage a controller.
DisconnectController Informs a set of drivers to stop managing a controller.
OpenProtocol Adds elements to the list of agents consuming a protocol interface.
CloseProtocol Removes elements from the list of agents consuming a protocol interface.
OpenProtocolInformation Retrieve the list of agents that are currently consuming a protocol interface.
ProtocolsPerHandle Retrieves the list of protocols installed on a handle. The return buffer is automatically allocated.
LocateHandleBuffer Retrieves the list of handles from the handle database that meet the search criteria. The return buffer is automatically allocated.
LocateProtocol Finds the first handle in the handle database the supports the requested protocol.
InstallMultipleProtocolInterfaces Installs one or more protocol interfaces onto a handle.
UninstallMultipleProtocolInterfaces Uninstalls one or more protocol interfaces from a handle.
CalculateCrc32 Computes and returns a 32-bit CRC for a data buffer.
CopyMem Copies the contents of one buffer to another buffer.
SetMem Fills a buffer with a specified value.
CreateEventEx Creates an event structure as part of an event group.

Related Definitions

#define EFI_BOOT_SERVICES_SIGNATURE 0x56524553544f4f42
#define EFI_BOOT_SERVICES_REVISION EFI_SPECIFICATION_VERSION

Description

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. The function pointers in this table are not valid after the operating system has taken control of the platform with a call to ExitBootServices().

Members

AllocatePages()

Allocates memory pages from the system.

Prototype

typedef
EFI_STATUS
AllocatePages(
  IN     EFI_ALLOCATE_TYPE    Type,
  IN     EFI_MEMORY_TYPE      MemoryType,
  IN     UINTN                Pages,
  IN OUT EFI_PHYSICAL_ADDRESS *Memory
  );

Parameters

Parameter Description
Type The type of allocation to perform.
MemoryType The type of memory to allocate. Normal allocations (that is, allocations by any UEFI application) are of type EfiLoaderData. MemoryType values in the range 0x80000000..0xFFFFFFFF are reserved for use by UEFI OS loaders that are provided by operating system vendors. The only illegal memory type values are those in the range EfiMaxMemoryType..0x7FFFFFFF.
Pages The number of contiguous 4 KB pages to allocate.
Memory Pointer to a physical address. On input, the way in which the address is used depends on the value of Type. See “Description” for more information. On output the address is set to the base of the page range that was allocated.

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 allocation requirements of Type, it changes the memory map to indicate that the pages are now of type MemoryType.

In general, UEFI OS loaders and applications should allocate memory (and pool) of type EfiLoaderData. Boot service drivers must allocate memory (and pool) of type EfiBootServicesData. Runtime drivers should allocate memory (and pool) of type EfiRuntimeServicesData (although such allocation can only be made during boot services time).

Allocation requests of Type AllocateAnyPages allocate any available range of pages that satisfies the request. On input, the address pointed to by Memory is ignored.

Allocation requests of Type AllocateMaxAddress allocate any available range of pages whose uppermost address is less than or equal to the address pointed to by Memory on input.

Allocation requests of Type AllocateAddress allocate pages at the address pointed to by Memory on input.

Status Codes Returned

Status Code Description
EFI_SUCCESS The requested pages were allocated.
EFI_OUT_OF_RESOURCES The pages could not be allocated.
EFI_INVALID_PARAMETER Type is not AllocateAnyPages or AllocateMaxAddress or AllocateAddress.
EFI_INVALID_PARAMETER MemoryType is in the range EfiMaxMemoryType..0x7FFFFFFF.
EFI_NOT_FOUND The requested pages could not be found.

AllocatePool()

Allocates pool memory.

Prototype

typedef
EFI_STATUS
AllocatePool (
  IN  EFI_MEMORY_TYPE PoolType,
  IN  UINTN           Size,
  OUT VOID            **Buffer
  );

Parameters

Parameter Description
PoolType The type of pool to allocate. PoolType values in the range 0x80000000..0xFFFFFFFF are reserved for use by UEFI OS loaders that are provided by operating system vendors. The only illegal memory type values are those in the range EfiMaxMemoryType..0x7FFFFFFF.
Size The number of bytes to allocate from the pool.
Buffer A pointer to a pointer to the allocated buffer if the call succeeds; undefined otherwise.


Description
The AllocatePool() function allocates a memory region of Size bytes from memory of type PoolType and returns the address of the allocated memory in the location referenced by Buffer. This function allocates pages from EfiConventionalMemory as needed to grow the requested pool type. All allocations are eight-byte aligned.

The allocated pool memory is returned to the available pool with the FreePool() function.

Status Codes Returned

Status Code Description
EFI_SUCCESS The requested number of bytes was allocated.
EFI_OUT_OF_RESOURCES The pool requested could not be allocated.
EFI_INVALID_PARAMETER PoolType was invalid.

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

Prototype

typedef
EFI_STATUS
CalculateCrc32 (
  IN VOID *Data,
  IN UINTN DataSize,
  OUT UINT32 *Crc32
  );

Parameters
Data A pointer to the buffer on which the 32-bit CRC is to be computed. DataSize The number of bytes in the buffer Data. Crc32 The 32-bit CRC that was computed for the data buffer specified by Data and DataSize.

Description
This function computes the 32-bit CRC for the data buffer specified by Data and DataSize. If the 32-bit CRC is computed, then it is returned in Crc32 and EFI_SUCCESS is returned.

If Data is NULL, then EFI_INVALID_PARAMETER is returned. If Crc32 is NULL, then EFI_INVALID_PARAMETER is returned. If DataSize is 0, then EFI_INVALID_PARAMETER is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The 32-bit CRC was computed for the data buffer and returned in Crc32.
EFI_INVALID_PARAMETER Data is NULL.
EFI_INVALID_PARAMETER Crc32 is NULL.
EFI_INVALID_PARAMETER DataSize is 0.

CloseEvent()

Closes an event.

Prototype

typedef
EFI_STATUS
CloseEvent(
  IN EFI_EVENT Event
  );

Parameters

Parameter Description
Event The event to close.

Description
The CloseEvent() function removes the caller’s reference to the event, removes it from any event group to which it belongs, 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

Status Code Description
EFI_SUCCESS The event has been closed.

CloseProtocol()

Closes a protocol on a handle that was opened using OpenProtocol().

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_CLOSE_PROTOCOL) (
  IN EFI_HANDLE Handle,
  IN EFI_GUID   *Protocol,
  IN EFI_HANDLE AgentHandle,
  IN EFI_HANDLE ControllerHandle
  );

Parameters

Parameter Description
Handle The handle for the protocol interface that was previously opened with OpenProtocol(), and is now being closed.
Protocol The published unique identifier of the protocol. It is the caller’s responsibility to pass in a valid GUID. See “Wired For Management Baseline” for a description of valid GUID values.
AgentHandle The handle of the agent that is closing the protocol interface. For agents that follow the UEFI Driver Model, this parameter is the handle that contains the EFI_DRIVER_BINDING_PROTOCOL instance that is produced by the UEFI driver that is opening the protocol interface. For UEFI applications, this is the image handle of the UEFI application. For applications that used HandleProtocol() to open the protocol interface, this will be the image handle of the EFI firmware.
ControllerHandle If the agent that opened a protocol is a driver that follows the UEFI Driver Model, then this parameter is the controller handle that required the protocol interface. If the agent does not follow the UEFI Driver Model, then this parameter is optional and may be NULL.

Description
This function updates the handle database to show that the protocol instance specified by Handle and Protocol is no longer required by the agent and controller specified AgentHandle and ControllerHandle.

If Handle or AgentHandle is not a valid EFI_HANDLE, then EFI_INVALID_PARAMETER is returned. If ControllerHandle is not NULL, and ControllerHandle is not a valid EFI_HANDLE, then EFI_INVALID_PARAMETER is returned. If Protocol is NULL, then EFI_INVALID_PARAMETER is returned.

If the interface specified by Protocol is not supported by the handle specified by Handle, then EFI_NOT_FOUND is returned.

If the interface specified by Protocol is supported by the handle specified by Handle, then a check is made to see if the protocol instance specified by Protocol and Handle was opened by AgentHandle and ControllerHandle with OpenProtocol(). If the protocol instance was not opened by AgentHandle and ControllerHandle, then EFI_NOT_FOUND is returned. If the protocol instance was opened by AgentHandle and ControllerHandle, then all of those references are removed from the handle database, and EFI_SUCCESS is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The protocol instance was closed.
EFI_INVALID_PARAMETER Handle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER AgentHandle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER ControllerHandle is not NULL and ControllerHandle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER Protocol is NULL.
EFI_NOT_FOUND Handle does not support the protocol specified by Protocol.
EFI_NOT_FOUND The protocol interface specified by Handle and Protocol is not currently open by AgentHandle and ControllerHandle.

Examples

EFI_BOOT_SERVICES *gBS;
EFI_HANDLE ImageHandle;
EFI_DRIVER_BINDING_PROTOCOL *This;
IN EFI_HANDLE ControllerHandle,
extern EFI_GUID gEfiXyzIoProtocol;
EFI_STATUS Status;
//
// Close the XYZ I/O Protocol that was opened on behalf of ControllerHandle
//
Status = gBS->CloseProtocol (
  ControllerHandle,
  &gEfiXyzIoProtocol,
  This->DriverBindingHandle,
  ControllerHandle
  );
//
// Close the XYZ I/O Protocol that was opened with BY_HANDLE_PROTOCOL
//
Status = gBS->CloseProtocol (
  ControllerHandle,
  &gEfiXyzIoProtocol,
  ImageHandle,
  NULL
  );

CopyMem()

The CopyMem() function copies the contents of one buffer to another buffer.

Prototype

typedef
VOID
CopyMem (
  IN VOID  *Destination,
  IN VOID  *Source,
  IN UINTN Length
  );

Parameters

Parameter Description
Destination Pointer to the destination buffer of the memory copy.
Source Pointer to the source buffer of the memory copy.
Length Number of bytes to copy from Source to Destination.

Description
The CopyMem() function copies Length bytes from the buffer Source to the buffer Destination.

The implementation of CopyMem() must be reentrant, and it must handle overlapping Source and Destination buffers. This means that the implementation of CopyMem() must choose the correct direction of the copy operation based on the type of overlap that exists between the Source and Destination buffers. If either the Source buffer or the Destination buffer crosses the top of the processor’s address space, then the result of the copy operation is unpredictable.

The contents of the Destination buffer on exit from this service must match the contents of the Source buffer on entry to this service. Due to potential overlaps, the contents of the Source buffer may be modified by this service. The following rules can be used to guarantee the correct behavior:

  1. If Destination and Source are identical, then no operation should be performed.
  2. If Destination > Source and Destination < (Source + Length), then the data should be copied from the Source buffer to the Destination buffer starting from the end of the buffers and working toward the beginning of the buffers.
  3. Otherwise, the data should be copied from the Source buffer to the Destination buffer starting from the beginning of the buffers and working toward the end of the buffers.

Status Codes Returned
None.

CreateEvent()

Creates an event.

Prototype

typedef
EFI_STATUS
CreateEvent (
  IN  UINT32           Type,
  IN  EFI_TPL          NotifyTpl,
  IN  EFI_EVENT_NOTIFY NotifyFunction, OPTIONAL
  IN  VOID             *NotifyContext, OPTIONAL
  OUT EFI_EVENT        *Event
  );

Parameters
Type The type of event to create and its mode and attributes. NotifyTpl The task priority level of event notifications, if needed. NotifyFunction Pointer to the event’s notification function, if any. NotifyContext Pointer to the notification function’s context; corresponds to parameter Context in the notification function. Event Pointer to the newly created event if the call succeeds; undefined otherwise.

Description
The CreateEvent() function creates a new event of type Type and returns it in the location referenced by Event. The event’s notification function, context, and task priority level are specified by NotifyFunction, NotifyContext, and NotifyTpl, respectively.

Events exist in one of two states, “waiting” or “signaled.” When an event is created, firmware puts it in the “waiting” state. When the event is signaled, firmware changes its state to “signaled” and, if EVT_NOTIFY_SIGNAL is specified, places a call to its notification function in a FIFO queue. There is a queue for each of the “basic” task priority levels defined in Section 6.1 (TPL_CALLBACK, and TPL_NOTIFY). The functions in these queues are invoked in FIFO order, starting with the highest priority level queue and proceeding to the lowest priority queue that is unmasked by the current TPL. If the current TPL is equal to or greater than the queued notification, it will wait until the TPL is lowered via RestoreTPL().

In a general sense, there are two “types” of events, synchronous and asynchronous. Asynchronous events are closely related to timers and are used to support periodic or timed interruption of program execution. This capability is typically used with device drivers. For example, a network device driver that needs to poll for the presence of new packets could create an event whose type includes EVT_TIMER and then call the SetTimer() function. When the timer expires, the firmware signals the event.

Synchronous events have no particular relationship to timers. Instead, they are used to ensure that certain activities occur following a call to a specific interface function. One example of this is the cleanup that needs to be performed in response to a call to the ExitBootServices() function. ExitBootServices() can clean up the firmware since it understands firmware internals, but it cannot 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.

Another example of the use of synchronous events occurs when an event of type EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE is used in conjunction with the SetVirtualAddressMap().

The EVT_NOTIFY_WAIT and EVT_NOTIFY_SIGNAL flags are exclusive. If neither flag is specified, the caller does not require any notification concerning the event and the NotifyTpl, NotifyFunction, and NotifyContext parameters are ignored. If EVT_NOTIFY_WAIT is specified and the event is not in the signaled state, then the EVT_NOTIFY_WAIT notify function is queued whenever a consumer of the event is waiting for the event (via WaitForEvent() or CheckEvent()). If the EVT_NOTIFY_SIGNAL flag is specified then the event’s notify function is queued whenever the event is signaled.

Note: Because its internal structure is unknown to the caller, Event cannot be modified by the caller. The only way to manipulate it is to use the published event interfaces.

Status Codes Returned

Status Code Description
EFI_SUCCESS The event structure was created.
EFI_INVALID_PARAMETER One of the parameters has an invalid value.
EFI_INVALID_PARAMETER Event is NULL.
EFI_INVALID_PARAMETER Type has an unsupported bit set.
EFI_INVALID_PARAMETER Type has both EVT_NOTIFY_SIGNAL and EVT_NOTIFY_WAIT set.
EFI_INVALID_PARAMETER Type has either EVT_NOTIFY_SIGNAL or EVT_NOTIFY_WAIT set and NotifyFunction is NULL.
EFI_INVALID_PARAMETER Type has either EVT_NOTIFY_SIGNAL or EVT_NOTIFY_WAIT set and NotifyTpl is not a supported TPL level.
EFI_OUT_OF_RESOURCES The event could not be allocated.

CreateEventEx()

Creates an event in a group.

Prototype

typedef
EFI_STATUS
CreateEventEx (
  IN  UINT32           Type,
  IN  EFI_TPL          NotifyTpl,
  IN  EFI_EVENT_NOTIFY NotifyFunction OPTIONAL,
  IN  CONST VOID       *NotifyContext OPTIONAL,
  IN  CONST EFI_GUID   *EventGroup OPTIONAL,
  OUT EFI_EVENT        *Event
  );

Parameters

Parameter Description
Type The type of event to create and its mode and attributes.
NotifyTpl The task priority level of event notifications,if needed. See RaiseTPL().
NotifyFunction Pointer to the event’s notification function, if any.
NotifyContext Pointer to the notification function’s context; corresponds to parameter Context in the notification function.
EventGroup Pointer to the unique identifier of the group to which this event belongs. If this is NULL, then the function behaves as if the parameters were passed to CreateEvent().
Event Pointer to the newly created event if the call succeeds; undefined otherwise.

Description
The CreateEventEx function creates a new event of type Type and returns it in the specified location indicated by Event. The event’s notification function, context and task priority are specified by NotifyFunction, NotifyContext, and NotifyTpl, respectively. The event will be added to the group of events identified by EventGroup.

If no group is specified by EventGroup, then this function behaves as if the same parameters had been passed to CreateEvent. Event groups are collections of events identified by a shared EFI_GUID where, when one member event is signaled, all other events are signaled and their individual notification actions are taken (as described in CreateEvent). All events are guaranteed to be signaled before the first notification action is taken. All notification functions will be executed in the order specified by their NotifyTpl. A single event can only be part of a single event group. An event may be removed from an event group by using CloseEvent().

The Type of an event uses the same values as defined in CreateEvent except that EVT_SIGNAL_EXIT_BOOT_SERVICES and EVT_SIGNAL_VIRTUAL_ADDRESS_CHANGE are not valid. If Type has EVT_NOTIFY_SIGNAL or EVT_NOTIFY_WAIT, then NotifyFunction must be non- NULL and NotifyTpl must be a valid task priority level. Otherwise these parameters are ignored. More than one event of type EVT_TIMER may be part of a single event group. However, there is no mechanism for determining which of the timers was signaled.

Configuration Table Groups
The GUID for a configuration table also defines a corresponding event group GUID with the same value . If the data represented by a configuration table is changed, InstallConfigurationTable() should be called. When InstallConfigurationTable() is called, the corresponding event is signaled. When this event is signaled, any components that cache information from the configuration table can optionally update their cached state. For example, EFI_ACPI_TABLE_GUID defines a configuration table for ACPI data. When ACPI data is changed, InstallConfigurationTable() is called. During the execution of InstallConfigurationTable(), a corresponding event group with EFI_ACPI_TABLE_GUID is signalled, allowing an application to invalidate any cached ACPI data.

Pre-Defined Event Groups This section describes the pre-defined event groups used by the UEFI specification.

Status Codes Returned

Status Code Description
EFI_SUCCESS The event structure was created.
EFI_INVALID_PARAMETER One of the parameters has an invalid value.
EFI_INVALID_PARAMETER Event is NULL.
EFI_INVALID_PARAMETER Type has an unsupported bit set.
EFI_INVALID_PARAMETER Type has both EVT_NOTIFY_SIGNAL and EVT_NOTIFY_WAIT set.
EFI_INVALID_PARAMETER Type has either EVT_NOTIFY_SIGNAL or EVT_NOTIFY_WAIT set and NotifyFunction is NULL.
EFI_INVALID_PARAMETER Type has either EVT_NOTIFY_SIGNAL or EVT_NOTIFY_WAIT set and NotifyTpl is not a supported TPL level.
EFI_OUT_OF_RESOURCES The event could not be allocated.


Exit()

Terminates a loaded EFI image and returns control to boot services.

Prototype

typedef
EFI_STATUS
Exit (
  IN EFI_HANDLE ImageHandle,
  IN EFI_STATUS ExitStatus,
  IN UINTN      ExitDataSize,
  IN CHAR16     *ExitData OPTIONAL
  );

Parameters

Parameter Description
ImageHandle Handle that identifies the image. This parameter is passed to the image on entry.
ExitStatus The image’s exit code.
ExitDataSize The size, in bytes, of ExitData. Ignored if ExitStatus is EFI_SUCCESS.
ExitData Pointer to a data buffer that includes a Null-terminated Unicode string, optionally followed by additional binary data. The string is a description that the caller may use to further indicate the reason for the image’s exit. ExitData is only valid if ExitStatus is something other than EFI_SUCCESS. The ExitData buffer must be allocated by calling AllocatePool().

Description
The Exit() function terminates the image referenced by ImageHandle and returns control to boot services. This function may not be called if the image has already returned from its entry point (EFI_IMAGE_ENTRY_POINT) or if it has loaded any child images that have not exited (all child images must exit before this image can exit).

Using Exit() is similar to returning from the image’s EFI_IMAGE_ENTRY_POINT except that Exit() may also return additional ExitData.

When an application exits a compliant system, 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(). (If the buffer is needed, firmware must allocate it by calling AllocatePool() and must return a pointer to it to the caller of StartImage().)

When an EFI boot service driver or runtime service driver exits, firmware frees the image only if the ExitStatus is an error code; otherwise the image stays resident in memory. The driver must not return an error code if it has installed any protocol handlers or other active callbacks into the system that have not (or cannot) be cleaned up. If the driver exits with an error code, it is responsible for freeing all resources before exiting. This includes any allocated memory (pages and/or pool), open file system handles, and so forth. It is valid to call Exit() or UnloadImage() for an image that was loaded by LoadImage() before calling StartImage(). This will free the image from memory without having started it.

If ImageHandle is a UEFI application, then all of the protocols that were opened by ImageHandle using the boot service OpenProtocol() are automatically closed with the boot service CloseProtocol(). If ImageHandle is an EFI boot services driver or runtime service driver, and ExitStatus is an error code, then all of the protocols that were opened by ImageHandle using the boot service OpenProtocol() are automatically closed with the boot service CloseProtocol(). If ImageHandle is an EFI boot services driver or runtime service driver, and ExitStatus is not an error code, then no protocols are automatically closed by this service.

Status Codes Returned

Status Code Description
(Does not return.) Image exit. Control is returned to the StartImage() call that invoked the image specified by ImageHandle.
EFI_SUCCESS The image specified by ImageHandle was unloaded. This condition only occurs for images that have been loaded with LoadImage() but have not been started with StartImage().
EFI_INVALID_PARAMETER The image specified by ImageHandle has been loaded and started with LoadImage() and StartImage(), but the image is not the currently executing image.

ExitBootServices()

Terminates all boot services.

Prototype

typedef
EFI_STATUS
ExitBootServices (
  IN EFI_HANDLE ImageHandle,
  IN UINTN      MapKey
  );

Parameters

Parameter Description
ImageHandle Handle that identifies the exiting image.
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. On success, the loader becomes responsible for the continued operation of the system. All events of type EVT_SIGNAL_EXIT_BOOT_SERVICES must be signaled before ExitBootServices() returns.

An EFI OS loader must ensure that it has the system’s current memory map at the time it calls ExitBootServices(). This is done by passing in the current memory map’s MapKey value as returned by GetMemoryMap(). Care must be taken to ensure that the memory map does not change between these two calls. It is suggested that GetMemoryMap() be called immediately before calling ExitBootServices(). If MapKey value is incorrect, ExitBootServices() returns EFI_INVALID_PARAMETER and GetMemoryMap() with ExitBootServices() must be called again. Firmware implementation may choose to do a partial shutdown of the boot services during the first call to ExitBootServices(). EFI OS loader should not make calls to any boot service function other then GetMemoryMap() after the first call to ExitBootServices().

On success, the EFI OS loader owns all available memory in the system. In addition, the loader can treat all memory in the map marked as EfiBootServicesCode and EfiBootServicesData as available free memory. No further calls to boot service functions or EFI device-handle-based protocols may be used, and the boot services watchdog timer is disabled. On success, several fields of the EFI System Table should be set to NULL. These include ConsoleInHandle, ConIn, ConsoleOutHandle, ConOut, StandardErrorHandle, StdErr, and BootServicesTable. In addition, since fields of the EFI System Table are being modified, the 32-bit CRC for the EFI System Table must be recomputed.

Status Codes Returned

Status Code Description
EFI_SUCCESS Boot services have been terminated.
EFI_INVALID_PARAMETER MapKey is incorrect.

FreePages()

Frees memory pages.

Prototype

typedef
EFI_STATUS
FreePages (
  IN EFI_PHYSICAL_ADDRESS Memory,
  IN UINTN                Pages
  );

Parameters

Parameter Description
Memory The base physical address of the pages to be freed.
Pages The number of contiguous 4 KB pages to free.

Description
The FreePages() function returns memory allocated by AllocatePages() to the firmware.

Status Codes Returned

Status Code Description
EFI_SUCCESS The requested memory pages were freed.
EFI_NOT_FOUND The requested memory pages were not allocated with AllocatePages().
EFI_INVALID_PARAMETER Memory is not a page-aligned address or Pages is invalid.

FreePool()

Returns pool memory to the system.

Prototype

typedef
EFI_STATUS
FreePool (
  IN VOID *Buffer
  );


Parameters

Parameter Description
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 AllocatePages().

Status Codes Returned

Status Code Description
EFI_SUCCESS The memory was returned to the system.
EFI_INVALID_PARAMETER Buffer was invalid.

GetMemoryMap()

Returns the current memory map.

Prototype

typedef
EFI_STATUS
GetMemoryMap (
  IN OUT UINTN                 *MemoryMapSize,
  IN OUT EFI_MEMORY_DESCRIPTOR *MemoryMap,
  OUT    UINTN                 *MapKey,
  OUT    UINTN                 *DescriptorSize,
  OUT    UINT32                *DescriptorVersion
);

Parameters

Parameter Description
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. On output, it is the size of the buffer returned by the firmware if the buffer was large enough, or the size of the buffer needed to contain the map if the buffer was too small.
MemoryMap A pointer to the buffer in which firmware places the current memory map. The map is an array of EFI_MEMORY_DESCRIPTORs.
MapKey A pointer to the location in which firmware returns the key for the current memory map.
DescriptorSize A pointer to the location in which firmware returns the size, in bytes, of an individual EFI_MEMORY_DESCRIPTOR.
DescriptorVersion A pointer to the location in which firmware returns the version number associated with the EFI_MEMORY_DESCRIPTOR.

Related Definitions

#define EFI_MEMORY_DESCRIPTOR_VERSION 1

Description
The GetMemoryMap() function returns a copy of the current memory map. The map is an array of memory descriptors, each of which describes a contiguous block of memory. The map describes all of memory, no matter how it is being used. That is, it includes blocks allocated by AllocatePages() and AllocatePool(), as well as blocks that the firmware is using for its own purposes. The memory map is only used to describe memory that is present in the system. Memory descriptors are never used to describe holes in the system memory map.

Until ExitBootServices() is called, the memory map is owned by the firmware and the currently executing EFI Image should only use memory pages it has explicitly allocated.

If the MemoryMap buffer is too small, the EFI_BUFFER_TOO_SMALL error code is returned and the MemoryMapSize value contains the size of the buffer needed to contain the current memory map. The actual size of the buffer allocated for the consequent call to GetMemoryMap() should be bigger then the value returned in MemoryMapSize, since allocation of the new buffer may potentially increase memory map size.

On success a MapKey is returned that identifies the current memory map. The firmware’s key is changed every time something in the memory map changes. In order to successfully invoke ExitBootServices() the caller must provide the current memory map key. 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. The structure of the EFI_MEMORY_DESCRIPTOR may be extended in the future but it will remain backwards compatible with the current definition. Thus OS software must use the DescriptorSize to find the start of each EFI_MEMORY_DESCRIPTOR in the MemoryMap array.

Status Codes Returned

Status Code Description
EFI_SUCCESS The memory map was returned in the MemoryMap buffer.
EFI_BUFFER_TOO_SMALL The MemoryMap buffer was too small. The current buffer size needed to hold the memory map is returned in MemoryMapSize.
EFI_INVALID_PARAMETER MemoryMapSize is NULL.
EFI_INVALID_PARAMETER The MemoryMap buffer is not too small and MemoryMap is NULL.

GetNextMonotonicCount()

Returns a monotonically increasing count for the platform.

Prototype

typedef
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. The low 32-bit value is volatile and is reset to zero on every system reset. It is increased by 1 on every call to GetNextMonotonicCount(). The high 32-bit value is nonvolatile and is increased by one on whenever the system resets or the low 32-bit counter overflows.

Status Codes Returned

Status Code Description
EFI_SUCCESS The next monotonic count was returned.
EFI_DEVICE_ERROR The device is not functioning properly.
EFI_INVALID_PARAMETER Count is NULL.

HandleProtocol()

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

Prototype

typedef
EFI_STATUS
HandleProtocol (
  IN  EFI_HANDLE Handle,
  IN  EFI_GUID   *Protocol,
  OUT VOID       **Interface
  );

Parameters
Handle The handle being queried. If Handle is not a valid EFI_HANDLE, then EFI_INVALID_PARAMETER is returned. Protocol The published unique identifier of the protocol. It is the caller’s responsibility to pass in a valid GUID. See “Wired For Management Baseline” for a description of valid GUID values. Interface Supplies the address where a pointer to the corresponding Protocol Interface is returned. NULL will be returned in *Interface if a structure is not associated with Protocol.

Description
The HandleProtocol() function queries Handle to determine if it supports Protocol. If it does, then on return Interface points to a pointer to the corresponding Protocol Interface. Interface can then be passed to any protocol service to identify the context of the request.

The HandleProtocol() function is still available for use by old EFI applications and drivers. However, all new applications and drivers should use OpenProtocol() in place of HandleProtocol(). The following code fragment shows a possible implementation of HandleProtocol() using OpenProtocol(). The variable EfiCoreImageHandle is the image handle of the EFI core.

EFI_STATUS
HandleProtocol (
  IN EFI_HANDLE Handle,
  IN EFI_GUID *Protocol,
  OUT VOID **Interface
  )
{
  return OpenProtocol (
    Handle,
    Protocol,
    Interface,
    EfiCoreImageHandle,
    NULL,
    EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
    );
}

Status Codes Returned

Status Code Description
EFI_SUCCESS The interface information for the specified protocol was returned.
EFI_UNSUPPORTED The device does not support the specified protocol.
EFI_INVALID_PARAMETER Handle is not a valid EFI_HANDLE..
EFI_INVALID_PARAMETER Protocol is NULL.
EFI_INVALID_PARAMETER Interface is NULL

InstallConfigurationTable()

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

Prototype

typedef
EFI_STATUS
InstallConfigurationTable (
  IN EFI_GUID *Guid,
  IN VOID     *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.

Description
The InstallConfigurationTable() function is used to maintain the list of configuration tables that are stored in the EFI System Table. The list is stored as an array of (GUID, Pointer) pairs. The list must be allocated from pool memory with PoolType set to EfiRuntimeServicesData.

If Guid is not a valid GUID, EFI_INVALID_PARAMETER is returned. If Guid is valid, there are four possibilities: • If Guid is not present in the System Table, and Table is not NULL, then the (Guid, Table) pair is added to the System Table. See Note below.

  • If Guid is not present in the System Table, and Table is NULL, then EFI_NOT_FOUND is returned.
  • If Guid is present in the System Table, and Table is not NULL, then the (Guid, Table) pair is updated with the new Table value.
  • If Guid is present in the System Table, and Table is NULL, then the entry associated with Guid is removed from the System Table. 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

Status Code Description
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 nonexistent entry.
EFI_OUT_OF_RESOURCES There is not enough memory available to complete the operation.

InstallProtocolInterface()

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. InstallMultipleProtocolInterfaces() performs more error checking than InstallProtocolInterface(), so it is recommended that InstallMultipleProtocolInterfaces() be used in place of InstallProtocolInterface().

Prototype

typedef
EFI_STATUS
InstallProtocolInterface (
  IN OUT EFI_HANDLE     *Handle,
  IN EFI_GUID           *Protocol,
  IN EFI_INTERFACE_TYPE InterfaceType,
  IN VOID               *Interface
  );

Parameters

Parameter Description
Handle A pointer to the EFI_HANDLE on which the interface is to be installed. If *Handle is NULL on input, a new handle is created and returned on output. If *Handle is not NULL on input, the protocol is added to the handle, and the handle is returned unmodified. If *Handle is not a valid handle, then EFI_INVALID_PARAMETER is returned.
Protocol The numeric ID of the protocol interface. It is the caller’s responsibility to pass in a valid GUID.
InterfaceType Indicates whether Interface is supplied in native form. This value indicates the original execution environment of the request.
Interface A pointer to the protocol interface. The Interface must adhere to the structure defined by Protocol. NULL can be used if a structure is not associated with Protocol.

Description
The InstallProtocolInterface() function installs a protocol interface (a GUID/Protocol Interface structure pair) on a device handle. The same GUID cannot be installed more than once onto the same handle. If installation of a duplicate GUID on a handle is attempted, an EFI_INVALID_PARAMETER will result.

Installing a protocol interface allows other components to locate the Handle, and the interfaces installed on it.

When a protocol interface is installed, the firmware calls all notification functions that have registered to wait for the installation of Protocol. For more information, see the RegisterProtocolNotify() function description.

Status Codes Returned

Status Code Description
EFI_SUCCESS The protocol interface was installed.
EFI_OUT_OF_RESOURCES Space for a new handle could not be allocated.
EFI_INVALID_PARAMETER Handle is NULL
EFI_INVALID_PARAMETER Protocol is NULL.
EFI_INVALID_PARAMETER InterfaceType is not EFI_NATIVE_INTERFACE.
EFI_INVALID_PARAMETER Protocol is already installed on the handle specified by Handle.

LoadImage()

Loads an EFI image into memory.

Prototype

typedef
EFI_STATUS
LoadImage (
  IN BOOLEAN BootPolicy,
  IN EFI_HANDLE ParentImageHandle,
  IN EFI_DEVICE_PATH_PROTOCOL *DevicePath,
  IN VOID *SourceBuffer OPTIONAL,
  IN UINTN SourceSize,
  OUT EFI_HANDLE *ImageHandle
  );


Parameters

Parameter Description
BootPolicy If TRUE, indicates that the request originates from the boot manager, and that the boot manager is attempting to load DevicePath as a boot selection. Ignored if SourceBuffer is not NULL.
ParentImageHandle The caller’s image handle. This field is used to initialize the ParentHandle field of the EFI_LOADED_IMAGE_PROTOCOL for the image that is being loaded.
DevicePath The DeviceHandle specific file path from which the image is loaded.
SourceBuffer If not NULL, a pointer to the memory location containing a copy of the image to be loaded.
SourceSize The size in bytes of SourceBuffer. Ignored if SourceBuffer is NULL.
ImageHandle Pointer to the returned image handle that is created when the image is successfully loaded.

Description
The LoadImage() function loads a UEFI 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.
  • If SourceBuffer is NULL, the function is a file copy operation that uses the EFI_SIMPLE_FILE_SYSTEM_PROTOCOL. If there is no instance of EFI_SIMPLE_FILE_SYSTEM_PROTOCOL associated with file path, then this function will attempt to use EFI_LOAD_FILE_PROTOCOL (BootPolicy is TRUE) or EFI_LOAD_FILE2_PROTOCOL, and then EFI_LOAD_FILE_PROTOCOL (BootPolicy is FALSE).

In all cases, this function will use the instance of these protocols associated with the handle that most closely matches DevicePath will be used. See the boot service description for more information on how the closest handle is located.

LoadFile() function. The default image responsible for booting is loaded when DevicePath specifies only the device (and there are no further device nodes).

  • In the case of EFI_LOAD_FILE2_PROTOCOL, the behavior is the same as above, except that it is only used if BootOption is FALSE.
  • If the platform supports driver signing and the image signature is not valid, then information about the image is recorded and EFI_SECURITY_VIOLATION is returned.
  • If the platform supports user authentication and loading of images on the specified FilePath is forbidden in the current user profile, then the information about the image is recorded and EFI_SECURITY_VIOLATION is returned.

Once the image is loaded, firmware creates and returns an EFI_HANDLE that identifies the image and supports EFI_LOADED_IMAGE_PROTOCOL and the EFI_LOADED_IMAGE_DEVICE_PATH_PROTOCOL. The caller may fill in the image’s “load options” data, or add additional protocol support to the handle before passing control to the newly loaded image by calling StartImage(). Also, once the image is loaded, the caller either starts it by calling StartImage() or unloads it by calling UnloadImage().

Once the image is loaded, LoadImage() installs the EFI_HII_PACKAGE_LIST_PROTOCOL on the handle if the image contains a custom PE/COFF resource with the type 'HII'. The protocol's interface pointer points to the HII package list which is contained in the resource's data.

Status Codes Returned

Status Code Description
EFI_SUCCESS Image was loaded into memory correctly.
EFI_NOT_FOUND Both SourceBuffer and DevicePath are NULL.
EFI_INVALID_PARAMETER One of the parameters has an invalid value.
EFI_INVALID_PARAMETER ImageHandle is NULL.
EFI_INVALID_PARAMETER ParentImageHandle is NULL.
EFI_INVALID_PARAMETER ParentImageHandle is not a valid EFI_HANDLE.
EFI_UNSUPPORTED The image type is not supported.
EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient resources.
EFI_LOAD_ERROR Image was not loaded because the image format was corrupt or not understood.
EFI_DEVICE_ERROR Image was not loaded because the device returned a read error.
EFI_SECURITY_VIOLATION Image was not loaded because the image's signature was invalid.

LocateDevicePath()

Locates the handle to a device on the device path that supports the specified protocol.

Prototype

typedef
EFI_STATUS
LocateDevicePath (
  IN     EFI_GUID                 *Protocol,
  IN OUT EFI_DEVICE_PATH_PROTOCOL **DevicePath,
  OUT    EFI_HANDLE               *Device
  );

Parameters

Parameter Description
Protocol The protocol to search for.
DevicePath On input, a pointer to a pointer to the device path. On output, the device path pointer is modified to point to the remaining part of the device path—that is, when the function finds the closest handle, it splits the device path into two parts, stripping off the front part, and returning the remaining portion.
Device A pointer to the returned device handle.

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. For example, a target device driver may issue the request with its own device path and locate the interfaces to perform I/O on its bus. It can also be used with a device path that contains a file path to strip off the file system portion of the device path, leaving the file path and handle to the file system driver needed to access the file.

If the handle for DevicePath supports the protocol (a direct match), the resulting device path is advanced to the device path terminator node.

Status Codes Returned

Status Code Description
EFI_SUCCESS The resulting handle was returned.
EFI_NOT_FOUND No handles matched the search.
EFI_INVALID_PARAMETER Protocol is NULL
EFI_INVALID_PARAMETER DevicePath is NULL.
EFI_INVALID_PARAMETER A handle matched the search and Device is NULL.

LocateHandle()

Returns an array of handles that support a specified protocol.

Prototype

typedef
EFI_STATUS
LocateHandle (
  IN     EFI_LOCATE_SEARCH_TYPE SearchType,
  IN     EFI_GUID               *Protocol OPTIONAL,
  IN     VOID                   *SearchKey OPTIONAL,
  IN OUT UINTN                  *BufferSize,
  OUT    EFI_HANDLE             *Buffer
  );

Parameters

Parameter Description
SearchType Specifies which handle(s) are to be returned.
Protocol Specifies the protocol to search by. This parameter is only valid if SearchType is ByProtocol.
SearchKey Specifies the search key. This parameter is ignored if SearchType is AllHandles or ByProtocol. If SearchType is ByRegisterNotify, the parameter must be the Registration value returned by function RegisterProtocolNotify().
BufferSize On input, the size in bytes of Buffer. On output, the size in bytes of the array returned in Buffer (if the buffer was large enough) or the size, in bytes, of the buffer needed to obtain the array (if the buffer was not large enough).
Buffer The buffer in which the array is returned.

Description
The LocateHandle() function returns an array of handles that match the SearchType request. If the input value of BufferSize is too small, the function returns EFI_BUFFER_TOO_SMALL and updates BufferSize to the size of the buffer needed to obtain the array.

Status Codes Returned

Status Code Description
EFI_SUCCESS The array of handles was returned.
EFI_NOT_FOUND No handles match the search.
EFI_BUFFER_TOO_SMALL The BufferSize is too small for the result. BufferSize has been updated with the size needed to complete the request.
EFI_INVALID_PARAMETER SearchType is not a member of EFI_LOCATE_SEARCH_TYPE.
EFI_INVALID_PARAMETER SearchType is ByRegisterNotify and SearchKey is NULL.
EFI_INVALID_PARAMETER SearchType is ByProtocol and Protocol is NULL.
EFI_INVALID_PARAMETER One or more matches are found and BufferSize is NULL.
EFI_INVALID_PARAMETER BufferSize is large enough for the result and Buffer is NULL

LocateProtocol()

Returns the first protocol instance that matches the given protocol.

Prototype

typedef
EFI_STATUS
LocateProtocol (
  IN  EFI_GUID *Protocol,
  IN  VOID     *Registration OPTIONAL,
  OUT VOID     **Interface
  );

Parameters

Parameter Description
Protocol Provides the protocol to search for.
Registration Optional registration key returned from RegisterProtocolNotify(). If Registration is NULL, then it is ignored.
Interface On return, a pointer to the first interface that matches Protocol and Registration.

Description
The LocateProtocol() function finds the first device handle that support Protocol, and returns a pointer to the protocol interface from that handle in Interface. If no protocol instances are found, then Interface is set to NULL.

If Interface is NULL, then EFI_INVALID_PARAMETER is returned. If Registration is NULL, and there are no handles in the handle database that support Protocol, then EFI_NOT_FOUND is returned.

If Registration is not NULL, and there are no new handles for Registration, then EFI_NOT_FOUND is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS A protocol instance matching Protocol was found and returned in Interface.
EFI_INVALID_PARAMETER Interface is NULL.
EFI_NOT_FOUND No protocol instances were found that match Protocol and Registration.

OpenProtocol()

Queries a handle to determine if it supports a specified protocol. If the protocol is supported by the handle, it opens the protocol on behalf of the calling agent. This is an extended version of the EFI boot service HandleProtocol().

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_OPEN_PROTOCOL) (
  IN  EFI_HANDLE Handle,
  IN  EFI_GUID   *Protocol,
  OUT VOID       **Interface OPTIONAL,
  IN  EFI_HANDLE AgentHandle,
  IN  EFI_HANDLE ControllerHandle,
  IN  UINT32     Attributes
  );

Parameters

Parameter Description
Handle The handle for the protocol interface that is being opened.
Protocol The published unique identifier of the protocol. It is the caller’s responsibility to pass in a valid GUID. See “Wired For Management Baseline” for a description of valid GUID values.
Interface Supplies the address where a pointer to the corresponding Protocol Interface is returned. NULL will be returned in *Interface if a structure is not associated with Protocol. This parameter is optional, and will be ignored if Attributes is EFI_OPEN_PROTOCOL_TEST_PROTOCOL.
AgentHandle The handle of the agent that is opening the protocol interface specified by Protocol and Interface. For agents that follow the UEFI Driver Model, this parameter is the handle that contains the EFI_DRIVER_BINDING_PROTOCOL instance that is produced by the UEFI driver that is opening the protocol interface. For UEFI applications, this is the image handle of the UEFI application that is opening the protocol interface. For applications that use HandleProtocol() to open a protocol interface, this parameter is the image handle of the EFI firmware.
ControllerHandle If the agent that is opening a protocol is a driver that follows the UEFI Driver Model, then this parameter is the controller handle that requires the protocol interface. If the agent does not follow the UEFI Driver Model, then this parameter is optional and may be NULL.
Attributes The open mode of the protocol interface specified by Handle and Protocol. See "Related Definitions" for the list of legal attributes.

Description
This function opens a protocol interface on the handle specified by Handle for the protocol specified by Protocol. The first three parameters are the same as HandleProtocol(). The only difference is that the agent that is opening a protocol interface is tracked in an EFI's internal handle database. The tracking is used by the UEFI Driver Model, and also used to determine if it is safe to uninstall or reinstall a protocol interface.

The agent that is opening the protocol interface is specified by AgentHandle, ControllerHandle, and Attributes. If the protocol interface can be opened, then AgentHandle, ControllerHandle, and Attributes are added to the list of agents that are consuming the protocol interface specified by Handle and Protocol. In addition, the protocol interface is returned in Interface, and EFI_SUCCESS is returned. If Attributes is TEST_PROTOCOL, then Interface is optional, and can be NULL.

There are a number of reasons that this function call can return an error. If an error is returned, then AgentHandle, ControllerHandle, and Attributes are not added to the list of agents consuming the protocol interface specified by Handle and Protocol, and Interface is returned unmodified. The following is the list of conditions that must be checked before this function can return EFI_SUCCESS.

If Protocol is NULL, then EFI_INVALID_PARAMETER is returned.

If Interface is NULL and Attributes is not TEST_PROTOCOL, then EFI_INVALID_PARAMETER is returned.

If Handle is not a valid EFI_HANDLE, then EFI_INVALID_PARAMETER is returned.

If Handle does not support Protocol, then EFI_UNSUPPORTED is returned.

If Attributes is not a legal value, then EFI_INVALID_PARAMETER is returned.

If Attributes is BY_CHILD_CONTROLLER, BY_DRIVER, EXCLUSIVE, or BY_DRIVER|EXCULSIVE, and AgentHandle is not a valid EFI_HANDLE, then EFI_INVALID_PARAMETER is returned.

If Attributes is BY_CHILD_CONTROLLER, BY_DRIVER, or BY_DRIVER|EXCULSIVE, and ControllerHandle is not a valid EFI_HANDLE, then EFI_INVALID_PARAMETER is returned.

If Attributes is BY_CHILD_CONTROLLER and Handle is identical to ControllerHandle, then EFI_INVALID_PARAMETER is returned.

If Attributes is BY_DRIVER , BY_DRIVER|EXCLUSIVE, or EXCLUSIVE, and there are any items on the open list of the protocol interface with an attribute of EXCLUSIVE or BY_DRIVER|EXCLUSIVE, then EFI_ACCESS_DENIED is returned.

If Attributes is BY_DRIVER, and there are any items on the open list of the protocol interface with an attribute of BY_DRIVER, and AgentHandle is the same agent handle in the open list item, then EFI_ALREADY_STARTED is returned.

If Attributes is BY_DRIVER, and there are any items on the open list of the protocol interface with an attribute of BY_DRIVER, and AgentHandle is different than the agent handle in the open list item, then EFI_ACCESS_DENIED is returned.

If Attributes is BY_DRIVER|EXCLUSIVE, and there are any items on the open list of the protocol interface with an attribute of BY_DRIVER|EXCLUSIVE, and AgentHandle is the same agent handle in the open list item, then EFI_ALREADY_STARTED is returned.

If Attributes is BY_DRIVER|EXCLUSIVE, and there are any items on the open list of the protocol interface with an attribute of BY_DRIVER|EXCLUSIVE, and AgentHandle is different than the agent handle in the open list item, then EFI_ACCESS_DENIED is returned.

If Attributes is BY_DRIVER|EXCLUSIVE or EXCLUSIVE, and there is an item on the open list of the protocol interface with an attribute of BY_DRIVER, then the boot service DisconnectController() is called for the driver on the open list. If there is an item in the open list of the protocol interface with an attribute of BY_DRIVER remaining after the DisconnectController() call has been made, EFI_ACCESS_DENIED is returned.

Related Definitions

#define EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL  0x00000001
#define EFI_OPEN_PROTOCOL_GET_PROTOCOL        0x00000002
#define EFI_OPEN_PROTOCOL_TEST_PROTOCOL       0x00000004
#define EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER 0x00000008
#define EFI_OPEN_PROTOCOL_BY_DRIVER           0x00000010
#define EFI_OPEN_PROTOCOL_EXCLUSIVE           0x00000020


Attribute Description
EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL Used in the implementation of HandleProtocol(). Since OpenProtocol() performs the same function as HandleProtocol() with additional functionality, HandleProtocol() can simply call OpenProtocol() with this Attributes value.
EFI_OPEN_PROTOCOL_GET_PROTOCOL Used by a driver to get a protocol interface from a handle. Care must be taken when using this open mode because the driver that opens a protocol interface in this manner will not be informed if the protocol interface is uninstalled or reinstalled. The caller is also not required to close the protocol interface with CloseProtocol().
EFI_OPEN_PROTOCOL_TEST_PROTOCOL CloseProtocol()]].
EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER Used by bus drivers to show that a protocol interface is being used by one of the child controllers of a bus. This information is used by the boot service ConnectController() to recursively connect all child controllers and by the boot service DisconnectController() to get the list of child controllers that a bus driver created.
EFI_OPEN_PROTOCOL_BY_DRIVER Used by a driver to gain access to a protocol interface. When this mode is used, the driver’s Stop() function will be called by DisconnectController() if the protocol interface is reinstalled or uninstalled. Once a protocol interface is opened by a driver with this attribute, no other drivers will be allowed to open the same protocol interface with the BY_DRIVER attribute.
EFI_OPEN_PROTOCOL_EXCLUSIVE Used by a driver to gain exclusive access to a protocol interface. If any other drivers have the protocol interface opened with an attribute of BY_DRIVER, then an attempt will be made to remove them with DisconnectController().
EFI_OPEN_PROTOCOL_EXCLUSIVE Used by applications to gain exclusive access to a protocol interface. If any drivers have the protocol interface opened with an attribute of BY_DRIVER, then an attempt will be made to remove them by calling the driver’s Stop() function.

Status Codes Returned

EFI_SUCCESS An item was added to the open list for the protocol interface, and the protocol interface was returned in Interface.
EFI_INVALID_PARAMETER Protocol is NULL.
EFI_INVALID_PARAMETER Interface is NULL, and Attributes is not TEST_PROTOCOL.
EFI_INVALID_PARAMETER Handle is not a valid EFI_HANDLE.
EFI_UNSUPPORTED Handle does not support Protocol.
EFI_INVALID_PARAMETER Attributes is not a legal value.
EFI_INVALID_PARAMETER Attributes is BY_CHILD_CONTROLLER and AgentHandle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER Attributes is BY_DRIVER and AgentHandle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER EXCLUSIVE and AgentHandle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER Attributes is EXCLUSIVE and AgentHandle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER Attributes is BY_CHILD_CONTROLLER and ControllerHandle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER Attributes is BY_DRIVER and ControllerHandle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER EXCLUSIVE and ControllerHandle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER Attributes is BY_CHILD_CONTROLLER and Handle is identical to ControllerHandle.
EFI_ACCESS_DENIED EXCLUSIVE or EXCLUSIVE.
EFI_ACCESS_DENIED EXCLUSIVE and there is an item on the open list with an attribute of EXCLUSIVE.
EFI_ACCESS_DENIED EXCLUSIVE or EXCLUSIVE.
EFI_ALREADY_STARTED Attributes is BY_DRIVER and there is an item on the open list with an attribute of BY_DRIVER whose agent handle is the same as AgentHandle.
EFI_ACCESS_DENIED Attributes is BY_DRIVER and there is an item on the open list with an attribute of BY_DRIVER whose agent handle is different than AgentHandle.
EFI_ALREADY_STARTED EXCLUSIVE and there is an item on the open list with an attribute of BY_DRIVER|EXCLUSIVE whose agent handle is the same as AgentHandle.
EFI_ACCESS_DENIED EXCLUSIVE and there is an item on the open list with an attribute of BY_DRIVER|EXCLUSIVE whose agent handle is different than AgentHandle.
EFI_ACCESS_DENIED EXCLSUIVE or EXCLUSIVE and there are items in the open list with an attribute of BY_DRIVER that could not be removed when DisconnectController() was called for that open item.

Examples

EFI_BOOT_SERVICES *gBS;
EFI_HANDLE ImageHandle;
EFI_DRIVER_BINDING_PROTOCOL *This;
IN EFI_HANDLE ControllerHandle,
extern EFI_GUID gEfiXyzIoProtocol;
EFI_XYZ_IO_PROTOCOL *XyzIo;
EFI_STATUS Status;
//
// EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL example
// Retrieves the XYZ I/O Protocol instance from ControllerHandle
// The application that is opening the protocol is identified by ImageHandle
// Possible return status codes:
// EFI_SUCCESS : The protocol was opened and returned in XyzIo
// EFI_UNSUPPORTED : The protocol is not present on ControllerHandle
//
Status = gBS->OpenProtocol (
  ControllerHandle,
  &gEfiXyzIoProtocol,
  &XyzIo,
  ImageHandle,
  NULL,
  EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL
  );

OpenProtocolInformation()

Retrieves the list of agents that currently have a protocol interface opened.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_OPEN_PROTOCOL_INFORMATION) (
  IN  EFI_HANDLE                          Handle,
  IN  EFI_GUID                            *Protocol,
  OUT EFI_OPEN_PROTOCOL_INFORMATION_ENTRY **EntryBuffer,
  OUT UINTN                               *EntryCount
  );

Parameters

Parameter Description
Handle The handle for the protocol interface that is being queried.
Protocol The published unique identifier of the protocol. It is the caller’s responsibility to pass in a valid GUID. See “Wired For Management Baseline” for a description of valid GUID values.
EntryBuffer A pointer to a buffer of open protocol information in the form of EFI_OPEN_PROTOCOL_INFORMATION_ENTRY structures. See "Related Definitions" for the declaration of this type. The buffer is allocated by this service, and it is the caller's responsibility to free this buffer when the caller no longer requires the buffer's contents.
EntryCount A pointer to the number of entries in EntryBuffer.

Description
This function allocates and returns a buffer of EFI_OPEN_PROTOCOL_INFORMATION_ENTRY structures. The buffer is returned in EntryBuffer, and the number of entries is returned in EntryCount.

If the interface specified by Protocol is not supported by the handle specified by Handle, then EFI_NOT_FOUND is returned.

If the interface specified by Protocol is supported by the handle specified by Handle, then EntryBuffer is allocated with the boot service AllocatePool(), and EntryCount is set to the number of entries in EntryBuffer. Each entry of EntryBuffer is filled in with the image handle, controller handle, and attributes that were passed to OpenProtocol() when the protocol interface was opened. The field OpenCount shows the number of times that the protocol interface has been opened by the agent specified by ImageHandle, ControllerHandle, and Attributes. After the contents of EntryBuffer have been filled in, EFI_SUCCESS is returned. It is the caller’s responsibility to call FreePool() on EntryBuffer when the caller no longer required the contents of EntryBuffer.

If there are not enough resources available to allocate EntryBuffer, then EFI_OUT_OF_RESOURCES is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The open protocol information was returned in EntryBuffer, and the number of entries was returned EntryCount.
EFI_NOT_FOUND Handle does not support the protocol specified by Protocol.
EFI_OUT_OF_RESOURCES There are not enough resources available to allocate EntryBuffer.

RaiseTPL()

Raises a task’s priority level and returns its previous level.

Prototype

typedef
EFI_TPL
RaiseTPL (
  IN EFI_TPL NewTpl
  );

Parameters

Parameter Description
NewTpl The new task priority level. It must be greater than or equal to the current task priority level.

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 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. By raising the task priority level to TPL_NOTIFY such notifications are masked until the task priority level is restored, thereby synchronizing execution with such notifications. Synchronous blocking I/O functions execute at TPL_NOTIFY. TPL_CALLBACK is the typically used for application level notification functions. Device drivers will typically use TPL_CALLBACK or TPL_NOTIFY for their notification functions. Applications and drivers may also use TPL_NOTIFY to protect data structures in critical sections of code.

The caller must restore the task priority level with RestoreTPL() to the previous level before returning.

NOTE: If NewTpl is below the current TPL level, then the system behavior is indeterminate. Additionally, only TPL_APPLICATION, TPL_CALLBACK, TPL_NOTIFY, and TPL_HIGH_LEVEL may be used. All other values are reserved for use by the firmware; using them will result in unpredictable behavior. Good coding practice dictates that all code should execute at its lowest possible TPL level, and the use of TPL levels above TPL_APPLICATION must be minimized. Executing at TPL levels above TPL_APPLICATION for extended periods of time may also result in unpredictable behavior.

Status Codes Returned
Unlike other UEFI interface functions, RaiseTPL() does not return a status code. Instead, it returns the previous task priority level, which is to be restored later with a matching call to RestoreTPL().

RestoreTPL()

Restores a task’s priority level to its previous value.

Prototype

typedef
VOID
RestoreTPL (
  IN EFI_TPL OldTpl
  );

Parameters

Parameter Description
OldTpl The previous task priority level to restore (the value from a previous, matching call to RaiseTPL()).

Description
The RestoreTPL() function restores a task’s priority level to its previous value. Calls to RestoreTPL() are matched with calls to RaiseTPL(). Note: If OldTpl is above the current TPL level, then the system behavior is indeterminate. Additionally, only TPL_APPLICATION, TPL_CALLBACK, TPL_NOTIFY, and TPL_HIGH_LEVEL may be used. All other values are reserved for use by the firmware; using them will result in unpredictable behavior. Good coding practice dictates that all code should execute at its lowest possible TPL level, and the use of TPL levels above TPL_APPLICATION must be minimized. Executing at TPL levels above TPL_APPLICATION for extended periods of time may also result in unpredictable behavior.

Status Codes Returned
None.

ReinstallProtocolInterface()

Reinstalls a protocol interface on a device handle.

Prototype

typedef
EFI_STATUS
ReinstallProtocolInterface (
  IN EFI_HANDLE Handle,
  IN EFI_GUID   *Protocol,
  IN VOID       *OldInterface,
  IN VOID       *NewInterface
  );

Parameters

Parameter Description
Handle Handle on which the interface is to be reinstalled. If Handle is not a valid handle, then EFI_INVALID_PARAMETER is returned.
Protocol The numeric ID of the interface. It is the caller’s responsibility to pass in a valid GUID. See “Wired For Management Baseline” for a description of valid GUID values.
OldInterface A pointer to the old interface. NULL can be used if a structure is not associated with Protocol.
NewInterface A pointer to the new interface. NULL can be used if a structure is not associated with Protocol.

Description
The ReinstallProtocolInterface() function reinstalls a protocol interface on a device handle. The OldInterface for Protocol is replaced by the NewInterface. NewInterface may be the same as OldInterface. If it is, the registered protocol notifies occur for the handle without replacing the interface on the handle.

As with InstallProtocolInterface(), any process that has registered to wait for the installation of the interface is notified. The caller is responsible for ensuring that there are no references to the OldInterface that is being removed.

The extension to this service directly addresses the limitations described in the section above. There may be some number of drivers currently consuming the protocol interface that is being reinstalled. In this case, it may be dangerous to replace a protocol interface in the system. It could result in an unstable state, because a driver may attempt to use the old protocol interface after a new one has been reinstalled. Since the usage of protocol interfaces is now being tracked for components that use the OpenProtocol() and CloseProtocol() boot services, a safe version of this function can be implemented.

When this function is called, a call is first made to the boot service InstallProtocolInterface(). This will guarantee that all of the agents are currently consuming the protocol interface OldInterface will stop using OldInterface. If UninstallProtocolInterface() returns EFI_ACCESS_DENIED, then this function returns EFI_ACCESS_DENIED, OldInterface remains on Handle, and the protocol notifies are not processed because NewInterface was never installed.

If UninstallProtocolInterface() succeeds, then a call is made to the boot service InstallProtocolInterface() to put the NewInterface onto Handle.

Finally, the boot service ConnectController() is called so all agents that were forced to release OldInterface with UninstallProtocolInterface() can now consume the protocol interface NewInterface that was installed with InstallProtocolInterface(). After OldInterface has been replaced with NewInterface, any process that has registered to wait for the installation of the interface is notified.

Status Codes Returned

Status Code Description
EFI_SUCCESS The protocol interface was reinstalled.
EFI_NOT_FOUND The OldInterface on the handle was not found.
EFI_ACCESS_DENIED The protocol interface could not be reinstalled, because OldInterface is still being used by a driver that will not release it.
EFI_INVALID_PARAMETER Handle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER Protocol is NULL

RegisterProtocolNotify()

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

Prototype

typedef
EFI_STATUS
RegisterProtocolNotify (
  IN EFI_GUID  *Protocol,
  IN EFI_EVENT Event,
  OUT VOID     **Registration
  );

Parameters

Parameter Description
Protocol The numeric ID of the protocol for which the event is to be registered.
Event Event that is to be signaled whenever a protocol interface is registered for Protocol. The same EFI_EVENT may be used for multiple protocol notify registrations.
Registration A pointer to a memory location to receive the registration value. This value must be saved and used by the notification function of Event to retrieve the list of handles that have added a protocol interface of type Protocol.

Description
The RegisterProtocolNotify() function creates an event that is to be signaled whenever a protocol interface is installed for Protocol by InstallProtocolInterface() or ReinstallProtocolInterface().

Once Event has been signaled, the LocateHandle() function can be called to identify the newly installed, or reinstalled, handles that support Protocol. The Registration parameter in RegisterProtocolNotify() corresponds to the SearchKey parameter in LocateHandle(). Note that the same handle may be returned multiple times if the handle reinstalls the target protocol ID multiple times. This is typical for removable media devices, because when such a device reappears, it will reinstall the Block I/O protocol to indicate that the device needs to be checked again. In response, layered Disk I/O and Simple File System protocols may then reinstall their protocols to indicate that they can be re-checked, and so forth.

Status Codes Returned

Status Code Description
EFI_SUCCESS The notification event has been registered.
EFI_OUT_OF_RESOURCES Space for the notification event could not be allocated.
EFI_INVALID_PARAMETER Protocol is NULL.
EFI_INVALID_PARAMETER Event is NULL.
EFI_INVALID_PARAMETER Registration is NULL.

SetMem()

The SetMem() function fills a buffer with a specified value.

Prototype

typedef
VOID
SetMem (
  IN VOID  *Buffer,
  IN UINTN Size,
  IN UINT8 Value
  );

Parameters
Buffer Pointer to the buffer to fill. Size Number of bytes in Buffer to fill. Value Value to fill Buffer with.

Description
This function fills Size bytes of Buffer with Value. The implementation of SetMem() must be reentrant. If Buffer crosses the top of the processor’s address space, the result of the SetMem() operation is unpredictable.

Status Codes Returned
None.

SetEvent()

Checks whether an event is in the signaled state.

Prototype

typedef
EFI_STATUS
CheckEvent (
  IN EFI_EVENT Event
  );

Parameters

Parameter Description
Event The event to check.

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. Otherwise, there are three possibilities:

  • If Event is in the signaled state, it is cleared and EFI_SUCCESS is returned.
  • If Event is not in the signaled state and has no notification function, EFI_NOT_READY is returned.
  • If Event is not in the signaled state but does have a notification function, the notification function is queued at the event’s notification task priority level. If the execution of the notification function causes Event to be signaled, then the signaled state is cleared and EFI_SUCCESS is returned; if the Event is not signaled, then EFI_NOT_READY is returned.

Status Codes Returned

Status Code Description
EFI_SUCCESS The event is in the signaled state.
EFI_NOT_READY The event is not in the signaled state.
EFI_INVALID_PARAMETER Event is of type EVT_NOTIFY_SIGNAL.

SetTimer()

Sets the type of timer and the trigger time for a timer event.

Prototype

typedef
EFI_STATUS
SetTimer (
  IN EFI_EVENT       Event,
  IN EFI_TIMER_DELAY Type,
  IN UINT64          TriggerTime
  );

Parameters

Parameter Description
Event The timer event that is to be signaled at the specified time.
Type The type of time that is specified in TriggerTime.
TriggerTime The number of 100ns units until the timer expires. A TriggerTime of 0 is legal. If Type is TimerRelative and TriggerTime is 0, then the timer event will be signaled on the next timer tick. If Type is TimerPeriodic and TriggerTime is 0, then the timer event will be signaled on every timer tick.

Status Codes Returned

Status Code Description
EFI_SUCCESS The event has been set to be signaled at the requested time.
EFI_INVALID_PARAMETER Event or Type is not valid.

SetWatchdogTimer()

Sets the system’s watchdog timer.

Prototype

typedef
EFI_STATUS
SetWatchdogTimer (
  IN UINTN   Timeout,
  IN UINT64  WatchdogCode,
  IN UINTN   DataSize,
  IN CHAR16* WatchdogData OPTIONAL
  );

Parameters

Parameter Description
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. Loaders and operating systems may use other timeout codes.
DataSize The size, in bytes, of WatchdogData.
WatchdogData A data buffer that includes a Null-terminated Unicode string, optionally followed by additional binary data. The string is a description that the call may use to further indicate the reason to be logged with a watchdog event.

Description
The SetWatchdogTimer() function sets the system’s watchdog timer.

If the watchdog timer expires, the event is logged by the firmware. The system may then either reset with the Runtime Service ResetSystem(), or perform a platform specific action that must eventually cause the platform to be reset. The watchdog timer is armed before the firmware's boot manager invokes an EFI boot option. The watchdog must be set to a period of 5 minutes. The EFI Image may reset or disable the watchdog timer as needed. If control is returned to the Boot Manager, the watchdog timer must be disabled.

The watchdog timer is only used during boot services. On successful completion of ExitBootServices() the watchdog timer is disabled.

The accuracy of the watchdog timer is +/- 1 second from the requested Timeout.

Status Codes Returned

Status Code Description
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.

SignalEvent()

Signals an event.

Prototype

typedef
EFI_STATUS
SignalEvent (
  IN EFI_EVENT Event 
  );

Parameters

Parameter Description
Event The event to signal.

Description
The supplied Event is placed in the signaled state. If Event is already in the signaled state, then EFI_SUCCESS is returned. If Event is of type EVT_NOTIFY_SIGNAL, then the event’s notification function is scheduled to be invoked at the event’s notification task priority level. SignalEvent() may be invoked from any task priority level.

If the supplied Event is a part of an event group, then all of the events in the event group are also signaled and their notification functions are scheduled. When signaling an event group, it is possible to create an event in the group, signal it and then close the event to remove it from the group. For example:

EFI_EVENT Event;
EFI_GUID gMyEventGroupGuid = EFI_MY_EVENT_GROUP_GUID;

gBS->CreateEventEx (
  0,
  0,
  NULL,
  NULL,
  &gMyEventGroupGuid,
  &Event
  );

gBS->SignalEvent (Event);
gBS->CloseEvent (Event);

Status Codes Returned

Status Code Description
EFI_SUCCESS The event was signaled.

Stall()

Induces a fine-grained stall.

Prototype

typedef
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.

Status Codes Returned

Status Code Description
EFI_SUCCESS Execution was stalled at least the requested number of Microseconds.

StartImage()

Transfers control to a loaded image’s entry point.

Prototype

typedef
EFI_STATUS
StartImage (
  IN  EFI_HANDLE ImageHandle,
  OUT UINTN      *ExitDataSize,
  OUT CHAR16     **ExitData OPTIONAL
  );

Parameters

Parameter Description
ImageHandle Handle of image to be started.
ExitDataSize Pointer to the size, in bytes, of ExitData. If ExitData is NULL, then this parameter is ignored and the contents of ExitDataSize are not modified.
ExitData Pointer to a pointer to a data buffer that includes a Null-terminated Unicode string, optionally followed by additional binary data. The string is a description that the caller may use to further indicate the reason for the image’s exit.

Description
The StartImage() function transfers control to the entry point of an image that was loaded by LoadImage(). The image may only be started one time.

Control returns from StartImage() when the loaded image’s EFI_IMAGE_ENTRY_POINT returns or when the loaded image calls Exit(). When that call is made, the ExitData buffer and ExitDataSize from Exit() are passed back through the ExitData buffer and ExitDataSize in this function. The caller of this function is responsible for returning the ExitData buffer to the pool by calling FreePool() when the buffer is no longer needed. Using Exit() is similar to returning from the image’s EFI_IMAGE_ENTRY_POINT except that Exit() may also return additional ExitData. Exit() function description defines clean up procedure performed by the firmware once loaded image returns control.

To maintain compatibility with UEFI drivers that are written to the EFI 1.02 Specification, StartImage() must monitor the handle database before and after each image is started. If any handles are created or modified when an image is started, then ConnectController() must be called with the Recursive parameter set to TRUE for each of the newly created or modified handles before StartImage() returns.

Status Codes Returned

Status Code Description
EFI_INVALID_PARAMETER ImageHandle is either an invalid image handle or the image has already been initialized with StartImage
Exit code from image Exit code from image.

UninstallProtocolInterface()

Removes a protocol interface from a device handle. It is recommended that UninstallMultipleProtocolInterfaces() be used in place of UninstallProtocolInterface().

Prototype

typedef
EFI_STATUS
UninstallProtocolInterface (
  IN EFI_HANDLE Handle,
  IN EFI_GUID   *Protocol,
  IN VOID       *Interface
  );

Parameters

Parameter Description
Handle The handle on which the interface was installed. If Handle is not a valid handle, then EFI_INVALID_PARAMETER is returned.
Protocol The numeric ID of the interface. It is the caller’s responsibility to pass in a valid GUID. See “Wired For Management Baseline” for a description of valid GUID values.
Interface A pointer to the interface. NULL can be used if a structure is not associated with Protocol.

Description
The UninstallProtocolInterface() function removes a protocol interface from the handle on which it was previously installed. The Protocol and Interface values define the protocol interface to remove from the handle.

The caller is responsible for ensuring that there are no references to a protocol interface that has been removed. In some cases, outstanding reference information is not available in the protocol, so the protocol, once added, cannot be removed. Examples include Console I/O, Block I/O, Disk I/O, and (in general) handles to device protocols. If the last protocol interface is removed from a handle, the handle is freed and is no longer valid.

The extension to this service directly addresses the limitations described in the section above. There may be some drivers that are currently consuming the protocol interface that needs to be uninstalled, so it may be dangerous to just blindly remove a protocol interface from the system. Since the usage of protocol interfaces is now being tracked for components that use the OpenProtocol() and CloseProtocol() boot services, a safe version of this function can be implemented. Before the protocol interface is removed, an attempt is made to force all the drivers that are consuming the protocol interface to stop consuming that protocol interface. This is done by calling the boot service DisconnectController() for the driver that currently have the protocol interface open with an attribute of EFI_OPEN_PROTOCOL_BY_DRIVER or EFI_OPEN_PROTOCOL_BY_DRIVER | EFI_OPEN_PROTOCOL_EXCLUSIVE.

If the disconnect succeeds, then those agents will have called the boot service CloseProtocol() to release the protocol interface. Lastly, all of the agents that have the protocol interface open with an attribute of EFI_OPEN_PROTOCOL_BY_HANDLE_PROTOCOL, EFI_OPEN_PROTOCOL_GET_PROTOCOL, or EFI_OPEN_PROTOCOL_TEST_PROTOCOL are closed. If there are any agents remaining that still have the protocol interface open, the protocol interface is not removed from the handle and EFI_ACCESS_DENIED is returned. In addition, all of the drivers that were disconnected with the boot service DisconnectController() earlier, are reconnected with the boot service ConnectController(). If there are no agents remaining that are consuming the protocol interface, then the protocol interface is removed from the handle as described above.

Status Codes Returned

Status Code Description
EFI_SUCCESS The interface was removed.
EFI_NOT_FOUND The interface was not found.
EFI_ACCESS_DENIED The interface was not removed because the interface is still being used by a driver.
EFI_INVALID_PARAMETER Handle is not a valid EFI_HANDLE.
EFI_INVALID_PARAMETER Protocol is NULL

WaitForEvent()

Stops execution until an event is signaled.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_WAIT_FOR_EVENT) (
 IN  UINTN     NumberOfEvents,
 IN  EFI_EVENT *Event,
 OUT UINTN     *Index
 );

Parameters

Parameter Description
NumberOfEvents The number of events in the Event array.
Event An array of EFI_EVENTs.
Index Pointer to the index of the event which satisfied the wait condition.

Description
This function must be called at priority level TPL_APPLICATION. If an attempt is made to call it at any other priority level, EFI_UNSUPPORTED is returned.

The list of events in the Event array are evaluated in order from first to last, and this evaluation is repeated until an event is signaled or an error is detected. The following checks are performed on each event in the Event array.

  • If an event is of type EVT_NOTIFY_SIGNAL, then EFI_INVALID_PARAMETER is returned and Index indicates the event that caused the failure.
  • If an event is in the signaled state, the signaled state is cleared and EFI_SUCCESS is returned, and Index indicates the event that was signaled.
  • If an event is not in the signaled state but does have a notification function, the notification function is queued at the event’s notification task priority level. If the execution of the event’s notification function causes the event to be signaled, then the signaled state is cleared, EFI_SUCCESS is returned, and Index indicates the event that was signaled.

To wait for a specified time, a timer event must be included in the Event array.

To check if an event is signaled without waiting, an already signaled event can be used as the last event in the list being checked, or the CheckEvent() interface may be used.

Status Codes Returned

Status Code
EFI_SUCCESS The event indicated by Index was signaled.
EFI_INVALID_PARAMETER NumberOfEvents is 0.
EFI_INVALID_PARAMETER The event indicated by Index is of type EVT_NOTIFY_SIGNAL.
EFI_UNSUPPORTED The current TPL is not TPL_APPLICATION.

Copyright (C) 2008-2009 Phoenix Technologies Ltd. All Rights Reserved. Portions copyright (C) 2008 Unified EFI, Inc. Used with permission.

Personal tools