MdeModulePkg/Core/Dxe/Image/Image.h

   1 /** @file
   2   Data structure and functions to load and unload PeImage.
   3
   4 Copyright (c) 2006 - 2018, 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 LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE  SIGNATURE_32('l','p','e','i')
  20
  21 typedef struct {
  22   UINTN                       Signature;
  23   /// Image handle
  24   EFI_HANDLE                  Handle;
  25   EFI_PE32_IMAGE_PROTOCOL     Pe32Image;
  26 } LOAD_PE32_IMAGE_PRIVATE_DATA;
  27
  28 #define LOAD_PE32_IMAGE_PRIVATE_DATA_FROM_THIS(a) \
  29           CR(a, LOAD_PE32_IMAGE_PRIVATE_DATA, Pe32Image, LOAD_PE32_IMAGE_PRIVATE_DATA_SIGNATURE)
  30
  31
  32 //
  33 // Private Data Types
  34 //
  35 #define IMAGE_FILE_HANDLE_SIGNATURE       SIGNATURE_32('i','m','g','f')
  36 typedef struct {
  37   UINTN               Signature;
  38   BOOLEAN             FreeBuffer;
  39   VOID                *Source;
  40   UINTN               SourceSize;
  41 } IMAGE_FILE_HANDLE;
  42
  43 /**
  44   Loads an EFI image into memory and returns a handle to the image with extended parameters.
  45
  46   @param  This                    Calling context
  47   @param  ParentImageHandle       The caller's image handle.
  48   @param  FilePath                The specific file path from which the image is
  49                                   loaded.
  50   @param  SourceBuffer            If not NULL, a pointer to the memory location
  51                                   containing a copy of the image to be loaded.
  52   @param  SourceSize              The size in bytes of SourceBuffer.
  53   @param  DstBuffer               The buffer to store the image.
  54   @param  NumberOfPages           For input, specifies the space size of the
  55                                   image by caller if not NULL. For output,
  56                                   specifies the actual space size needed.
  57   @param  ImageHandle             Image handle for output.
  58   @param  EntryPoint              Image entry point for output.
  59   @param  Attribute               The bit mask of attributes to set for the load
  60                                   PE image.
  61
  62   @retval EFI_SUCCESS             The image was loaded into memory.
  63   @retval EFI_NOT_FOUND           The FilePath was not found.
  64   @retval EFI_INVALID_PARAMETER   One of the parameters has an invalid value.
  65   @retval EFI_UNSUPPORTED         The image type is not supported, or the device
  66                                   path cannot be parsed to locate the proper
  67                                   protocol for loading the file.
  68   @retval EFI_OUT_OF_RESOURCES    Image was not loaded due to insufficient
  69                                   resources.
  70   @retval EFI_LOAD_ERROR          Image was not loaded because the image format was corrupt or not
  71                                   understood.
  72   @retval EFI_DEVICE_ERROR        Image was not loaded because the device returned a read error.
  73   @retval EFI_ACCESS_DENIED       Image was not loaded because the platform policy prohibits the
  74                                   image from being loaded. NULL is returned in *ImageHandle.
  75   @retval EFI_SECURITY_VIOLATION  Image was loaded and an ImageHandle was created with a
  76                                   valid EFI_LOADED_IMAGE_PROTOCOL. However, the current
  77                                   platform policy specifies that the image should not be started.
  78
  79 **/
  80 EFI_STATUS
  81 EFIAPI
  82 CoreLoadImageEx (
  83   IN  EFI_PE32_IMAGE_PROTOCOL          *This,
  84   IN  EFI_HANDLE                       ParentImageHandle,
  85   IN  EFI_DEVICE_PATH_PROTOCOL         *FilePath,
  86   IN  VOID                             *SourceBuffer       OPTIONAL,
  87   IN  UINTN                            SourceSize,
  88   IN  EFI_PHYSICAL_ADDRESS             DstBuffer           OPTIONAL,
  89   OUT UINTN                            *NumberOfPages      OPTIONAL,
  90   OUT EFI_HANDLE                       *ImageHandle,
  91   OUT EFI_PHYSICAL_ADDRESS             *EntryPoint         OPTIONAL,
  92   IN  UINT32                           Attribute
  93   );
  94
  95
  96 /**
  97   Unload the specified image.
  98
  99   @param  This                    Indicates the calling context.
 100   @param  ImageHandle             The specified image handle.
 101
 102   @retval EFI_INVALID_PARAMETER   Image handle is NULL.
 103   @retval EFI_UNSUPPORTED         Attempt to unload an unsupported image.
 104   @retval EFI_SUCCESS             Image successfully unloaded.
 105
 106 **/
 107 EFI_STATUS
 108 EFIAPI
 109 CoreUnloadImageEx (
 110   IN EFI_PE32_IMAGE_PROTOCOL  *This,
 111   IN EFI_HANDLE                         ImageHandle
 112   );
 113 #endif