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