MdeModulePkg/Include/Protocol/LoadPe32Image.h

   1 /** @file
   2
   3   Load Pe32 Image protocol enables loading and unloading EFI images into memory and executing those images.
   4   This protocol uses File Device Path to get an EFI image.
   5
   6 Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   7 This program and the accompanying materials are licensed and made available under
   8 the terms and conditions of the BSD License that accompanies this distribution.
   9 The full text of the license may be found at
  10 http://opensource.org/licenses/bsd-license.php.
  11
  12 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  13 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  14
  15 **/
  16
  17 #ifndef __LOAD_PE32_IMAGE_H__
  18 #define __LOAD_PE32_IMAGE_H__
  19
  20 #define PE32_IMAGE_PROTOCOL_GUID  \
  21   {0x5cb5c776,0x60d5,0x45ee,{0x88,0x3c,0x45,0x27,0x8,0xcd,0x74,0x3f }}
  22
  23 #define EFI_LOAD_PE_IMAGE_ATTRIBUTE_NONE                                 0x00
  24 #define EFI_LOAD_PE_IMAGE_ATTRIBUTE_RUNTIME_REGISTRATION                 0x01
  25 #define EFI_LOAD_PE_IMAGE_ATTRIBUTE_DEBUG_IMAGE_INFO_TABLE_REGISTRATION  0x02
  26
  27 typedef struct _EFI_PE32_IMAGE_PROTOCOL   EFI_PE32_IMAGE_PROTOCOL;
  28
  29 /**
  30
  31   Loads an EFI image into memory and returns a handle to the image with extended parameters.
  32
  33   @param  This                The pointer to the LoadPe32Image protocol instance
  34   @param  ParentImageHandle   The caller's image handle.
  35   @param  FilePath            The specific file path from which the image is loaded.
  36   @param  SourceBuffer        If not NULL, a pointer to the memory location containing a copy of
  37                               the image to be loaded.
  38   @param  SourceSize          The size in bytes of SourceBuffer.
  39   @param  DstBuffer           The buffer to store the image.
  40   @param  NumberOfPages       For input, specifies the space size of the image by caller if not NULL.
  41                               For output, specifies the actual space size needed.
  42   @param  ImageHandle         The image handle for output.
  43   @param  EntryPoint          The image entry point for output.
  44   @param  Attribute           The bit mask of attributes to set for the load PE image.
  45
  46   @retval EFI_SUCCESS           The image was loaded into memory.
  47   @retval EFI_NOT_FOUND         The FilePath was not found.
  48   @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.
  49   @retval EFI_UNSUPPORTED       The image type is not supported, or the device path cannot be
  50                                 parsed to locate the proper protocol for loading the file.
  51   @retval EFI_OUT_OF_RESOURCES  The image was not loaded due to insufficient memory resources.
  52   @retval EFI_LOAD_ERROR        Image was not loaded because the image format was corrupt or not
  53                                 understood.
  54   @retval EFI_DEVICE_ERROR      Image was not loaded because the device returned a read error.
  55   @retval EFI_ACCESS_DENIED     Image was not loaded because the platform policy prohibits the
  56                                 image from being loaded. NULL is returned in *ImageHandle.
  57   @retval EFI_SECURITY_VIOLATION Image was loaded and an ImageHandle was created with a
  58                                 valid EFI_LOADED_IMAGE_PROTOCOL. However, the current
  59                                 platform policy specifies that the image should not be started.
  60 **/
  61 typedef
  62 EFI_STATUS
  63 (EFIAPI *LOAD_PE_IMAGE)(
  64   IN EFI_PE32_IMAGE_PROTOCOL           *This,
  65   IN  EFI_HANDLE                       ParentImageHandle,
  66   IN  EFI_DEVICE_PATH_PROTOCOL         *FilePath,
  67   IN  VOID                             *SourceBuffer       OPTIONAL,
  68   IN  UINTN                            SourceSize,
  69   IN  EFI_PHYSICAL_ADDRESS             DstBuffer           OPTIONAL,
  70   IN OUT UINTN                         *NumberOfPages      OPTIONAL,
  71   OUT EFI_HANDLE                       *ImageHandle,
  72   OUT EFI_PHYSICAL_ADDRESS             *EntryPoint         OPTIONAL,
  73   IN  UINT32                           Attribute
  74   );
  75
  76 /**
  77
  78   Unload the specified image.
  79
  80   @param  This             The pointer to the LoadPe32Image protocol instance
  81   @param  ImageHandle      The specified image handle to be unloaded.
  82
  83   @retval EFI_INVALID_PARAMETER Image handle is NULL.
  84   @retval EFI_UNSUPPORTED       Attempted to unload an unsupported image.
  85   @retval EFI_SUCCESS           The image successfully unloaded.
  86
  87 --*/
  88 typedef
  89 EFI_STATUS
  90 (EFIAPI *UNLOAD_PE_IMAGE)(
  91   IN EFI_PE32_IMAGE_PROTOCOL          *This,
  92   IN EFI_HANDLE                       ImageHandle
  93   );
  94
  95 struct _EFI_PE32_IMAGE_PROTOCOL {
  96   LOAD_PE_IMAGE     LoadPeImage;
  97   UNLOAD_PE_IMAGE   UnLoadPeImage;
  98 };
  99
 100 extern EFI_GUID gEfiLoadPeImageProtocolGuid;
 101
 102 #endif
 103