2 Core image handling services to load and unload PeImage.
4 Copyright (c) 2006 - 2017, 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"}
95 UINT16 mDxeCoreImageMachineType
= 0;
98 Return machine type name.
100 @param MachineType The machine type
102 @return machine type name
111 for (Index
= 0; Index
< sizeof(mMachineTypeInfo
)/sizeof(mMachineTypeInfo
[0]); Index
++) {
112 if (mMachineTypeInfo
[Index
].MachineType
== MachineType
) {
113 return mMachineTypeInfo
[Index
].MachineTypeName
;
121 Add the Image Services to EFI Boot Services Table and install the protocol
122 interfaces for this image.
124 @param HobStart The HOB to initialize
130 CoreInitializeImageServices (
135 LOADED_IMAGE_PRIVATE_DATA
*Image
;
136 EFI_PHYSICAL_ADDRESS DxeCoreImageBaseAddress
;
137 UINT64 DxeCoreImageLength
;
138 VOID
*DxeCoreEntryPoint
;
139 EFI_PEI_HOB_POINTERS DxeCoreHob
;
142 // Searching for image hob
144 DxeCoreHob
.Raw
= HobStart
;
145 while ((DxeCoreHob
.Raw
= GetNextHob (EFI_HOB_TYPE_MEMORY_ALLOCATION
, DxeCoreHob
.Raw
)) != NULL
) {
146 if (CompareGuid (&DxeCoreHob
.MemoryAllocationModule
->MemoryAllocationHeader
.Name
, &gEfiHobMemoryAllocModuleGuid
)) {
152 DxeCoreHob
.Raw
= GET_NEXT_HOB (DxeCoreHob
);
154 ASSERT (DxeCoreHob
.Raw
!= NULL
);
156 DxeCoreImageBaseAddress
= DxeCoreHob
.MemoryAllocationModule
->MemoryAllocationHeader
.MemoryBaseAddress
;
157 DxeCoreImageLength
= DxeCoreHob
.MemoryAllocationModule
->MemoryAllocationHeader
.MemoryLength
;
158 DxeCoreEntryPoint
= (VOID
*) (UINTN
) DxeCoreHob
.MemoryAllocationModule
->EntryPoint
;
159 gDxeCoreFileName
= &DxeCoreHob
.MemoryAllocationModule
->ModuleName
;
162 // Initialize the fields for an internal driver
164 Image
= &mCorePrivateImage
;
166 Image
->EntryPoint
= (EFI_IMAGE_ENTRY_POINT
)(UINTN
)DxeCoreEntryPoint
;
167 Image
->ImageBasePage
= DxeCoreImageBaseAddress
;
168 Image
->NumberOfPages
= (UINTN
)(EFI_SIZE_TO_PAGES((UINTN
)(DxeCoreImageLength
)));
169 Image
->Tpl
= gEfiCurrentTpl
;
170 Image
->Info
.SystemTable
= gDxeCoreST
;
171 Image
->Info
.ImageBase
= (VOID
*)(UINTN
)DxeCoreImageBaseAddress
;
172 Image
->Info
.ImageSize
= DxeCoreImageLength
;
175 // Install the protocol interfaces for this image
177 Status
= CoreInstallProtocolInterface (
179 &gEfiLoadedImageProtocolGuid
,
180 EFI_NATIVE_INTERFACE
,
183 ASSERT_EFI_ERROR (Status
);
185 mCurrentImage
= Image
;
188 // Fill in DXE globals
190 mDxeCoreImageMachineType
= PeCoffLoaderGetMachineType (Image
->Info
.ImageBase
);
191 gDxeCoreImageHandle
= Image
->Handle
;
192 gDxeCoreLoadedImage
= &Image
->Info
;
194 if (FeaturePcdGet (PcdFrameworkCompatibilitySupport
)) {
196 // Export DXE Core PE Loader functionality for backward compatibility.
198 Status
= CoreInstallProtocolInterface (
199 &mLoadPe32PrivateData
.Handle
,
200 &gEfiLoadPeImageProtocolGuid
,
201 EFI_NATIVE_INTERFACE
,
202 &mLoadPe32PrivateData
.Pe32Image
206 ProtectUefiImage (&Image
->Info
, Image
->LoadedImageDevicePath
);
212 Read image file (specified by UserHandle) into user specified buffer with specified offset
215 @param UserHandle Image file handle
216 @param Offset Offset to the source file
217 @param ReadSize For input, pointer of size to read; For output,
218 pointer of size actually read.
219 @param Buffer Buffer to write into
221 @retval EFI_SUCCESS Successfully read the specified part of file
230 IN OUT UINTN
*ReadSize
,
235 IMAGE_FILE_HANDLE
*FHand
;
237 if (UserHandle
== NULL
|| ReadSize
== NULL
|| Buffer
== NULL
) {
238 return EFI_INVALID_PARAMETER
;
241 if (MAX_ADDRESS
- Offset
< *ReadSize
) {
242 return EFI_INVALID_PARAMETER
;
245 FHand
= (IMAGE_FILE_HANDLE
*)UserHandle
;
246 ASSERT (FHand
->Signature
== IMAGE_FILE_HANDLE_SIGNATURE
);
249 // Move data from our local copy of the file
251 EndPosition
= Offset
+ *ReadSize
;
252 if (EndPosition
> FHand
->SourceSize
) {
253 *ReadSize
= (UINT32
)(FHand
->SourceSize
- Offset
);
255 if (Offset
>= FHand
->SourceSize
) {
259 CopyMem (Buffer
, (CHAR8
*)FHand
->Source
+ Offset
, *ReadSize
);
263 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
264 memory range is available, the function will mark the corresponding bits to 1 which indicates the memory range is used.
265 The function is only invoked when load modules at fixed address feature is enabled.
267 @param ImageBase The base address the image will be loaded at.
268 @param ImageSize The size of the image
270 @retval EFI_SUCCESS The memory range the image will be loaded in is available
271 @retval EFI_NOT_FOUND The memory range the image will be loaded in is not available
274 CheckAndMarkFixLoadingMemoryUsageBitMap (
275 IN EFI_PHYSICAL_ADDRESS ImageBase
,
279 UINT32 DxeCodePageNumber
;
281 EFI_PHYSICAL_ADDRESS DxeCodeBase
;
282 UINTN BaseOffsetPageNumber
;
283 UINTN TopOffsetPageNumber
;
286 // The DXE code range includes RuntimeCodePage range and Boot time code range.
288 DxeCodePageNumber
= PcdGet32(PcdLoadFixAddressRuntimeCodePageNumber
);
289 DxeCodePageNumber
+= PcdGet32(PcdLoadFixAddressBootTimeCodePageNumber
);
290 DxeCodeSize
= EFI_PAGES_TO_SIZE(DxeCodePageNumber
);
291 DxeCodeBase
= gLoadModuleAtFixAddressConfigurationTable
.DxeCodeTopAddress
- DxeCodeSize
;
294 // If the memory usage bit map is not initialized, do it. Every bit in the array
295 // indicate the status of the corresponding memory page, available or not
297 if (mDxeCodeMemoryRangeUsageBitMap
== NULL
) {
298 mDxeCodeMemoryRangeUsageBitMap
= AllocateZeroPool(((DxeCodePageNumber
/64) + 1)*sizeof(UINT64
));
301 // If the Dxe code memory range is not allocated or the bit map array allocation failed, return EFI_NOT_FOUND
303 if (!gLoadFixedAddressCodeMemoryReady
|| mDxeCodeMemoryRangeUsageBitMap
== NULL
) {
304 return EFI_NOT_FOUND
;
307 // Test the memory range for loading the image in the DXE code range.
309 if (gLoadModuleAtFixAddressConfigurationTable
.DxeCodeTopAddress
< ImageBase
+ ImageSize
||
310 DxeCodeBase
> ImageBase
) {
311 return EFI_NOT_FOUND
;
314 // Test if the memory is avalaible or not.
316 BaseOffsetPageNumber
= (UINTN
)EFI_SIZE_TO_PAGES((UINT32
)(ImageBase
- DxeCodeBase
));
317 TopOffsetPageNumber
= (UINTN
)EFI_SIZE_TO_PAGES((UINT32
)(ImageBase
+ ImageSize
- DxeCodeBase
));
318 for (Index
= BaseOffsetPageNumber
; Index
< TopOffsetPageNumber
; Index
++) {
319 if ((mDxeCodeMemoryRangeUsageBitMap
[Index
/ 64] & LShiftU64(1, (Index
% 64))) != 0) {
321 // This page is already used.
323 return EFI_NOT_FOUND
;
328 // Being here means the memory range is available. So mark the bits for the memory range
330 for (Index
= BaseOffsetPageNumber
; Index
< TopOffsetPageNumber
; Index
++) {
331 mDxeCodeMemoryRangeUsageBitMap
[Index
/ 64] |= LShiftU64(1, (Index
% 64));
337 Get the fixed loading address from image header assigned by build tool. This function only be called
338 when Loading module at Fixed address feature enabled.
340 @param ImageContext Pointer to the image context structure that describes the PE/COFF
341 image that needs to be examined by this function.
342 @retval EFI_SUCCESS An fixed loading address is assigned to this image by build tools .
343 @retval EFI_NOT_FOUND The image has no assigned fixed loading address.
347 GetPeCoffImageFixLoadingAssignedAddress(
348 IN OUT PE_COFF_LOADER_IMAGE_CONTEXT
*ImageContext
351 UINTN SectionHeaderOffset
;
353 EFI_IMAGE_SECTION_HEADER SectionHeader
;
354 EFI_IMAGE_OPTIONAL_HEADER_UNION
*ImgHdr
;
357 UINT16 NumberOfSections
;
358 IMAGE_FILE_HANDLE
*Handle
;
359 UINT64 ValueInSectionHeader
;
362 Status
= EFI_NOT_FOUND
;
365 // Get PeHeader pointer
367 Handle
= (IMAGE_FILE_HANDLE
*)ImageContext
->Handle
;
368 ImgHdr
= (EFI_IMAGE_OPTIONAL_HEADER_UNION
*)((CHAR8
* )Handle
->Source
+ ImageContext
->PeCoffHeaderOffset
);
369 SectionHeaderOffset
= (UINTN
)(
370 ImageContext
->PeCoffHeaderOffset
+
372 sizeof (EFI_IMAGE_FILE_HEADER
) +
373 ImgHdr
->Pe32
.FileHeader
.SizeOfOptionalHeader
375 NumberOfSections
= ImgHdr
->Pe32
.FileHeader
.NumberOfSections
;
378 // Get base address from the first section header that doesn't point to code section.
380 for (Index
= 0; Index
< NumberOfSections
; Index
++) {
382 // Read section header from file
384 Size
= sizeof (EFI_IMAGE_SECTION_HEADER
);
385 Status
= ImageContext
->ImageRead (
386 ImageContext
->Handle
,
391 if (EFI_ERROR (Status
)) {
394 if (Size
!= sizeof (EFI_IMAGE_SECTION_HEADER
)) {
395 return EFI_NOT_FOUND
;
398 Status
= EFI_NOT_FOUND
;
400 if ((SectionHeader
.Characteristics
& EFI_IMAGE_SCN_CNT_CODE
) == 0) {
402 // Build tool will save the address in PointerToRelocations & PointerToLineNumbers fields in the first section header
403 // that doesn't point to code section in image header, as well as ImageBase field of image header. And there is an
404 // assumption that when the feature is enabled, if a module is assigned a loading address by tools, PointerToRelocations
405 // & PointerToLineNumbers fields should NOT be Zero, or else, these 2 fields should be set to Zero
407 ValueInSectionHeader
= ReadUnaligned64((UINT64
*)&SectionHeader
.PointerToRelocations
);
408 if (ValueInSectionHeader
!= 0) {
410 // When the feature is configured as load module at fixed absolute address, the ImageAddress field of ImageContext
411 // hold the spcified address. If the feature is configured as load module at fixed offset, ImageAddress hold an offset
412 // relative to top address
414 if ((INT64
)PcdGet64(PcdLoadModuleAtFixAddressEnable
) < 0) {
415 ImageContext
->ImageAddress
= gLoadModuleAtFixAddressConfigurationTable
.DxeCodeTopAddress
+ (INT64
)(INTN
)ImageContext
->ImageAddress
;
418 // Check if the memory range is available.
420 Status
= CheckAndMarkFixLoadingMemoryUsageBitMap (ImageContext
->ImageAddress
, (UINTN
)(ImageContext
->ImageSize
+ ImageContext
->SectionAlignment
));
424 SectionHeaderOffset
+= sizeof (EFI_IMAGE_SECTION_HEADER
);
426 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
));
430 Loads, relocates, and invokes a PE/COFF image
432 @param BootPolicy If TRUE, indicates that the request originates
433 from the boot manager, and that the boot
434 manager is attempting to load FilePath as a
436 @param Pe32Handle The handle of PE32 image
437 @param Image PE image to be loaded
438 @param DstBuffer The buffer to store the image
439 @param EntryPoint A pointer to the entry point
440 @param Attribute The bit mask of attributes to set for the load
443 @retval EFI_SUCCESS The file was loaded, relocated, and invoked
444 @retval EFI_OUT_OF_RESOURCES There was not enough memory to load and
445 relocate the PE/COFF file
446 @retval EFI_INVALID_PARAMETER Invalid parameter
447 @retval EFI_BUFFER_TOO_SMALL Buffer for image is too small
452 IN BOOLEAN BootPolicy
,
454 IN LOADED_IMAGE_PRIVATE_DATA
*Image
,
455 IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL
,
456 OUT EFI_PHYSICAL_ADDRESS
*EntryPoint OPTIONAL
,
461 BOOLEAN DstBufAlocated
;
464 ZeroMem (&Image
->ImageContext
, sizeof (Image
->ImageContext
));
466 Image
->ImageContext
.Handle
= Pe32Handle
;
467 Image
->ImageContext
.ImageRead
= (PE_COFF_LOADER_READ_FILE
)CoreReadImageFile
;
470 // Get information about the image being loaded
472 Status
= PeCoffLoaderGetImageInfo (&Image
->ImageContext
);
473 if (EFI_ERROR (Status
)) {
477 if (!EFI_IMAGE_MACHINE_TYPE_SUPPORTED (Image
->ImageContext
.Machine
)) {
478 if (!EFI_IMAGE_MACHINE_CROSS_TYPE_SUPPORTED (Image
->ImageContext
.Machine
)) {
480 // The PE/COFF loader can support loading image types that can be executed.
481 // If we loaded an image type that we can not execute return EFI_UNSUPORTED.
483 DEBUG ((EFI_D_ERROR
, "Image type %s can't be loaded ", GetMachineTypeName(Image
->ImageContext
.Machine
)));
484 DEBUG ((EFI_D_ERROR
, "on %s UEFI system.\n", GetMachineTypeName(mDxeCoreImageMachineType
)));
485 return EFI_UNSUPPORTED
;
490 // Set EFI memory type based on ImageType
492 switch (Image
->ImageContext
.ImageType
) {
493 case EFI_IMAGE_SUBSYSTEM_EFI_APPLICATION
:
494 Image
->ImageContext
.ImageCodeMemoryType
= EfiLoaderCode
;
495 Image
->ImageContext
.ImageDataMemoryType
= EfiLoaderData
;
497 case EFI_IMAGE_SUBSYSTEM_EFI_BOOT_SERVICE_DRIVER
:
498 Image
->ImageContext
.ImageCodeMemoryType
= EfiBootServicesCode
;
499 Image
->ImageContext
.ImageDataMemoryType
= EfiBootServicesData
;
501 case EFI_IMAGE_SUBSYSTEM_EFI_RUNTIME_DRIVER
:
502 case EFI_IMAGE_SUBSYSTEM_SAL_RUNTIME_DRIVER
:
503 Image
->ImageContext
.ImageCodeMemoryType
= EfiRuntimeServicesCode
;
504 Image
->ImageContext
.ImageDataMemoryType
= EfiRuntimeServicesData
;
507 Image
->ImageContext
.ImageError
= IMAGE_ERROR_INVALID_SUBSYSTEM
;
508 return EFI_UNSUPPORTED
;
512 // Allocate memory of the correct memory type aligned on the required image boundary
514 DstBufAlocated
= FALSE
;
515 if (DstBuffer
== 0) {
517 // Allocate Destination Buffer as caller did not pass it in
520 if (Image
->ImageContext
.SectionAlignment
> EFI_PAGE_SIZE
) {
521 Size
= (UINTN
)Image
->ImageContext
.ImageSize
+ Image
->ImageContext
.SectionAlignment
;
523 Size
= (UINTN
)Image
->ImageContext
.ImageSize
;
526 Image
->NumberOfPages
= EFI_SIZE_TO_PAGES (Size
);
529 // If the image relocations have not been stripped, then load at any address.
530 // Otherwise load at the address at which it was linked.
532 // Memory below 1MB should be treated reserved for CSM and there should be
533 // no modules whose preferred load addresses are below 1MB.
535 Status
= EFI_OUT_OF_RESOURCES
;
537 // If Loading Module At Fixed Address feature is enabled, the module should be loaded to
538 // a specified address.
540 if (PcdGet64(PcdLoadModuleAtFixAddressEnable
) != 0 ) {
541 Status
= GetPeCoffImageFixLoadingAssignedAddress (&(Image
->ImageContext
));
543 if (EFI_ERROR (Status
)) {
545 // If the code memory is not ready, invoke CoreAllocatePage with AllocateAnyPages to load the driver.
547 DEBUG ((EFI_D_INFO
|EFI_D_LOAD
, "LOADING MODULE FIXED ERROR: Loading module at fixed address failed since specified memory is not available.\n"));
549 Status
= CoreAllocatePages (
551 (EFI_MEMORY_TYPE
) (Image
->ImageContext
.ImageCodeMemoryType
),
552 Image
->NumberOfPages
,
553 &Image
->ImageContext
.ImageAddress
557 if (Image
->ImageContext
.ImageAddress
>= 0x100000 || Image
->ImageContext
.RelocationsStripped
) {
558 Status
= CoreAllocatePages (
560 (EFI_MEMORY_TYPE
) (Image
->ImageContext
.ImageCodeMemoryType
),
561 Image
->NumberOfPages
,
562 &Image
->ImageContext
.ImageAddress
565 if (EFI_ERROR (Status
) && !Image
->ImageContext
.RelocationsStripped
) {
566 Status
= CoreAllocatePages (
568 (EFI_MEMORY_TYPE
) (Image
->ImageContext
.ImageCodeMemoryType
),
569 Image
->NumberOfPages
,
570 &Image
->ImageContext
.ImageAddress
574 if (EFI_ERROR (Status
)) {
577 DstBufAlocated
= TRUE
;
580 // Caller provided the destination buffer
583 if (Image
->ImageContext
.RelocationsStripped
&& (Image
->ImageContext
.ImageAddress
!= DstBuffer
)) {
585 // If the image relocations were stripped, and the caller provided a
586 // destination buffer address that does not match the address that the
587 // image is linked at, then the image cannot be loaded.
589 return EFI_INVALID_PARAMETER
;
592 if (Image
->NumberOfPages
!= 0 &&
593 Image
->NumberOfPages
<
594 (EFI_SIZE_TO_PAGES ((UINTN
)Image
->ImageContext
.ImageSize
+ Image
->ImageContext
.SectionAlignment
))) {
595 Image
->NumberOfPages
= EFI_SIZE_TO_PAGES ((UINTN
)Image
->ImageContext
.ImageSize
+ Image
->ImageContext
.SectionAlignment
);
596 return EFI_BUFFER_TOO_SMALL
;
599 Image
->NumberOfPages
= EFI_SIZE_TO_PAGES ((UINTN
)Image
->ImageContext
.ImageSize
+ Image
->ImageContext
.SectionAlignment
);
600 Image
->ImageContext
.ImageAddress
= DstBuffer
;
603 Image
->ImageBasePage
= Image
->ImageContext
.ImageAddress
;
604 if (!Image
->ImageContext
.IsTeImage
) {
605 Image
->ImageContext
.ImageAddress
=
606 (Image
->ImageContext
.ImageAddress
+ Image
->ImageContext
.SectionAlignment
- 1) &
607 ~((UINTN
)Image
->ImageContext
.SectionAlignment
- 1);
611 // Load the image from the file into the allocated memory
613 Status
= PeCoffLoaderLoadImage (&Image
->ImageContext
);
614 if (EFI_ERROR (Status
)) {
619 // If this is a Runtime Driver, then allocate memory for the FixupData that
620 // is used to relocate the image when SetVirtualAddressMap() is called. The
621 // relocation is done by the Runtime AP.
623 if ((Attribute
& EFI_LOAD_PE_IMAGE_ATTRIBUTE_RUNTIME_REGISTRATION
) != 0) {
624 if (Image
->ImageContext
.ImageType
== EFI_IMAGE_SUBSYSTEM_EFI_RUNTIME_DRIVER
) {
625 Image
->ImageContext
.FixupData
= AllocateRuntimePool ((UINTN
)(Image
->ImageContext
.FixupDataSize
));
626 if (Image
->ImageContext
.FixupData
== NULL
) {
627 Status
= EFI_OUT_OF_RESOURCES
;
634 // Relocate the image in memory
636 Status
= PeCoffLoaderRelocateImage (&Image
->ImageContext
);
637 if (EFI_ERROR (Status
)) {
642 // Flush the Instruction Cache
644 InvalidateInstructionCacheRange ((VOID
*)(UINTN
)Image
->ImageContext
.ImageAddress
, (UINTN
)Image
->ImageContext
.ImageSize
);
647 // Copy the machine type from the context to the image private data. This
648 // is needed during image unload to know if we should call an EBC protocol
649 // to unload the image.
651 Image
->Machine
= Image
->ImageContext
.Machine
;
654 // Get the image entry point. If it's an EBC image, then call into the
655 // interpreter to create a thunk for the entry point and use the returned
656 // value for the entry point.
658 Image
->EntryPoint
= (EFI_IMAGE_ENTRY_POINT
)(UINTN
)Image
->ImageContext
.EntryPoint
;
659 if (Image
->ImageContext
.Machine
== EFI_IMAGE_MACHINE_EBC
) {
661 // Locate the EBC interpreter protocol
663 Status
= CoreLocateProtocol (&gEfiEbcProtocolGuid
, NULL
, (VOID
**)&Image
->Ebc
);
664 if (EFI_ERROR(Status
) || Image
->Ebc
== NULL
) {
665 DEBUG ((DEBUG_LOAD
| DEBUG_ERROR
, "CoreLoadPeImage: There is no EBC interpreter for an EBC image.\n"));
670 // Register a callback for flushing the instruction cache so that created
671 // thunks can be flushed.
673 Status
= Image
->Ebc
->RegisterICacheFlush (Image
->Ebc
, (EBC_ICACHE_FLUSH
)InvalidateInstructionCacheRange
);
674 if (EFI_ERROR(Status
)) {
679 // Create a thunk for the image's entry point. This will be the new
680 // entry point for the image.
682 Status
= Image
->Ebc
->CreateThunk (
685 (VOID
*)(UINTN
) Image
->ImageContext
.EntryPoint
,
686 (VOID
**) &Image
->EntryPoint
688 if (EFI_ERROR(Status
)) {
694 // Fill in the image information for the Loaded Image Protocol
696 Image
->Type
= Image
->ImageContext
.ImageType
;
697 Image
->Info
.ImageBase
= (VOID
*)(UINTN
)Image
->ImageContext
.ImageAddress
;
698 Image
->Info
.ImageSize
= Image
->ImageContext
.ImageSize
;
699 Image
->Info
.ImageCodeType
= (EFI_MEMORY_TYPE
) (Image
->ImageContext
.ImageCodeMemoryType
);
700 Image
->Info
.ImageDataType
= (EFI_MEMORY_TYPE
) (Image
->ImageContext
.ImageDataMemoryType
);
701 if ((Attribute
& EFI_LOAD_PE_IMAGE_ATTRIBUTE_RUNTIME_REGISTRATION
) != 0) {
702 if (Image
->ImageContext
.ImageType
== EFI_IMAGE_SUBSYSTEM_EFI_RUNTIME_DRIVER
) {
704 // Make a list off all the RT images so we can let the RT AP know about them.
706 Image
->RuntimeData
= AllocateRuntimePool (sizeof(EFI_RUNTIME_IMAGE_ENTRY
));
707 if (Image
->RuntimeData
== NULL
) {
710 Image
->RuntimeData
->ImageBase
= Image
->Info
.ImageBase
;
711 Image
->RuntimeData
->ImageSize
= (UINT64
) (Image
->Info
.ImageSize
);
712 Image
->RuntimeData
->RelocationData
= Image
->ImageContext
.FixupData
;
713 Image
->RuntimeData
->Handle
= Image
->Handle
;
714 InsertTailList (&gRuntime
->ImageHead
, &Image
->RuntimeData
->Link
);
715 InsertImageRecord (Image
->RuntimeData
);
720 // Fill in the entry point of the image if it is available
722 if (EntryPoint
!= NULL
) {
723 *EntryPoint
= Image
->ImageContext
.EntryPoint
;
727 // Print the load address and the PDB file name if it is available
734 CHAR8 EfiFileName
[256];
737 DEBUG ((DEBUG_INFO
| DEBUG_LOAD
,
738 "Loading driver at 0x%11p EntryPoint=0x%11p ",
739 (VOID
*)(UINTN
) Image
->ImageContext
.ImageAddress
,
740 FUNCTION_ENTRY_POINT (Image
->ImageContext
.EntryPoint
)));
744 // Print Module Name by Pdb file path.
745 // Windows and Unix style file path are all trimmed correctly.
747 if (Image
->ImageContext
.PdbPointer
!= NULL
) {
749 for (Index
= 0; Image
->ImageContext
.PdbPointer
[Index
] != 0; Index
++) {
750 if ((Image
->ImageContext
.PdbPointer
[Index
] == '\\') || (Image
->ImageContext
.PdbPointer
[Index
] == '/')) {
751 StartIndex
= Index
+ 1;
755 // Copy the PDB file name to our temporary string, and replace .pdb with .efi
756 // The PDB file name is limited in the range of 0~255.
757 // If the length is bigger than 255, trim the redudant characters to avoid overflow in array boundary.
759 for (Index
= 0; Index
< sizeof (EfiFileName
) - 4; Index
++) {
760 EfiFileName
[Index
] = Image
->ImageContext
.PdbPointer
[Index
+ StartIndex
];
761 if (EfiFileName
[Index
] == 0) {
762 EfiFileName
[Index
] = '.';
764 if (EfiFileName
[Index
] == '.') {
765 EfiFileName
[Index
+ 1] = 'e';
766 EfiFileName
[Index
+ 2] = 'f';
767 EfiFileName
[Index
+ 3] = 'i';
768 EfiFileName
[Index
+ 4] = 0;
773 if (Index
== sizeof (EfiFileName
) - 4) {
774 EfiFileName
[Index
] = 0;
776 DEBUG ((DEBUG_INFO
| DEBUG_LOAD
, "%a", EfiFileName
)); // &Image->ImageContext.PdbPointer[StartIndex]));
778 DEBUG ((DEBUG_INFO
| DEBUG_LOAD
, "\n"));
790 if (DstBufAlocated
) {
791 CoreFreePages (Image
->ImageContext
.ImageAddress
, Image
->NumberOfPages
);
794 if (Image
->ImageContext
.FixupData
!= NULL
) {
795 CoreFreePool (Image
->ImageContext
.FixupData
);
804 Get the image's private data from its handle.
806 @param ImageHandle The image handle
808 @return Return the image private data associated with ImageHandle.
811 LOADED_IMAGE_PRIVATE_DATA
*
812 CoreLoadedImageInfo (
813 IN EFI_HANDLE ImageHandle
817 EFI_LOADED_IMAGE_PROTOCOL
*LoadedImage
;
818 LOADED_IMAGE_PRIVATE_DATA
*Image
;
820 Status
= CoreHandleProtocol (
822 &gEfiLoadedImageProtocolGuid
,
823 (VOID
**)&LoadedImage
825 if (!EFI_ERROR (Status
)) {
826 Image
= LOADED_IMAGE_PRIVATE_DATA_FROM_THIS (LoadedImage
);
828 DEBUG ((DEBUG_LOAD
, "CoreLoadedImageInfo: Not an ImageHandle %p\n", ImageHandle
));
837 Unloads EFI image from memory.
839 @param Image EFI image
840 @param FreePage Free allocated pages
844 CoreUnloadAndCloseImage (
845 IN LOADED_IMAGE_PRIVATE_DATA
*Image
,
851 EFI_HANDLE
*HandleBuffer
;
853 EFI_GUID
**ProtocolGuidArray
;
856 EFI_OPEN_PROTOCOL_INFORMATION_ENTRY
*OpenInfo
;
861 ProtocolGuidArray
= NULL
;
863 if (Image
->Started
) {
864 UnregisterMemoryProfileImage (Image
);
867 UnprotectUefiImage (&Image
->Info
, Image
->LoadedImageDevicePath
);
869 if (Image
->Ebc
!= NULL
) {
871 // If EBC protocol exists we must perform cleanups for this image.
873 Image
->Ebc
->UnloadImage (Image
->Ebc
, Image
->Handle
);
877 // Unload image, free Image->ImageContext->ModHandle
879 PeCoffLoaderUnloadImage (&Image
->ImageContext
);
882 // Free our references to the image handle
884 if (Image
->Handle
!= NULL
) {
886 Status
= CoreLocateHandleBuffer (
893 if (!EFI_ERROR (Status
)) {
894 for (HandleIndex
= 0; HandleIndex
< HandleCount
; HandleIndex
++) {
895 Status
= CoreProtocolsPerHandle (
896 HandleBuffer
[HandleIndex
],
900 if (!EFI_ERROR (Status
)) {
901 for (ProtocolIndex
= 0; ProtocolIndex
< ArrayCount
; ProtocolIndex
++) {
902 Status
= CoreOpenProtocolInformation (
903 HandleBuffer
[HandleIndex
],
904 ProtocolGuidArray
[ProtocolIndex
],
908 if (!EFI_ERROR (Status
)) {
909 for (OpenInfoIndex
= 0; OpenInfoIndex
< OpenInfoCount
; OpenInfoIndex
++) {
910 if (OpenInfo
[OpenInfoIndex
].AgentHandle
== Image
->Handle
) {
911 Status
= CoreCloseProtocol (
912 HandleBuffer
[HandleIndex
],
913 ProtocolGuidArray
[ProtocolIndex
],
915 OpenInfo
[OpenInfoIndex
].ControllerHandle
919 if (OpenInfo
!= NULL
) {
920 CoreFreePool(OpenInfo
);
924 if (ProtocolGuidArray
!= NULL
) {
925 CoreFreePool(ProtocolGuidArray
);
929 if (HandleBuffer
!= NULL
) {
930 CoreFreePool (HandleBuffer
);
934 CoreRemoveDebugImageInfoEntry (Image
->Handle
);
936 Status
= CoreUninstallProtocolInterface (
938 &gEfiLoadedImageDevicePathProtocolGuid
,
939 Image
->LoadedImageDevicePath
942 Status
= CoreUninstallProtocolInterface (
944 &gEfiLoadedImageProtocolGuid
,
948 if (Image
->ImageContext
.HiiResourceData
!= 0) {
949 Status
= CoreUninstallProtocolInterface (
951 &gEfiHiiPackageListProtocolGuid
,
952 (VOID
*) (UINTN
) Image
->ImageContext
.HiiResourceData
958 if (Image
->RuntimeData
!= NULL
) {
959 if (Image
->RuntimeData
->Link
.ForwardLink
!= NULL
) {
961 // Remove the Image from the Runtime Image list as we are about to Free it!
963 RemoveEntryList (&Image
->RuntimeData
->Link
);
964 RemoveImageRecord (Image
->RuntimeData
);
966 CoreFreePool (Image
->RuntimeData
);
970 // Free the Image from memory
972 if ((Image
->ImageBasePage
!= 0) && FreePage
) {
973 CoreFreePages (Image
->ImageBasePage
, Image
->NumberOfPages
);
977 // Done with the Image structure
979 if (Image
->Info
.FilePath
!= NULL
) {
980 CoreFreePool (Image
->Info
.FilePath
);
983 if (Image
->LoadedImageDevicePath
!= NULL
) {
984 CoreFreePool (Image
->LoadedImageDevicePath
);
987 if (Image
->FixupData
!= NULL
) {
988 CoreFreePool (Image
->FixupData
);
991 CoreFreePool (Image
);
996 Loads an EFI image into memory and returns a handle to the image.
998 @param BootPolicy If TRUE, indicates that the request originates
999 from the boot manager, and that the boot
1000 manager is attempting to load FilePath as a
1002 @param ParentImageHandle The caller's image handle.
1003 @param FilePath The specific file path from which the image is
1005 @param SourceBuffer If not NULL, a pointer to the memory location
1006 containing a copy of the image to be loaded.
1007 @param SourceSize The size in bytes of SourceBuffer.
1008 @param DstBuffer The buffer to store the image
1009 @param NumberOfPages If not NULL, it inputs a pointer to the page
1010 number of DstBuffer and outputs a pointer to
1011 the page number of the image. If this number is
1012 not enough, return EFI_BUFFER_TOO_SMALL and
1013 this parameter contains the required number.
1014 @param ImageHandle Pointer to the returned image handle that is
1015 created when the image is successfully loaded.
1016 @param EntryPoint A pointer to the entry point
1017 @param Attribute The bit mask of attributes to set for the load
1020 @retval EFI_SUCCESS The image was loaded into memory.
1021 @retval EFI_NOT_FOUND The FilePath was not found.
1022 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
1023 @retval EFI_BUFFER_TOO_SMALL The buffer is too small
1024 @retval EFI_UNSUPPORTED The image type is not supported, or the device
1025 path cannot be parsed to locate the proper
1026 protocol for loading the file.
1027 @retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient
1029 @retval EFI_LOAD_ERROR Image was not loaded because the image format was corrupt or not
1031 @retval EFI_DEVICE_ERROR Image was not loaded because the device returned a read error.
1032 @retval EFI_ACCESS_DENIED Image was not loaded because the platform policy prohibits the
1033 image from being loaded. NULL is returned in *ImageHandle.
1034 @retval EFI_SECURITY_VIOLATION Image was loaded and an ImageHandle was created with a
1035 valid EFI_LOADED_IMAGE_PROTOCOL. However, the current
1036 platform policy specifies that the image should not be started.
1040 CoreLoadImageCommon (
1041 IN BOOLEAN BootPolicy
,
1042 IN EFI_HANDLE ParentImageHandle
,
1043 IN EFI_DEVICE_PATH_PROTOCOL
*FilePath
,
1044 IN VOID
*SourceBuffer OPTIONAL
,
1045 IN UINTN SourceSize
,
1046 IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL
,
1047 IN OUT UINTN
*NumberOfPages OPTIONAL
,
1048 OUT EFI_HANDLE
*ImageHandle
,
1049 OUT EFI_PHYSICAL_ADDRESS
*EntryPoint OPTIONAL
,
1053 LOADED_IMAGE_PRIVATE_DATA
*Image
;
1054 LOADED_IMAGE_PRIVATE_DATA
*ParentImage
;
1055 IMAGE_FILE_HANDLE FHand
;
1057 EFI_STATUS SecurityStatus
;
1058 EFI_HANDLE DeviceHandle
;
1059 UINT32 AuthenticationStatus
;
1060 EFI_DEVICE_PATH_PROTOCOL
*OriginalFilePath
;
1061 EFI_DEVICE_PATH_PROTOCOL
*HandleFilePath
;
1062 EFI_DEVICE_PATH_PROTOCOL
*InputFilePath
;
1063 EFI_DEVICE_PATH_PROTOCOL
*Node
;
1065 BOOLEAN ImageIsFromFv
;
1066 BOOLEAN ImageIsFromLoadFile
;
1068 SecurityStatus
= EFI_SUCCESS
;
1070 ASSERT (gEfiCurrentTpl
< TPL_NOTIFY
);
1074 // The caller must pass in a valid ParentImageHandle
1076 if (ImageHandle
== NULL
|| ParentImageHandle
== NULL
) {
1077 return EFI_INVALID_PARAMETER
;
1080 ParentImage
= CoreLoadedImageInfo (ParentImageHandle
);
1081 if (ParentImage
== NULL
) {
1082 DEBUG((DEBUG_LOAD
|DEBUG_ERROR
, "LoadImageEx: Parent handle not an image handle\n"));
1083 return EFI_INVALID_PARAMETER
;
1086 ZeroMem (&FHand
, sizeof (IMAGE_FILE_HANDLE
));
1087 FHand
.Signature
= IMAGE_FILE_HANDLE_SIGNATURE
;
1088 OriginalFilePath
= FilePath
;
1089 InputFilePath
= FilePath
;
1090 HandleFilePath
= FilePath
;
1091 DeviceHandle
= NULL
;
1092 Status
= EFI_SUCCESS
;
1093 AuthenticationStatus
= 0;
1094 ImageIsFromFv
= FALSE
;
1095 ImageIsFromLoadFile
= FALSE
;
1098 // If the caller passed a copy of the file, then just use it
1100 if (SourceBuffer
!= NULL
) {
1101 FHand
.Source
= SourceBuffer
;
1102 FHand
.SourceSize
= SourceSize
;
1103 Status
= CoreLocateDevicePath (&gEfiDevicePathProtocolGuid
, &HandleFilePath
, &DeviceHandle
);
1104 if (EFI_ERROR (Status
)) {
1105 DeviceHandle
= NULL
;
1107 if (SourceSize
> 0) {
1108 Status
= EFI_SUCCESS
;
1110 Status
= EFI_LOAD_ERROR
;
1113 if (FilePath
== NULL
) {
1114 return EFI_INVALID_PARAMETER
;
1118 // Try to get the image device handle by checking the match protocol.
1121 Status
= CoreLocateDevicePath (&gEfiFirmwareVolume2ProtocolGuid
, &HandleFilePath
, &DeviceHandle
);
1122 if (!EFI_ERROR (Status
)) {
1123 ImageIsFromFv
= TRUE
;
1125 HandleFilePath
= FilePath
;
1126 Status
= CoreLocateDevicePath (&gEfiSimpleFileSystemProtocolGuid
, &HandleFilePath
, &DeviceHandle
);
1127 if (EFI_ERROR (Status
)) {
1129 HandleFilePath
= FilePath
;
1130 Status
= CoreLocateDevicePath (&gEfiLoadFile2ProtocolGuid
, &HandleFilePath
, &DeviceHandle
);
1132 if (EFI_ERROR (Status
)) {
1133 HandleFilePath
= FilePath
;
1134 Status
= CoreLocateDevicePath (&gEfiLoadFileProtocolGuid
, &HandleFilePath
, &DeviceHandle
);
1135 if (!EFI_ERROR (Status
)) {
1136 ImageIsFromLoadFile
= TRUE
;
1137 Node
= HandleFilePath
;
1144 // Get the source file buffer by its device path.
1146 FHand
.Source
= GetFileBufferByFilePath (
1150 &AuthenticationStatus
1152 if (FHand
.Source
== NULL
) {
1153 Status
= EFI_NOT_FOUND
;
1155 FHand
.FreeBuffer
= TRUE
;
1156 if (ImageIsFromLoadFile
) {
1158 // LoadFile () may cause the device path of the Handle be updated.
1160 OriginalFilePath
= AppendDevicePath (DevicePathFromHandle (DeviceHandle
), Node
);
1165 if (EFI_ERROR (Status
)) {
1170 if (gSecurity2
!= NULL
) {
1172 // Verify File Authentication through the Security2 Architectural Protocol
1174 SecurityStatus
= gSecurity2
->FileAuthentication (
1181 if (!EFI_ERROR (SecurityStatus
) && ImageIsFromFv
) {
1183 // When Security2 is installed, Security Architectural Protocol must be published.
1185 ASSERT (gSecurity
!= NULL
);
1188 // Verify the Authentication Status through the Security Architectural Protocol
1189 // Only on images that have been read using Firmware Volume protocol.
1191 SecurityStatus
= gSecurity
->FileAuthenticationState (
1193 AuthenticationStatus
,
1197 } else if ((gSecurity
!= NULL
) && (OriginalFilePath
!= NULL
)) {
1199 // Verify the Authentication Status through the Security Architectural Protocol
1201 SecurityStatus
= gSecurity
->FileAuthenticationState (
1203 AuthenticationStatus
,
1209 // Check Security Status.
1211 if (EFI_ERROR (SecurityStatus
) && SecurityStatus
!= EFI_SECURITY_VIOLATION
) {
1212 if (SecurityStatus
== EFI_ACCESS_DENIED
) {
1214 // Image was not loaded because the platform policy prohibits the image from being loaded.
1215 // It's the only place we could meet EFI_ACCESS_DENIED.
1217 *ImageHandle
= NULL
;
1219 Status
= SecurityStatus
;
1225 // Allocate a new image structure
1227 Image
= AllocateZeroPool (sizeof(LOADED_IMAGE_PRIVATE_DATA
));
1228 if (Image
== NULL
) {
1229 Status
= EFI_OUT_OF_RESOURCES
;
1234 // Pull out just the file portion of the DevicePath for the LoadedImage FilePath
1236 FilePath
= OriginalFilePath
;
1237 if (DeviceHandle
!= NULL
) {
1238 Status
= CoreHandleProtocol (DeviceHandle
, &gEfiDevicePathProtocolGuid
, (VOID
**)&HandleFilePath
);
1239 if (!EFI_ERROR (Status
)) {
1240 FilePathSize
= GetDevicePathSize (HandleFilePath
) - sizeof(EFI_DEVICE_PATH_PROTOCOL
);
1241 FilePath
= (EFI_DEVICE_PATH_PROTOCOL
*) (((UINT8
*)FilePath
) + FilePathSize
);
1245 // Initialize the fields for an internal driver
1247 Image
->Signature
= LOADED_IMAGE_PRIVATE_DATA_SIGNATURE
;
1248 Image
->Info
.SystemTable
= gDxeCoreST
;
1249 Image
->Info
.DeviceHandle
= DeviceHandle
;
1250 Image
->Info
.Revision
= EFI_LOADED_IMAGE_PROTOCOL_REVISION
;
1251 Image
->Info
.FilePath
= DuplicateDevicePath (FilePath
);
1252 Image
->Info
.ParentHandle
= ParentImageHandle
;
1255 if (NumberOfPages
!= NULL
) {
1256 Image
->NumberOfPages
= *NumberOfPages
;
1258 Image
->NumberOfPages
= 0 ;
1262 // Install the protocol interfaces for this image
1263 // don't fire notifications yet
1265 Status
= CoreInstallProtocolInterfaceNotify (
1267 &gEfiLoadedImageProtocolGuid
,
1268 EFI_NATIVE_INTERFACE
,
1272 if (EFI_ERROR (Status
)) {
1277 // Load the image. If EntryPoint is Null, it will not be set.
1279 Status
= CoreLoadPeImage (BootPolicy
, &FHand
, Image
, DstBuffer
, EntryPoint
, Attribute
);
1280 if (EFI_ERROR (Status
)) {
1281 if ((Status
== EFI_BUFFER_TOO_SMALL
) || (Status
== EFI_OUT_OF_RESOURCES
)) {
1282 if (NumberOfPages
!= NULL
) {
1283 *NumberOfPages
= Image
->NumberOfPages
;
1289 if (NumberOfPages
!= NULL
) {
1290 *NumberOfPages
= Image
->NumberOfPages
;
1294 // Register the image in the Debug Image Info Table if the attribute is set
1296 if ((Attribute
& EFI_LOAD_PE_IMAGE_ATTRIBUTE_DEBUG_IMAGE_INFO_TABLE_REGISTRATION
) != 0) {
1297 CoreNewDebugImageInfoEntry (EFI_DEBUG_IMAGE_INFO_TYPE_NORMAL
, &Image
->Info
, Image
->Handle
);
1301 //Reinstall loaded image protocol to fire any notifications
1303 Status
= CoreReinstallProtocolInterface (
1305 &gEfiLoadedImageProtocolGuid
,
1309 if (EFI_ERROR (Status
)) {
1314 // If DevicePath parameter to the LoadImage() is not NULL, then make a copy of DevicePath,
1315 // otherwise Loaded Image Device Path Protocol is installed with a NULL interface pointer.
1317 if (OriginalFilePath
!= NULL
) {
1318 Image
->LoadedImageDevicePath
= DuplicateDevicePath (OriginalFilePath
);
1322 // Install Loaded Image Device Path Protocol onto the image handle of a PE/COFE image
1324 Status
= CoreInstallProtocolInterface (
1326 &gEfiLoadedImageDevicePathProtocolGuid
,
1327 EFI_NATIVE_INTERFACE
,
1328 Image
->LoadedImageDevicePath
1330 if (EFI_ERROR (Status
)) {
1335 // Install HII Package List Protocol onto the image handle
1337 if (Image
->ImageContext
.HiiResourceData
!= 0) {
1338 Status
= CoreInstallProtocolInterface (
1340 &gEfiHiiPackageListProtocolGuid
,
1341 EFI_NATIVE_INTERFACE
,
1342 (VOID
*) (UINTN
) Image
->ImageContext
.HiiResourceData
1344 if (EFI_ERROR (Status
)) {
1348 ProtectUefiImage (&Image
->Info
, Image
->LoadedImageDevicePath
);
1351 // Success. Return the image handle
1353 *ImageHandle
= Image
->Handle
;
1357 // All done accessing the source file
1358 // If we allocated the Source buffer, free it
1360 if (FHand
.FreeBuffer
) {
1361 CoreFreePool (FHand
.Source
);
1363 if (OriginalFilePath
!= InputFilePath
) {
1364 CoreFreePool (OriginalFilePath
);
1368 // There was an error. If there's an Image structure, free it
1370 if (EFI_ERROR (Status
)) {
1371 if (Image
!= NULL
) {
1372 CoreUnloadAndCloseImage (Image
, (BOOLEAN
)(DstBuffer
== 0));
1375 } else if (EFI_ERROR (SecurityStatus
)) {
1376 Status
= SecurityStatus
;
1380 // Track the return status from LoadImage.
1382 if (Image
!= NULL
) {
1383 Image
->LoadImageStatus
= Status
;
1393 Loads an EFI image into memory and returns a handle to the image.
1395 @param BootPolicy If TRUE, indicates that the request originates
1396 from the boot manager, and that the boot
1397 manager is attempting to load FilePath as a
1399 @param ParentImageHandle The caller's image handle.
1400 @param FilePath The specific file path from which the image is
1402 @param SourceBuffer If not NULL, a pointer to the memory location
1403 containing a copy of the image to be loaded.
1404 @param SourceSize The size in bytes of SourceBuffer.
1405 @param ImageHandle Pointer to the returned image handle that is
1406 created when the image is successfully loaded.
1408 @retval EFI_SUCCESS The image was loaded into memory.
1409 @retval EFI_NOT_FOUND The FilePath was not found.
1410 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
1411 @retval EFI_UNSUPPORTED The image type is not supported, or the device
1412 path cannot be parsed to locate the proper
1413 protocol for loading the file.
1414 @retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient
1416 @retval EFI_LOAD_ERROR Image was not loaded because the image format was corrupt or not
1418 @retval EFI_DEVICE_ERROR Image was not loaded because the device returned a read error.
1419 @retval EFI_ACCESS_DENIED Image was not loaded because the platform policy prohibits the
1420 image from being loaded. NULL is returned in *ImageHandle.
1421 @retval EFI_SECURITY_VIOLATION Image was loaded and an ImageHandle was created with a
1422 valid EFI_LOADED_IMAGE_PROTOCOL. However, the current
1423 platform policy specifies that the image should not be started.
1429 IN BOOLEAN BootPolicy
,
1430 IN EFI_HANDLE ParentImageHandle
,
1431 IN EFI_DEVICE_PATH_PROTOCOL
*FilePath
,
1432 IN VOID
*SourceBuffer OPTIONAL
,
1433 IN UINTN SourceSize
,
1434 OUT EFI_HANDLE
*ImageHandle
1443 Tick
= GetPerformanceCounter ();
1446 Status
= CoreLoadImageCommon (
1452 (EFI_PHYSICAL_ADDRESS
) (UINTN
) NULL
,
1456 EFI_LOAD_PE_IMAGE_ATTRIBUTE_RUNTIME_REGISTRATION
| EFI_LOAD_PE_IMAGE_ATTRIBUTE_DEBUG_IMAGE_INFO_TABLE_REGISTRATION
1460 if (!EFI_ERROR (Status
)) {
1462 // ImageHandle will be valid only Status is success.
1464 Handle
= *ImageHandle
;
1467 PERF_START (Handle
, "LoadImage:", NULL
, Tick
);
1468 PERF_END (Handle
, "LoadImage:", NULL
, 0);
1476 Loads an EFI image into memory and returns a handle to the image with extended parameters.
1478 @param This Calling context
1479 @param ParentImageHandle The caller's image handle.
1480 @param FilePath The specific file path from which the image is
1482 @param SourceBuffer If not NULL, a pointer to the memory location
1483 containing a copy of the image to be loaded.
1484 @param SourceSize The size in bytes of SourceBuffer.
1485 @param DstBuffer The buffer to store the image.
1486 @param NumberOfPages For input, specifies the space size of the
1487 image by caller if not NULL. For output,
1488 specifies the actual space size needed.
1489 @param ImageHandle Image handle for output.
1490 @param EntryPoint Image entry point for output.
1491 @param Attribute The bit mask of attributes to set for the load
1494 @retval EFI_SUCCESS The image was loaded into memory.
1495 @retval EFI_NOT_FOUND The FilePath was not found.
1496 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
1497 @retval EFI_UNSUPPORTED The image type is not supported, or the device
1498 path cannot be parsed to locate the proper
1499 protocol for loading the file.
1500 @retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient
1502 @retval EFI_LOAD_ERROR Image was not loaded because the image format was corrupt or not
1504 @retval EFI_DEVICE_ERROR Image was not loaded because the device returned a read error.
1505 @retval EFI_ACCESS_DENIED Image was not loaded because the platform policy prohibits the
1506 image from being loaded. NULL is returned in *ImageHandle.
1507 @retval EFI_SECURITY_VIOLATION Image was loaded and an ImageHandle was created with a
1508 valid EFI_LOADED_IMAGE_PROTOCOL. However, the current
1509 platform policy specifies that the image should not be started.
1515 IN EFI_PE32_IMAGE_PROTOCOL
*This
,
1516 IN EFI_HANDLE ParentImageHandle
,
1517 IN EFI_DEVICE_PATH_PROTOCOL
*FilePath
,
1518 IN VOID
*SourceBuffer OPTIONAL
,
1519 IN UINTN SourceSize
,
1520 IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL
,
1521 OUT UINTN
*NumberOfPages OPTIONAL
,
1522 OUT EFI_HANDLE
*ImageHandle
,
1523 OUT EFI_PHYSICAL_ADDRESS
*EntryPoint OPTIONAL
,
1533 Tick
= GetPerformanceCounter ();
1536 Status
= CoreLoadImageCommon (
1550 if (!EFI_ERROR (Status
)) {
1552 // ImageHandle will be valid only Status is success.
1554 Handle
= *ImageHandle
;
1557 PERF_START (Handle
, "LoadImage:", NULL
, Tick
);
1558 PERF_END (Handle
, "LoadImage:", NULL
, 0);
1565 Transfer control to a loaded image's entry point.
1567 @param ImageHandle Handle of image to be started.
1568 @param ExitDataSize Pointer of the size to ExitData
1569 @param ExitData Pointer to a pointer to a data buffer that
1570 includes a Null-terminated string,
1571 optionally followed by additional binary data.
1572 The string is a description that the caller may
1573 use to further indicate the reason for the
1576 @retval EFI_INVALID_PARAMETER Invalid parameter
1577 @retval EFI_OUT_OF_RESOURCES No enough buffer to allocate
1578 @retval EFI_SECURITY_VIOLATION The current platform policy specifies that the image should not be started.
1579 @retval EFI_SUCCESS Successfully transfer control to the image's
1586 IN EFI_HANDLE ImageHandle
,
1587 OUT UINTN
*ExitDataSize
,
1588 OUT CHAR16
**ExitData OPTIONAL
1592 LOADED_IMAGE_PRIVATE_DATA
*Image
;
1593 LOADED_IMAGE_PRIVATE_DATA
*LastImage
;
1594 UINT64 HandleDatabaseKey
;
1600 Handle
= ImageHandle
;
1602 Image
= CoreLoadedImageInfo (ImageHandle
);
1603 if (Image
== NULL
|| Image
->Started
) {
1604 return EFI_INVALID_PARAMETER
;
1606 if (EFI_ERROR (Image
->LoadImageStatus
)) {
1607 return Image
->LoadImageStatus
;
1611 // The image to be started must have the machine type supported by DxeCore.
1613 if (!EFI_IMAGE_MACHINE_TYPE_SUPPORTED (Image
->Machine
)) {
1615 // Do not ASSERT here, because image might be loaded via EFI_IMAGE_MACHINE_CROSS_TYPE_SUPPORTED
1616 // But it can not be started.
1618 DEBUG ((EFI_D_ERROR
, "Image type %s can't be started ", GetMachineTypeName(Image
->Machine
)));
1619 DEBUG ((EFI_D_ERROR
, "on %s UEFI system.\n", GetMachineTypeName(mDxeCoreImageMachineType
)));
1620 return EFI_UNSUPPORTED
;
1624 Tick
= GetPerformanceCounter ();
1629 // Push the current start image context, and
1630 // link the current image to the head. This is the
1631 // only image that can call Exit()
1633 HandleDatabaseKey
= CoreGetHandleDatabaseKey ();
1634 LastImage
= mCurrentImage
;
1635 mCurrentImage
= Image
;
1636 Image
->Tpl
= gEfiCurrentTpl
;
1639 // Set long jump for Exit() support
1640 // JumpContext must be aligned on a CPU specific boundary.
1641 // Overallocate the buffer and force the required alignment
1643 Image
->JumpBuffer
= AllocatePool (sizeof (BASE_LIBRARY_JUMP_BUFFER
) + BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT
);
1644 if (Image
->JumpBuffer
== NULL
) {
1646 // Image may be unloaded after return with failure,
1647 // then ImageHandle may be invalid, so use NULL handle to record perf log.
1649 PERF_START (NULL
, "StartImage:", NULL
, Tick
);
1650 PERF_END (NULL
, "StartImage:", NULL
, 0);
1651 return EFI_OUT_OF_RESOURCES
;
1653 Image
->JumpContext
= ALIGN_POINTER (Image
->JumpBuffer
, BASE_LIBRARY_JUMP_BUFFER_ALIGNMENT
);
1655 SetJumpFlag
= SetJump (Image
->JumpContext
);
1657 // The initial call to SetJump() must always return 0.
1658 // Subsequent calls to LongJump() cause a non-zero value to be returned by SetJump().
1660 if (SetJumpFlag
== 0) {
1661 RegisterMemoryProfileImage (Image
, (Image
->ImageContext
.ImageType
== EFI_IMAGE_SUBSYSTEM_EFI_APPLICATION
? EFI_FV_FILETYPE_APPLICATION
: EFI_FV_FILETYPE_DRIVER
));
1663 // Call the image's entry point
1665 Image
->Started
= TRUE
;
1666 Image
->Status
= Image
->EntryPoint (ImageHandle
, Image
->Info
.SystemTable
);
1669 // Add some debug information if the image returned with error.
1670 // This make the user aware and check if the driver image have already released
1671 // all the resource in this situation.
1673 DEBUG_CODE_BEGIN ();
1674 if (EFI_ERROR (Image
->Status
)) {
1675 DEBUG ((DEBUG_ERROR
, "Error: Image at %11p start failed: %r\n", Image
->Info
.ImageBase
, Image
->Status
));
1680 // If the image returns, exit it through Exit()
1682 CoreExit (ImageHandle
, Image
->Status
, 0, NULL
);
1686 // Image has completed. Verify the tpl is the same
1688 ASSERT (Image
->Tpl
== gEfiCurrentTpl
);
1689 CoreRestoreTpl (Image
->Tpl
);
1691 CoreFreePool (Image
->JumpBuffer
);
1694 // Pop the current start image context
1696 mCurrentImage
= LastImage
;
1699 // Go connect any handles that were created or modified while the image executed.
1701 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 (Handle
, "StartImage:", NULL
, Tick
);
1752 PERF_END (Handle
, "StartImage:", NULL
, 0);
1757 Terminates the currently loaded EFI image and returns control to boot services.
1759 @param ImageHandle Handle that identifies the image. This
1760 parameter is passed to the image on entry.
1761 @param Status The image's exit code.
1762 @param ExitDataSize The size, in bytes, of ExitData. Ignored if
1763 ExitStatus is EFI_SUCCESS.
1764 @param ExitData Pointer to a data buffer that includes a
1765 Null-terminated Unicode string, optionally
1766 followed by additional binary data. The string
1767 is a description that the caller may use to
1768 further indicate the reason for the image's
1771 @retval EFI_INVALID_PARAMETER Image handle is NULL or it is not current
1773 @retval EFI_SUCCESS Successfully terminates the currently loaded
1775 @retval EFI_ACCESS_DENIED Should never reach there.
1776 @retval EFI_OUT_OF_RESOURCES Could not allocate pool
1782 IN EFI_HANDLE ImageHandle
,
1783 IN EFI_STATUS Status
,
1784 IN UINTN ExitDataSize
,
1785 IN CHAR16
*ExitData OPTIONAL
1788 LOADED_IMAGE_PRIVATE_DATA
*Image
;
1792 // Prevent possible reentrance to this function
1793 // for the same ImageHandle
1795 OldTpl
= CoreRaiseTpl (TPL_NOTIFY
);
1797 Image
= CoreLoadedImageInfo (ImageHandle
);
1798 if (Image
== NULL
) {
1799 Status
= EFI_INVALID_PARAMETER
;
1803 if (!Image
->Started
) {
1805 // The image has not been started so just free its resources
1807 CoreUnloadAndCloseImage (Image
, TRUE
);
1808 Status
= EFI_SUCCESS
;
1813 // Image has been started, verify this image can exit
1815 if (Image
!= mCurrentImage
) {
1816 DEBUG ((DEBUG_LOAD
|DEBUG_ERROR
, "Exit: Image is not exitable image\n"));
1817 Status
= EFI_INVALID_PARAMETER
;
1824 Image
->Status
= Status
;
1827 // If there's ExitData info, move it
1829 if (ExitData
!= NULL
) {
1830 Image
->ExitDataSize
= ExitDataSize
;
1831 Image
->ExitData
= AllocatePool (Image
->ExitDataSize
);
1832 if (Image
->ExitData
== NULL
) {
1833 Status
= EFI_OUT_OF_RESOURCES
;
1836 CopyMem (Image
->ExitData
, ExitData
, Image
->ExitDataSize
);
1839 CoreRestoreTpl (OldTpl
);
1841 // return to StartImage
1843 LongJump (Image
->JumpContext
, (UINTN
)-1);
1846 // If we return from LongJump, then it is an error
1849 Status
= EFI_ACCESS_DENIED
;
1851 CoreRestoreTpl (OldTpl
);
1861 @param ImageHandle Handle that identifies the image to be
1864 @retval EFI_SUCCESS The image has been unloaded.
1865 @retval EFI_UNSUPPORTED The image has been started, and does not support
1867 @retval EFI_INVALID_PARAMPETER ImageHandle is not a valid image handle.
1873 IN EFI_HANDLE ImageHandle
1877 LOADED_IMAGE_PRIVATE_DATA
*Image
;
1879 Image
= CoreLoadedImageInfo (ImageHandle
);
1880 if (Image
== NULL
) {
1882 // The image handle is not valid
1884 Status
= EFI_INVALID_PARAMETER
;
1888 if (Image
->Started
) {
1890 // The image has been started, request it to unload.
1892 Status
= EFI_UNSUPPORTED
;
1893 if (Image
->Info
.Unload
!= NULL
) {
1894 Status
= Image
->Info
.Unload (ImageHandle
);
1899 // This Image hasn't been started, thus it can be unloaded
1901 Status
= EFI_SUCCESS
;
1905 if (!EFI_ERROR (Status
)) {
1907 // if the Image was not started or Unloaded O.K. then clean up
1909 CoreUnloadAndCloseImage (Image
, TRUE
);
1919 Unload the specified image.
1921 @param This Indicates the calling context.
1922 @param ImageHandle The specified image handle.
1924 @retval EFI_INVALID_PARAMETER Image handle is NULL.
1925 @retval EFI_UNSUPPORTED Attempt to unload an unsupported image.
1926 @retval EFI_SUCCESS Image successfully unloaded.
1932 IN EFI_PE32_IMAGE_PROTOCOL
*This
,
1933 IN EFI_HANDLE ImageHandle
1936 return CoreUnloadImage (ImageHandle
);