Package ghidra.app.util.bin.format.elf.relocation

# Class ElfRelocationHandler

java.lang.Object
ghidra.app.util.bin.format.elf.relocation.ElfRelocationHandler

All Implemented Interfaces:
  `ExtensionPoint`

Direct Known Subclasses:
  `AbstractElfRelocationHandler`

public abstract class ElfRelocationHandler extends Object implements ExtensionPoint
NOTE: ELF relocation handler implementations should extend `AbstractElfRelocationHandler` which now uses `ElfRelocationType` enum values instead of simple constants. This class may transition to an interface in the future. This abstract class remains exposed for backward compatibility with older implementations.
`ElfRelocationHandler` provides the base class for processor specific ELF relocation handlers. Implementations may only specify a public default constructor as they will be identified and instatiated by the `ClassSearcher`. As such their name must end with "ElfRelocationHandler" (e.g., MyProc_ElfRelocationHandler).

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final String`
  `GOT_BLOCK_NAME`
  Fabricated Global Offset Table (GOT) name/prefix to be used when processing an object module and a GOT must be fabricated to allow relocation processing.

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `ElfRelocationHandler()`
  Deprecated, for removal: This API element is subject to removal in a future version.
  extending `AbstractElfRelocationHandler` in conjunction with the use of a processor-specific `ElfRelocationType` enum is now preferred.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `applyComponentOffsetPointer(Program program, Address addr, long componentOffset)`
  Apply a pointer-typedef with a specified component-offset if specified address is not contained within an execute block.
  `static void`
  `bookmarkNoHandlerError(Program program, Address relocationAddress, int typeId, int symbolIndex, String symbolName)`
  Generate error bookmark at relocationAddress indicating a missing relocation handler.
  `static void`
  `bookmarkUnsupportedRelr(Program program, Address relocationAddress, int symbolIndex, String symbolName)`
  Generate error bookmark at relocationAddress indicating an unsupported RELR relocation.
  `abstract boolean`
  `canRelocate(ElfHeader elf)`
  `protected ElfRelocationContext`
  `createRelocationContext(ElfLoadHelper loadHelper, Map<ElfSymbol,Address> symbolMap)`
  Relocation context for a specific Elf image and relocation table.
  `int`
  `getRelrRelocationType()`
  Get the architecture-specific relative relocation type which should be applied to RELR relocations.
  `static void`
  `markAsError(Program program, Address relocationAddress, int typeId, int symbolIndex, String symbolName, String msg, MessageLog log)`
  Generate error log entry and bookmark at relocationAddress
  `protected void`
  `markAsError(Program program, Address relocationAddress, int typeId, String symbolName, int symbolIndex, String msg, MessageLog log)`
  Generate error log entry and bookmark at relocationAddress where relocation failed to be applied.
  `static void`
  `markAsError(Program program, Address relocationAddress, long typeId, String symbolName, String msg, MessageLog log)`
  Deprecated.
  `static void`
  `markAsError(Program program, Address relocationAddress, String type, String symbolName, String msg, MessageLog log)`
  Deprecated.
  `protected void`
  `markAsUnhandled(Program program, Address relocationAddress, int typeId, String symbolName, int symbolIndex, MessageLog log)`
  Generate error log entry and bookmark at relocationAddress indicating an unhandled relocation.
  `static void`
  `markAsUnhandled(Program program, Address relocationAddress, long typeId, long symbolIndex, String symbolName, MessageLog log)`
  Deprecated.
  `protected void`
  `markAsWarning(Program program, Address relocationAddress, int typeId, String symbolName, int symbolIndex, String msg, MessageLog log)`
  Generate warning log entry and bookmark at relocationAddress where relocation failed to be applied.
  `static void`
  `markAsWarning(Program program, Address relocationAddress, String type, String symbolName, int symbolIndex, String msg, MessageLog log)`
  Deprecated.
  `static void`
  `markAsWarning(Program program, Address relocationAddress, String type, String msg, MessageLog log)`
  Deprecated.
  `protected abstract RelocationResult`
  `relocate(ElfRelocationContext elfRelocationContext, ElfRelocation relocation, Address relocationAddress)`
  Perform relocation fixup.
  `static void`
  `warnExternalOffsetRelocation(Program program, Address relocationAddress, Address symbolAddr, String symbolName, long adjustment, MessageLog log)`
  Determine if symbolAddr is contained within the EXTERNAL block with a non-zero adjustment.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### GOT_BLOCK_NAME

    public static final String GOT_BLOCK_NAME
    Fabricated Global Offset Table (GOT) name/prefix to be used when processing an object module and a GOT must be fabricated to allow relocation processing.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### ElfRelocationHandler

    @Deprecated(since="11.1", forRemoval=true) protected ElfRelocationHandler()
    Deprecated, for removal: This API element is subject to removal in a future version.
    extending `AbstractElfRelocationHandler` in conjunction with the use of a processor-specific `ElfRelocationType` enum is now preferred.
    Default abstract constructor for an `ElfRelocationHandler`.

- ## Method Details

  - ### canRelocate

    public abstract boolean canRelocate(ElfHeader elf)

  - ### getRelrRelocationType

    public int getRelrRelocationType()
    Get the architecture-specific relative relocation type which should be applied to RELR relocations. The default implementation returns 0 which indicates RELR is unsupported.
    Returns:
      RELR relocation type ID value

  - ### createRelocationContext

    protected ElfRelocationContext createRelocationContext(ElfLoadHelper loadHelper, Map<ElfSymbol,Address> symbolMap)
    Relocation context for a specific Elf image and relocation table. The relocation context is used to process relocations and manage any data required to process relocations.
    Parameters:
      `loadHelper` - Elf load helper
      `symbolMap` - Elf symbol placement map
    Returns:
      relocation context or null if unsupported

  - ### relocate

    protected abstract RelocationResult relocate(ElfRelocationContext elfRelocationContext, ElfRelocation relocation, Address relocationAddress) throws MemoryAccessException, NotFoundException
    Perform relocation fixup.
    IMPORTANT: this class must be overriden if this implementation does not specify an `ElfRelocationType` enum class (see `ElfRelocationHandler()`).
    Parameters:
      `elfRelocationContext` - relocation context
      `relocation` - ELF relocation
      `relocationAddress` - relocation target address (fixup location)
    Returns:
      applied relocation result (conveys status and applied byte-length)
    Throws:
      `MemoryAccessException` - memory access failure
      `NotFoundException` - NOTE: use of this exception is deprecated and should not be thrown

  - ### markAsUnhandled

    protected void markAsUnhandled(Program program, Address relocationAddress, int typeId, String symbolName, int symbolIndex, MessageLog log)
    Generate error log entry and bookmark at relocationAddress indicating an unhandled relocation.
    Parameters:
      `program` - program
      `relocationAddress` - relocation address to be bookmarked
      `typeId` - relocation type ID value
      `symbolName` - associated symbol name
      `symbolIndex` - symbol index within symbol table (-1 to ignore)
      `log` - import log

  - ### markAsError

    protected void markAsError(Program program, Address relocationAddress, int typeId, String symbolName, int symbolIndex, String msg, MessageLog log)
    Generate error log entry and bookmark at relocationAddress where relocation failed to be applied.
    Parameters:
      `program` - program
      `relocationAddress` - relocation address to be bookmarked
      `typeId` - relocation type ID value
      `symbolName` - associated symbol name
      `symbolIndex` - symbol index within symbol table (-1 to ignore)
      `msg` - error message
      `log` - import log

  - ### markAsWarning

    protected void markAsWarning(Program program, Address relocationAddress, int typeId, String symbolName, int symbolIndex, String msg, MessageLog log)
    Generate warning log entry and bookmark at relocationAddress where relocation failed to be applied.
    Parameters:
      `program` - program
      `relocationAddress` - relocation address to be bookmarked
      `typeId` - relocation type ID value
      `symbolName` - associated symbol name
      `symbolIndex` - symbol index within symbol table (-1 to ignore)
      `msg` - error message
      `log` - import log

  - ### applyComponentOffsetPointer

    public static void applyComponentOffsetPointer(Program program, Address addr, long componentOffset)
    Apply a pointer-typedef with a specified component-offset if specified address is not contained within an execute block.
    Parameters:
      `program` - program
      `addr` - address where data should be applied
      `componentOffset` - component offset

  - ### warnExternalOffsetRelocation

    public static void warnExternalOffsetRelocation(Program program, Address relocationAddress, Address symbolAddr, String symbolName, long adjustment, MessageLog log)
    Determine if symbolAddr is contained within the EXTERNAL block with a non-zero adjustment. If so, relocationAddress will be marked with a `EXTERNAL Data Elf Relocation with pointer-offset` warning or error bookmark. Bookmark and logged message will be conveyed as an error if relocationAddress resides within an executable memory block.
    NOTE: This method should only be invoked when the symbol offset will be adjusted with a non-zero value (i.e., addend).
    Parameters:
      `program` - program
      `relocationAddress` - relocation address to be bookmarked if EXTERNAL block relocation
      `symbolAddr` - symbol address correspondng to relocation (may be null)
      `symbolName` - symbol name (may not be null if symbolAddr is not null)
      `adjustment` - relocation symbol offset adjustment/addend
      `log` - import log

  - ### bookmarkNoHandlerError

    public static void bookmarkNoHandlerError(Program program, Address relocationAddress, int typeId, int symbolIndex, String symbolName)
    Generate error bookmark at relocationAddress indicating a missing relocation handler.
    Parameters:
      `program` - program
      `relocationAddress` - relocation address to be bookmarked
      `typeId` - relocation type ID value
      `symbolIndex` - associated symbol index within symbol table (-1 to ignore)
      `symbolName` - associated symbol name

  - ### bookmarkUnsupportedRelr

    public static void bookmarkUnsupportedRelr(Program program, Address relocationAddress, int symbolIndex, String symbolName)
    Generate error bookmark at relocationAddress indicating an unsupported RELR relocation.
    Parameters:
      `program` - program
      `relocationAddress` - relocation address to be bookmarked
      `symbolIndex` - associated symbol index within symbol table (-1 to ignore)
      `symbolName` - associated symbol name

  - ### markAsError

    public static void markAsError(Program program, Address relocationAddress, int typeId, int symbolIndex, String symbolName, String msg, MessageLog log)
    Generate error log entry and bookmark at relocationAddress
    Parameters:
      `program` - program
      `relocationAddress` - relocation address to be bookmarked
      `typeId` - relocation type
      `symbolIndex` - associated symbol index within symbol table (-1 to ignore)
      `symbolName` - associated symbol name
      `msg` - error messge
      `log` - import log

  - ### markAsUnhandled

    @Deprecated public static void markAsUnhandled(Program program, Address relocationAddress, long typeId, long symbolIndex, String symbolName, MessageLog log)
    Deprecated.
    Generate error log entry and bookmark at relocationAddress indicating an unhandled relocation.
    Parameters:
      `program` - program
      `relocationAddress` - relocation address to be bookmarked
      `typeId` - relocation type ID value (limited to int value).
      `symbolIndex` - associated symbol index within symbol table (limited to int value).
      `symbolName` - associated symbol name
      `log` - import log

  - ### markAsWarning

    @Deprecated public static void markAsWarning(Program program, Address relocationAddress, String type, String msg, MessageLog log)
    Deprecated.
    Generate warning log entry and bookmark at relocationAddress
    Parameters:
      `program` - program
      `relocationAddress` - relocation address to be bookmarked
      `type` - relocation type ID name
      `msg` - message associated with warning
      `log` - import log

  - ### markAsWarning

    @Deprecated public static void markAsWarning(Program program, Address relocationAddress, String type, String symbolName, int symbolIndex, String msg, MessageLog log)
    Deprecated.
    Generate warning log entry and bookmark at relocationAddress
    Parameters:
      `program` - program
      `relocationAddress` - relocation address to be bookmarked
      `type` - relocation type ID name
      `symbolName` - symbol name
      `symbolIndex` - symbol index (-1 to ignore)
      `msg` - message associated with warning
      `log` - import log

  - ### markAsError

    @Deprecated public static void markAsError(Program program, Address relocationAddress, long typeId, String symbolName, String msg, MessageLog log)
    Deprecated.
    Generate error log entry and bookmark at relocationAddress
    Parameters:
      `program` - program
      `relocationAddress` - relocation address to be bookmarked
      `typeId` - relocation type ID value
      `symbolName` - associated symbol name
      `msg` - error messge
      `log` - import log

  - ### markAsError

    @Deprecated public static void markAsError(Program program, Address relocationAddress, String type, String symbolName, String msg, MessageLog log)
    Deprecated.
    Generate error log entry and bookmark at relocationAddress
    Parameters:
      `program` - program
      `relocationAddress` - relocation address to be bookmarked
      `type` - relocation type ID name
      `symbolName` - associated symbol name
      `msg` - additional error message
      `log` - import log