#include "DxeMain.h"
#include "Image.h"

Data Structures
struct	EMULATOR_ENTRY

struct	MACHINE_TYPE_INFO

Functions
CHAR16 *	GetMachineTypeName (UINT16 MachineType)

STATIC VOID EFIAPI	PeCoffEmuProtocolNotify (IN EFI_EVENT Event, IN VOID *Context)

EFI_STATUS	CoreInitializeImageServices (IN VOID *HobStart)

EFI_STATUS EFIAPI	CoreReadImageFile (IN VOID UserHandle, IN UINTN Offset, IN OUT UINTN ReadSize, OUT VOID *Buffer)

EFI_STATUS	CheckAndMarkFixLoadingMemoryUsageBitMap (IN EFI_PHYSICAL_ADDRESS ImageBase, IN UINTN ImageSize)

EFI_STATUS	GetPeCoffImageFixLoadingAssignedAddress (IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext)

STATIC BOOLEAN	CoreIsImageTypeSupported (IN OUT LOADED_IMAGE_PRIVATE_DATA *Image)

EFI_STATUS	CoreLoadPeImage (IN BOOLEAN BootPolicy, IN VOID Pe32Handle, IN LOADED_IMAGE_PRIVATE_DATA Image, IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL, OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL, IN UINT32 Attribute)

LOADED_IMAGE_PRIVATE_DATA *	CoreLoadedImageInfo (IN EFI_HANDLE ImageHandle)

VOID	CoreUnloadAndCloseImage (IN LOADED_IMAGE_PRIVATE_DATA *Image, IN BOOLEAN FreePage)

EFI_STATUS	CoreLoadImageCommon (IN BOOLEAN BootPolicy, IN EFI_HANDLE ParentImageHandle, IN EFI_DEVICE_PATH_PROTOCOL FilePath, IN VOID SourceBuffer OPTIONAL, IN UINTN SourceSize, IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL, IN OUT UINTN NumberOfPages OPTIONAL, OUT EFI_HANDLE ImageHandle, OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL, IN UINT32 Attribute)

EFI_STATUS EFIAPI	CoreLoadImage (IN BOOLEAN BootPolicy, IN EFI_HANDLE ParentImageHandle, IN EFI_DEVICE_PATH_PROTOCOL FilePath, IN VOID SourceBuffer OPTIONAL, IN UINTN SourceSize, OUT EFI_HANDLE *ImageHandle)

EFI_STATUS EFIAPI	CoreStartImage (IN EFI_HANDLE ImageHandle, OUT UINTN ExitDataSize, OUT CHAR16 *ExitData OPTIONAL)

EFI_STATUS EFIAPI	CoreExit (IN EFI_HANDLE ImageHandle, IN EFI_STATUS Status, IN UINTN ExitDataSize, IN CHAR16 *ExitData OPTIONAL)

EFI_STATUS EFIAPI	CoreUnloadImage (IN EFI_HANDLE ImageHandle)

Detailed Description

Core image handling services to load and unload PeImage.

Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.
SPDX-License-Identifier: BSD-2-Clause-Patent

Definition in file Image.c.

Function Documentation

◆ CheckAndMarkFixLoadingMemoryUsageBitMap()

EFI_STATUS CheckAndMarkFixLoadingMemoryUsageBitMap	(	IN EFI_PHYSICAL_ADDRESS	ImageBase,
		IN UINTN	ImageSize
	)

To check memory usage bit map array to figure out if the memory range the image will be loaded in is available or not. If memory range is available, the function will mark the corresponding bits to 1 which indicates the memory range is used. The function is only invoked when load modules at fixed address feature is enabled.

Parameters

ImageBase	The base address the image will be loaded at.
ImageSize	The size of the image

Return values

EFI_SUCCESS	The memory range the image will be loaded in is available
EFI_NOT_FOUND	The memory range the image will be loaded in is not available

Definition at line 347 of file Image.c.

◆ CoreExit()

EFI_STATUS EFIAPI CoreExit	(	IN EFI_HANDLE	ImageHandle,
		IN EFI_STATUS	Status,
		IN UINTN	ExitDataSize,
		IN CHAR16 *ExitData	OPTIONAL
	)

Terminates the currently loaded EFI image and returns control to boot services.

Parameters

ImageHandle	Handle that identifies the image. This parameter is passed to the image on entry.
Status	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.

Return values

EFI_INVALID_PARAMETER	Image handle is NULL or it is not current image.
EFI_SUCCESS	Successfully terminates the currently loaded EFI image.
EFI_ACCESS_DENIED	Should never reach there.
EFI_OUT_OF_RESOURCES	Could not allocate pool

