]> git.proxmox.com Git - mirror_edk2.git/blame - MdePkg/Include/Library/PeCoffLib.h
Update GCC version of VAR_ARG () to be compatible with non GCC version of VAR_ARG...
[mirror_edk2.git] / MdePkg / Include / Library / PeCoffLib.h
CommitLineData
fb3df220 1/** @file\r
50a64e5b 2 Provides services to load and relocate a PE/COFF image.\r
fb3df220 3\r
badcbfb2 4 The PE/COFF Loader Library abstracts the implementation of a PE/COFF loader for\r
5 IA-32, x86, IPF, and EBC processor types. The library functions are memory based \r
6 and can be ported easily to any environment.\r
7 \r
373ade0e 8Copyright (c) 2006 - 2008, Intel Corporation \r
50a64e5b 9All rights reserved. This program and the accompanying materials \r
10are licensed and made available under the terms and conditions of the BSD License \r
11which accompanies this distribution. The full text of the license may be found at \r
12http://opensource.org/licenses/bsd-license.php \r
fb3df220 13\r
50a64e5b 14THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, \r
15WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. \r
fb3df220 16\r
fb3df220 17**/\r
18\r
19#ifndef __BASE_PE_COFF_LIB_H__\r
20#define __BASE_PE_COFF_LIB_H__\r
21\r
d8dcb666 22#include <IndustryStandard/PeImage.h>\r
fb3df220 23//\r
24// Return status codes from the PE/COFF Loader services\r
fb3df220 25//\r
26#define IMAGE_ERROR_SUCCESS 0\r
27#define IMAGE_ERROR_IMAGE_READ 1 \r
28#define IMAGE_ERROR_INVALID_PE_HEADER_SIGNATURE 2\r
29#define IMAGE_ERROR_INVALID_MACHINE_TYPE 3\r
30#define IMAGE_ERROR_INVALID_SUBSYSTEM 4\r
31#define IMAGE_ERROR_INVALID_IMAGE_ADDRESS 5\r
32#define IMAGE_ERROR_INVALID_IMAGE_SIZE 6\r
33#define IMAGE_ERROR_INVALID_SECTION_ALIGNMENT 7\r
34#define IMAGE_ERROR_SECTION_NOT_LOADED 8\r
35#define IMAGE_ERROR_FAILED_RELOCATION 9\r
36#define IMAGE_ERROR_FAILED_ICACHE_FLUSH 10\r
37\r
badcbfb2 38/**\r
39 Reads contents of a PE/COFF image.\r
40\r
41 A function of this type reads contents of the PE/COFF image specified by FileHandle. The read \r
42 operation copies ReadSize bytes from the PE/COFF image starting at byte offset FileOffset into \r
43 the buffer specified by Buffer. The size of the buffer actually read is returned in ReadSize. \r
44 If FileOffset specifies an offset past the end of the PE/COFF image, a ReadSize of 0 is returned.\r
45 A function of this type must be registered in the ImageRead field of a PE_COFF_LOADER_IMAGE_CONTEXT \r
46 structure for the PE/COFF Loader Library service to function correctly. This function abstracts access \r
47 to a PE/COFF image so it can be implemented in an environment specific manner. For example, SEC and PEI \r
48 environments may access memory directly to read the contents of a PE/COFF image, and DXE or UEFI \r
49 environments may require protocol services to read the contents of PE/COFF image \r
50 stored on FLASH, disk, or network devices.\r
51 \r
52 If FileHandle is not a valid handle, then ASSERT().\r
53 If ReadSize is NULL, then ASSERT().\r
54 If Buffer is NULL, then ASSERT().\r
55\r
56 @param FileHandle Pointer to the file handle to read the PE/COFF image.\r
57 @param FileOffset Offset into the PE/COFF image to begin the read operation.\r
58 @param ReadSize On input, the size in bytes of the requested read operation. \r
59 On output, the number of bytes actually read.\r
60 @param Buffer Output buffer that contains the data read from the PE/COFF image.\r
61 \r
62 @retval RETURN_SUCCESS The specified portion of the PE/COFF image was read and the size \r
63 @retval RETURN_DEVICE_ERROR The specified portion of the PE/COFF image could not be read due \r
64 to a device error.\r
65\r
66**/\r
146332ae 67typedef\r
68RETURN_STATUS\r
a5c1c592 69(EFIAPI *PE_COFF_LOADER_READ_FILE)(\r
146332ae 70 IN VOID *FileHandle,\r
71 IN UINTN FileOffset,\r
72 IN OUT UINTN *ReadSize,\r
73 OUT VOID *Buffer\r
74 );\r
75\r
f6d7003d 76///\r
77/// Context structure used while PE/COFF image is being loaded and relocated\r
78///\r
146332ae 79typedef struct {\r
f6d7003d 80 ///\r
81 /// Is set by PeCoffLoaderGetImageInfo() to the ImageBase in the PE/COFF header\r
82 ///\r
146332ae 83 PHYSICAL_ADDRESS ImageAddress;\r
f6d7003d 84 ///\r
85 /// Is set by PeCoffLoaderGetImageInfo() to the SizeOfImage in the PE/COFF header.\r
86 /// Image size includes the size of Debug Entry if it is present.\r
87 ///\r
146332ae 88 UINT64 ImageSize;\r
f6d7003d 89 ///\r
90 /// Is set to zero by PeCoffLoaderGetImageInfo(). If DestinationAddress is non zero,\r
91 /// PeCoffLoaderRelocateImage() will relocate the image using this base address.\r
92 /// If the DestinationAddress is zero, the ImageAddress will be used as the base\r
93 /// address of relocation.\r
94 ///\r
146332ae 95 PHYSICAL_ADDRESS DestinationAddress;\r
f6d7003d 96 ///\r
97 /// PeCoffLoaderLoadImage() sets EntryPoint to to the entry point of the PE/COFF image.\r
98 ///\r
146332ae 99 PHYSICAL_ADDRESS EntryPoint;\r
f6d7003d 100 ///\r
101 /// Passed in by the caller to PeCoffLoaderGetImageInfo() and PeCoffLoaderLoadImage()\r
102 /// to abstract accessing the image from the library.\r
103 ///\r
146332ae 104 PE_COFF_LOADER_READ_FILE ImageRead;\r
f6d7003d 105 ///\r
106 /// Used as the FileHandle passed into the ImageRead function when it's called.\r
107 ///\r
146332ae 108 VOID *Handle;\r
f6d7003d 109 ///\r
110 /// Caller allocated buffer of size FixupDataSize that can be optionally allocated\r
111 /// prior to calling PeCoffLoaderRelocateImage(). \r
112 /// This buffer is filled with the information used to fix up the image. \r
113 /// The fixups have been applied to the image and this entry is just for information.\r
114 ///\r
146332ae 115 VOID *FixupData;\r
f6d7003d 116 ///\r
117 /// Is set by PeCoffLoaderGetImageInfo() to the Section Alignment in the PE/COFF header\r
3ecdcd11 118 /// If the image is a TE image, then this field is set to 0.\r
f6d7003d 119 ///\r
146332ae 120 UINT32 SectionAlignment;\r
f6d7003d 121 ///\r
122 /// Set by PeCoffLoaderGetImageInfo() to offset to the PE/COFF header.\r
123 /// If the PE/COFF image does not start with a DOS header, this value is zero; \r
124 /// otherwise, it's the offset to the PE/COFF header.\r
125 ///\r
146332ae 126 UINT32 PeCoffHeaderOffset;\r
f6d7003d 127 ///\r
128 /// Set by PeCoffLoaderGetImageInfo() to the Relative Virtual Address of the debug directory\r
129 /// if it exists in the image\r
130 ///\r
146332ae 131 UINT32 DebugDirectoryEntryRva;\r
f6d7003d 132 ///\r
133 /// Set by PeCoffLoaderLoadImage() to CodeView area of the PE/COFF Debug directory.\r
134 ///\r
146332ae 135 VOID *CodeView;\r
f6d7003d 136 ///\r
137 /// Set by PeCoffLoaderLoadImage() to point to the PDB entry contained in the CodeView area.\r
138 /// The PdbPointer points to the filename of the PDB file used for source-level debug of \r
139 /// the image by a debugger.\r
140 ///\r
146332ae 141 CHAR8 *PdbPointer;\r
f6d7003d 142 ///\r
143 /// Is set by PeCoffLoaderGetImageInfo() to the Section Alignment in the PE/COFF header.\r
144 ///\r
146332ae 145 UINTN SizeOfHeaders;\r
f6d7003d 146 ///\r
147 /// Not used by this library class. Other library classes that layer on top of this library\r
148 /// class fill in this value as part of their GetImageInfo call. \r
149 /// This allows the caller of the library to know what type of memory needs to be allocated\r
150 /// to load and relocate the image.\r
151 ///\r
146332ae 152 UINT32 ImageCodeMemoryType;\r
f6d7003d 153 ///\r
154 /// Not used by this library class. Other library classes that layer on top of this library \r
155 /// class fill in this value as part of their GetImageInfo call.\r
156 /// This allows the caller of the library to know what type of memory needs to be allocated\r
157 /// to load and relocate the image\r
158 ///\r
146332ae 159 UINT32 ImageDataMemoryType;\r
f6d7003d 160 ///\r
161 /// Set by any of the library functions if they encounter an error. \r
162 ///\r
146332ae 163 UINT32 ImageError;\r
f6d7003d 164 ///\r
165 /// Set by PeCoffLoaderLoadImage() to indicate the size of FixupData that the caller must\r
166 /// allocate before calling PeCoffLoaderRelocateImage()\r
167 ///\r
146332ae 168 UINTN FixupDataSize;\r
f6d7003d 169 ///\r
170 /// Set by PeCoffLoaderGetImageInfo() to the machine type stored in the PE/COFF header\r
171 ///\r
146332ae 172 UINT16 Machine;\r
f6d7003d 173 ///\r
174 /// Set by PeCoffLoaderGetImageInfo() to the subsystem type stored in the PE/COFF header.\r
175 ///\r
146332ae 176 UINT16 ImageType;\r
f6d7003d 177 ///\r
178 /// Set by PeCoffLoaderGetImageInfo() to TRUE if the PE/COFF image does not contain\r
179 /// relocation information.\r
180 ///\r
146332ae 181 BOOLEAN RelocationsStripped;\r
f6d7003d 182 ///\r
183 /// Set by PeCoffLoaderGetImageInfo() to TRUE if the image is a TE image. \r
184 /// For a definition of the TE Image format, see the Platform Initialization Pre-EFI\r
185 /// Initialization Core Interface Specification.\r
186 ///\r
146332ae 187 BOOLEAN IsTeImage;\r
b4500f6e 188 ///\r
189 /// Set by PeCoffLoaderLoadImage() to the HII resource offset\r
190 /// if the image contains a custom PE/COFF resource with the type 'HII';\r
191 /// otherwise, the entry remains to be 0.\r
192 ///\r
193 PHYSICAL_ADDRESS HiiResourceData;\r
146332ae 194} PE_COFF_LOADER_IMAGE_CONTEXT;\r
fb3df220 195\r
196/**\r
197 Retrieves information about a PE/COFF image.\r
198\r
3ecdcd11
LG
199 Computes the PeCoffHeaderOffset, IsTeImage, ImageType, ImageAddress, ImageSize, \r
200 DestinationAddress, RelocationsStripped, SectionAlignment, SizeOfHeaders, and \r
201 DebugDirectoryEntryRva fields of the ImageContext structure. \r
202 If ImageContext is NULL, then return RETURN_INVALID_PARAMETER. \r
203 If the PE/COFF image accessed through the ImageRead service in the ImageContext \r
204 structure is not a supported PE/COFF image type, then return RETURN_UNSUPPORTED. \r
205 If any errors occur while computing the fields of ImageContext, \r
206 then the error status is returned in the ImageError field of ImageContext. \r
207 If the image is a TE image, then SectionAlignment is set to 0.\r
badcbfb2 208 The ImageRead and Handle fields of ImageContext structure must be valid prior \r
209 to invoking this service.\r
fb3df220 210\r
211 @param ImageContext Pointer to the image context structure that describes the PE/COFF\r
212 image that needs to be examined by this function.\r
213\r
214 @retval RETURN_SUCCESS The information on the PE/COFF image was collected.\r
215 @retval RETURN_INVALID_PARAMETER ImageContext is NULL.\r
216 @retval RETURN_UNSUPPORTED The PE/COFF image is not supported.\r
217\r
218**/\r
219RETURN_STATUS\r
220EFIAPI\r
221PeCoffLoaderGetImageInfo (\r
222 IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext\r
ed66e1bc 223 );\r
fb3df220 224\r
225/**\r
226 Applies relocation fixups to a PE/COFF image that was loaded with PeCoffLoaderLoadImage().\r
227\r
228 If the DestinationAddress field of ImageContext is 0, then use the ImageAddress field of\r
229 ImageContext as the relocation base address. Otherwise, use the DestinationAddress field\r
230 of ImageContext as the relocation base address. The caller must allocate the relocation\r
badcbfb2 231 fixup log buffer and fill in the FixupData field of ImageContext prior to calling this function.\r
232 \r
233 The ImageRead, Handle, PeCoffHeaderOffset, IsTeImage, Machine, ImageType, ImageAddress, \r
234 ImageSize, DestinationAddress, RelocationsStripped, SectionAlignment, SizeOfHeaders, \r
235 DebugDirectoryEntryRva, EntryPoint, FixupDataSize, CodeView, PdbPointer, and FixupData of \r
236 the ImageContext structure must be valid prior to invoking this service.\r
237 \r
fb3df220 238 If ImageContext is NULL, then ASSERT().\r
239\r
240 @param ImageContext Pointer to the image context structure that describes the PE/COFF\r
241 image that is being relocated.\r
242\r
243 @retval RETURN_SUCCESS The PE/COFF image was relocated.\r
244 Extended status information is in the ImageError field of ImageContext.\r
245 @retval RETURN_LOAD_ERROR The image in not a valid PE/COFF image.\r
246 Extended status information is in the ImageError field of ImageContext.\r
247 @retval RETURN_UNSUPPORTED A relocation record type is not supported.\r
248 Extended status information is in the ImageError field of ImageContext.\r
249\r
250**/\r
251RETURN_STATUS\r
252EFIAPI\r
253PeCoffLoaderRelocateImage (\r
254 IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext\r
ed66e1bc 255 );\r
fb3df220 256\r
257/**\r
258 Loads a PE/COFF image into memory.\r
259\r
260 Loads the PE/COFF image accessed through the ImageRead service of ImageContext into the buffer\r
261 specified by the ImageAddress and ImageSize fields of ImageContext. The caller must allocate\r
262 the load buffer and fill in the ImageAddress and ImageSize fields prior to calling this function.\r
b4500f6e 263 The EntryPoint, FixupDataSize, CodeView, PdbPointer and HiiResourceData fields of ImageContext are computed.\r
badcbfb2 264 The ImageRead, Handle, PeCoffHeaderOffset, IsTeImage, Machine, ImageType, ImageAddress, ImageSize, \r
265 DestinationAddress, RelocationsStripped, SectionAlignment, SizeOfHeaders, and DebugDirectoryEntryRva \r
266 fields of the ImageContext structure must be valid prior to invoking this service.\r
267 \r
fb3df220 268 If ImageContext is NULL, then ASSERT().\r
269\r
270 @param ImageContext Pointer to the image context structure that describes the PE/COFF\r
271 image that is being loaded.\r
272\r
273 @retval RETURN_SUCCESS The PE/COFF image was loaded into the buffer specified by\r
274 the ImageAddress and ImageSize fields of ImageContext.\r
275 Extended status information is in the ImageError field of ImageContext.\r
276 @retval RETURN_BUFFER_TOO_SMALL The caller did not provide a large enough buffer.\r
277 Extended status information is in the ImageError field of ImageContext.\r
278 @retval RETURN_LOAD_ERROR The PE/COFF image is an EFI Runtime image with no relocations.\r
279 Extended status information is in the ImageError field of ImageContext.\r
280 @retval RETURN_INVALID_PARAMETER The image address is invalid.\r
281 Extended status information is in the ImageError field of ImageContext.\r
282\r
283**/\r
284RETURN_STATUS\r
285EFIAPI\r
286PeCoffLoaderLoadImage (\r
287 IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext\r
ed66e1bc 288 );\r
fb3df220 289\r
290\r
291/**\r
badcbfb2 292 Reads contents of a PE/COFF image from a buffer in system memory.\r
293 \r
294 This is the default implementation of a PE_COFF_LOADER_READ_FILE function \r
295 that assumes FileHandle pointer to the beginning of a PE/COFF image. \r
296 This function reads contents of the PE/COFF image that starts at the system memory \r
297 address specified by FileHandle. The read operation copies ReadSize bytes from the \r
298 PE/COFF image starting at byte offset FileOffset into the buffer specified by Buffer. \r
299 The size of the buffer actually read is returned in ReadSize.\r
300 \r
301 If FileHandle is NULL, then ASSERT().\r
302 If ReadSize is NULL, then ASSERT().\r
303 If Buffer is NULL, then ASSERT().\r
fb3df220 304\r
badcbfb2 305 @param FileHandle Pointer to base of the input stream\r
306 @param FileOffset Offset into the PE/COFF image to begin the read operation.\r
307 @param ReadSize On input, the size in bytes of the requested read operation. \r
308 On output, the number of bytes actually read.\r
309 @param Buffer Output buffer that contains the data read from the PE/COFF image.\r
fb3df220 310\r
311 @retval RETURN_SUCCESS Data is read from FileOffset from the Handle into \r
312 the buffer.\r
313**/\r
314RETURN_STATUS\r
315EFIAPI\r
316PeCoffLoaderImageReadFromMemory (\r
317 IN VOID *FileHandle,\r
318 IN UINTN FileOffset,\r
319 IN OUT UINTN *ReadSize,\r
320 OUT VOID *Buffer\r
ed66e1bc 321 );\r
fb3df220 322\r
323\r
324/**\r
325 Reapply fixups on a fixed up PE32/PE32+ image to allow virutal calling at EFI\r
326 runtime. \r
327 \r
9833a9bb
LG
328 This function reapplies relocation fixups to the PE/COFF image specified by ImageBase \r
329 and ImageSize so the image will execute correctly when the PE/COFF image is mapped \r
330 to the address specified by VirtualImageBase. RelocationData must be identical \r
331 to the FiuxupData buffer from the PE_COFF_LOADER_IMAGE_CONTEXT structure \r
332 after this PE/COFF image was relocated with PeCoffLoaderRelocateImage().\r
fb3df220 333\r
badcbfb2 334 @param ImageBase Base address of a PE/COFF image that has been loaded \r
335 and relocated into system memory.\r
336 @param VirtImageBase The request virtual address that the PE/COFF image is to\r
337 be fixed up for.\r
338 @param ImageSize The size, in bytes, of the PE/COFF image.\r
339 @param RelocationData A pointer to the relocation data that was collected when the PE/COFF \r
340 image was relocated using PeCoffLoaderRelocateImage().\r
fb3df220 341 \r
342**/\r
343VOID\r
344EFIAPI\r
345PeCoffLoaderRelocateImageForRuntime (\r
346 IN PHYSICAL_ADDRESS ImageBase,\r
347 IN PHYSICAL_ADDRESS VirtImageBase,\r
348 IN UINTN ImageSize,\r
349 IN VOID *RelocationData\r
ed66e1bc 350 );\r
fb3df220 351\r
3d7b0992
LG
352/**\r
353 Unloads a loaded PE/COFF image from memory and releases its taken resource.\r
badcbfb2 354 Releases any environment specific resources that were allocated when the image \r
355 specified by ImageContext was loaded using PeCoffLoaderLoadImage(). \r
356 \r
3d7b0992
LG
357 For NT32 emulator, the PE/COFF image loaded by system needs to release.\r
358 For real platform, the PE/COFF image loaded by Core doesn't needs to be unloaded, \r
359 this function can simply return RETURN_SUCCESS.\r
badcbfb2 360 \r
361 If ImageContext is NULL, then ASSERT().\r
362 \r
3d7b0992
LG
363 @param ImageContext Pointer to the image context structure that describes the PE/COFF\r
364 image to be unloaded.\r
fb3df220 365\r
3d7b0992
LG
366 @retval RETURN_SUCCESS The PE/COFF image was unloaded successfully.\r
367**/\r
368RETURN_STATUS\r
369EFIAPI\r
370PeCoffLoaderUnloadImage (\r
0465a73e 371 IN OUT PE_COFF_LOADER_IMAGE_CONTEXT *ImageContext\r
ed66e1bc 372 );\r
fb3df220 373#endif\r