MdeModulePkg/Core/Dxe/Image.h

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