Definition at line 1833 of file Image.c.

◆ CoreInitializeImageServices()

EFI_STATUS CoreInitializeImageServices ( IN VOID * HobStart )

Add the Image Services to EFI Boot Services Table and install the protocol interfaces for this image.

Parameters

HobStart The HOB to initialize

Returns: Status code.

Definition at line 186 of file Image.c.

◆ CoreIsImageTypeSupported()

STATIC BOOLEAN CoreIsImageTypeSupported ( IN OUT LOADED_IMAGE_PRIVATE_DATA * Image )

Decides whether a PE/COFF image can execute on this system, either natively or via emulation/interpretation. In the latter case, the PeCoffEmu member of the LOADED_IMAGE_PRIVATE_DATA struct pointer is populated with a pointer to the emulator protocol that supports this image.

Parameters

[in,out] Image LOADED_IMAGE_PRIVATE_DATA struct pointer

Return values

TRUE	The image is supported
FALSE	The image is not supported

Definition at line 526 of file Image.c.

◆ CoreLoadedImageInfo()

LOADED_IMAGE_PRIVATE_DATA * CoreLoadedImageInfo ( IN EFI_HANDLE ImageHandle )

Get the image's private data from its handle.

Parameters

ImageHandle The image handle

Returns: Return the image private data associated with ImageHandle.

Definition at line 910 of file Image.c.

◆ CoreLoadImage()

EFI_STATUS EFIAPI CoreLoadImage	(	IN BOOLEAN	BootPolicy,
		IN EFI_HANDLE	ParentImageHandle,
		IN EFI_DEVICE_PATH_PROTOCOL *	FilePath,
		IN VOID *SourceBuffer	OPTIONAL,
		IN UINTN	SourceSize,
		OUT EFI_HANDLE *	ImageHandle
	)

Loads an EFI image into memory and returns a handle to the image.

Parameters

BootPolicy	If TRUE, indicates that the request originates from the boot manager, and that the boot manager is attempting to load FilePath as a boot selection.
ParentImageHandle	The caller's image handle.
FilePath	The 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.
ImageHandle	Pointer to the returned image handle that is created when the image is successfully loaded.

Return values

EFI_SUCCESS	The image was loaded into memory.
EFI_NOT_FOUND	The FilePath was not found.
EFI_INVALID_PARAMETER	One of the parameters has an invalid value.
EFI_UNSUPPORTED	The image type is not supported, or the device path cannot be parsed to locate the proper protocol for loading the file.
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_ACCESS_DENIED	Image was not loaded because the platform policy prohibits the image from being loaded. NULL is returned in *ImageHandle.
EFI_SECURITY_VIOLATION	Image was loaded and an ImageHandle was created with a valid EFI_LOADED_IMAGE_PROTOCOL. However, the current platform policy specifies that the image should not be started.

Definition at line 1544 of file Image.c.

◆ CoreLoadImageCommon()

EFI_STATUS CoreLoadImageCommon	(	IN BOOLEAN	BootPolicy,
		IN EFI_HANDLE	ParentImageHandle,
		IN EFI_DEVICE_PATH_PROTOCOL *	FilePath,
		IN VOID *SourceBuffer	OPTIONAL,
		IN UINTN	SourceSize,
		IN EFI_PHYSICAL_ADDRESS DstBuffer	OPTIONAL,
		IN OUT UINTN *NumberOfPages	OPTIONAL,
		OUT EFI_HANDLE *	ImageHandle,
		OUT EFI_PHYSICAL_ADDRESS *EntryPoint	OPTIONAL,
		IN UINT32	Attribute
	)

Loads an EFI image into memory and returns a handle to the image.

Parameters

BootPolicy	If TRUE, indicates that the request originates from the boot manager, and that the boot manager is attempting to load FilePath as a boot selection.
ParentImageHandle	The caller's image handle.
FilePath	The 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.
DstBuffer	The buffer to store the image
NumberOfPages	If not NULL, it inputs a pointer to the page number of DstBuffer and outputs a pointer to the page number of the image. If this number is not enough, return EFI_BUFFER_TOO_SMALL and this parameter contains the required number.
ImageHandle	Pointer to the returned image handle that is created when the image is successfully loaded.
EntryPoint	A pointer to the entry point
Attribute	The bit mask of attributes to set for the load PE image

Return values

