MdeModulePkg/Core/Dxe/Image.h

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