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