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      *DeviceHandleDevicePath;
  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 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  VOID                       *Pe32Handle,
 227   IN  LOADED_IMAGE_PRIVATE_DATA  *Image,
 228   IN  EFI_PHYSICAL_ADDRESS       DstBuffer   OPTIONAL,
 229   OUT EFI_PHYSICAL_ADDRESS       *EntryPoint  OPTIONAL,
 230   IN  UINT32                     Attribute
 231   )
 232 /*++
 233
 234 Routine Description:
 235
 236   Loads, relocates, and invokes a PE/COFF image
 237
 238 Arguments:
 239
 240   Pe32Handle       - The handle of PE32 image
 241   Image            - PE image to be loaded
 242   DstBuffer        - The buffer to store the image
 243   EntryPoint       - A pointer to the entry point
 244   Attribute        - The bit mask of attributes to set for the load PE image
 245
 246 Returns:
 247
 248   EFI_SUCCESS           - The file was loaded, relocated, and invoked
 249
 250   EFI_OUT_OF_RESOURCES  - There was not enough memory to load and relocate the PE/COFF file
 251
 252   EFI_INVALID_PARAMETER - Invalid parameter
 253
 254   EFI_BUFFER_TOO_SMALL  - Buffer for image is too small
 255
 256 --*/
 257 ;
 258
 259 LOADED_IMAGE_PRIVATE_DATA *
 260 CoreLoadedImageInfo (
 261   IN EFI_HANDLE  ImageHandle
 262   )
 263 /*++
 264
 265 Routine Description:
 266
 267   TODO: Add function description
 268
 269 Arguments:
 270
 271   ImageHandle - TODO: add argument description
 272
 273 Returns:
 274
 275   TODO: add return values
 276
 277 --*/
 278 ;
 279
 280 VOID
 281 CoreUnloadAndCloseImage (
 282   IN LOADED_IMAGE_PRIVATE_DATA  *Image,
 283   IN BOOLEAN                    FreePage
 284   )
 285 /*++
 286
 287 Routine Description:
 288
 289   Unloads EFI image from memory.
 290
 291 Arguments:
 292
 293   Image      - EFI image
 294   FreePage   - Free allocated pages
 295
 296 Returns:
 297
 298   None
 299
 300 --*/
 301 ;
 302
 303
 304 //
 305 // Exported Image functions
 306 //
 307
 308 EFI_STATUS
 309 EFIAPI
 310 CoreLoadImageEx (
 311   IN EFI_PE32_IMAGE_PROTOCOL           *This,
 312   IN  EFI_HANDLE                       ParentImageHandle,
 313   IN  EFI_DEVICE_PATH_PROTOCOL         *FilePath,
 314   IN  VOID                             *SourceBuffer       OPTIONAL,
 315   IN  UINTN                            SourceSize,
 316   IN  EFI_PHYSICAL_ADDRESS             DstBuffer           OPTIONAL,
 317   OUT UINTN                            *NumberOfPages      OPTIONAL,
 318   OUT EFI_HANDLE                       *ImageHandle,
 319   OUT EFI_PHYSICAL_ADDRESS             *EntryPoint         OPTIONAL,
 320   IN  UINT32                           Attribute
 321   )
 322 /*++
 323
 324 Routine Description:
 325
 326   Loads an EFI image into memory and returns a handle to the image with extended parameters.
 327
 328 Arguments:
 329
 330   ParentImageHandle   - The caller's image handle.
 331   FilePath            - The specific file path from which the image is loaded.
 332   SourceBuffer        - If not NULL, a pointer to the memory location containing a copy of
 333                         the image to be loaded.
 334   SourceSize          - The size in bytes of SourceBuffer.
 335   DstBuffer           - The buffer to store the image.
 336   NumberOfPages       - For input, specifies the space size of the image by caller if not NULL.
 337                         For output, specifies the actual space size needed.
 338   ImageHandle         - Image handle for output.
 339   EntryPoint          - Image entry point for output.
 340   Attribute           - The bit mask of attributes to set for the load PE image.
 341
 342 Returns:
 343
 344   EFI_SUCCESS            - The image was loaded into memory.
 345   EFI_NOT_FOUND          - The FilePath was not found.
 346   EFI_INVALID_PARAMETER  - One of the parameters has an invalid value.
 347   EFI_UNSUPPORTED        - The image type is not supported, or the device path cannot be
 348                            parsed to locate the proper protocol for loading the file.
 349   EFI_OUT_OF_RESOURCES   - Image was not loaded due to insufficient resources.
 350 --*/
 351 ;
 352
 353 EFI_STATUS
 354 EFIAPI
 355 CoreUnloadImageEx (
 356   IN EFI_PE32_IMAGE_PROTOCOL            *This,
 357   IN EFI_HANDLE                         ImageHandle
 358   )
 359 /*++
 360
 361 Routine Description:
 362
 363   Unload the specified image.
 364
 365 Arguments:
 366
 367   This              - Indicates the calling context.
 368
 369   ImageHandle       - The specified image handle.
 370
 371 Returns:
 372
 373   EFI_INVALID_PARAMETER       - Image handle is NULL.
 374
 375   EFI_UNSUPPORTED             - Attempt to unload an unsupported image.
 376
 377   EFI_SUCCESS                 - Image successfully unloaded.
 378
 379 --*/
 380 ;
 381 #endif