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