2 Data structure and functions to load and unload PeImage.
4 Copyright (c) 2006 - 2008, Intel Corporation. <BR>
5 All rights reserved. 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 #define LOADED_IMAGE_PRIVATE_DATA_SIGNATURE EFI_SIGNATURE_32('l','d','r','i')
25 EFI_HANDLE Handle
; // Image handle
26 UINTN Type
; // Image type
28 BOOLEAN Started
; // If entrypoint has been called
30 EFI_IMAGE_ENTRY_POINT EntryPoint
; // The image's entry point
31 EFI_LOADED_IMAGE_PROTOCOL Info
; // loaded image protocol
33 EFI_PHYSICAL_ADDRESS ImageBasePage
; // Location in memory
34 UINTN NumberOfPages
; // Number of pages
36 CHAR8
*FixupData
; // Original fixup data
38 EFI_TPL Tpl
; // Tpl of started image
39 EFI_STATUS Status
; // Status returned by started image
41 UINTN ExitDataSize
; // Size of ExitData from started image
42 VOID
*ExitData
; // Pointer to exit data from started image
43 VOID
*JumpBuffer
; // Pointer to pool allocation for context save/retore
44 BASE_LIBRARY_JUMP_BUFFER
*JumpContext
; // Pointer to buffer for context save/retore
45 UINT16 Machine
; // Machine type from PE image
47 EFI_EBC_PROTOCOL
*Ebc
; // EBC Protocol pointer
49 EFI_RUNTIME_IMAGE_ENTRY
*RuntimeData
; // Runtime image list
51 EFI_DEVICE_PATH_PROTOCOL
*LoadedImageDevicePath
; // Pointer to Loaded Image Device Path Protocl
53 PE_COFF_LOADER_IMAGE_CONTEXT ImageContext
; // PeCoffLoader ImageContext
55 } LOADED_IMAGE_PRIVATE_DATA
;
57 #define LOADED_IMAGE_PRIVATE_DATA_FROM_THIS(a) \
58 CR(a, LOADED_IMAGE_PRIVATE_DATA, Info, LOADED_IMAGE_PRIVATE_DATA_SIGNATURE)
62 #define LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE EFI_SIGNATURE_32('l','p','e','i')
66 EFI_HANDLE Handle
; // Image handle
67 EFI_PE32_IMAGE_PROTOCOL Pe32Image
;
68 } LOAD_PE32_IMAGE_PRIVATE_DATA
;
70 #define LOAD_PE32_IMAGE_PRIVATE_DATA_FROM_THIS(a) \
71 CR(a, LOAD_PE32_IMAGE_PRIVATE_DATA, Pe32Image, LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE)
78 #define IMAGE_FILE_HANDLE_SIGNATURE EFI_SIGNATURE_32('i','m','g','f')
88 // Abstractions for reading image contents
93 Opens a file for (simple) reading. The simple read abstraction
94 will access the file either from a memory copy, from a file
95 system interface, or from the load file interface.
97 @param BootPolicy Policy for Open Image File.
98 @param SourceBuffer Pointer to the memory location containing copy
99 of the image to be loaded.
100 @param SourceSize The size in bytes of SourceBuffer.
101 @param FilePath The specific file path from which the image is
103 @param DeviceHandle Pointer to the return device handle.
104 @param ImageFileHandle Pointer to the image file handle.
105 @param AuthenticationStatus Pointer to a caller-allocated UINT32 in which
106 the authentication status is returned.
108 @retval EFI_SUCCESS Image file successfully opened.
109 @retval EFI_LOAD_ERROR If the caller passed a copy of the file, and
111 @retval EFI_INVALID_PARAMETER File path is not valid.
112 @retval EFI_NOT_FOUND File not found.
117 IN BOOLEAN BootPolicy
,
118 IN VOID
*SourceBuffer OPTIONAL
,
120 IN OUT EFI_DEVICE_PATH_PROTOCOL
**FilePath
,
121 OUT EFI_HANDLE
*DeviceHandle
,
122 IN IMAGE_FILE_HANDLE
*ImageFileHandle
,
123 OUT UINT32
*AuthenticationStatus
129 Read image file (specified by UserHandle) into user specified buffer with specified offset
132 @param UserHandle Image file handle
133 @param Offset Offset to the source file
134 @param ReadSize For input, pointer of size to read; For output,
135 pointer of size actually read.
136 @param Buffer Buffer to write into
138 @retval EFI_SUCCESS Successfully read the specified part of file
147 IN OUT UINTN
*ReadSize
,
153 A function out of date, should be removed.
155 @param ImageFileHandle Handle of the file to close
161 IN IMAGE_FILE_HANDLE
*ImageFileHandle
165 // Image processing worker functions
169 Search a handle to a device on a specified device path that supports a specified protocol,
170 interface of that protocol on that handle is another output.
172 @param Protocol The protocol to search for
173 @param FilePath The specified device path
174 @param Interface Interface of the protocol on the handle
175 @param Handle The handle to the device on the specified device
176 path that supports the protocol.
182 CoreDevicePathToInterface (
183 IN EFI_GUID
*Protocol
,
184 IN EFI_DEVICE_PATH_PROTOCOL
**FilePath
,
185 OUT VOID
**Interface
,
186 OUT EFI_HANDLE
*Handle
191 Loads, relocates, and invokes a PE/COFF image
193 @param BootPolicy If TRUE, indicates that the request originates
194 from the boot manager, and that the boot
195 manager is attempting to load FilePath as a
197 @param Pe32Handle The handle of PE32 image
198 @param Image PE image to be loaded
199 @param DstBuffer The buffer to store the image
200 @param EntryPoint A pointer to the entry point
201 @param Attribute The bit mask of attributes to set for the load
204 @retval EFI_SUCCESS The file was loaded, relocated, and invoked
205 @retval EFI_OUT_OF_RESOURCES There was not enough memory to load and
206 relocate the PE/COFF file
207 @retval EFI_INVALID_PARAMETER Invalid parameter
208 @retval EFI_BUFFER_TOO_SMALL Buffer for image is too small
213 IN BOOLEAN BootPolicy
,
215 IN LOADED_IMAGE_PRIVATE_DATA
*Image
,
216 IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL
,
217 OUT EFI_PHYSICAL_ADDRESS
*EntryPoint OPTIONAL
,
223 Get the image's private data from its handle.
225 @param ImageHandle The image handle
227 @return Return the image private data associated with ImageHandle.
230 LOADED_IMAGE_PRIVATE_DATA
*
231 CoreLoadedImageInfo (
232 IN EFI_HANDLE ImageHandle
237 Unloads EFI image from memory.
239 @param Image EFI image
240 @param FreePage Free allocated pages
244 CoreUnloadAndCloseImage (
245 IN LOADED_IMAGE_PRIVATE_DATA
*Image
,
251 // Exported Image functions
256 Loads an EFI image into memory and returns a handle to the image with extended parameters.
258 @param This Calling context
259 @param ParentImageHandle The caller's image handle.
260 @param FilePath The specific file path from which the image is
262 @param SourceBuffer If not NULL, a pointer to the memory location
263 containing a copy of the image to be loaded.
264 @param SourceSize The size in bytes of SourceBuffer.
265 @param DstBuffer The buffer to store the image.
266 @param NumberOfPages For input, specifies the space size of the
267 image by caller if not NULL. For output,
268 specifies the actual space size needed.
269 @param ImageHandle Image handle for output.
270 @param EntryPoint Image entry point for output.
271 @param Attribute The bit mask of attributes to set for the load
274 @retval EFI_SUCCESS The image was loaded into memory.
275 @retval EFI_NOT_FOUND The FilePath was not found.
276 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
277 @retval EFI_UNSUPPORTED The image type is not supported, or the device
278 path cannot be parsed to locate the proper
279 protocol for loading the file.
280 @retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient
287 IN EFI_PE32_IMAGE_PROTOCOL
*This
,
288 IN EFI_HANDLE ParentImageHandle
,
289 IN EFI_DEVICE_PATH_PROTOCOL
*FilePath
,
290 IN VOID
*SourceBuffer OPTIONAL
,
292 IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL
,
293 OUT UINTN
*NumberOfPages OPTIONAL
,
294 OUT EFI_HANDLE
*ImageHandle
,
295 OUT EFI_PHYSICAL_ADDRESS
*EntryPoint OPTIONAL
,
301 Unload the specified image.
303 @param This Indicates the calling context.
304 @param ImageHandle The specified image handle.
306 @retval EFI_INVALID_PARAMETER Image handle is NULL.
307 @retval EFI_UNSUPPORTED Attempt to unload an unsupported image.
308 @retval EFI_SUCCESS Image successfully unloaded.
314 IN EFI_PE32_IMAGE_PROTOCOL
*This
,
315 IN EFI_HANDLE ImageHandle