MdeModulePkg/Core/Dxe/Image/Image.h

   1 /** @file
   2   Data structure and functions to load and unload PeImage.
   3
   4 Copyright (c) 2006 - 2011, Intel Corporation. All rights reserved.<BR>
   5 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   /// Status returned by LoadImage() service.
  62   EFI_STATUS                  LoadImageStatus;
  63 } LOADED_IMAGE_PRIVATE_DATA;
  64
  65 #define LOADED_IMAGE_PRIVATE_DATA_FROM_THIS(a) \
  66           CR(a, LOADED_IMAGE_PRIVATE_DATA, Info, LOADED_IMAGE_PRIVATE_DATA_SIGNATURE)
  67
  68
  69 #define LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE  SIGNATURE_32('l','p','e','i')
  70
  71 typedef struct {
  72   UINTN                       Signature;
  73   /// Image handle
  74   EFI_HANDLE                  Handle;
  75   EFI_PE32_IMAGE_PROTOCOL     Pe32Image;
  76 } LOAD_PE32_IMAGE_PRIVATE_DATA;
  77
  78 #define LOAD_PE32_IMAGE_PRIVATE_DATA_FROM_THIS(a) \
  79           CR(a, LOAD_PE32_IMAGE_PRIVATE_DATA, Pe32Image, LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE)
  80
  81
  82 //
  83 // Private Data Types
  84 //
  85 #define IMAGE_FILE_HANDLE_SIGNATURE       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   Loads an EFI image into memory and returns a handle to the image with extended parameters.
  95
  96   @param  This                    Calling context
  97   @param  ParentImageHandle       The caller's image handle.
  98   @param  FilePath                The specific file path from which the image is
  99                                   loaded.
 100   @param  SourceBuffer            If not NULL, a pointer to the memory location
 101                                   containing a copy of the image to be loaded.
 102   @param  SourceSize              The size in bytes of SourceBuffer.
 103   @param  DstBuffer               The buffer to store the image.
 104   @param  NumberOfPages           For input, specifies the space size of the
 105                                   image by caller if not NULL. For output,
 106                                   specifies the actual space size needed.
 107   @param  ImageHandle             Image handle for output.
 108   @param  EntryPoint              Image entry point for output.
 109   @param  Attribute               The bit mask of attributes to set for the load
 110                                   PE image.
 111
 112   @retval EFI_SUCCESS             The image was loaded into memory.
 113   @retval EFI_NOT_FOUND           The FilePath was not found.
 114   @retval EFI_INVALID_PARAMETER   One of the parameters has an invalid value.
 115   @retval EFI_UNSUPPORTED         The image type is not supported, or the device
 116                                   path cannot be parsed to locate the proper
 117                                   protocol for loading the file.
 118   @retval EFI_OUT_OF_RESOURCES    Image was not loaded due to insufficient
 119                                   resources.
 120   @retval EFI_LOAD_ERROR          Image was not loaded because the image format was corrupt or not
 121                                   understood.
 122   @retval EFI_DEVICE_ERROR        Image was not loaded because the device returned a read error.
 123   @retval EFI_ACCESS_DENIED       Image was not loaded because the platform policy prohibits the
 124                                   image from being loaded. NULL is returned in *ImageHandle.
 125   @retval EFI_SECURITY_VIOLATION  Image was loaded and an ImageHandle was created with a
 126                                   valid EFI_LOADED_IMAGE_PROTOCOL. However, the current
 127                                   platform policy specifies that the image should not be started.
 128
 129 **/
 130 EFI_STATUS
 131 EFIAPI
 132 CoreLoadImageEx (
 133   IN  EFI_PE32_IMAGE_PROTOCOL          *This,
 134   IN  EFI_HANDLE                       ParentImageHandle,
 135   IN  EFI_DEVICE_PATH_PROTOCOL         *FilePath,
 136   IN  VOID                             *SourceBuffer       OPTIONAL,
 137   IN  UINTN                            SourceSize,
 138   IN  EFI_PHYSICAL_ADDRESS             DstBuffer           OPTIONAL,
 139   OUT UINTN                            *NumberOfPages      OPTIONAL,
 140   OUT EFI_HANDLE                       *ImageHandle,
 141   OUT EFI_PHYSICAL_ADDRESS             *EntryPoint         OPTIONAL,
 142   IN  UINT32                           Attribute
 143   );
 144
 145
 146 /**
 147   Unload the specified image.
 148
 149   @param  This                    Indicates the calling context.
 150   @param  ImageHandle             The specified image handle.
 151
 152   @retval EFI_INVALID_PARAMETER   Image handle is NULL.
 153   @retval EFI_UNSUPPORTED         Attempt to unload an unsupported image.
 154   @retval EFI_SUCCESS             Image successfully unloaded.
 155
 156 **/
 157 EFI_STATUS
 158 EFIAPI
 159 CoreUnloadImageEx (
 160   IN EFI_PE32_IMAGE_PROTOCOL  *This,
 161   IN EFI_HANDLE                         ImageHandle
 162   );
 163 #endif