MdeModulePkg/Core/Dxe/Image/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 #define LOADED_IMAGE_PRIVATE_DATA_SIGNATURE   SIGNATURE_32('l','d','r','i')
  20
  21 typedef struct {
  22     UINTN                       Signature;
  23         /// Image handle
  24     EFI_HANDLE                  Handle;
  25         /// Image type
  26     UINTN                       Type;
  27         /// If entrypoint has been called
  28     BOOLEAN                     Started;
  29         /// The image's entry point
  30     EFI_IMAGE_ENTRY_POINT       EntryPoint;
  31         /// loaded image protocol
  32     EFI_LOADED_IMAGE_PROTOCOL   Info;
  33         /// Location in memory
  34     EFI_PHYSICAL_ADDRESS        ImageBasePage;
  35         /// Number of pages
  36     UINTN                       NumberOfPages;
  37         /// Original fixup data
  38     CHAR8                       *FixupData;
  39         /// Tpl of started image
  40     EFI_TPL                     Tpl;
  41         /// Status returned by started image
  42     EFI_STATUS                  Status;
  43         /// Size of ExitData from started image
  44     UINTN                       ExitDataSize;
  45         /// Pointer to exit data from started image
  46     VOID                        *ExitData;
  47         /// Pointer to pool allocation for context save/retore
  48     VOID                        *JumpBuffer;
  49         /// Pointer to buffer for context save/retore
  50     BASE_LIBRARY_JUMP_BUFFER    *JumpContext;
  51         /// Machine type from PE image
  52     UINT16                      Machine;
  53         /// EBC Protocol pointer
  54     EFI_EBC_PROTOCOL            *Ebc;
  55         /// Runtime image list
  56     EFI_RUNTIME_IMAGE_ENTRY     *RuntimeData;
  57         /// Pointer to Loaded Image Device Path Protocl
  58     EFI_DEVICE_PATH_PROTOCOL    *LoadedImageDevicePath;
  59         /// PeCoffLoader ImageContext
  60     PE_COFF_LOADER_IMAGE_CONTEXT  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 #define LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE  SIGNATURE_32('l','p','e','i')
  69
  70 typedef struct {
  71     UINTN                       Signature;
  72         /// Image handle
  73     EFI_HANDLE                  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 // Private Data Types
  83 //
  84 #define IMAGE_FILE_HANDLE_SIGNATURE       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   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   Read image file (specified by UserHandle) into user specified buffer with specified offset
 131   and length.
 132
 133   @param  UserHandle             Image file handle
 134   @param  Offset                 Offset to the source file
 135   @param  ReadSize               For input, pointer of size to read; For output,
 136                                  pointer of size actually read.
 137   @param  Buffer                 Buffer to write into
 138
 139   @retval EFI_SUCCESS            Successfully read the specified part of file
 140                                  into buffer.
 141
 142 **/
 143 EFI_STATUS
 144 EFIAPI
 145 CoreReadImageFile (
 146   IN     VOID    *UserHandle,
 147   IN     UINTN   Offset,
 148   IN OUT UINTN   *ReadSize,
 149   OUT    VOID    *Buffer
 150   );
 151
 152
 153 /**
 154   Loads an EFI image into memory and returns a handle to the image with extended parameters.
 155
 156   @param  This                    Calling context
 157   @param  ParentImageHandle       The caller's image handle.
 158   @param  FilePath                The specific file path from which the image is
 159                                   loaded.
 160   @param  SourceBuffer            If not NULL, a pointer to the memory location
 161                                   containing a copy of the image to be loaded.
 162   @param  SourceSize              The size in bytes of SourceBuffer.
 163   @param  DstBuffer               The buffer to store the image.
 164   @param  NumberOfPages           For input, specifies the space size of the
 165                                   image by caller if not NULL. For output,
 166                                   specifies the actual space size needed.
 167   @param  ImageHandle             Image handle for output.
 168   @param  EntryPoint              Image entry point for output.
 169   @param  Attribute               The bit mask of attributes to set for the load
 170                                   PE image.
 171
 172   @retval EFI_SUCCESS             The image was loaded into memory.
 173   @retval EFI_NOT_FOUND           The FilePath was not found.
 174   @retval EFI_INVALID_PARAMETER   One of the parameters has an invalid value.
 175   @retval EFI_UNSUPPORTED         The image type is not supported, or the device
 176                                   path cannot be parsed to locate the proper
 177                                   protocol for loading the file.
 178   @retval EFI_OUT_OF_RESOURCES    Image was not loaded due to insufficient
 179                                   resources.
 180
 181 **/
 182 EFI_STATUS
 183 EFIAPI
 184 CoreLoadImageEx (
 185   IN  EFI_PE32_IMAGE_PROTOCOL          *This,
 186   IN  EFI_HANDLE                       ParentImageHandle,
 187   IN  EFI_DEVICE_PATH_PROTOCOL         *FilePath,
 188   IN  VOID                             *SourceBuffer       OPTIONAL,
 189   IN  UINTN                            SourceSize,
 190   IN  EFI_PHYSICAL_ADDRESS             DstBuffer           OPTIONAL,
 191   OUT UINTN                            *NumberOfPages      OPTIONAL,
 192   OUT EFI_HANDLE                       *ImageHandle,
 193   OUT EFI_PHYSICAL_ADDRESS             *EntryPoint         OPTIONAL,
 194   IN  UINT32                           Attribute
 195   );
 196
 197
 198 /**
 199   Unload the specified image.
 200
 201   @param  This                    Indicates the calling context.
 202   @param  ImageHandle             The specified image handle.
 203
 204   @retval EFI_INVALID_PARAMETER   Image handle is NULL.
 205   @retval EFI_UNSUPPORTED         Attempt to unload an unsupported image.
 206   @retval EFI_SUCCESS             Image successfully unloaded.
 207
 208 **/
 209 EFI_STATUS
 210 EFIAPI
 211 CoreUnloadImageEx (
 212   IN EFI_PE32_IMAGE_PROTOCOL  *This,
 213   IN EFI_HANDLE                         ImageHandle
 214   );
 215 #endif