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
  93 /**
  94   Opens a file for (simple) reading.  The simple read abstraction
  95   will access the file either from a memory copy, from a file
  96   system interface, or from the load file interface.
  97
  98   @param  BootPolicy             Policy for Open Image File.
  99   @param  SourceBuffer           Pointer to the memory location containing copy
 100                                  of the image to be loaded.
 101   @param  SourceSize             The size in bytes of SourceBuffer.
 102   @param  FilePath               The specific file path from which the image is
 103                                  loaded
 104   @param  DeviceHandle           Pointer to the return device handle.
 105   @param  ImageFileHandle        Pointer to the image file handle.
 106   @param  AuthenticationStatus   Pointer to a caller-allocated UINT32 in which
 107                                  the authentication status is returned.
 108
 109   @retval EFI_SUCCESS            Image file successfully opened.
 110   @retval EFI_LOAD_ERROR         If the caller passed a copy of the file, and
 111                                  SourceSize is 0.
 112   @retval EFI_INVALID_PARAMETER  File path is not valid.
 113   @retval EFI_NOT_FOUND          File not found.
 114
 115 **/
 116 EFI_STATUS
 117 CoreOpenImageFile (
 118   IN BOOLEAN                        BootPolicy,
 119   IN VOID                           *SourceBuffer   OPTIONAL,
 120   IN UINTN                          SourceSize,
 121   IN OUT EFI_DEVICE_PATH_PROTOCOL   **FilePath,
 122   OUT EFI_HANDLE                    *DeviceHandle,
 123   IN IMAGE_FILE_HANDLE              *ImageFileHandle,
 124   OUT UINT32                        *AuthenticationStatus
 125   )
 126 ;
 127
 128
 129
 130 /**
 131   Read image file (specified by UserHandle) into user specified buffer with specified offset
 132   and length.
 133
 134   @param  UserHandle             Image file handle
 135   @param  Offset                 Offset to the source file
 136   @param  ReadSize               For input, pointer of size to read; For output,
 137                                  pointer of size actually read.
 138   @param  Buffer                 Buffer to write into
 139
 140   @retval EFI_SUCCESS            Successfully read the specified part of file
 141                                  into buffer.
 142
 143 **/
 144 EFI_STATUS
 145 EFIAPI
 146 CoreReadImageFile (
 147   IN     VOID     *UserHandle,
 148   IN     UINTN    Offset,
 149   IN OUT UINTN    *ReadSize,
 150   OUT     VOID    *Buffer
 151   )
 152 ;
 153
 154
 155 /**
 156   A function out of date, should be removed.
 157
 158   @param  ImageFileHandle        Handle of the file to close
 159
 160 **/
 161 VOID
 162 EFIAPI
 163 CoreCloseImageFile (
 164   IN IMAGE_FILE_HANDLE *ImageFileHandle
 165   )
 166 ;
 167
 168 //
 169 // Image processing worker functions
 170 //
 171
 172 /**
 173   Search a handle to a device on a specified device path that supports a specified protocol,
 174   interface of that protocol on that handle is another output.
 175
 176   @param  Protocol               The protocol to search for
 177   @param  FilePath               The specified device path
 178   @param  Interface              Interface of the protocol on the handle
 179   @param  Handle                 The handle to the device on the specified device
 180                                  path that supports the protocol.
 181
 182   @return Status code.
 183
 184 **/
 185 EFI_STATUS
 186 CoreDevicePathToInterface (
 187   IN EFI_GUID                     *Protocol,
 188   IN OUT EFI_DEVICE_PATH_PROTOCOL **FilePath,
 189   OUT VOID                        **Interface,
 190   OUT EFI_HANDLE                  *Handle
 191   )
 192 ;
 193
 194
 195 /**
 196   Loads, relocates, and invokes a PE/COFF image
 197
 198   @param  BootPolicy              If TRUE, indicates that the request originates
 199                                   from the boot manager, and that the boot
 200                                   manager is attempting to load FilePath as a
 201                                   boot selection.
 202   @param  Pe32Handle              The handle of PE32 image
 203   @param  Image                   PE image to be loaded
 204   @param  DstBuffer               The buffer to store the image
 205   @param  EntryPoint              A pointer to the entry point
 206   @param  Attribute               The bit mask of attributes to set for the load
 207                                   PE image
 208
 209   @retval EFI_SUCCESS             The file was loaded, relocated, and invoked
 210   @retval EFI_OUT_OF_RESOURCES    There was not enough memory to load and
 211                                   relocate the PE/COFF file
 212   @retval EFI_INVALID_PARAMETER   Invalid parameter
 213   @retval EFI_BUFFER_TOO_SMALL    Buffer for image is too small
 214
 215 **/
 216 EFI_STATUS
 217 CoreLoadPeImage (
 218   IN  BOOLEAN                    BootPolicy,
 219   IN  VOID                       *Pe32Handle,
 220   IN  LOADED_IMAGE_PRIVATE_DATA  *Image,
 221   IN  EFI_PHYSICAL_ADDRESS       DstBuffer   OPTIONAL,
 222   OUT EFI_PHYSICAL_ADDRESS       *EntryPoint  OPTIONAL,
 223   IN  UINT32                     Attribute
 224   )
 225 ;
 226
 227
 228 /**
 229   Get the image's private data from its handle.
 230
 231   @param  ImageHandle             The image handle
 232
 233   @return Return the image private data associated with ImageHandle.
 234
 235 **/
 236 LOADED_IMAGE_PRIVATE_DATA *
 237 CoreLoadedImageInfo (
 238   IN EFI_HANDLE  ImageHandle
 239   )
 240 ;
 241
 242
 243 /**
 244   Unloads EFI image from memory.
 245
 246   @param  Image                   EFI image
 247   @param  FreePage                Free allocated pages
 248
 249 **/
 250 VOID
 251 CoreUnloadAndCloseImage (
 252   IN LOADED_IMAGE_PRIVATE_DATA  *Image,
 253   IN BOOLEAN                    FreePage
 254   )
 255 ;
 256
 257
 258 //
 259 // Exported Image functions
 260 //
 261
 262
 263 /**
 264   Loads an EFI image into memory and returns a handle to the image with extended parameters.
 265
 266   @param  This                    Calling context
 267   @param  ParentImageHandle       The caller's image handle.
 268   @param  FilePath                The specific file path from which the image is
 269                                   loaded.
 270   @param  SourceBuffer            If not NULL, a pointer to the memory location
 271                                   containing a copy of the image to be loaded.
 272   @param  SourceSize              The size in bytes of SourceBuffer.
 273   @param  DstBuffer               The buffer to store the image.
 274   @param  NumberOfPages           For input, specifies the space size of the
 275                                   image by caller if not NULL. For output,
 276                                   specifies the actual space size needed.
 277   @param  ImageHandle             Image handle for output.
 278   @param  EntryPoint              Image entry point for output.
 279   @param  Attribute               The bit mask of attributes to set for the load
 280                                   PE image.
 281
 282   @retval EFI_SUCCESS             The image was loaded into memory.
 283   @retval EFI_NOT_FOUND           The FilePath was not found.
 284   @retval EFI_INVALID_PARAMETER   One of the parameters has an invalid value.
 285   @retval EFI_UNSUPPORTED         The image type is not supported, or the device
 286                                   path cannot be parsed to locate the proper
 287                                   protocol for loading the file.
 288   @retval EFI_OUT_OF_RESOURCES    Image was not loaded due to insufficient
 289                                   resources.
 290
 291 **/
 292 EFI_STATUS
 293 EFIAPI
 294 CoreLoadImageEx (
 295   IN EFI_PE32_IMAGE_PROTOCOL           *This,
 296   IN  EFI_HANDLE                       ParentImageHandle,
 297   IN  EFI_DEVICE_PATH_PROTOCOL         *FilePath,
 298   IN  VOID                             *SourceBuffer       OPTIONAL,
 299   IN  UINTN                            SourceSize,
 300   IN  EFI_PHYSICAL_ADDRESS             DstBuffer           OPTIONAL,
 301   OUT UINTN                            *NumberOfPages      OPTIONAL,
 302   OUT EFI_HANDLE                       *ImageHandle,
 303   OUT EFI_PHYSICAL_ADDRESS             *EntryPoint         OPTIONAL,
 304   IN  UINT32                           Attribute
 305   )
 306 ;
 307
 308
 309 /**
 310   Unload the specified image.
 311
 312   @param  This                    Indicates the calling context.
 313   @param  ImageHandle             The specified image handle.
 314
 315   @retval EFI_INVALID_PARAMETER   Image handle is NULL.
 316   @retval EFI_UNSUPPORTED         Attempt to unload an unsupported image.
 317   @retval EFI_SUCCESS             Image successfully unloaded.
 318
 319 **/
 320 EFI_STATUS
 321 EFIAPI
 322 CoreUnloadImageEx (
 323   IN EFI_PE32_IMAGE_PROTOCOL            *This,
 324   IN EFI_HANDLE                         ImageHandle
 325   )
 326 ;
 327 #endif