2 Core image handling services to load and unload PeImage.
4 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials
6 are licensed and made available under the terms and conditions of the BSD License
7 which accompanies this distribution. The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
21 LOADED_IMAGE_PRIVATE_DATA
*mCurrentImage
= NULL
;
23 LOAD_PE32_IMAGE_PRIVATE_DATA mLoadPe32PrivateData
= {
24 LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE
,
34 // This code is needed to build the Image handle for the DXE Core
36 LOADED_IMAGE_PRIVATE_DATA mCorePrivateImage
= {
37 LOADED_IMAGE_PRIVATE_DATA_SIGNATURE
, // Signature
39 EFI_IMAGE_SUBSYSTEM_EFI_BOOT_SERVICE_DRIVER
, // Image type
40 TRUE
, // If entrypoint has been called
43 EFI_LOADED_IMAGE_INFORMATION_REVISION
, // Revision
44 NULL
, // Parent handle
45 NULL
, // System handle
47 NULL
, // Device handle
56 EfiBootServicesCode
, // ImageCodeType
57 EfiBootServicesData
// ImageDataType
59 (EFI_PHYSICAL_ADDRESS
)0, // ImageBasePage
63 EFI_SUCCESS
, // Status
71 NULL
// LoadedImageDevicePath
74 // The field is define for Loading modules at fixed address feature to tracker the PEI code
75 // memory range usage. It is a bit mapped array in which every bit indicates the correspoding memory page
78 GLOBAL_REMOVE_IF_UNREFERENCED UINT64
*mDxeCodeMemoryRangeUsageBitMap
=NULL
;
82 CHAR16
*MachineTypeName
;
86 // EBC machine is not listed in this table, because EBC is in the default supported scopes of other machine type.
88 GLOBAL_REMOVE_IF_UNREFERENCED MACHINE_TYPE_INFO mMachineTypeInfo
[] = {
89 {EFI_IMAGE_MACHINE_IA32
, L
"IA32"},
90 {EFI_IMAGE_MACHINE_IA64
, L
"IA64"},
91 {EFI_IMAGE_MACHINE_X64
, L
"X64"},
92 {EFI_IMAGE_MACHINE_ARMTHUMB_MIXED
, L
"ARM"},
93 {EFI_IMAGE_MACHINE_AARCH64
, L
"AARCH64"}
96 UINT16 mDxeCoreImageMachineType
= 0;
99 Return machine type name.
101 @param MachineType The machine type
103 @return machine type name
112 for (Index
= 0; Index
< sizeof(mMachineTypeInfo
)/sizeof(mMachineTypeInfo
[0]); Index
++) {
113 if (mMachineTypeInfo
[Index
].MachineType
== MachineType
) {
114 return mMachineTypeInfo
[Index
].MachineTypeName
;
122 Add the Image Services to EFI Boot Services Table and install the protocol
123 interfaces for this image.
125 @param HobStart The HOB to initialize
131 CoreInitializeImageServices (
136 LOADED_IMAGE_PRIVATE_DATA
*Image
;
137 EFI_PHYSICAL_ADDRESS DxeCoreImageBaseAddress
;
138 UINT64 DxeCoreImageLength
;
139 VOID
*DxeCoreEntryPoint
;
140 EFI_PEI_HOB_POINTERS DxeCoreHob
;
143 // Searching for image hob
145 DxeCoreHob
.Raw
= HobStart
;
146 while ((DxeCoreHob
.Raw
= GetNextHob (EFI_HOB_TYPE_MEMORY_ALLOCATION
, DxeCoreHob
.Raw
)) != NULL
) {
147 if (CompareGuid (&DxeCoreHob
.MemoryAllocationModule
->MemoryAllocationHeader
.Name
, &gEfiHobMemoryAllocModuleGuid
)) {
153 DxeCoreHob
.Raw
= GET_NEXT_HOB (DxeCoreHob
);
155 ASSERT (DxeCoreHob
.Raw
!= NULL
);
157 DxeCoreImageBaseAddress
= DxeCoreHob
.MemoryAllocationModule
->MemoryAllocationHeader
.MemoryBaseAddress
;
158 DxeCoreImageLength
= DxeCoreHob
.MemoryAllocationModule
->MemoryAllocationHeader
.MemoryLength
;
159 DxeCoreEntryPoint
= (VOID
*) (UINTN
) DxeCoreHob
.MemoryAllocationModule
->EntryPoint
;
160 gDxeCoreFileName
= &DxeCoreHob
.MemoryAllocationModule
->ModuleName
;
163 // Initialize the fields for an internal driver
165 Image
= &mCorePrivateImage
;
167 Image
->EntryPoint
= (EFI_IMAGE_ENTRY_POINT
)(UINTN
)DxeCoreEntryPoint
;
168 Image
->ImageBasePage
= DxeCoreImageBaseAddress
;
169 Image
->NumberOfPages
= (UINTN
)(EFI_SIZE_TO_PAGES((UINTN
)(DxeCoreImageLength
)));
170 Image
->Tpl
= gEfiCurrentTpl
;
171 Image
->Info
.SystemTable
= gDxeCoreST
;
172 Image
->Info
.ImageBase
= (VOID
*)(UINTN
)DxeCoreImageBaseAddress
;
173 Image
->Info
.ImageSize
= DxeCoreImageLength
;
176 // Install the protocol interfaces for this image
178 Status
= CoreInstallProtocolInterface (
180 &gEfiLoadedImageProtocolGuid
,
181 EFI_NATIVE_INTERFACE
,
184 ASSERT_EFI_ERROR (Status
);
186 mCurrentImage
= Image
;
189 // Fill in DXE globals
191 mDxeCoreImageMachineType
= PeCoffLoaderGetMachineType (Image
->Info
.ImageBase
);
192 gDxeCoreImageHandle
= Image
->Handle
;
193 gDxeCoreLoadedImage
= &Image
->Info
;
195 if (FeaturePcdGet (PcdFrameworkCompatibilitySupport
)) {
197 // Export DXE Core PE Loader functionality for backward compatibility.
199 Status
= CoreInstallProtocolInterface (
200 &mLoadPe32PrivateData
.Handle
,
201 &gEfiLoadPeImageProtocolGuid
,
202 EFI_NATIVE_INTERFACE
,
203 &mLoadPe32PrivateData
.Pe32Image
207 ProtectUefiImage (&Image
->Info
, Image
->LoadedImageDevicePath
);
213 Read image file (specified by UserHandle) into user specified buffer with specified offset
216 @param UserHandle Image file handle
217 @param Offset Offset to the source file
218 @param ReadSize For input, pointer of size to read; For output,
219 pointer of size actually read.
220 @param Buffer Buffer to write into
222 @retval EFI_SUCCESS Successfully read the specified part of file
231 IN OUT UINTN
*ReadSize
,
236 IMAGE_FILE_HANDLE
*FHand
;
238 if (UserHandle
== NULL
|| ReadSize
== NULL
|| Buffer
== NULL
) {
239 return EFI_INVALID_PARAMETER
;
242 if (MAX_ADDRESS
- Offset
< *ReadSize
) {
243 return EFI_INVALID_PARAMETER
;
246 FHand
= (IMAGE_FILE_HANDLE
*)UserHandle
;
247 ASSERT (FHand
->Signature
== IMAGE_FILE_HANDLE_SIGNATURE
);
250 // Move data from our local copy of the file
252 EndPosition
= Offset
+ *ReadSize
;
253 if (EndPosition
> FHand
->SourceSize
) {
254 *ReadSize
= (UINT32
)(FHand
->SourceSize
- Offset
);
256 if (Offset
>= FHand
->SourceSize
) {
260 CopyMem (Buffer
, (CHAR8
*)FHand
->Source
+ Offset
, *ReadSize
);
264 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
265 memory range is available, the function will mark the corresponding bits to 1 which indicates the memory range is used.
266 The function is only invoked when load modules at fixed address feature is enabled.
268 @param ImageBase The base address the image will be loaded at.
269 @param ImageSize The size of the image
271 @retval EFI_SUCCESS The memory range the image will be loaded in is available
272 @retval EFI_NOT_FOUND The memory range the image will be loaded in is not available
275 CheckAndMarkFixLoadingMemoryUsageBitMap (
276 IN EFI_PHYSICAL_ADDRESS ImageBase
,
280 UINT32 DxeCodePageNumber
;
282 EFI_PHYSICAL_ADDRESS DxeCodeBase
;
283 UINTN BaseOffsetPageNumber
;
284 UINTN TopOffsetPageNumber
;
287 // The DXE code range includes RuntimeCodePage range and Boot time code range.
289 DxeCodePageNumber
= PcdGet32(PcdLoadFixAddressRuntimeCodePageNumber
);
290 DxeCodePageNumber
+= PcdGet32(PcdLoadFixAddressBootTimeCodePageNumber
);
291 DxeCodeSize
= EFI_PAGES_TO_SIZE(DxeCodePageNumber
);
292 DxeCodeBase
= gLoadModuleAtFixAddressConfigurationTable
.DxeCodeTopAddress
- DxeCodeSize
;
295 // If the memory usage bit map is not initialized, do it. Every bit in the array
296 // indicate the status of the corresponding memory page, available or not
298 if (mDxeCodeMemoryRangeUsageBitMap
== NULL
) {
299 mDxeCodeMemoryRangeUsageBitMap
= AllocateZeroPool(((DxeCodePageNumber
/64) + 1)*sizeof(UINT64
));
302 // If the Dxe code memory range is not allocated or the bit map array allocation failed, return EFI_NOT_FOUND
304 if (!gLoadFixedAddressCodeMemoryReady
|| mDxeCodeMemoryRangeUsageBitMap
== NULL
) {
305 return EFI_NOT_FOUND
;
308 // Test the memory range for loading the image in the DXE code range.
310 if (gLoadModuleAtFixAddressConfigurationTable
.DxeCodeTopAddress
< ImageBase
+ ImageSize
||
311 DxeCodeBase
> ImageBase
) {
312 return EFI_NOT_FOUND
;
315 // Test if the memory is avalaible or not.
317 BaseOffsetPageNumber
= EFI_SIZE_TO_PAGES((UINT32
)(ImageBase
- DxeCodeBase
));
318 TopOffsetPageNumber
= EFI_SIZE_TO_PAGES((UINT32
)(ImageBase
+ ImageSize
- DxeCodeBase
));
319 for (Index
= BaseOffsetPageNumber
; Index
< TopOffsetPageNumber
; Index
++) {
320 if ((mDxeCodeMemoryRangeUsageBitMap
[Index
/ 64] & LShiftU64(1, (Index
% 64))) != 0) {
322 // This page is already used.
324 return EFI_NOT_FOUND
;
329 // Being here means the memory range is available. So mark the bits for the memory range
331 for (Index
= BaseOffsetPageNumber
; Index
< TopOffsetPageNumber
; Index
++) {
332 mDxeCodeMemoryRangeUsageBitMap
[Index
/ 64] |= LShiftU64(1, (Index
% 64));
338 Get the fixed loading address from image header assigned by build tool. This function only be called
339 when Loading module at Fixed address feature enabled.
341 @param ImageContext Pointer to the image context structure that describes the PE/COFF
342 image that needs to be examined by this function.
343 @retval EFI_SUCCESS An fixed loading address is assigned to this image by build tools .
344 @retval EFI_NOT_FOUND The image has no assigned fixed loading address.
348 GetPeCoffImageFixLoadingAssignedAddress(
349 IN OUT PE_COFF_LOADER_IMAGE_CONTEXT
*ImageContext
352 UINTN SectionHeaderOffset
;
354 EFI_IMAGE_SECTION_HEADER SectionHeader
;
355 EFI_IMAGE_OPTIONAL_HEADER_UNION
*ImgHdr
;
358 UINT16 NumberOfSections
;
359 IMAGE_FILE_HANDLE
*Handle
;
360 UINT64 ValueInSectionHeader
;
363 Status
= EFI_NOT_FOUND
;
366 // Get PeHeader pointer
368 Handle
= (IMAGE_FILE_HANDLE
*)ImageContext
->Handle
;
369 ImgHdr
= (EFI_IMAGE_OPTIONAL_HEADER_UNION
*)((CHAR8
* )Handle
->Source
+ ImageContext
->PeCoffHeaderOffset
);
370 SectionHeaderOffset
= ImageContext
->PeCoffHeaderOffset
+
372 sizeof (EFI_IMAGE_FILE_HEADER
) +
373 ImgHdr
->Pe32
.FileHeader
.SizeOfOptionalHeader
;
374 NumberOfSections
= ImgHdr
->Pe32
.FileHeader
.NumberOfSections
;
377 // Get base address from the first section header that doesn't point to code section.
379 for (Index
= 0; Index
< NumberOfSections
; Index
++) {
381 // Read section header from file
383 Size
= sizeof (EFI_IMAGE_SECTION_HEADER
);
384 Status
= ImageContext
->ImageRead (
385 ImageContext
->Handle
,
390 if (EFI_ERROR (Status
)) {
393 if (Size
!= sizeof (EFI_IMAGE_SECTION_HEADER
)) {
394 return EFI_NOT_FOUND
;
397 Status
= EFI_NOT_FOUND
;
399 if ((SectionHeader
.Characteristics
& EFI_IMAGE_SCN_CNT_CODE
) == 0) {
401 // Build tool will save the address in PointerToRelocations & PointerToLineNumbers fields in the first section header
402 // that doesn't point to code section in image header, as well as ImageBase field of image header. And there is an
403 // assumption that when the feature is enabled, if a module is assigned a loading address by tools, PointerToRelocations
404 // & PointerToLineNumbers fields should NOT be Zero, or else, these 2 fields should be set to Zero
406 ValueInSectionHeader
= ReadUnaligned64((UINT64
*)&SectionHeader
.PointerToRelocations
);
407 if (ValueInSectionHeader
!= 0) {
409 // When the feature is configured as load module at fixed absolute address, the ImageAddress field of ImageContext
410 // hold the spcified address. If the feature is configured as load module at fixed offset, ImageAddress hold an offset
411 // relative to top address
413 if ((INT64
)PcdGet64(PcdLoadModuleAtFixAddressEnable
) < 0) {
414 ImageContext
->ImageAddress
= gLoadModuleAtFixAddressConfigurationTable
.DxeCodeTopAddress
+ (INT64
)(INTN
)ImageContext
->ImageAddress
;
417 // Check if the memory range is available.
419 Status
= CheckAndMarkFixLoadingMemoryUsageBitMap (ImageContext
->ImageAddress
, (UINTN
)(ImageContext
->ImageSize
+ ImageContext
->SectionAlignment
));
423 SectionHeaderOffset
+= sizeof (EFI_IMAGE_SECTION_HEADER
);
425 DEBUG ((EFI_D_INFO
|EFI_D_LOAD
, "LOADING MODULE FIXED INFO: Loading module at fixed address 0x%11p. Status = %r \n", (VOID
*)(UINTN
)(ImageContext
->ImageAddress
), Status
));
429 Loads, relocates, and invokes a PE/COFF image
431 @param BootPolicy If TRUE, indicates that the request originates
432 from the boot manager, and that the boot
433 manager is attempting to load FilePath as a
435 @param Pe32Handle The handle of PE32 image
436 @param Image PE image to be loaded
437 @param DstBuffer The buffer to store the image
438 @param EntryPoint A pointer to the entry point
439 @param Attribute The bit mask of attributes to set for the load
442 @retval EFI_SUCCESS The file was loaded, relocated, and invoked
443 @retval EFI_OUT_OF_RESOURCES There was not enough memory to load and
444 relocate the PE/COFF file
445 @retval EFI_INVALID_PARAMETER Invalid parameter
446 @retval EFI_BUFFER_TOO_SMALL Buffer for image is too small
451 IN BOOLEAN BootPolicy
,
453 IN LOADED_IMAGE_PRIVATE_DATA
*Image
,
454 IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL
,
455 OUT EFI_PHYSICAL_ADDRESS
*EntryPoint OPTIONAL
,
460 BOOLEAN DstBufAlocated
;
463 ZeroMem (&Image
->ImageContext
, sizeof (Image
->ImageContext
));
465 Image
->ImageContext
.Handle
= Pe32Handle
;
466 Image
->ImageContext
.ImageRead
= (PE_COFF_LOADER_READ_FILE
)CoreReadImageFile
;
469 // Get information about the image being loaded
471 Status
= PeCoffLoaderGetImageInfo (&Image
->ImageContext
);
472 if (EFI_ERROR (Status
)) {
476 if (!EFI_IMAGE_MACHINE_TYPE_SUPPORTED (Image
->ImageContext
.Machine
)) {
477 if (!EFI_IMAGE_MACHINE_CROSS_TYPE_SUPPORTED (Image
->ImageContext
.Machine
)) {
479 // The PE/COFF loader can support loading image types that can be executed.
480 // If we loaded an image type that we can not execute return EFI_UNSUPORTED.
482 DEBUG ((EFI_D_ERROR
, "Image type %s can't be loaded ", GetMachineTypeName(Image
->ImageContext
.Machine
)));
483 DEBUG ((EFI_D_ERROR
, "on %s UEFI system.\n", GetMachineTypeName(mDxeCoreImageMachineType
)));
484 return EFI_UNSUPPORTED
;
489 // Set EFI memory type based on ImageType
491 switch (Image
->ImageContext
.ImageType
) {
492 case EFI_IMAGE_SUBSYSTEM_EFI_APPLICATION
:
493 Image
->ImageContext
.ImageCodeMemoryType
= EfiLoaderCode
;
494 Image
->ImageContext
.ImageDataMemoryType
= EfiLoaderData
;
496 case EFI_IMAGE_SUBSYSTEM_EFI_BOOT_SERVICE_DRIVER
:
497 Image
->ImageContext
.ImageCodeMemoryType
= EfiBootServicesCode
;
498 Image
->ImageContext
.ImageDataMemoryType
= EfiBootServicesData
;
500 case EFI_IMAGE_SUBSYSTEM_EFI_RUNTIME_DRIVER
:
501 case EFI_IMAGE_SUBSYSTEM_SAL_RUNTIME_DRIVER
:
502 Image
->ImageContext
.ImageCodeMemoryType
= EfiRuntimeServicesCode
;
503 Image
->ImageContext
.ImageDataMemoryType
= EfiRuntimeServicesData
;
506 Image
->ImageContext
.ImageError
= IMAGE_ERROR_INVALID_SUBSYSTEM
;
507 return EFI_UNSUPPORTED
;
511 // Allocate memory of the correct memory type aligned on the required image boundary
513 DstBufAlocated
= FALSE
;
514 if (DstBuffer
== 0) {
516 // Allocate Destination Buffer as caller did not pass it in
519 if (Image
->ImageContext
.SectionAlignment
> EFI_PAGE_SIZE
) {
520 Size
= (UINTN
)Image
->ImageContext
.ImageSize
+ Image
->ImageContext
.SectionAlignment
;
522 Size
= (UINTN
)Image
->ImageContext
.ImageSize
;
525 Image
->NumberOfPages
= EFI_SIZE_TO_PAGES (Size
);
528 // If the image relocations have not been stripped, then load at any address.
529 // Otherwise load at the address at which it was linked.
531 // Memory below 1MB should be treated reserved for CSM and there should be
532 // no modules whose preferred load addresses are below 1MB.
534 Status
= EFI_OUT_OF_RESOURCES
;
536 // If Loading Module At Fixed Address feature is enabled, the module should be loaded to
537 // a specified address.
539 if (PcdGet64(PcdLoadModuleAtFixAddressEnable
) != 0 ) {
540 Status
= GetPeCoffImageFixLoadingAssignedAddress (&(Image
->ImageContext
));
542 if (EFI_ERROR (Status
)) {
544 // If the code memory is not ready, invoke CoreAllocatePage with AllocateAnyPages to load the driver.
546 DEBUG ((EFI_D_INFO
|EFI_D_LOAD
, "LOADING MODULE FIXED ERROR: Loading module at fixed address failed since specified memory is not available.\n"));
548 Status
= CoreAllocatePages (
550 (EFI_MEMORY_TYPE
) (Image
->ImageContext
.ImageCodeMemoryType
),
551 Image
->NumberOfPages
,
552 &Image
->ImageContext
.ImageAddress
556 if (Image
->ImageContext
.ImageAddress
>= 0x100000 || Image
->ImageContext
.RelocationsStripped
) {
557 Status
= CoreAllocatePages (
559 (EFI_MEMORY_TYPE
) (Image
->ImageContext
.ImageCodeMemoryType
),
560 Image
->NumberOfPages
,
561 &Image
->ImageContext
.ImageAddress
564 if (EFI_ERROR (Status
) && !Image
->ImageContext
.RelocationsStripped
) {
565 Status
= CoreAllocatePages (
567 (EFI_MEMORY_TYPE
) (Image
->ImageContext
.ImageCodeMemoryType
),
568 Image
->NumberOfPages
,
569 &Image
->ImageContext
.ImageAddress
573 if (EFI_ERROR (Status
)) {
576 DstBufAlocated
= TRUE
;
579 // Caller provided the destination buffer
582 if (Image
->ImageContext
.RelocationsStripped
&& (Image
->ImageContext
.ImageAddress
!= DstBuffer
)) {
584 // If the image relocations were stripped, and the caller provided a
585 // destination buffer address that does not match the address that the
586 // image is linked at, then the image cannot be loaded.
588 return EFI_INVALID_PARAMETER
;
591 if (Image
->NumberOfPages
!= 0 &&
592 Image
->NumberOfPages
<
593 (EFI_SIZE_TO_PAGES ((UINTN
)Image
->ImageContext
.ImageSize
+ Image
->ImageContext
.SectionAlignment
))) {
594 Image
->NumberOfPages
= EFI_SIZE_TO_PAGES ((UINTN
)Image
->ImageContext
.ImageSize
+ Image
->ImageContext
.SectionAlignment
);
595 return EFI_BUFFER_TOO_SMALL
;
598 Image
->NumberOfPages
= EFI_SIZE_TO_PAGES ((UINTN
)Image
->ImageContext
.ImageSize
+ Image
->ImageContext
.SectionAlignment
);
599 Image
->ImageContext
.ImageAddress
= DstBuffer
;
602 Image
->ImageBasePage
= Image
->ImageContext
.ImageAddress
;
603 if (!Image
->ImageContext
.IsTeImage
) {
604 Image
->ImageContext
.ImageAddress
=
605 (Image
->ImageContext
.ImageAddress
+ Image
->ImageContext
.SectionAlignment
- 1) &
606 ~((UINTN
)Image
->ImageContext
.SectionAlignment
- 1);
610 // Load the image from the file into the allocated memory
612 Status
= PeCoffLoaderLoadImage (&Image
->ImageContext
);
613 if (EFI_ERROR (Status
)) {
618 // If this is a Runtime Driver, then allocate memory for the FixupData that
619 // is used to relocate the image when SetVirtualAddressMap() is called. The
620 // relocation is done by the Runtime AP.
622 if ((Attribute
& EFI_LOAD_PE_IMAGE_ATTRIBUTE_RUNTIME_REGISTRATION
) != 0) {
623 if (Image
->ImageContext
.ImageType
== EFI_IMAGE_SUBSYSTEM_EFI_RUNTIME_DRIVER
) {
624 Image
->ImageContext
.FixupData
= AllocateRuntimePool ((UINTN
)(Image
->ImageContext
.FixupDataSize
));
625 if (Image
->ImageContext
.FixupData
== NULL
) {
626 Status
= EFI_OUT_OF_RESOURCES
;
633 // Relocate the image in memory
635 Status
= PeCoffLoaderRelocateImage (&Image
->ImageContext
);
636 if (EFI_ERROR (Status
)) {
641 // Flush the Instruction Cache
643 InvalidateInstructionCacheRange ((VOID
*)(UINTN
)Image
->ImageContext
.ImageAddress
, (UINTN
)Image
->ImageContext
.ImageSize
);
646 // Copy the machine type from the context to the image private data. This
647 // is needed during image unload to know if we should call an EBC protocol
648 // to unload the image.
650 Image
->Machine
= Image
->ImageContext
.Machine
;
653 // Get the image entry point. If it's an EBC image, then call into the
654 // interpreter to create a thunk for the entry point and use the returned
655 // value for the entry point.
657 Image
->EntryPoint
= (EFI_IMAGE_ENTRY_POINT
)(UINTN
)Image
->ImageContext
.EntryPoint
;
658 if (Image
->ImageContext
.Machine
== EFI_IMAGE_MACHINE_EBC
) {
660 // Locate the EBC interpreter protocol
662 Status
= CoreLocateProtocol (&gEfiEbcProtocolGuid
, NULL
, (VOID
**)&Image
->Ebc
);
663 if (EFI_ERROR(Status
) || Image
->Ebc
== NULL
) {
664 DEBUG ((DEBUG_LOAD
| DEBUG_ERROR
, "CoreLoadPeImage: There is no EBC interpreter for an EBC image.\n"));
669 // Register a callback for flushing the instruction cache so that created
670 // thunks can be flushed.
672 Status
= Image
->Ebc
->RegisterICacheFlush (Image
->Ebc
, (EBC_ICACHE_FLUSH
)InvalidateInstructionCacheRange
);
673 if (EFI_ERROR(Status
)) {
678 // Create a thunk for the image's entry point. This will be the new
679 // entry point for the image.
681 Status
= Image
->Ebc
->CreateThunk (
684 (VOID
*)(UINTN
) Image
->ImageContext
.EntryPoint
,
685 (VOID
**) &Image
->EntryPoint
687 if (EFI_ERROR(Status
)) {
693 // Fill in the image information for the Loaded Image Protocol
695 Image
->Type
= Image
->ImageContext
.ImageType
;
696 Image
->Info
.ImageBase
= (VOID
*)(UINTN
)Image
->ImageContext
.ImageAddress
;
697 Image
->Info
.ImageSize
= Image
->ImageContext
.ImageSize
;
698 Image
->Info
.ImageCodeType
= (EFI_MEMORY_TYPE
) (Image
->ImageContext
.ImageCodeMemoryType
);
699 Image
->Info
.ImageDataType
= (EFI_MEMORY_TYPE
) (Image
->ImageContext
.ImageDataMemoryType
);
700 if ((Attribute
& EFI_LOAD_PE_IMAGE_ATTRIBUTE_RUNTIME_REGISTRATION
) != 0) {
701 if (Image
->ImageContext
.ImageType
== EFI_IMAGE_SUBSYSTEM_EFI_RUNTIME_DRIVER
) {
703 // Make a list off all the RT images so we can let the RT AP know about them.
705 Image
->RuntimeData
= AllocateRuntimePool (sizeof(EFI_RUNTIME_IMAGE_ENTRY
));
706 if (Image
->RuntimeData
== NULL
) {
709 Image
->RuntimeData
->ImageBase
= Image
->Info
.ImageBase
;
710 Image
->RuntimeData
->ImageSize
= (UINT64
) (Image
->Info
.ImageSize
);
711 Image
->RuntimeData
->RelocationData
= Image
->ImageContext
.FixupData
;
712 Image
->RuntimeData
->Handle
= Image
->Handle
;
713 InsertTailList (&gRuntime
->ImageHead
, &Image
->RuntimeData
->Link
);
714 InsertImageRecord (Image
->RuntimeData
);
719 // Fill in the entry point of the image if it is available
721 if (EntryPoint
!= NULL
) {
722 *EntryPoint
= Image
->ImageContext
.EntryPoint
;
726 // Print the load address and the PDB file name if it is available
733 CHAR8 EfiFileName
[256];
736 DEBUG ((DEBUG_INFO
| DEBUG_LOAD
,
737 "Loading driver at 0x%11p EntryPoint=0x%11p ",
738 (VOID
*)(UINTN
) Image
->ImageContext
.ImageAddress
,
739 FUNCTION_ENTRY_POINT (Image
->ImageContext
.EntryPoint
)));
743 // Print Module Name by Pdb file path.
744 // Windows and Unix style file path are all trimmed correctly.
746 if (Image
->ImageContext
.PdbPointer
!= NULL
) {
748 for (Index
= 0; Image
->ImageContext
.PdbPointer
[Index
] != 0; Index
++) {
749 if ((Image
->ImageContext
.PdbPointer
[Index
] == '\\') || (Image
->ImageContext
.PdbPointer
[Index
] == '/')) {
750 StartIndex
= Index
+ 1;
754 // Copy the PDB file name to our temporary string, and replace .pdb with .efi
755 // The PDB file name is limited in the range of 0~255.
756 // If the length is bigger than 255, trim the redudant characters to avoid overflow in array boundary.
758 for (Index
= 0; Index
< sizeof (EfiFileName
) - 4; Index
++) {
759 EfiFileName
[Index
] = Image
->ImageContext
.PdbPointer
[Index
+ StartIndex
];
760 if (EfiFileName
[Index
] == 0) {
761 EfiFileName
[Index
] = '.';
763 if (EfiFileName
[Index
] == '.') {
764 EfiFileName
[Index
+ 1] = 'e';
765 EfiFileName
[Index
+ 2] = 'f';
766 EfiFileName
[Index
+ 3] = 'i';
767 EfiFileName
[Index
+ 4] = 0;
772 if (Index
== sizeof (EfiFileName
) - 4) {
773 EfiFileName
[Index
] = 0;
775 DEBUG ((DEBUG_INFO
| DEBUG_LOAD
, "%a", EfiFileName
)); // &Image->ImageContext.PdbPointer[StartIndex]));
777 DEBUG ((DEBUG_INFO
| DEBUG_LOAD
, "\n"));
789 if (DstBufAlocated
) {
790 CoreFreePages (Image
->ImageContext
.ImageAddress
, Image
->NumberOfPages
);
791 Image
->ImageContext
.ImageAddress
= 0;
792 Image
->ImageBasePage
= 0;
795 if (Image
->ImageContext
.FixupData
!= NULL
) {
796 CoreFreePool (Image
->ImageContext
.FixupData
);
805 Get the image's private data from its handle.
807 @param ImageHandle The image handle
809 @return Return the image private data associated with ImageHandle.
812 LOADED_IMAGE_PRIVATE_DATA
*
813 CoreLoadedImageInfo (
814 IN EFI_HANDLE ImageHandle
818 EFI_LOADED_IMAGE_PROTOCOL
*LoadedImage
;
819 LOADED_IMAGE_PRIVATE_DATA
*Image
;
821 Status
= CoreHandleProtocol (
823 &gEfiLoadedImageProtocolGuid
,
824 (VOID
**)&LoadedImage
826 if (!EFI_ERROR (Status
)) {
827 Image
= LOADED_IMAGE_PRIVATE_DATA_FROM_THIS (LoadedImage
);
829 DEBUG ((DEBUG_LOAD
, "CoreLoadedImageInfo: Not an ImageHandle %p\n", ImageHandle
));
838 Unloads EFI image from memory.
840 @param Image EFI image
841 @param FreePage Free allocated pages
845 CoreUnloadAndCloseImage (
846 IN LOADED_IMAGE_PRIVATE_DATA
*Image
,
852 EFI_HANDLE
*HandleBuffer
;
854 EFI_GUID
**ProtocolGuidArray
;
857 EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
*OpenInfo
;
862 ProtocolGuidArray
= NULL
;
864 if (Image
->Started
) {
865 UnregisterMemoryProfileImage (Image
);
868 UnprotectUefiImage (&Image
->Info
, Image
->LoadedImageDevicePath
);
870 if (Image
->Ebc
!= NULL
) {
872 // If EBC protocol exists we must perform cleanups for this image.
874 Image
->Ebc
->UnloadImage (Image
->Ebc
, Image
->Handle
);
878 // Unload image, free Image->ImageContext->ModHandle
880 PeCoffLoaderUnloadImage (&Image
->ImageContext
);
883 // Free our references to the image handle
885 if (Image
->Handle
!= NULL
) {
887 Status
= CoreLocateHandleBuffer (
894 if (!EFI_ERROR (Status
)) {
895 for (HandleIndex
= 0; HandleIndex
< HandleCount
; HandleIndex
++) {
896 Status
= CoreProtocolsPerHandle (
897 HandleBuffer
[HandleIndex
],
901 if (!EFI_ERROR (Status
)) {
902 for (ProtocolIndex
= 0; ProtocolIndex
< ArrayCount
; ProtocolIndex
++) {
903 Status
= CoreOpenProtocolInformation (
904 HandleBuffer
[HandleIndex
],
905 ProtocolGuidArray
[ProtocolIndex
],
909 if (!EFI_ERROR (Status
)) {
910 for (OpenInfoIndex
= 0; OpenInfoIndex
< OpenInfoCount
; OpenInfoIndex
++) {
911 if (OpenInfo
[OpenInfoIndex
].AgentHandle
== Image
->Handle
) {
912 Status
= CoreCloseProtocol (
913 HandleBuffer
[HandleIndex
],
914 ProtocolGuidArray
[ProtocolIndex
],
916 OpenInfo
[OpenInfoIndex
].ControllerHandle
920 if (OpenInfo
!= NULL
) {
921 CoreFreePool(OpenInfo
);
925 if (ProtocolGuidArray
!= NULL
) {
926 CoreFreePool(ProtocolGuidArray
);
930 if (HandleBuffer
!= NULL
) {
931 CoreFreePool (HandleBuffer
);
935 CoreRemoveDebugImageInfoEntry (Image
->Handle
);
937 Status
= CoreUninstallProtocolInterface (
939 &gEfiLoadedImageDevicePathProtocolGuid
,
940 Image
->LoadedImageDevicePath
943 Status
= CoreUninstallProtocolInterface (
945 &gEfiLoadedImageProtocolGuid
,
949 if (Image
->ImageContext
.HiiResourceData
!= 0) {
950 Status
= CoreUninstallProtocolInterface (
952 &gEfiHiiPackageListProtocolGuid
,
953 (VOID
*) (UINTN
) Image
->ImageContext
.HiiResourceData
959 if (Image
->RuntimeData
!= NULL
) {
960 if (Image
->RuntimeData
->Link
.ForwardLink
!= NULL
) {
962 // Remove the Image from the Runtime Image list as we are about to Free it!
964 RemoveEntryList (&Image
->RuntimeData
->Link
);
965 RemoveImageRecord (Image
->RuntimeData
);
967 CoreFreePool (Image
->RuntimeData
);
971 // Free the Image from memory
973 if ((Image
->ImageBasePage
!= 0) && FreePage
) {
974 CoreFreePages (Image
->ImageBasePage
, Image
->NumberOfPages
);
978 // Done with the Image structure
980 if (Image
->Info
.FilePath
!= NULL
) {
981 CoreFreePool (Image
->Info
.FilePath
);
984 if (Image
->LoadedImageDevicePath
!= NULL
) {
985 CoreFreePool (Image
->LoadedImageDevicePath
);
988 if (Image
->FixupData
!= NULL
) {
989 CoreFreePool (Image
->FixupData
);
992 CoreFreePool (Image
);
997 Loads an EFI image into memory and returns a handle to the image.
999 @param BootPolicy If TRUE, indicates that the request originates
1000 from the boot manager, and that the boot
1001 manager is attempting to load FilePath as a
1003 @param ParentImageHandle The caller's image handle.
1004 @param FilePath The specific file path from which the image is
1006 @param SourceBuffer If not NULL, a pointer to the memory location
1007 containing a copy of the image to be loaded.
1008 @param SourceSize The size in bytes of SourceBuffer.
1009 @param DstBuffer The buffer to store the image
1010 @param NumberOfPages If not NULL, it inputs a pointer to the page
1011 number of DstBuffer and outputs a pointer to
1012 the page number of the image. If this number is
1013 not enough, return EFI_BUFFER_TOO_SMALL and
1014 this parameter contains the required number.
1015 @param ImageHandle Pointer to the returned image handle that is
1016 created when the image is successfully loaded.
1017 @param EntryPoint A pointer to the entry point
1018 @param Attribute The bit mask of attributes to set for the load
1021 @retval EFI_SUCCESS The image was loaded into memory.
1022 @retval EFI_NOT_FOUND The FilePath was not found.
1023 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
1024 @retval EFI_BUFFER_TOO_SMALL The buffer is too small
1025 @retval EFI_UNSUPPORTED The image type is not supported, or the device
1026 path cannot be parsed to locate the proper
1027 protocol for loading the file.
1028 @retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient
1030 @retval EFI_LOAD_ERROR Image was not loaded because the image format was corrupt or not
1032 @retval EFI_DEVICE_ERROR Image was not loaded because the device returned a read error.
1033 @retval EFI_ACCESS_DENIED Image was not loaded because the platform policy prohibits the
1034 image from being loaded. NULL is returned in *ImageHandle.
1035 @retval EFI_SECURITY_VIOLATION Image was loaded and an ImageHandle was created with a
1036 valid EFI_LOADED_IMAGE_PROTOCOL. However, the current
1037 platform policy specifies that the image should not be started.
1041 CoreLoadImageCommon (
1042 IN BOOLEAN BootPolicy
,
1043 IN EFI_HANDLE ParentImageHandle
,
1044 IN EFI_DEVICE_PATH_PROTOCOL
*FilePath
,
1045 IN VOID
*SourceBuffer OPTIONAL
,
1046 IN UINTN SourceSize
,
1047 IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL
,
1048 IN OUT UINTN
*NumberOfPages OPTIONAL
,
1049 OUT EFI_HANDLE
*ImageHandle
,
1050 OUT EFI_PHYSICAL_ADDRESS
*EntryPoint OPTIONAL
,
1054 LOADED_IMAGE_PRIVATE_DATA
*Image
;
1055 LOADED_IMAGE_PRIVATE_DATA
*ParentImage
;
1056 IMAGE_FILE_HANDLE FHand
;
1058 EFI_STATUS SecurityStatus
;
1059 EFI_HANDLE DeviceHandle
;
1060 UINT32 AuthenticationStatus
;
1061 EFI_DEVICE_PATH_PROTOCOL
*OriginalFilePath
;
1062 EFI_DEVICE_PATH_PROTOCOL
*HandleFilePath
;
1063 EFI_DEVICE_PATH_PROTOCOL
*InputFilePath
;
1064 EFI_DEVICE_PATH_PROTOCOL
*Node
;
1066 BOOLEAN ImageIsFromFv
;
1067 BOOLEAN ImageIsFromLoadFile
;
1069 SecurityStatus
= EFI_SUCCESS
;
1071 ASSERT (gEfiCurrentTpl
< TPL_NOTIFY
);
1075 // The caller must pass in a valid ParentImageHandle
1077 if (ImageHandle
== NULL
|| ParentImageHandle
== NULL
) {
1078 return EFI_INVALID_PARAMETER
;
1081 ParentImage
= CoreLoadedImageInfo (ParentImageHandle
);
1082 if (ParentImage
== NULL
) {
1083 DEBUG((DEBUG_LOAD
|DEBUG_ERROR
, "LoadImageEx: Parent handle not an image handle\n"));
1084 return EFI_INVALID_PARAMETER
;
1087 ZeroMem (&FHand
, sizeof (IMAGE_FILE_HANDLE
));
1088 FHand
.Signature
= IMAGE_FILE_HANDLE_SIGNATURE
;
1089 OriginalFilePath
= FilePath
;
1090 InputFilePath
= FilePath
;
1091 HandleFilePath
= FilePath
;
1092 DeviceHandle
= NULL
;
1093 Status
= EFI_SUCCESS
;
1094 AuthenticationStatus
= 0;
1095 ImageIsFromFv
= FALSE
;
1096 ImageIsFromLoadFile
= FALSE
;
1099 // If the caller passed a copy of the file, then just use it
1101 if (SourceBuffer
!= NULL
) {
1102 FHand
.Source
= SourceBuffer
;
1103 FHand
.SourceSize
= SourceSize
;
1104 Status
= CoreLocateDevicePath (&gEfiDevicePathProtocolGuid
, &HandleFilePath
, &DeviceHandle
);
1105 if (EFI_ERROR (Status
)) {
1106 DeviceHandle
= NULL
;
1108 if (SourceSize
> 0) {
1109 Status
= EFI_SUCCESS
;
1111 Status
= EFI_LOAD_ERROR
;
1114 if (FilePath
== NULL
) {
1115 return EFI_INVALID_PARAMETER
;
1119 // Try to get the image device handle by checking the match protocol.
1122 Status
= CoreLocateDevicePath (&gEfiFirmwareVolume2ProtocolGuid
, &HandleFilePath
, &DeviceHandle
);
1123 if (!EFI_ERROR (Status
)) {
1124 ImageIsFromFv
= TRUE
;
1126 HandleFilePath
= FilePath
;
1127 Status
= CoreLocateDevicePath (&gEfiSimpleFileSystemProtocolGuid
, &HandleFilePath
, &DeviceHandle
);
1128 if (EFI_ERROR (Status
)) {
1130 HandleFilePath
= FilePath
;
1131 Status
= CoreLocateDevicePath (&gEfiLoadFile2ProtocolGuid
, &HandleFilePath
, &DeviceHandle
);
1133 if (EFI_ERROR (Status
)) {
1134 HandleFilePath
= FilePath
;
1135 Status
= CoreLocateDevicePath (&gEfiLoadFileProtocolGuid
, &HandleFilePath
, &DeviceHandle
);
1136 if (!EFI_ERROR (Status
)) {
1137 ImageIsFromLoadFile
= TRUE
;
1138 Node
= HandleFilePath
;
1145 // Get the source file buffer by its device path.
1147 FHand
.Source
= GetFileBufferByFilePath (
1151 &AuthenticationStatus
1153 if (FHand
.Source
== NULL
) {
1154 Status
= EFI_NOT_FOUND
;
1156 FHand
.FreeBuffer
= TRUE
;
1157 if (ImageIsFromLoadFile
) {
1159 // LoadFile () may cause the device path of the Handle be updated.
1161 OriginalFilePath
= AppendDevicePath (DevicePathFromHandle (DeviceHandle
), Node
);
1166 if (EFI_ERROR (Status
)) {
1171 if (gSecurity2
!= NULL
) {
1173 // Verify File Authentication through the Security2 Architectural Protocol
1175 SecurityStatus
= gSecurity2
->FileAuthentication (
1182 if (!EFI_ERROR (SecurityStatus
) && ImageIsFromFv
) {
1184 // When Security2 is installed, Security Architectural Protocol must be published.
1186 ASSERT (gSecurity
!= NULL
);
1189 // Verify the Authentication Status through the Security Architectural Protocol
1190 // Only on images that have been read using Firmware Volume protocol.
1192 SecurityStatus
= gSecurity
->FileAuthenticationState (
1194 AuthenticationStatus
,
1198 } else if ((gSecurity
!= NULL
) && (OriginalFilePath
!= NULL
)) {
1200 // Verify the Authentication Status through the Security Architectural Protocol
1202 SecurityStatus
= gSecurity
->FileAuthenticationState (
1204 AuthenticationStatus
,
1210 // Check Security Status.
1212 if (EFI_ERROR (SecurityStatus
) && SecurityStatus
!= EFI_SECURITY_VIOLATION
) {
1213 if (SecurityStatus
== EFI_ACCESS_DENIED
) {
1215 // Image was not loaded because the platform policy prohibits the image from being loaded.
1216 // It's the only place we could meet EFI_ACCESS_DENIED.
1218 *ImageHandle
= NULL
;
1220 Status
= SecurityStatus
;
1226 // Allocate a new image structure
1228 Image
= AllocateZeroPool (sizeof(LOADED_IMAGE_PRIVATE_DATA
));
1229 if (Image
== NULL
) {
1230 Status
= EFI_OUT_OF_RESOURCES
;
1235 // Pull out just the file portion of the DevicePath for the LoadedImage FilePath
1237 FilePath
= OriginalFilePath
;
1238 if (DeviceHandle
!= NULL
) {
1239 Status
= CoreHandleProtocol (DeviceHandle
, &gEfiDevicePathProtocolGuid
, (VOID
**)&HandleFilePath
);
1240 if (!EFI_ERROR (Status
)) {
1241 FilePathSize
= GetDevicePathSize (HandleFilePath
) - sizeof(EFI_DEVICE_PATH_PROTOCOL
);
1242 FilePath
= (EFI_DEVICE_PATH_PROTOCOL
*) (((UINT8
*)FilePath
) + FilePathSize
);
1246 // Initialize the fields for an internal driver
1248 Image
->Signature
= LOADED_IMAGE_PRIVATE_DATA_SIGNATURE
;
1249 Image
->Info
.SystemTable
= gDxeCoreST
;
1250 Image
->Info
.DeviceHandle
= DeviceHandle
;
1251 Image
->Info
.Revision
= EFI_LOADED_IMAGE_PROTOCOL_REVISION
;
1252 Image
->Info
.FilePath
= DuplicateDevicePath (FilePath
);
1253 Image
->Info
.ParentHandle
= ParentImageHandle
;
1256 if (NumberOfPages
!= NULL
) {
1257 Image
->NumberOfPages
= *NumberOfPages
;
1259 Image
->NumberOfPages
= 0 ;
1263 // Install the protocol interfaces for this image
1264 // don't fire notifications yet
1266 Status
= CoreInstallProtocolInterfaceNotify (
1268 &gEfiLoadedImageProtocolGuid
,
1269 EFI_NATIVE_INTERFACE
,
1273 if (EFI_ERROR (Status
)) {
1278 // Load the image. If EntryPoint is Null, it will not be set.
1280 Status
= CoreLoadPeImage (BootPolicy
, &FHand
, Image
, DstBuffer
, EntryPoint
, Attribute
);
1281 if (EFI_ERROR (Status
)) {
1282 if ((Status
== EFI_BUFFER_TOO_SMALL
) || (Status
== EFI_OUT_OF_RESOURCES
)) {
1283 if (NumberOfPages
!= NULL
) {
1284 *NumberOfPages
= Image
->NumberOfPages
;
1290 if (NumberOfPages
!= NULL
) {
1291 *NumberOfPages
= Image
->NumberOfPages
;
1295 // Register the image in the Debug Image Info Table if the attribute is set
1297 if ((Attribute
& EFI_LOAD_PE_IMAGE_ATTRIBUTE_DEBUG_IMAGE_INFO_TABLE_REGISTRATION
) != 0) {
1298 CoreNewDebugImageInfoEntry (EFI_DEBUG_IMAGE_INFO_TYPE_NORMAL
, &Image
->Info
, Image
->Handle
);
1302 //Reinstall loaded image protocol to fire any notifications
1304 Status
= CoreReinstallProtocolInterface (
1306 &gEfiLoadedImageProtocolGuid
,
1310 if (EFI_ERROR (Status
)) {
1315 // If DevicePath parameter to the LoadImage() is not NULL, then make a copy of DevicePath,
1316 // otherwise Loaded Image Device Path Protocol is installed with a NULL interface pointer.
1318 if (OriginalFilePath
!= NULL
) {
1319 Image
->LoadedImageDevicePath
= DuplicateDevicePath (OriginalFilePath
);
1323 // Install Loaded Image Device Path Protocol onto the image handle of a PE/COFE image
1325 Status
= CoreInstallProtocolInterface (
1327 &gEfiLoadedImageDevicePathProtocolGuid
,
1328 EFI_NATIVE_INTERFACE
,
1329 Image
->LoadedImageDevicePath
1331 if (EFI_ERROR (Status
)) {
1336 // Install HII Package List Protocol onto the image handle
1338 if (Image
->ImageContext
.HiiResourceData
!= 0) {
1339 Status
= CoreInstallProtocolInterface (
1341 &gEfiHiiPackageListProtocolGuid
,
1342 EFI_NATIVE_INTERFACE
,
1343 (VOID
*) (UINTN
) Image
->ImageContext
.HiiResourceData
1345 if (EFI_ERROR (Status
)) {
1349 ProtectUefiImage (&Image
->Info
, Image
->LoadedImageDevicePath
);
1352 // Success. Return the image handle
1354 *ImageHandle
= Image
->Handle
;
1358 // All done accessing the source file
1359 // If we allocated the Source buffer, free it
1361 if (FHand
.FreeBuffer
) {
1362 CoreFreePool (FHand
.Source
);
1364 if (OriginalFilePath
!= InputFilePath
) {
1365 CoreFreePool (OriginalFilePath
);
1369 // There was an error. If there's an Image structure, free it
1371 if (EFI_ERROR (Status
)) {
1372 if (Image
!= NULL
) {
1373 CoreUnloadAndCloseImage (Image
, (BOOLEAN
)(DstBuffer
== 0));
1376 } else if (EFI_ERROR (SecurityStatus
)) {
1377 Status
= SecurityStatus
;
1381 // Track the return status from LoadImage.
1383 if (Image
!= NULL
) {
1384 Image
->LoadImageStatus
= Status
;
1394 Loads an EFI image into memory and returns a handle to the image.
1396 @param BootPolicy If TRUE, indicates that the request originates
1397 from the boot manager, and that the boot
1398 manager is attempting to load FilePath as a
1400 @param ParentImageHandle The caller's image handle.
1401 @param FilePath The specific file path from which the image is
1403 @param SourceBuffer If not NULL, a pointer to the memory location
1404 containing a copy of the image to be loaded.
1405 @param SourceSize The size in bytes of SourceBuffer.
1406 @param ImageHandle Pointer to the returned image handle that is
1407 created when the image is successfully loaded.
1409 @retval EFI_SUCCESS The image was loaded into memory.
1410 @retval EFI_NOT_FOUND The FilePath was not found.
1411 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
1412 @retval EFI_UNSUPPORTED The image type is not supported, or the device
1413 path cannot be parsed to locate the proper
1414 protocol for loading the file.
1415 @retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient
1417 @retval EFI_LOAD_ERROR Image was not loaded because the image format was corrupt or not
1419 @retval EFI_DEVICE_ERROR Image was not loaded because the device returned a read error.
1420 @retval EFI_ACCESS_DENIED Image was not loaded because the platform policy prohibits the
1421 image from being loaded. NULL is returned in *ImageHandle.
1422 @retval EFI_SECURITY_VIOLATION Image was loaded and an ImageHandle was created with a
1423 valid EFI_LOADED_IMAGE_PROTOCOL. However, the current
1424 platform policy specifies that the image should not be started.
1430 IN BOOLEAN BootPolicy
,
1431 IN EFI_HANDLE ParentImageHandle
,
1432 IN EFI_DEVICE_PATH_PROTOCOL
*FilePath
,
1433 IN VOID
*SourceBuffer OPTIONAL
,
1434 IN UINTN SourceSize
,
1435 OUT EFI_HANDLE
*ImageHandle
1441 PERF_LOAD_IMAGE_BEGIN (NULL
);
1443 Status
= CoreLoadImageCommon (
1449 (EFI_PHYSICAL_ADDRESS
) (UINTN
) NULL
,
1453 EFI_LOAD_PE_IMAGE_ATTRIBUTE_RUNTIME_REGISTRATION
| EFI_LOAD_PE_IMAGE_ATTRIBUTE_DEBUG_IMAGE_INFO_TABLE_REGISTRATION
1457 if (!EFI_ERROR (Status
)) {
1459 // ImageHandle will be valid only Status is success.
1461 Handle
= *ImageHandle
;
1464 PERF_LOAD_IMAGE_END (Handle
);
1472 Loads an EFI image into memory and returns a handle to the image with extended parameters.
1474 @param This Calling context
1475 @param ParentImageHandle The caller's image handle.
1476 @param FilePath The specific file path from which the image is
1478 @param SourceBuffer If not NULL, a pointer to the memory location
1479 containing a copy of the image to be loaded.
1480 @param SourceSize The size in bytes of SourceBuffer.
1481 @param DstBuffer The buffer to store the image.
1482 @param NumberOfPages For input, specifies the space size of the
1483 image by caller if not NULL. For output,
1484 specifies the actual space size needed.
1485 @param ImageHandle Image handle for output.
1486 @param EntryPoint Image entry point for output.
1487 @param Attribute The bit mask of attributes to set for the load
1490 @retval EFI_SUCCESS The image was loaded into memory.
1491 @retval EFI_NOT_FOUND The FilePath was not found.
1492 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
1493 @retval EFI_UNSUPPORTED The image type is not supported, or the device
1494 path cannot be parsed to locate the proper
1495 protocol for loading the file.
1496 @retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient
1498 @retval EFI_LOAD_ERROR Image was not loaded because the image format was corrupt or not
1500 @retval EFI_DEVICE_ERROR Image was not loaded because the device returned a read error.
1501 @retval EFI_ACCESS_DENIED Image was not loaded because the platform policy prohibits the
1502 image from being loaded. NULL is returned in *ImageHandle.
1503 @retval EFI_SECURITY_VIOLATION Image was loaded and an ImageHandle was created with a
1504 valid EFI_LOADED_IMAGE_PROTOCOL. However, the current
1505 platform policy specifies that the image should not be started.
1511 IN EFI_PE32_IMAGE_PROTOCOL
*This
,
1512 IN EFI_HANDLE ParentImageHandle
,
1513 IN EFI_DEVICE_PATH_PROTOCOL
*FilePath
,
1514 IN VOID
*SourceBuffer OPTIONAL
,
1515 IN UINTN SourceSize
,
1516 IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL
,
1517 OUT UINTN
*NumberOfPages OPTIONAL
,
1518 OUT EFI_HANDLE
*ImageHandle
,
1519 OUT EFI_PHYSICAL_ADDRESS
*EntryPoint OPTIONAL
,
1526 PERF_LOAD_IMAGE_BEGIN (NULL
);
1528 Status
= CoreLoadImageCommon (
1542 if (!EFI_ERROR (Status
)) {
1544 // ImageHandle will be valid only Status is success.
1546 Handle
= *ImageHandle
;
1549 PERF_LOAD_IMAGE_END (Handle
);
1556 Transfer control to a loaded image's entry point.
1558 @param ImageHandle Handle of image to be started.
1559 @param ExitDataSize Pointer of the size to ExitData
1560 @param ExitData Pointer to a pointer to a data buffer that
1561 includes a Null-terminated string,
1562 optionally followed by additional binary data.
1563 The string is a description that the caller may
1564 use to further indicate the reason for the
1567 @retval EFI_INVALID_PARAMETER Invalid parameter
1568 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
1569 @retval EFI_SECURITY_VIOLATION The current platform policy specifies that the image should not be started.
1570 @retval EFI_SUCCESS Successfully transfer control to the image's
1577 IN EFI_HANDLE ImageHandle
,
1578 OUT UINTN
*ExitDataSize
,
1579 OUT CHAR16
**ExitData OPTIONAL
1583 LOADED_IMAGE_PRIVATE_DATA
*Image
;
1584 LOADED_IMAGE_PRIVATE_DATA
*LastImage
;
1585 UINT64 HandleDatabaseKey
;
1589 Handle
= ImageHandle
;
1591 Image
= CoreLoadedImageInfo (ImageHandle
);
1592 if (Image
== NULL
|| Image
->Started
) {
1593 return EFI_INVALID_PARAMETER
;
1595 if (EFI_ERROR (Image
->LoadImageStatus
)) {
1596 return Image
->LoadImageStatus
;
1600 // The image to be started must have the machine type supported by DxeCore.
1602 if (!EFI_IMAGE_MACHINE_TYPE_SUPPORTED (Image
->Machine
)) {
1604 // Do not ASSERT here, because image might be loaded via EFI_IMAGE_MACHINE_CROSS_TYPE_SUPPORTED
1605 // But it can not be started.
1607 DEBUG ((EFI_D_ERROR
, "Image type %s can't be started ", GetMachineTypeName(Image
->Machine
)));
1608 DEBUG ((EFI_D_ERROR
, "on %s UEFI system.\n", GetMachineTypeName(mDxeCoreImageMachineType
)));
1609 return EFI_UNSUPPORTED
;
1612 PERF_START_IMAGE_BEGIN (Handle
);
1616 // Push the current start image context, and
1617 // link the current image to the head. This is the
1618 // only image that can call Exit()
1620 HandleDatabaseKey
= CoreGetHandleDatabaseKey ();
1621 LastImage
= mCurrentImage
;
1622 mCurrentImage
= Image
;
1623 Image
->Tpl
= gEfiCurrentTpl
;
1626 // Set long jump for Exit() support
1627 // JumpContext must be aligned on a CPU specific boundary.
1628 // Overallocate the buffer and force the required alignment
1630 Image
->JumpBuffer
= AllocatePool (sizeof (BASE_LIBRARY_JUMP_BUFFER
) + BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT
);
1631 if (Image
->JumpBuffer
== NULL
) {
1633 // Image may be unloaded after return with failure,
1634 // then ImageHandle may be invalid, so use NULL handle to record perf log.
1636 PERF_START_IMAGE_END (NULL
);
1639 // Pop the current start image context
1641 mCurrentImage
= LastImage
;
1643 return EFI_OUT_OF_RESOURCES
;
1645 Image
->JumpContext
= ALIGN_POINTER (Image
->JumpBuffer
, BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT
);
1647 SetJumpFlag
= SetJump (Image
->JumpContext
);
1649 // The initial call to SetJump() must always return 0.
1650 // Subsequent calls to LongJump() cause a non-zero value to be returned by SetJump().
1652 if (SetJumpFlag
== 0) {
1653 RegisterMemoryProfileImage (Image
, (Image
->ImageContext
.ImageType
== EFI_IMAGE_SUBSYSTEM_EFI_APPLICATION
? EFI_FV_FILETYPE_APPLICATION
: EFI_FV_FILETYPE_DRIVER
));
1655 // Call the image's entry point
1657 Image
->Started
= TRUE
;
1658 Image
->Status
= Image
->EntryPoint (ImageHandle
, Image
->Info
.SystemTable
);
1661 // Add some debug information if the image returned with error.
1662 // This make the user aware and check if the driver image have already released
1663 // all the resource in this situation.
1665 DEBUG_CODE_BEGIN ();
1666 if (EFI_ERROR (Image
->Status
)) {
1667 DEBUG ((DEBUG_ERROR
, "Error: Image at %11p start failed: %r\n", Image
->Info
.ImageBase
, Image
->Status
));
1672 // If the image returns, exit it through Exit()
1674 CoreExit (ImageHandle
, Image
->Status
, 0, NULL
);
1678 // Image has completed. Verify the tpl is the same
1680 ASSERT (Image
->Tpl
== gEfiCurrentTpl
);
1681 CoreRestoreTpl (Image
->Tpl
);
1683 CoreFreePool (Image
->JumpBuffer
);
1686 // Pop the current start image context
1688 mCurrentImage
= LastImage
;
1691 // UEFI Specification - StartImage() - EFI 1.10 Extension
1692 // To maintain compatibility with UEFI drivers that are written to the EFI
1693 // 1.02 Specification, StartImage() must monitor the handle database before
1694 // and after each image is started. If any handles are created or modified
1695 // when an image is started, then EFI_BOOT_SERVICES.ConnectController() must
1696 // be called with the Recursive parameter set to TRUE for each of the newly
1697 // created or modified handles before StartImage() returns.
1699 if (Image
->Type
!= EFI_IMAGE_SUBSYSTEM_EFI_APPLICATION
) {
1700 CoreConnectHandlesByKey (HandleDatabaseKey
);
1704 // Handle the image's returned ExitData
1706 DEBUG_CODE_BEGIN ();
1707 if (Image
->ExitDataSize
!= 0 || Image
->ExitData
!= NULL
) {
1709 DEBUG ((DEBUG_LOAD
, "StartImage: ExitDataSize %d, ExitData %p", (UINT32
)Image
->ExitDataSize
, Image
->ExitData
));
1710 if (Image
->ExitData
!= NULL
) {
1711 DEBUG ((DEBUG_LOAD
, " (%hs)", Image
->ExitData
));
1713 DEBUG ((DEBUG_LOAD
, "\n"));
1718 // Return the exit data to the caller
1720 if (ExitData
!= NULL
&& ExitDataSize
!= NULL
) {
1721 *ExitDataSize
= Image
->ExitDataSize
;
1722 *ExitData
= Image
->ExitData
;
1725 // Caller doesn't want the exit data, free it
1727 CoreFreePool (Image
->ExitData
);
1728 Image
->ExitData
= NULL
;
1732 // Save the Status because Image will get destroyed if it is unloaded.
1734 Status
= Image
->Status
;
1737 // If the image returned an error, or if the image is an application
1740 if (EFI_ERROR (Image
->Status
) || Image
->Type
== EFI_IMAGE_SUBSYSTEM_EFI_APPLICATION
) {
1741 CoreUnloadAndCloseImage (Image
, TRUE
);
1743 // ImageHandle may be invalid after the image is unloaded, so use NULL handle to record perf log.
1751 PERF_START_IMAGE_END (Handle
);
1756 Terminates the currently loaded EFI image and returns control to boot services.
1758 @param ImageHandle Handle that identifies the image. This
1759 parameter is passed to the image on entry.
1760 @param Status The image's exit code.
1761 @param ExitDataSize The size, in bytes, of ExitData. Ignored if
1762 ExitStatus is EFI_SUCCESS.
1763 @param ExitData Pointer to a data buffer that includes a
1764 Null-terminated Unicode string, optionally
1765 followed by additional binary data. The string
1766 is a description that the caller may use to
1767 further indicate the reason for the image's
1770 @retval EFI_INVALID_PARAMETER Image handle is NULL or it is not current
1772 @retval EFI_SUCCESS Successfully terminates the currently loaded
1774 @retval EFI_ACCESS_DENIED Should never reach there.
1775 @retval EFI_OUT_OF_RESOURCES Could not allocate pool
1781 IN EFI_HANDLE ImageHandle
,
1782 IN EFI_STATUS Status
,
1783 IN UINTN ExitDataSize
,
1784 IN CHAR16
*ExitData OPTIONAL
1787 LOADED_IMAGE_PRIVATE_DATA
*Image
;
1791 // Prevent possible reentrance to this function
1792 // for the same ImageHandle
1794 OldTpl
= CoreRaiseTpl (TPL_NOTIFY
);
1796 Image
= CoreLoadedImageInfo (ImageHandle
);
1797 if (Image
== NULL
) {
1798 Status
= EFI_INVALID_PARAMETER
;
1802 if (!Image
->Started
) {
1804 // The image has not been started so just free its resources
1806 CoreUnloadAndCloseImage (Image
, TRUE
);
1807 Status
= EFI_SUCCESS
;
1812 // Image has been started, verify this image can exit
1814 if (Image
!= mCurrentImage
) {
1815 DEBUG ((DEBUG_LOAD
|DEBUG_ERROR
, "Exit: Image is not exitable image\n"));
1816 Status
= EFI_INVALID_PARAMETER
;
1823 Image
->Status
= Status
;
1826 // If there's ExitData info, move it
1828 if (ExitData
!= NULL
) {
1829 Image
->ExitDataSize
= ExitDataSize
;
1830 Image
->ExitData
= AllocatePool (Image
->ExitDataSize
);
1831 if (Image
->ExitData
== NULL
) {
1832 Status
= EFI_OUT_OF_RESOURCES
;
1835 CopyMem (Image
->ExitData
, ExitData
, Image
->ExitDataSize
);
1838 CoreRestoreTpl (OldTpl
);
1840 // return to StartImage
1842 LongJump (Image
->JumpContext
, (UINTN
)-1);
1845 // If we return from LongJump, then it is an error
1848 Status
= EFI_ACCESS_DENIED
;
1850 CoreRestoreTpl (OldTpl
);
1860 @param ImageHandle Handle that identifies the image to be
1863 @retval EFI_SUCCESS The image has been unloaded.
1864 @retval EFI_UNSUPPORTED The image has been started, and does not support
1866 @retval EFI_INVALID_PARAMPETER ImageHandle is not a valid image handle.
1872 IN EFI_HANDLE ImageHandle
1876 LOADED_IMAGE_PRIVATE_DATA
*Image
;
1878 Image
= CoreLoadedImageInfo (ImageHandle
);
1879 if (Image
== NULL
) {
1881 // The image handle is not valid
1883 Status
= EFI_INVALID_PARAMETER
;
1887 if (Image
->Started
) {
1889 // The image has been started, request it to unload.
1891 Status
= EFI_UNSUPPORTED
;
1892 if (Image
->Info
.Unload
!= NULL
) {
1893 Status
= Image
->Info
.Unload (ImageHandle
);
1898 // This Image hasn't been started, thus it can be unloaded
1900 Status
= EFI_SUCCESS
;
1904 if (!EFI_ERROR (Status
)) {
1906 // if the Image was not started or Unloaded O.K. then clean up
1908 CoreUnloadAndCloseImage (Image
, TRUE
);
1918 Unload the specified image.
1920 @param This Indicates the calling context.
1921 @param ImageHandle The specified image handle.
1923 @retval EFI_INVALID_PARAMETER Image handle is NULL.
1924 @retval EFI_UNSUPPORTED Attempt to unload an unsupported image.
1925 @retval EFI_SUCCESS Image successfully unloaded.
1931 IN EFI_PE32_IMAGE_PROTOCOL
*This
,
1932 IN EFI_HANDLE ImageHandle
1935 return CoreUnloadImage (ImageHandle
);