]> git.proxmox.com Git - mirror_edk2.git/blob - MdeModulePkg/Core/Dxe/Image/Image.h
retain gEfiLoadPeImageProtocolGuid, and only published by DxeCore to keep backward...
[mirror_edk2.git] / MdeModulePkg / Core / Dxe / Image / Image.h
1 /** @file
2 Data structure and functions to load and unload PeImage.
3
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
9
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.
12
13 **/
14
15
16 #ifndef _IMAGE_H_
17 #define _IMAGE_H_
18
19 #define LOADED_IMAGE_PRIVATE_DATA_SIGNATURE SIGNATURE_32('l','d','r','i')
20
21 typedef struct {
22 UINTN Signature;
23 /// Image handle
24 EFI_HANDLE Handle;
25 /// Image type
26 UINTN Type;
27 /// If entrypoint has been called
28 BOOLEAN Started;
29 /// The image's entry point
30 EFI_IMAGE_ENTRY_POINT EntryPoint;
31 /// loaded image protocol
32 EFI_LOADED_IMAGE_PROTOCOL Info;
33 /// Location in memory
34 EFI_PHYSICAL_ADDRESS ImageBasePage;
35 /// Number of pages
36 UINTN NumberOfPages;
37 /// Original fixup data
38 CHAR8 *FixupData;
39 /// Tpl of started image
40 EFI_TPL Tpl;
41 /// Status returned by started image
42 EFI_STATUS Status;
43 /// Size of ExitData from started image
44 UINTN ExitDataSize;
45 /// Pointer to exit data from started image
46 VOID *ExitData;
47 /// Pointer to pool allocation for context save/retore
48 VOID *JumpBuffer;
49 /// Pointer to buffer for context save/retore
50 BASE_LIBRARY_JUMP_BUFFER *JumpContext;
51 /// Machine type from PE image
52 UINT16 Machine;
53 /// EBC Protocol pointer
54 EFI_EBC_PROTOCOL *Ebc;
55 /// Runtime image list
56 EFI_RUNTIME_IMAGE_ENTRY *RuntimeData;
57 /// Pointer to Loaded Image Device Path Protocl
58 EFI_DEVICE_PATH_PROTOCOL *LoadedImageDevicePath;
59 /// PeCoffLoader ImageContext
60 PE_COFF_LOADER_IMAGE_CONTEXT ImageContext;
61
62 } LOADED_IMAGE_PRIVATE_DATA;
63
64 #define LOADED_IMAGE_PRIVATE_DATA_FROM_THIS(a) \
65 CR(a, LOADED_IMAGE_PRIVATE_DATA, Info, LOADED_IMAGE_PRIVATE_DATA_SIGNATURE)
66
67
68 #define LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE SIGNATURE_32('l','p','e','i')
69
70 typedef struct {
71 UINTN Signature;
72 /// Image handle
73 EFI_HANDLE Handle;
74 EFI_PE32_IMAGE_PROTOCOL Pe32Image;
75 } LOAD_PE32_IMAGE_PRIVATE_DATA;
76
77 #define LOAD_PE32_IMAGE_PRIVATE_DATA_FROM_THIS(a) \
78 CR(a, LOAD_PE32_IMAGE_PRIVATE_DATA, Pe32Image, LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE)
79
80
81 //
82 // Private Data Types
83 //
84 #define IMAGE_FILE_HANDLE_SIGNATURE SIGNATURE_32('i','m','g','f')
85 typedef struct {
86 UINTN Signature;
87 BOOLEAN FreeBuffer;
88 VOID *Source;
89 UINTN SourceSize;
90 } IMAGE_FILE_HANDLE;
91
92
93 /**
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.
97
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
103 loaded
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.
108
109 @retval EFI_SUCCESS Image file successfully opened.
110 @retval EFI_LOAD_ERROR If the caller passed a copy of the file, and
111 SourceSize is 0.
112 @retval EFI_INVALID_PARAMETER File path is not valid.
113 @retval EFI_NOT_FOUND File not found.
114
115 **/
116 EFI_STATUS
117 CoreOpenImageFile (
118 IN BOOLEAN BootPolicy,
119 IN VOID *SourceBuffer OPTIONAL,
120 IN UINTN SourceSize,
121 IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath,
122 OUT EFI_HANDLE *DeviceHandle,
123 IN IMAGE_FILE_HANDLE *ImageFileHandle,
124 OUT UINT32 *AuthenticationStatus
125 );
126
127
128
129 /**
130 Read image file (specified by UserHandle) into user specified buffer with specified offset
131 and length.
132
133 @param UserHandle Image file handle
134 @param Offset Offset to the source file
135 @param ReadSize For input, pointer of size to read; For output,
136 pointer of size actually read.
137 @param Buffer Buffer to write into
138
139 @retval EFI_SUCCESS Successfully read the specified part of file
140 into buffer.
141
142 **/
143 EFI_STATUS
144 EFIAPI
145 CoreReadImageFile (
146 IN VOID *UserHandle,
147 IN UINTN Offset,
148 IN OUT UINTN *ReadSize,
149 OUT VOID *Buffer
150 );
151
152
153 /**
154 Loads an EFI image into memory and returns a handle to the image with extended parameters.
155
156 @param This Calling context
157 @param ParentImageHandle The caller's image handle.
158 @param FilePath The specific file path from which the image is
159 loaded.
160 @param SourceBuffer If not NULL, a pointer to the memory location
161 containing a copy of the image to be loaded.
162 @param SourceSize The size in bytes of SourceBuffer.
163 @param DstBuffer The buffer to store the image.
164 @param NumberOfPages For input, specifies the space size of the
165 image by caller if not NULL. For output,
166 specifies the actual space size needed.
167 @param ImageHandle Image handle for output.
168 @param EntryPoint Image entry point for output.
169 @param Attribute The bit mask of attributes to set for the load
170 PE image.
171
172 @retval EFI_SUCCESS The image was loaded into memory.
173 @retval EFI_NOT_FOUND The FilePath was not found.
174 @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
175 @retval EFI_UNSUPPORTED The image type is not supported, or the device
176 path cannot be parsed to locate the proper
177 protocol for loading the file.
178 @retval EFI_OUT_OF_RESOURCES Image was not loaded due to insufficient
179 resources.
180
181 **/
182 EFI_STATUS
183 EFIAPI
184 CoreLoadImageEx (
185 IN EFI_PE32_IMAGE_PROTOCOL *This,
186 IN EFI_HANDLE ParentImageHandle,
187 IN EFI_DEVICE_PATH_PROTOCOL *FilePath,
188 IN VOID *SourceBuffer OPTIONAL,
189 IN UINTN SourceSize,
190 IN EFI_PHYSICAL_ADDRESS DstBuffer OPTIONAL,
191 OUT UINTN *NumberOfPages OPTIONAL,
192 OUT EFI_HANDLE *ImageHandle,
193 OUT EFI_PHYSICAL_ADDRESS *EntryPoint OPTIONAL,
194 IN UINT32 Attribute
195 );
196
197
198 /**
199 Unload the specified image.
200
201 @param This Indicates the calling context.
202 @param ImageHandle The specified image handle.
203
204 @retval EFI_INVALID_PARAMETER Image handle is NULL.
205 @retval EFI_UNSUPPORTED Attempt to unload an unsupported image.
206 @retval EFI_SUCCESS Image successfully unloaded.
207
208 **/
209 EFI_STATUS
210 EFIAPI
211 CoreUnloadImageEx (
212 IN EFI_PE32_IMAGE_PROTOCOL *This,
213 IN EFI_HANDLE ImageHandle
214 );
215 #endif