9. Protocols - EFI Loaded Image

This section defines EFI_LOADED_IMAGE_PROTOCOL and the EFI_LOADED_IMAGE_DEVICE_PATH_PROTOCOL. Respectively, these protocols describe an Image that has been loaded into memory and specifies the device path used when a PE/COFF image was loaded through the EFI Boot Service LoadImage(). These descriptions include the source from which the image was loaded, the current location of the image in memory, the type of memory allocated for the image, and the parameters passed to the image when it was invoked.

9.1. EFI Loaded Image Protocol

9.1.1. EFI_LOADED_IMAGE_PROTOCOL

Summary

Can be used on any image handle to obtain information about the loaded image.

GUID

#define EFI_LOADED_IMAGE_PROTOCOL_GUID \
  {0x5B1B31A1,0x9562,0x11d2,\
    {0x8E,0x3F,0x00,0xA0,0xC9,0x69,0x72,0x3B}}

Revision Number

#define EFI_LOADED_IMAGE_PROTOCOL_REVISION 0x1000

Protocol Interface Structure

typedef struct {
   UINT32                        Revision;
   EFI_HANDLE                    ParentHandle;
   EFI_System_Table              *SystemTable;

   // Source location of the image
   EFI_HANDLE                    DeviceHandle;
   EFI_DEVICE_PATH_PROTOCOL      *FilePath;
   VOID                          *Reserved;

   // Image’s load options
   UINT32                        LoadOptionsSize;
   VOID                          *LoadOptions;

   // Location where image was loaded
   VOID                          *ImageBase;
   UINT64                        ImageSize;
   EFI_MEMORY_TYPE               ImageCodeType;
   EFI_MEMORY_TYPE               ImageDataType;
   EFI_IMAGE_UNLOAD              Unload;
} EFI_LOADED_IMAGE_PROTOCOL;

Parameters

Revision: Defines the revision of the EFI_LOADED_IMAGE_PROTOCOL structure. All future revisions will be backward compatible to the current revision.
ParentHandle: Parent image’s image handle. NULL if the image is loaded directly from the firmware’s boot manager. Type EFI_HANDLE is defined in Services – Boot Services.
SystemTable: The image’s EFI system table pointer. Type EFI_SYSTEM_TABLE defined in EFI System Table.
DeviceHandle: The device handle that the EFI Image was loaded from. Type EFI_HANDLE is defined in Services – Boot Services.
FilePath: A pointer to the file path portion specific to DeviceHandle that the EFI Image was loaded from. EFI_DEVICE_PATH_PROTOCOL is defined in EFI Device Path Protocol .
Reserved: Reserved. DO NOT USE.
LoadOptionsSize: The size in bytes of LoadOptions.
LoadOptions: A pointer to the image’s binary load options. See the OptionalData parameter in the Load Options section of the Boot Manager chapter for information on the source of the LoadOptions data.
ImageBase: The base address at which the image was loaded.
ImageSize: The size in bytes of the loaded image.
ImageCodeType: The memory type that the code sections were loaded as. Type EFI_MEMORY_TYPE is defined in Services – Boot Services.
ImageDataType: The memory type that the data sections were loaded as. Type EFI_MEMORY_TYPE is defined in in Services – Boot Services.
Unload: Function that unloads the image - see Section 9.1.2.

Description

Each loaded image has an image handle that supports EFI_LOADED_IMAGE_PROTOCOL. When an image is started, it is passed the image handle for itself. The image can use the handle to obtain its relevant image data stored in the EFI_LOADED_IMAGE_PROTOCOL structure, such as its load options.

9.1.2. EFI_LOADED_IMAGE_PROTOCOL.Unload()

Summary

Unloads an image from memory.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_IMAGE_UNLOAD) (
  IN EFI_HANDLE               ImageHandle,
  );

Parameters

ImageHandle: The handle to the image to unload. Type EFI_HANDLE Driver Model Boot Services

Description

The Unload() function is a callback that a driver registers to do cleanup when the UnloadImage boot service function is called.

Status Codes Returned

EFI_SUCCESS	The image was unloaded.
EFI_INVALID_PARAMETER	The ImageHandle was not valid.

9.2. EFI Loaded Image Device Path Protocol

9.2.1. EFI_LOADED_IMAGE_DEVICE_PATH_PROTOCOL

Summary

When installed, the Loaded Image Device Path Protocol specifies the device path that was used when a PE/COFF image was loaded through the EFI Boot Service LoadImage().

GUID

#define EFI_LOADED_IMAGE_DEVICE_PATH_PROTOCOL_GUID \
   {0xbc62157e,0x3e33,0x4fec,\
  {0x99,0x20,0x2d,0x3b,0x36,0xd7,0x50,0xdf}}

Description

The Loaded Image Device Path Protocol uses the same protocol interface structure as the Device Path Protocol defined in Chapter 9. The only difference between the Device Path Protocol and the Loaded Image Device Path Protocol is the protocol GUID value.

The Loaded Image Device Path Protocol must be installed onto the image handle of a PE/COFF image loaded through the EFI Boot Service LoadImage(). A copy of the device path specified by the DevicePath parameter to the EFI Boot Service LoadImage() is made before it is installed onto the image handle. It is legal to call LoadImage() for a buffer in memory with a NULL DevicePath parameter. In this case, the Loaded Image Device Path Protocol is installed with a NULL interface pointer.