EFI_SUCCESS	The image was loaded into memory.
EFI_NOT_FOUND	The FilePath was not found.
EFI_INVALID_PARAMETER	One of the parameters has an invalid value.
EFI_BUFFER_TOO_SMALL	The buffer is too small
EFI_UNSUPPORTED	The image type is not supported, or the device path cannot be parsed to locate the proper protocol for loading the file.
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_ACCESS_DENIED	Image was not loaded because the platform policy prohibits the image from being loaded. NULL is returned in *ImageHandle.
EFI_SECURITY_VIOLATION	Image was loaded and an ImageHandle was created with a valid EFI_LOADED_IMAGE_PROTOCOL. However, the current platform policy specifies that the image should not be started.

Definition at line 1138 of file Image.c.

◆ CoreLoadPeImage()

EFI_STATUS CoreLoadPeImage	(	IN BOOLEAN	BootPolicy,
		IN VOID *	Pe32Handle,
		IN LOADED_IMAGE_PRIVATE_DATA *	Image,
		IN EFI_PHYSICAL_ADDRESS DstBuffer	OPTIONAL,
		OUT EFI_PHYSICAL_ADDRESS *EntryPoint	OPTIONAL,
		IN UINT32	Attribute
	)

Loads, relocates, and invokes a PE/COFF image

Parameters

BootPolicy	If TRUE, indicates that the request originates from the boot manager, and that the boot manager is attempting to load FilePath as a boot selection.
Pe32Handle	The handle of PE32 image
Image	PE image to be loaded
DstBuffer	The buffer to store the image
EntryPoint	A pointer to the entry point
Attribute	The bit mask of attributes to set for the load PE image

Return values

EFI_SUCCESS	The file was loaded, relocated, and invoked
EFI_OUT_OF_RESOURCES	There was not enough memory to load and relocate the PE/COFF file
EFI_INVALID_PARAMETER	Invalid parameter
EFI_BUFFER_TOO_SMALL	Buffer for image is too small

Definition at line 579 of file Image.c.

◆ CoreReadImageFile()

EFI_STATUS EFIAPI CoreReadImageFile	(	IN VOID *	UserHandle,
		IN UINTN	Offset,
		IN OUT UINTN *	ReadSize,
		OUT VOID *	Buffer
	)

Read image file (specified by UserHandle) into user specified buffer with specified offset and length.

Parameters

UserHandle	Image file handle
Offset	Offset to the source file
ReadSize	For input, pointer of size to read; For output, pointer of size actually read.
Buffer	Buffer to write into

Return values

EFI_SUCCESS Successfully read the specified part of file into buffer.

Definition at line 298 of file Image.c.

◆ CoreStartImage()

EFI_STATUS EFIAPI CoreStartImage	(	IN EFI_HANDLE	ImageHandle,
		OUT UINTN *	ExitDataSize,
		OUT CHAR16 **ExitData	OPTIONAL
	)

Transfer control to a loaded image's entry point.

Parameters

ImageHandle	Handle of image to be started.
ExitDataSize	Pointer of the size to ExitData
ExitData	Pointer to a pointer to a data buffer that includes a Null-terminated 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.

Return values

EFI_INVALID_PARAMETER	Invalid parameter
EFI_OUT_OF_RESOURCES	No enough buffer to allocate
EFI_SECURITY_VIOLATION	The current platform policy specifies that the image should not be started.
EFI_SUCCESS	Successfully transfer control to the image's entry point.

Definition at line 1605 of file Image.c.

◆ CoreUnloadAndCloseImage()

VOID CoreUnloadAndCloseImage	(	IN LOADED_IMAGE_PRIVATE_DATA *	Image,
		IN BOOLEAN	FreePage
	)

Unloads EFI image from memory.

Parameters

Image	EFI image
FreePage	Free allocated pages

Definition at line 941 of file Image.c.

◆ CoreUnloadImage()

EFI_STATUS EFIAPI CoreUnloadImage ( IN EFI_HANDLE ImageHandle )

Unloads an image.

Parameters

ImageHandle Handle that identifies the image to be unloaded.

Return values

EFI_SUCCESS	The image has been unloaded.
EFI_UNSUPPORTED	The image has been started, and does not support unload.
EFI_INVALID_PARAMPETER	ImageHandle is not a valid image handle.

Definition at line 1922 of file Image.c.

◆ GetMachineTypeName()

CHAR16 * GetMachineTypeName ( UINT16 MachineType )

Return machine type name.

Parameters

MachineType The machine type

Returns: machine type name

Definition at line 98 of file Image.c.

◆ GetPeCoffImageFixLoadingAssignedAddress()

EFI_STATUS GetPeCoffImageFixLoadingAssignedAddress ( IN OUT PE_COFF_LOADER_IMAGE_CONTEXT * ImageContext )

