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