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

# Interface ElfLoadHelper

public interface ElfLoadHelper
`ElfLoadHelper` exposes loader methods useful to ElfExtension implementations.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `addArtificialRelocTableEntry(Address address, int length)`
  Add an artificial relocation table entry if none previously existed for the specified address.
  `AddressRange`
  `allocateLinkageBlock(int alignment, int size, String purpose)`
  Get a free aligned address range within the program's memory block structure to facilitate dynamic memory block allocation requirements to support relocation processing (e.g., fake EXTERNAL memory block, generated GOT for object modules, etc.).
  `Data`
  `createData(Address address, DataType dt)`
  Create a data item using the specified data type
  `Function`
  `createExternalFunctionLinkage(String name, Address functionAddr, Address indirectPointerAddr)`
  Create an external function within the UNKNOWN space and a corresponding thunk at the internalFunctionAddr.
  `Function`
  `createOneByteFunction(String name, Address address, boolean isEntry)`
  Create a one-byte function, so that when the code is analyzed, it will be disassembled, and the function created with the correct body.
  `Symbol`
  `createSymbol(Address addr, String name, boolean isPrimary, boolean pinAbsolute, Namespace namespace)`
  Create the specified label symbol within the program.
  `Data`
  `createUndefinedData(Address address, int length)`
  Create an undefined data item to reserve the location as data, without specifying the type.
  `Address`
  `findLoadAddress(MemoryLoadable section, long byteOffsetWithinSection)`
  Find the program address at which a specified offset within a section or segment was loaded/resolved.
  `Address`
  `getDefaultAddress(long addressableWordOffset)`
  Get the program address for an addressableWordOffset within the default address space.
  `ElfHeader`
  `getElfHeader()`
  Get ELF Header object
  `Address`
  `getElfSymbolAddress(ElfSymbol elfSymbol)`
  Get the memory address of a previously resolved symbol
  `Long`
  `getGOTValue()`
  Returns the appropriate .got (Global Offset Table) section address using the DT_PLTGOT value defined in the .dynamic section.
  `long`
  `getImageBaseWordAdjustmentOffset()`
  Get the program image base offset adjustment.
  `MessageLog`
  `getLog()`
  Get the message log
  `<T> T`
  `getOption(String optionName, T defaultValue)`
  Get an import processing option value
  `long`
  `getOriginalValue(Address addr, boolean signExtend)`
  Get the original memory value at the specified address if a relocation was applied at the specified address (not containing).
  `Program`
  `getProgram()`
  Get program object
  `void`
  `log(String msg)`
  Output loader log message
  `void`
  `log(Throwable t)`
  Output loader log message.
  `void`
  `markAsCode(Address address)`
  Mark this location as code in the CodeMap.
  `void`
  `setElfSymbolAddress(ElfSymbol elfSymbol, Address address)`
  Add specified elfSymbol to the loader symbol map after its program address has been assigned