Get the fixed loading address from image header assigned by build tool. This function only be called when Loading module at Fixed address feature enabled.

Parameters

ImageContext Pointer to the image context structure that describes the PE/COFF image that needs to be examined by this function.

Return values

EFI_SUCCESS	An fixed loading address is assigned to this image by build tools .
EFI_NOT_FOUND	The image has no assigned fixed loading address.

Definition at line 427 of file Image.c.

◆ PeCoffEmuProtocolNotify()

STATIC VOID EFIAPI PeCoffEmuProtocolNotify	(	IN EFI_EVENT	Event,
		IN VOID *	Context
	)

Notification event handler registered by CoreInitializeImageServices () to keep track of which PE/COFF image emulators are available.

Parameters

Event	The Event that is being processed, not used.
Context	Event Context, not used.

Definition at line 124 of file Image.c.

Variable Documentation

◆ mAvailableEmulators

STATIC LIST_ENTRY mAvailableEmulators

Definition at line 23 of file Image.c.

◆ mCorePrivateImage

LOADED_IMAGE_PRIVATE_DATA mCorePrivateImage

Definition at line 30 of file Image.c.

◆ mCurrentImage

LOADED_IMAGE_PRIVATE_DATA* mCurrentImage = NULL

Definition at line 15 of file Image.c.

◆ mDxeCodeMemoryRangeUsageBitMap

GLOBAL_REMOVE_IF_UNREFERENCED UINT64* mDxeCodeMemoryRangeUsageBitMap = NULL

Definition at line 72 of file Image.c.

◆ mDxeCoreImageMachineType

UINT16 mDxeCoreImageMachineType = 0

Definition at line 88 of file Image.c.

◆ mMachineTypeInfo

GLOBAL_REMOVE_IF_UNREFERENCED MACHINE_TYPE_INFO mMachineTypeInfo[]

Initial value:

= {
  { EFI_IMAGE_MACHINE_IA32,        L"IA32"        },
  { EFI_IMAGE_MACHINE_IA64,        L"IA64"        },
  { EFI_IMAGE_MACHINE_X64,         L"X64"         },
  { EFI_IMAGE_MACHINE_AARCH64,     L"AARCH64"     },
  { EFI_IMAGE_MACHINE_RISCV64,     L"RISCV64"     },
  { EFI_IMAGE_MACHINE_LOONGARCH64, L"LOONGARCH64" },
}

Definition at line 79 of file Image.c.

◆ mPeCoffEmuProtocolNotifyRegistration

STATIC VOID* mPeCoffEmuProtocolNotifyRegistration

Definition at line 25 of file Image.c.

◆ mPeCoffEmuProtocolRegistrationEvent

STATIC EFI_EVENT mPeCoffEmuProtocolRegistrationEvent

Definition at line 24 of file Image.c.

Variables
LOADED_IMAGE_PRIVATE_DATA *	mCurrentImage = NULL

STATIC LIST_ENTRY	mAvailableEmulators

STATIC EFI_EVENT	mPeCoffEmuProtocolRegistrationEvent

STATIC VOID *	mPeCoffEmuProtocolNotifyRegistration

LOADED_IMAGE_PRIVATE_DATA	mCorePrivateImage

GLOBAL_REMOVE_IF_UNREFERENCED UINT64 *	mDxeCodeMemoryRangeUsageBitMap = NULL

GLOBAL_REMOVE_IF_UNREFERENCED MACHINE_TYPE_INFO	mMachineTypeInfo []

UINT16	mDxeCoreImageMachineType = 0

Data Structures

Functions

Variables

Detailed Description

Function Documentation

◆ CheckAndMarkFixLoadingMemoryUsageBitMap()

◆ CoreExit()

◆ CoreInitializeImageServices()

◆ CoreIsImageTypeSupported()

◆ CoreLoadedImageInfo()

◆ CoreLoadImage()

◆ CoreLoadImageCommon()

◆ CoreLoadPeImage()

◆ CoreReadImageFile()

◆ CoreStartImage()

◆ CoreUnloadAndCloseImage()

◆ CoreUnloadImage()

◆ GetMachineTypeName()

◆ GetPeCoffImageFixLoadingAssignedAddress()

◆ PeCoffEmuProtocolNotify()

Variable Documentation

◆ mAvailableEmulators

◆ mCorePrivateImage

◆ mCurrentImage

◆ mDxeCodeMemoryRangeUsageBitMap

◆ mDxeCoreImageMachineType

◆ mMachineTypeInfo

◆ mPeCoffEmuProtocolNotifyRegistration

◆ mPeCoffEmuProtocolRegistrationEvent