3 Data structure and functions to load and unload PeImage.
5 Copyright (c) 2006 - 2008, Intel Corporation
6 All rights reserved. This program and the accompanying materials
7 are licensed and made available under the terms and conditions of the BSD License
8 which accompanies this distribution. The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
22 #define LOADED_IMAGE_PRIVATE_DATA_SIGNATURE EFI_SIGNATURE_32('l','d','r','i')
26 EFI_HANDLE Handle
; // Image handle
27 UINTN Type
; // Image type
29 BOOLEAN Started
; // If entrypoint has been called
31 EFI_IMAGE_ENTRY_POINT EntryPoint
; // The image's entry point
32 EFI_LOADED_IMAGE_PROTOCOL Info
; // loaded image protocol
34 EFI_PHYSICAL_ADDRESS ImageBasePage
; // Location in memory
35 UINTN NumberOfPages
; // Number of pages
37 CHAR8
*FixupData
; // Original fixup data
39 EFI_TPL Tpl
; // Tpl of started image
40 EFI_STATUS Status
; // Status returned by started image
42 UINTN ExitDataSize
; // Size of ExitData from started image
43 VOID
*ExitData
; // Pointer to exit data from started image
44 VOID
*JumpBuffer
; // Pointer to pool allocation for context save/retore
45 BASE_LIBRARY_JUMP_BUFFER
*JumpContext
; // Pointer to buffer for context save/retore
46 UINT16 Machine
; // Machine type from PE image
48 EFI_EBC_PROTOCOL
*Ebc
; // EBC Protocol pointer
50 EFI_RUNTIME_IMAGE_ENTRY
*RuntimeData
; // Runtime image list
52 EFI_DEVICE_PATH_PROTOCOL
*LoadedImageDevicePath
; // Pointer to Loaded Image Device Path Protocl
54 PE_COFF_LOADER_IMAGE_CONTEXT ImageContext
; // PeCoffLoader ImageContext
56 } LOADED_IMAGE_PRIVATE_DATA
;
58 #define LOADED_IMAGE_PRIVATE_DATA_FROM_THIS(a) \
59 CR(a, LOADED_IMAGE_PRIVATE_DATA, Info, LOADED_IMAGE_PRIVATE_DATA_SIGNATURE)
63 #define LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE EFI_SIGNATURE_32('l','p','e','i')
67 EFI_HANDLE Handle
; // Image handle
68 EFI_PE32_IMAGE_PROTOCOL Pe32Image
;
69 } LOAD_PE32_IMAGE_PRIVATE_DATA
;
71 #define LOAD_PE32_IMAGE_PRIVATE_DATA_FROM_THIS(a) \
72 CR(a, LOAD_PE32_IMAGE_PRIVATE_DATA, Pe32Image, LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE)
79 #define IMAGE_FILE_HANDLE_SIGNATURE EFI_SIGNATURE_32('i','m','g','f')
89 // Abstractions for reading image contents
94 Opens a file for (simple) reading. The simple read abstraction
95 will access the file either from a memory copy, from a file
96 system interface, or from the load file interface.
98 @param BootPolicy Policy for Open Image File.
99 @param SourceBuffer Pointer to the memory location containing copy
100 of the image to be loaded.
101 @param SourceSize The size in bytes of SourceBuffer.
102 @param FilePath The specific file path from which the image is
104 @param DeviceHandle Pointer to the return device handle.
105 @param ImageFileHandle Pointer to the image file handle.
106 @param AuthenticationStatus Pointer to a caller-allocated UINT32 in which
107 the authentication status is returned.
109 @retval EFI_SUCCESS Image file successfully opened.
110 @retval EFI_LOAD_ERROR If the caller passed a copy of the file, and
112 @retval EFI_INVALID_PARAMETER File path is not valid.
113 @retval EFI_NOT_FOUND File not found.
118 IN BOOLEAN BootPolicy
,
119 IN VOID
*SourceBuffer OPTIONAL
,
121 IN OUT EFI_DEVICE_PATH_PROTOCOL
**FilePath
,
122 OUT EFI_HANDLE
*DeviceHandle
,
123 IN IMAGE_FILE_HANDLE
*ImageFileHandle
,
124 OUT UINT32
*AuthenticationStatus
131 Read image file (specified by UserHandle) into user specified buffer with specified offset
134 @param UserHandle Image file handle
135 @param Offset Offset to the source file
136 @param ReadSize For input, pointer of size to read; For output,
137 pointer of size actually read.
138 @param Buffer Buffer to write into
140 @retval EFI_SUCCESS Successfully read the specified part of file
149 IN OUT UINTN
*ReadSize
,
156 A function out of date, should be removed.
158 @param ImageFileHandle Handle of the file to close
164 IN IMAGE_FILE_HANDLE
*ImageFileHandle
169 // Image processing worker functions
173 Search a handle to a device on a specified device path that supports a specified protocol,
174 interface of that protocol on that handle is another output.
176 @param Protocol The protocol to search for
177 @param FilePath The specified device path
178 @param Interface Interface of the protocol on the handle
179 @param Handle The handle to the device on the specified device
180 path that supports the protocol.
186 CoreDevicePathToInterface (
187 IN EFI_GUID
*Protocol
,
188 IN OUT EFI_DEVICE_PATH_PROTOCOL
**FilePath
,
189 OUT VOID
**Interface
,
190 OUT EFI_HANDLE
*Handle
196 Loads, relocates, and invokes a PE/COFF image
198 @param BootPolicy If TRUE, indicates that the request originates
199 from the boot manager, and that the boot
200 manager is attempting to load FilePath as a
202 @param Pe32Handle The handle of PE32 image
203 @param Image PE image to be loaded
204 @param DstBuffer The buffer to store the image
205 @param EntryPoint A pointer to the entry point
206 @param Attribute The bit mask of attributes to set for the load
209 @retval EFI_SUCCESS The file was loaded, relocated, and invoked
210 @retval EFI_OUT_OF_RESOURCES There was not enough memory to load and
211 relocate the PE/COFF file
212 @retval EFI_INVALID_PARAMETER Invalid parameter
213 @retval EFI_BUFFER_TOO_SMALL Buffer for image is too small
218 IN BOOLEAN BootPolicy
,
220 IN LOADED_IMAGE_PRIVATE_DATA
*Image
,
221 IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL
,
222 OUT EFI_PHYSICAL_ADDRESS
*EntryPoint OPTIONAL
,
229 Get the image's private data from its handle.
231 @param ImageHandle The image handle
233 @return Return the image private data associated with ImageHandle.
236 LOADED_IMAGE_PRIVATE_DATA
*
237 CoreLoadedImageInfo (
238 IN EFI_HANDLE ImageHandle
244 Unloads EFI image from memory.
246 @param Image EFI image
247 @param FreePage Free allocated pages
251 CoreUnloadAndCloseImage (
252 IN LOADED_IMAGE_PRIVATE_DATA
*Image
,
259 // Exported Image functions
264 Loads an EFI image into memory and returns a handle to the image with extended parameters.
266 @param This Calling context
267 @param ParentImageHandle The caller's image handle.
268 @param FilePath The specific file path from which the image is
270 @param SourceBuffer If not NULL, a pointer to the memory location
271 containing a copy of the image to be loaded.
272 @param SourceSize The size in bytes of SourceBuffer.
273 @param DstBuffer The buffer to store the image.
274 @param NumberOfPages For input, specifies the space size of the
275 image by caller if not NULL. For output,
276 specifies the actual space size needed.
277 @param ImageHandle Image handle for output.
278 @param EntryPoint Image entry point for output.
279 @param Attribute The bit mask of attributes to set for the load
282 @retval EFI_SUCCESS The image was loaded into memory.
283 @retval EFI_NOT_FOUND The FilePath was not found.
284 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
285 @retval EFI_UNSUPPORTED The image type is not supported, or the device
286 path cannot be parsed to locate the proper
287 protocol for loading the file.
288 @retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient
295 IN EFI_PE32_IMAGE_PROTOCOL
*This
,
296 IN EFI_HANDLE ParentImageHandle
,
297 IN EFI_DEVICE_PATH_PROTOCOL
*FilePath
,
298 IN VOID
*SourceBuffer OPTIONAL
,
300 IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL
,
301 OUT UINTN
*NumberOfPages OPTIONAL
,
302 OUT EFI_HANDLE
*ImageHandle
,
303 OUT EFI_PHYSICAL_ADDRESS
*EntryPoint OPTIONAL
,
310 Unload the specified image.
312 @param This Indicates the calling context.
313 @param ImageHandle The specified image handle.
315 @retval EFI_INVALID_PARAMETER Image handle is NULL.
316 @retval EFI_UNSUPPORTED Attempt to unload an unsupported image.
317 @retval EFI_SUCCESS Image successfully unloaded.
323 IN EFI_PE32_IMAGE_PROTOCOL
*This
,
324 IN EFI_HANDLE ImageHandle