Removed CommonHeader.h from MdePkg & MdeModulePkg
[mirror_edk2.git] / MdeModulePkg / Core / Dxe / Image.h
CommitLineData
28a00297 1/*++\r
2\r
3Copyright (c) 2006, Intel Corporation\r
4All rights reserved. This program and the accompanying materials\r
5are licensed and made available under the terms and conditions of the BSD License\r
6which accompanies this distribution. The full text of the license may be found at\r
7http://opensource.org/licenses/bsd-license.php\r
8\r
9THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
10WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
11\r
12Module Name:\r
13\r
14 Image.h\r
15\r
16Abstract:\r
17\r
18Revision History\r
19\r
20--*/\r
21\r
22\r
23#ifndef _IMAGE_H_\r
24#define _IMAGE_H_\r
25\r
26\r
27\r
28#define LOADED_IMAGE_PRIVATE_DATA_SIGNATURE EFI_SIGNATURE_32('l','d','r','i')\r
29\r
30typedef struct {\r
31 UINTN Signature;\r
32 EFI_HANDLE Handle; // Image handle\r
33 UINTN Type; // Image type\r
34\r
35 BOOLEAN Started; // If entrypoint has been called\r
36\r
37 EFI_IMAGE_ENTRY_POINT EntryPoint; // The image's entry point\r
38 EFI_LOADED_IMAGE_PROTOCOL Info; // loaded image protocol\r
39\r
40 EFI_PHYSICAL_ADDRESS ImageBasePage; // Location in memory\r
41 UINTN NumberOfPages; // Number of pages\r
42\r
43 CHAR8 *FixupData; // Original fixup data\r
44\r
45 EFI_TPL Tpl; // Tpl of started image\r
46 EFI_STATUS Status; // Status returned by started image\r
47\r
48 UINTN ExitDataSize; // Size of ExitData from started image\r
49 VOID *ExitData; // Pointer to exit data from started image\r
50 VOID *JumpBuffer; // Pointer to pool allocation for context save/retore\r
51 BASE_LIBRARY_JUMP_BUFFER *JumpContext; // Pointer to buffer for context save/retore\r
52 UINT16 Machine; // Machine type from PE image\r
53\r
54 EFI_EBC_PROTOCOL *Ebc; // EBC Protocol pointer\r
55\r
56 EFI_RUNTIME_IMAGE_ENTRY *RuntimeData; // Runtime image list\r
57\r
58 PE_COFF_LOADER_IMAGE_CONTEXT ImageContext; // PeCoffLoader ImageContext\r
59\r
60} LOADED_IMAGE_PRIVATE_DATA;\r
61\r
62#define LOADED_IMAGE_PRIVATE_DATA_FROM_THIS(a) \\r
63 CR(a, LOADED_IMAGE_PRIVATE_DATA, Info, LOADED_IMAGE_PRIVATE_DATA_SIGNATURE)\r
64\r
65\r
66\r
67#define LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE EFI_SIGNATURE_32('l','p','e','i')\r
68\r
69typedef struct {\r
70 UINTN Signature;\r
71 EFI_HANDLE Handle; // Image handle\r
72 EFI_PE32_IMAGE_PROTOCOL Pe32Image;\r
73} LOAD_PE32_IMAGE_PRIVATE_DATA;\r
74\r
75#define LOAD_PE32_IMAGE_PRIVATE_DATA_FROM_THIS(a) \\r
76 CR(a, LOAD_PE32_IMAGE_PRIVATE_DATA, Pe32Image, LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE)\r
77\r
78\r
79\r
80//\r
81// Private Data Types\r
82//\r
83#define IMAGE_FILE_HANDLE_SIGNATURE EFI_SIGNATURE_32('i','m','g','f')\r
84typedef struct {\r
85 UINTN Signature;\r
86 BOOLEAN FreeBuffer;\r
87 VOID *Source;\r
88 UINTN SourceSize;\r
89} IMAGE_FILE_HANDLE;\r
90\r
91\r
92//\r
93// Abstractions for reading image contents\r
94//\r
95\r
96EFI_STATUS\r
97CoreOpenImageFile (\r
98 IN BOOLEAN BootPolicy,\r
99 IN VOID *SourceBuffer OPTIONAL,\r
100 IN UINTN SourceSize,\r
101 IN OUT EFI_DEVICE_PATH_PROTOCOL *FilePath,\r
102 OUT EFI_HANDLE *DeviceHandle,\r
103 IN IMAGE_FILE_HANDLE *ImageFileHandle,\r
104 OUT UINT32 *AuthenticationStatus\r
105 )\r
106/*++\r
107\r
108Routine Description:\r
109\r
110 Opens a file for (simple) reading. The simple read abstraction\r
111 will access the file either from a memory copy, from a file\r
112 system interface, or from the load file interface.\r
113\r
114Arguments:\r
115\r
116 BootPolicy - Policy for Open Image File.\r
117 SourceBuffer - Pointer to the memory location containing copy\r
118 of the image to be loaded.\r
119 SourceSize - The size in bytes of SourceBuffer.\r
120 FilePath - The specific file path from which the image is loaded\r
121 DeviceHandle - Pointer to the return device handle.\r
122 ImageFileHandle - Pointer to the image file handle.\r
123 AuthenticationStatus - Pointer to a caller-allocated UINT32 in which the authentication status is returned.\r
124\r
125Returns:\r
126\r
127 A handle to access the file\r
128\r
129--*/\r
130;\r
131\r
132\r
133EFI_STATUS\r
134EFIAPI\r
135CoreReadImageFile (\r
136 IN VOID *UserHandle,\r
137 IN UINTN Offset,\r
138 IN OUT UINTN *ReadSize,\r
139 OUT VOID *Buffer\r
140 )\r
141/*++\r
142\r
143Routine Description:\r
144\r
145 Read image file (specified by UserHandle) into user specified buffer with specified offset\r
146 and length.\r
147\r
148Arguments:\r
149\r
150 UserHandle - Image file handle\r
151\r
152 Offset - Offset to the source file\r
153\r
154 ReadSize - For input, pointer of size to read;\r
155 For output, pointer of size actually read.\r
156\r
157 Buffer - Buffer to write into\r
158\r
159Returns:\r
160\r
161 EFI_SUCCESS - Successfully read the specified part of file into buffer.\r
162\r
163--*/\r
164;\r
165\r
166VOID\r
167EFIAPI\r
168CoreCloseImageFile (\r
169 IN IMAGE_FILE_HANDLE *ImageFileHandle\r
170 )\r
171/*++\r
172\r
173Routine Description:\r
174\r
175 A function out of date, should be removed.\r
176\r
177Arguments:\r
178\r
179 ImageFileHandle - Handle of the file to close\r
180\r
181Returns:\r
182\r
183 None\r
184\r
185--*/\r
186;\r
187\r
188//\r
189// Image processing worker functions\r
190//\r
191EFI_STATUS\r
192CoreDevicePathToInterface (\r
193 IN EFI_GUID *Protocol,\r
194 IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath,\r
195 OUT VOID **Interface,\r
196 OUT EFI_HANDLE *Handle\r
197 )\r
198/*++\r
199\r
200Routine Description:\r
201\r
202 Search a handle to a device on a specified device path that supports a specified protocol,\r
203 interface of that protocol on that handle is another output.\r
204\r
205Arguments:\r
206\r
207 Protocol - The protocol to search for\r
208\r
209 FilePath - The specified device path\r
210\r
211 Interface - Interface of the protocol on the handle\r
212\r
213 Handle - The handle to the device on the specified device path that supports the protocol.\r
214\r
215Returns:\r
216\r
217 Status code.\r
218\r
219--*/\r
220;\r
221\r
222EFI_STATUS\r
223CoreLoadPeImage (\r
224 IN VOID *Pe32Handle,\r
225 IN LOADED_IMAGE_PRIVATE_DATA *Image,\r
226 IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL,\r
227 OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL,\r
228 IN UINT32 Attribute\r
229 )\r
230/*++\r
231\r
232Routine Description:\r
233\r
234 Loads, relocates, and invokes a PE/COFF image\r
235\r
236Arguments:\r
237\r
238 Pe32Handle - The handle of PE32 image\r
239 Image - PE image to be loaded\r
240 DstBuffer - The buffer to store the image\r
241 EntryPoint - A pointer to the entry point\r
242 Attribute - The bit mask of attributes to set for the load PE image\r
243\r
244Returns:\r
245\r
246 EFI_SUCCESS - The file was loaded, relocated, and invoked\r
247\r
248 EFI_OUT_OF_RESOURCES - There was not enough memory to load and relocate the PE/COFF file\r
249\r
250 EFI_INVALID_PARAMETER - Invalid parameter\r
251\r
252 EFI_BUFFER_TOO_SMALL - Buffer for image is too small\r
253\r
254--*/\r
255;\r
256\r
257LOADED_IMAGE_PRIVATE_DATA *\r
258CoreLoadedImageInfo (\r
259 IN EFI_HANDLE ImageHandle\r
260 )\r
261/*++\r
262\r
263Routine Description:\r
264\r
265 TODO: Add function description\r
266\r
267Arguments:\r
268\r
269 ImageHandle - TODO: add argument description\r
270\r
271Returns:\r
272\r
273 TODO: add return values\r
274\r
275--*/\r
276;\r
277\r
278VOID\r
279CoreUnloadAndCloseImage (\r
280 IN LOADED_IMAGE_PRIVATE_DATA *Image,\r
281 IN BOOLEAN FreePage\r
282 )\r
283/*++\r
284\r
285Routine Description:\r
286\r
287 Unloads EFI image from memory.\r
288\r
289Arguments:\r
290\r
291 Image - EFI image\r
292 FreePage - Free allocated pages\r
293\r
294Returns:\r
295\r
296 None\r
297\r
298--*/\r
299;\r
300\r
301\r
302//\r
303// Exported Image functions\r
304//\r
305\r
306EFI_STATUS\r
307EFIAPI\r
308CoreLoadImageEx (\r
309 IN EFI_PE32_IMAGE_PROTOCOL *This,\r
310 IN EFI_HANDLE ParentImageHandle,\r
311 IN EFI_DEVICE_PATH_PROTOCOL *FilePath,\r
312 IN VOID *SourceBuffer OPTIONAL,\r
313 IN UINTN SourceSize,\r
314 IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL,\r
315 OUT UINTN *NumberOfPages OPTIONAL,\r
316 OUT EFI_HANDLE *ImageHandle,\r
317 OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL,\r
318 IN UINT32 Attribute\r
319 )\r
320/*++\r
321\r
322Routine Description:\r
323\r
324 Loads an EFI image into memory and returns a handle to the image with extended parameters.\r
325\r
326Arguments:\r
327\r
328 ParentImageHandle - The caller's image handle.\r
329 FilePath - The specific file path from which the image is loaded.\r
330 SourceBuffer - If not NULL, a pointer to the memory location containing a copy of\r
331 the image to be loaded.\r
332 SourceSize - The size in bytes of SourceBuffer.\r
333 DstBuffer - The buffer to store the image.\r
334 NumberOfPages - For input, specifies the space size of the image by caller if not NULL.\r
335 For output, specifies the actual space size needed.\r
336 ImageHandle - Image handle for output.\r
337 EntryPoint - Image entry point for output.\r
338 Attribute - The bit mask of attributes to set for the load PE image.\r
339\r
340Returns:\r
341\r
342 EFI_SUCCESS - The image was loaded into memory.\r
343 EFI_NOT_FOUND - The FilePath was not found.\r
344 EFI_INVALID_PARAMETER - One of the parameters has an invalid value.\r
345 EFI_UNSUPPORTED - The image type is not supported, or the device path cannot be\r
346 parsed to locate the proper protocol for loading the file.\r
347 EFI_OUT_OF_RESOURCES - Image was not loaded due to insufficient resources.\r
348--*/\r
349;\r
350\r
351EFI_STATUS\r
352EFIAPI\r
353CoreUnloadImageEx (\r
354 IN EFI_PE32_IMAGE_PROTOCOL *This,\r
355 IN EFI_HANDLE ImageHandle\r
356 )\r
357/*++\r
358\r
359Routine Description:\r
360\r
361 Unload the specified image.\r
362\r
363Arguments:\r
364\r
365 This - Indicates the calling context.\r
366\r
367 ImageHandle - The specified image handle.\r
368\r
369Returns:\r
370\r
371 EFI_INVALID_PARAMETER - Image handle is NULL.\r
372\r
373 EFI_UNSUPPORTED - Attempt to unload an unsupported image.\r
374\r
375 EFI_SUCCESS - Image successfully unloaded.\r
376\r
377--*/\r
378;\r
379#endif\r