BaseTools/Source/C/Common/PeCoffLib.h

   1 /** @file
   2   Function prototypes and defines on Memory Only PE COFF loader
   3
   4   Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7 **/
   8
   9 #ifndef __BASE_PE_COFF_LIB_H__
  10 #define __BASE_PE_COFF_LIB_H__
  11
  12 //
  13 // Return status codes from the PE/COFF Loader services
  14 // BUGBUG: Find where used and see if can be replaced by RETURN_STATUS codes
  15 //
  16 #define IMAGE_ERROR_SUCCESS                      0
  17 #define IMAGE_ERROR_IMAGE_READ                   1
  18 #define IMAGE_ERROR_INVALID_PE_HEADER_SIGNATURE  2
  19 #define IMAGE_ERROR_INVALID_MACHINE_TYPE         3
  20 #define IMAGE_ERROR_INVALID_SUBSYSTEM            4
  21 #define IMAGE_ERROR_INVALID_IMAGE_ADDRESS        5
  22 #define IMAGE_ERROR_INVALID_IMAGE_SIZE           6
  23 #define IMAGE_ERROR_INVALID_SECTION_ALIGNMENT    7
  24 #define IMAGE_ERROR_SECTION_NOT_LOADED           8
  25 #define IMAGE_ERROR_FAILED_RELOCATION            9
  26 #define IMAGE_ERROR_FAILED_ICACHE_FLUSH          10
  27
  28
  29 //
  30 // PE/COFF Loader Read Function passed in by caller
  31 //
  32 typedef
  33 RETURN_STATUS
  34 (EFIAPI *PE_COFF_LOADER_READ_FILE) (
  35   IN     VOID   *FileHandle,
  36   IN     UINTN  FileOffset,
  37   IN OUT UINTN  *ReadSize,
  38   OUT    VOID   *Buffer
  39   );
  40
  41 //
  42 // Context structure used while PE/COFF image is being loaded and relocated
  43 //
  44 typedef struct {
  45   PHYSICAL_ADDRESS                  ImageAddress;
  46   UINT64                            ImageSize;
  47   PHYSICAL_ADDRESS                  DestinationAddress;
  48   PHYSICAL_ADDRESS                  EntryPoint;
  49   PE_COFF_LOADER_READ_FILE          ImageRead;
  50   VOID                              *Handle;
  51   VOID                              *FixupData;
  52   UINT32                            SectionAlignment;
  53   UINT32                            PeCoffHeaderOffset;
  54   UINT32                            DebugDirectoryEntryRva;
  55   VOID                              *CodeView;
  56   CHAR8                             *PdbPointer;
  57   UINTN                             SizeOfHeaders;
  58   UINT32                            ImageCodeMemoryType;
  59   UINT32                            ImageDataMemoryType;
  60   UINT32                            ImageError;
  61   UINTN                             FixupDataSize;
  62   UINT16                            Machine;
  63   UINT16                            ImageType;
  64   BOOLEAN                           RelocationsStripped;
  65   BOOLEAN                           IsTeImage;
  66 } PE_COFF_LOADER_IMAGE_CONTEXT;
  67
  68
  69 /**
  70   Retrieves information on a PE/COFF image
  71
  72   @param  ImageContext The context of the image being loaded
  73
  74   @retval  EFI_SUCCESS The information on the PE/COFF image was collected.
  75   @retval  EFI_INVALID_PARAMETER ImageContext is NULL.
  76   @retval  EFI_UNSUPPORTED The PE/COFF image is not supported.
  77   @retval  Otherwise The error status from reading the PE/COFF image using the
  78   ImageContext->ImageRead() function
  79
  80 **/
  81 RETURN_STATUS
  82 EFIAPI
  83 PeCoffLoaderGetImageInfo (
  84   IN OUT PE_COFF_LOADER_IMAGE_CONTEXT  *ImageContext
  85   )
  86 ;
  87
  88 /**
  89   Relocates a PE/COFF image in memory
  90
  91   @param  ImageContext Contains information on the loaded image to relocate
  92
  93   @retval EFI_SUCCESS      if the PE/COFF image was relocated
  94   @retval EFI_LOAD_ERROR   if the image is not a valid PE/COFF image
  95   @retval EFI_UNSUPPORTED  not support
  96
  97 **/
  98 RETURN_STATUS
  99 EFIAPI
 100 PeCoffLoaderRelocateImage (
 101   IN OUT PE_COFF_LOADER_IMAGE_CONTEXT  *ImageContext
 102   )
 103 ;
 104
 105 /**
 106   Loads a PE/COFF image into memory
 107
 108   @param  ImageContext Contains information on image to load into memory
 109
 110   @retval EFI_SUCCESS            if the PE/COFF image was loaded
 111   @retval EFI_BUFFER_TOO_SMALL   if the caller did not provide a large enough buffer
 112   @retval EFI_LOAD_ERROR         if the image is a runtime driver with no relocations
 113   @retval EFI_INVALID_PARAMETER  if the image address is invalid
 114
 115 **/
 116 RETURN_STATUS
 117 EFIAPI
 118 PeCoffLoaderLoadImage (
 119   IN OUT PE_COFF_LOADER_IMAGE_CONTEXT  *ImageContext
 120   )
 121 ;
 122
 123 VOID *
 124 EFIAPI
 125 PeCoffLoaderGetPdbPointer (
 126   IN VOID  *Pe32Data
 127   )
 128 ;
 129
 130 RETURN_STATUS
 131 EFIAPI
 132 PeCoffLoaderGetEntryPoint (
 133   IN  VOID  *Pe32Data,
 134   OUT VOID  **EntryPoint,
 135   OUT VOID  **BaseOfImage
 136   )
 137 ;
 138
 139 //
 140 // These functions are used by the ARM PE/COFF relocation code and by
 141 // the ELF to PE/COFF converter so that is why they are public
 142 //
 143
 144 /**
 145   Pass in a pointer to an ARM MOVT or MOVW immediate instruction and
 146   return the immediate data encoded in the instruction
 147
 148   @param  Instruction   Pointer to ARM MOVT or MOVW immediate instruction
 149
 150   @return Immediate address encoded in the instruction
 151
 152 **/
 153 UINT16
 154 EFIAPI
 155 ThumbMovtImmediateAddress (
 156   IN UINT16 *Instruction
 157   );
 158
 159 /**
 160   Update an ARM MOVT or MOVW immediate instruction immediate data.
 161
 162   @param  Instruction   Pointer to ARM MOVT or MOVW immediate instruction
 163   @param  Address       New address to patch into the instruction
 164
 165 **/
 166 VOID
 167 EFIAPI
 168 ThumbMovtImmediatePatch (
 169   IN OUT UINT16 *Instruction,
 170   IN     UINT16 Address
 171   );
 172
 173
 174 /**
 175   Pass in a pointer to an ARM MOVW/MOVT instruction pair and
 176   return the immediate data encoded in the two` instruction
 177
 178   @param  Instructions  Pointer to ARM MOVW/MOVT instruction pair
 179
 180   @return Immediate address encoded in the instructions
 181
 182 **/
 183 UINT32
 184 EFIAPI
 185 ThumbMovwMovtImmediateAddress (
 186   IN UINT16 *Instructions
 187   );
 188
 189 /**
 190   Update an ARM MOVW/MOVT immediate instruction instruction pair.
 191
 192   @param  Instructions  Pointer to ARM MOVW/MOVT instruction pair
 193   @param  Address       New address to patch into the instructions
 194 **/
 195 VOID
 196 EFIAPI
 197 ThumbMovwMovtImmediatePatch (
 198   IN OUT UINT16 *Instructions,
 199   IN     UINT32 Address
 200   );
 201
 202
 203
 204 #endif