- ## Method Details

  - ### getProgram

    Program getProgram()
    Get program object
    Returns:
      program object

  - ### getOption

    <T> T getOption(String optionName, T defaultValue)
    Get an import processing option value
    Type Parameters:
      `T` - class of option value (e.g., String, Boolean, etc.)
    Parameters:
      `optionName` - option name
      `defaultValue` - default option value which also establishes expected value type
    Returns:
      option value

  - ### getElfHeader

    ElfHeader getElfHeader()
    Get ELF Header object
    Returns:
      ELF Header object

  - ### getLog

    MessageLog getLog()
    Get the message log
    Returns:
      message log

  - ### log

    void log(String msg)
    Output loader log message
    Parameters:
      `msg` - text message

  - ### log

    void log(Throwable t)
    Output loader log message.
    Parameters:
      `t` - exception/throwable error

  - ### markAsCode

    void markAsCode(Address address)
    Mark this location as code in the CodeMap. The analyzers will pick this up and disassemble the code.
    Parameters:
      `address` - code memory address to be marked

  - ### createOneByteFunction

    Function createOneByteFunction(String name, Address address, boolean isEntry)
    Create a one-byte function, so that when the code is analyzed, it will be disassembled, and the function created with the correct body.
    Parameters:
      `name` - name of function or null for default (or label already applied)
      `address` - address of function
      `isEntry` - mark function as entry point if true
    Returns:
      new or existing function.

  - ### createExternalFunctionLinkage

    Function createExternalFunctionLinkage(String name, Address functionAddr, Address indirectPointerAddr)
    Create an external function within the UNKNOWN space and a corresponding thunk at the internalFunctionAddr. If the functionAddr and/or indirectPointerAddr has a symbol with `<name>` it will be removed so as not to replicate the external function name.
    Parameters:
      `name` - external function name
      `functionAddr` - location of thunk function (memory address only)
      `indirectPointerAddr` - if not null a pointer to functionAddr will be written (size of pointer based 32 or 64 bits based upon ELF size). Memory must exist and will be converted to initialized if needed.
    Returns:
      thunk function or null if failure occurred

  - ### createUndefinedData

    Data createUndefinedData(Address address, int length)
    Create an undefined data item to reserve the location as data, without specifying the type. If `ElfLoaderOptionsFactory.applyUndefinedSymbolData(java.util.List)` returns false data will not be applied and null will be returned.
    Parameters:
      `address` - location of undefined data to create
      `length` - size of the undefined data item
    Returns:
      `Data` which was created or null if conflict occurs or disabled by option

  - ### createData

    Data createData(Address address, DataType dt)
    Create a data item using the specified data type
    Parameters:
      `address` - location of undefined data to create
      `dt` - data type
    Returns:
      `Data` which was created or null if conflict occurs

  - ### setElfSymbolAddress

    void setElfSymbolAddress(ElfSymbol elfSymbol, Address address)
    Add specified elfSymbol to the loader symbol map after its program address has been assigned
    Parameters:
      `elfSymbol` - elf symbol
      `address` - program address (may be null if not applicable)

  - ### getElfSymbolAddress

    Address getElfSymbolAddress(ElfSymbol elfSymbol)
    Get the memory address of a previously resolved symbol
    Parameters:
      `elfSymbol` - elf symbol
    Returns:
      memory address or null if unknown

  - ### createSymbol

    Symbol createSymbol(Address addr, String name, boolean isPrimary, boolean pinAbsolute, Namespace namespace) throws InvalidInputException
    Create the specified label symbol within the program.
    Parameters:
      `addr` - program address
      `name` - symbol/label name
      `isPrimary` - true if is symbol should be made primary (certain name patterns excluded)
      `pinAbsolute` - true if address is absolute and should not change
      `namespace` - symbol namespace (should generally be null for global namespace)
    Returns:
      program symbol
    Throws:
      `InvalidInputException` - if an invalid name is specified

  - ### findLoadAddress

    Address findLoadAddress(MemoryLoadable section, long byteOffsetWithinSection)
    Find the program address at which a specified offset within a section or segment was loaded/resolved.
    Parameters:
      `section` - a segment or section header which was loaded to memory
      `byteOffsetWithinSection` - offset within section
    Returns:
      resolved load address or null if not loaded

  - ### getDefaultAddress

    Address getDefaultAddress(long addressableWordOffset)
    Get the program address for an addressableWordOffset within the default address space. This method is responsible for applying any program image base change imposed during the import (see `getImageBaseWordAdjustmentOffset()`.
    Parameters:
      `addressableWordOffset` - absolute word offset. The offset should already include default image base and pre-link adjustment (see `ElfHeader.adjustAddressForPrelink(long)`).
    Returns:
      memory address in default code space

  - ### getImageBaseWordAdjustmentOffset

    long getImageBaseWordAdjustmentOffset()
    Get the program image base offset adjustment. The value returned reflects the actual program image base minus the default image base (see `ElfHeader.getImageBase()`. This will generally be zero (0), unless the program image base differs from the default. It may be necessary to add this value to any pre-linked address values such as those contained with the dynamic table. (Applies to default address space only)
    Returns:
      image base adjustment value

  - ### getGOTValue

    Long getGOTValue()
    Returns the appropriate .got (Global Offset Table) section address using the DT_PLTGOT value defined in the .dynamic section. If the dynamic value is not defined, the symbol offset for _GLOBAL_OFFSET_TABLE_ will be used, otherwise null will be returned. See `ElfConstants.GOT_SYMBOL_NAME`.
    Returns:
      the .got section address offset

  - ### allocateLinkageBlock

    AddressRange allocateLinkageBlock(int alignment, int size, String purpose)

    Get a free aligned address range within the program's memory block structure to facilitate dynamic memory block allocation requirements to support relocation processing (e.g., fake EXTERNAL memory block, generated GOT for object modules, etc.). The range returned for the EXTERNAL memory block may be very large but only that portion used should be committed the program's memory map. The EXTERNAL memory block must be committed to the memory map prior to any subsequent invocations of this method

    NOTES: Additional support may be required for spaces with odd word sizes, small 16-bit default memory space, or when shared memory regions exist.

    Parameters:
      `alignment` - required byte alignment of allocated range
      `size` - size of requested allocation (size <= 0 reserved for EXTERNAL block)
      `purpose` - brief descriptive purpose of range.
    Returns:
      address range or null if no unallocated range found

  - ### getOriginalValue

    long getOriginalValue(Address addr, boolean signExtend) throws MemoryAccessException

    Get the original memory value at the specified address if a relocation was applied at the specified address (not containing). Current memory value will be returned if no relocation has been applied at specified address. The value size is either 8-bytes if `ElfHeader.is64Bit()`, otherwise it will be 4-bytes. This is primarily intended to inspect original bytes within the GOT which may have had relocations applied to them.

    Parameters:
      `addr` - memory address
      `signExtend` - if true sign-extend to long, else treat as unsigned
    Returns:
      original bytes value
    Throws:
      `MemoryAccessException` - if memory read fails

  - ### addArtificialRelocTableEntry

    boolean addArtificialRelocTableEntry(Address address, int length)
    Add an artificial relocation table entry if none previously existed for the specified address. This is intended to record original file bytes when forced modifications have been performed during the ELF import processing. A relocation type of 0 and a status of `Relocation.Status.APPLIED_OTHER` will be applied to the relocation entry. NOTE: The number of recorded original FileBytes currently ignores the specified length. However, the length is still used to verify that the intended modification region does not intersect another relocation.
    Parameters:
      `address` - relocation address
      `length` - number of bytes affected
    Returns:
      true if recorded successfully, or false if conflict with existing relocation entry and memory addressing error occurs