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