MdeModulePkg/Core/Dxe/Image.h

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