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

# Class ElfLoadAdapter

java.lang.Object
ghidra.app.util.bin.format.elf.extend.ElfLoadAdapter

Direct Known Subclasses:
  `ElfExtension`

public class ElfLoadAdapter extends Object
`ElfLoadAdapter` provides the base ELF load adapter implementation which may be extended to facilitate target specific behavior.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ElfLoadAdapter()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `final void`
  `addDynamicTypes(Map<Integer,ElfDynamicType> dynamicTypeMap)`
  Add all extension specific Dynamic table entry types (e.g., DT_ prefix).
  `void`
  `addLoadOptions(ElfHeader elf, List<Option> options)`
  Add extension-specific load options
  `final void`
  `addProgramHeaderTypes(Map<Integer,ElfProgramHeaderType> programHeaderTypeMap)`
  Add all extension specific Program Header types (e.g., PT_ prefix).
  `final void`
  `addSectionHeaderTypes(HashMap<Integer,ElfSectionHeaderType> sectionHeaderTypeMap)`
  Add all extension specific Section Header types (e.g., SHT_ prefix).
  `Address`
  `calculateSymbolAddress(ElfLoadHelper elfLoadHelper, ElfSymbol elfSymbol)`
  This method allows an extension to override the default address calculation for loading a symbol.
  `boolean`
  `canHandle(ElfHeader elf)`
  Check if this extension can handle the specified elf header.
  `boolean`
  `canHandle(ElfLoadHelper elfLoadHelper)`
  Check if this extension can handle the specified elf image.
  `Address`
  `creatingFunction(ElfLoadHelper elfLoadHelper, Address functionAddress)`
  Prior to the ELF loader creating a function this method will be invoked to permit an extension to adjust the address and/or apply context to the intended location.
  `Address`
  `evaluateElfSymbol(ElfLoadHelper elfLoadHelper, ElfSymbol elfSymbol, Address address, boolean isExternal)`
  During symbol processing this method will be invoked to permit an extension to adjust the address and/or apply context to the intended symbol location.
  `long`
  `getAdjustedLoadSize(ElfProgramHeader elfProgramHeader)`
  Return the memory bytes to be loaded from the underlying file for the specified program header.
  `long`
  `getAdjustedMemoryOffset(long elfOffset, AddressSpace space)`
  Perform any required offset adjustment to account for differences between offset values contained within ELF headers and the language modeling of the associated address space.
  `long`
  `getAdjustedMemorySize(ElfProgramHeader elfProgramHeader)`
  Return the memory segment size in bytes for the specified program header.
  `long`
  `getAdjustedSize(ElfSectionHeader section)`
  Returns the memory section size in bytes for the specified section header.
  `String`
  `getDataTypeSuffix()`
  Return the data type naming suffix which should be used when creating types derived from data supplied by this extension.
  `int`
  `getDefaultAlignment(ElfLoadHelper elfLoadHelper)`
  Get the default alignment within the default address space.
  `long`
  `getDefaultImageBase(ElfHeader elfHeader)`
  Get the default image base to be used when one cannot be determined.
  `int`
  `getExternalBlockReserveSize()`
  Get reserve size of the EXTERNAL memory block as addressable units within the default memory space.
  `InputStream`
  `getFilteredLoadInputStream(ElfLoadHelper elfLoadHelper, MemoryLoadable loadable, Address start, long dataLength, InputStream dataInput)`
  Return filtered InputStream for loading a memory block (includes non-loaded OTHER blocks).
  `int`
  `getLinkageBlockAlignment()`
  Get the dynamic memory block allocation alignment as addressable units within the default memory space.
  `int`
  `getPreferredExternalBlockSize()`
  Get the preferred free range size for the EXTERNAL memory block as addressable units within the default memory space.
  `Address`
  `getPreferredSectionAddress(ElfLoadHelper elfLoadHelper, ElfSectionHeader elfSectionHeader)`
  Get the preferred load address for an allocated program section.
  `AddressSpace`
  `getPreferredSectionAddressSpace(ElfLoadHelper elfLoadHelper, ElfSectionHeader elfSectionHeader)`
  Get the preferred load address space for an allocated section.
  `Address`
  `getPreferredSegmentAddress(ElfLoadHelper elfLoadHelper, ElfProgramHeader elfProgramHeader)`
  Get the preferred load address for a program segment.
  `AddressSpace`
  `getPreferredSegmentAddressSpace(ElfLoadHelper elfLoadHelper, ElfProgramHeader elfProgramHeader)`
  Get the preferred load address space for an allocated program segment.
  `Class<? extends ElfRelocation>`
  `getRelocationClass(ElfHeader elfHeader)`
  Get the ElfRelocation class which should be used to properly parse the relocation tables.
  `Long`
  `getSectionSymbolRelativeOffset(ElfSectionHeader section, Address sectionBase, ElfSymbol elfSymbol)`
  Get the section-relative offset for the specified ELF symbol which is bound to the specified section.
  `boolean`
  `hasFilteredLoadInputStream(ElfLoadHelper elfLoadHelper, MemoryLoadable loadable, Address start)`
  Determine if the use of `getFilteredLoadInputStream(ElfLoadHelper, MemoryLoadable, Address, long, InputStream)` is required when loading a memory block.
  `Boolean`
  `isSectionAllocated(ElfSectionHeader section)`
  Determine if the specified section is "allocated" within memory.
  `Boolean`
  `isSectionExecutable(ElfSectionHeader section)`
  Get the execute permission for the specified section (i.e., instructions permitted).
  `Boolean`
  `isSectionWritable(ElfSectionHeader section)`
  Get the write permission for the specified section.
  `Boolean`
  `isSegmentExecutable(ElfProgramHeader segment)`
  Get the execute permission for the specified segment.
  `Boolean`
  `isSegmentReadable(ElfProgramHeader segment)`
  Get the read permission for the specified segment.
  `Boolean`
  `isSegmentWritable(ElfProgramHeader segment)`
  Get the write permission for the specified segment.
  `void`
  `processElf(ElfLoadHelper elfLoadHelper, TaskMonitor monitor)`
  Perform extension specific processing of Elf image during program load.
  `void`
  `processGotPlt(ElfLoadHelper elfLoadHelper, TaskMonitor monitor)`
  Perform extension specific processing of Elf GOT/PLT tables and any other related function relocation mechanism (e.g., function descriptors, etc) after normal REL/RELA relocation fix-ups have been applied.

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

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

- ## Constructor Details

  - ### ElfLoadAdapter

    public ElfLoadAdapter()

- ## Method Details

  - ### addDynamicTypes

    public final void addDynamicTypes(Map<Integer,ElfDynamicType> dynamicTypeMap)
    Add all extension specific Dynamic table entry types (e.g., DT_ prefix). This method will add all those statically defined ElfDynamicType fields within this class.
    Parameters:
      `dynamicTypeMap` - map to which ElfDynamicType definitions should be added

  - ### addProgramHeaderTypes

    public final void addProgramHeaderTypes(Map<Integer,ElfProgramHeaderType> programHeaderTypeMap)
    Add all extension specific Program Header types (e.g., PT_ prefix). This method will add all those statically defined ElfProgramHeaderType fields within this class.
    Parameters:
      `programHeaderTypeMap` - map to which ElfProgramHeaderType definitions should be added

  - ### addSectionHeaderTypes

    public final void addSectionHeaderTypes(HashMap<Integer,ElfSectionHeaderType> sectionHeaderTypeMap)
    Add all extension specific Section Header types (e.g., SHT_ prefix). This method will add all those statically defined ElfSectionHeaderType fields within this class.
    Parameters:
      `sectionHeaderTypeMap` - map to which ElfSectionHeaderType definitions should be added

  - ### getPreferredSegmentAddressSpace

    public AddressSpace getPreferredSegmentAddressSpace(ElfLoadHelper elfLoadHelper, ElfProgramHeader elfProgramHeader)
    Get the preferred load address space for an allocated program segment. The OTHER space is reserved and should not be returned by this method. This method may only return a physical address space and not an overlay address space.
    Parameters:
      `elfLoadHelper` - load helper object
      `elfProgramHeader` - elf program segment header
    Returns:
      preferred load address space

  - ### getPreferredSegmentAddress

    public Address getPreferredSegmentAddress(ElfLoadHelper elfLoadHelper, ElfProgramHeader elfProgramHeader)
    Get the preferred load address for a program segment. This method may only return a physical address and not an overlay address.
    Parameters:
      `elfLoadHelper` - load helper object
      `elfProgramHeader` - elf program segment header
    Returns:
      preferred load address

  - ### getDefaultAlignment

    public int getDefaultAlignment(ElfLoadHelper elfLoadHelper)
    Get the default alignment within the default address space.
    Parameters:
      `elfLoadHelper` - helper object
    Returns:
      default alignment within the default address space.

  - ### getPreferredSectionAddressSpace

    public AddressSpace getPreferredSectionAddressSpace(ElfLoadHelper elfLoadHelper, ElfSectionHeader elfSectionHeader)
    Get the preferred load address space for an allocated section. The OTHER space is reserved and should not be returned by this method. This method may only return a physical address space and not an overlay address space.
    Parameters:
      `elfLoadHelper` - load helper object
      `elfSectionHeader` - elf section header
    Returns:
      preferred load address space

  - ### getPreferredSectionAddress

    public Address getPreferredSectionAddress(ElfLoadHelper elfLoadHelper, ElfSectionHeader elfSectionHeader)
    Get the preferred load address for an allocated program section. This method may only return a physical address and not an overlay address.
    Parameters:
      `elfLoadHelper` - load helper object
      `elfSectionHeader` - elf program section header
    Returns:
      preferred load address

  - ### canHandle

    public boolean canHandle(ElfHeader elf)
    Check if this extension can handle the specified elf header. If this method returns true, this extension will be used to obtain extended types definitions and to perform additional load processing.
    Parameters:
      `elf` - elf header
    Returns:
      true if this extension should be used when loading the elf image which corresponds to the specified header.

  - ### canHandle

    public boolean canHandle(ElfLoadHelper elfLoadHelper)
    Check if this extension can handle the specified elf image. This method can provide a more accurate check based upon the actual language utilized. While the ELF header may have stipulated a specific processor via the machine-id, a completely different and incompatible language may have been used.
    Parameters:
      `elfLoadHelper` - elf header
    Returns:
      true if this extension can properly support the ELF header and the current program/language.

  - ### getDataTypeSuffix

    public String getDataTypeSuffix()
    Return the data type naming suffix which should be used when creating types derived from data supplied by this extension.
    Returns:
      type naming suffix or null

  - ### getAdjustedMemoryOffset

    public long getAdjustedMemoryOffset(long elfOffset, AddressSpace space)
    Perform any required offset adjustment to account for differences between offset values contained within ELF headers and the language modeling of the associated address space.
    WARNING: This is an experimental method and is not yet fully supported.
    NOTE: This has currently been utilized for symbol address offset adjustment only.
    Parameters:
      `elfOffset` - memory offset from ELF header
      `space` - associated address space
    Returns:
      offset appropriate for use in space (does not account for image base alterations)

  - ### processElf

    public void processElf(ElfLoadHelper elfLoadHelper, TaskMonitor monitor) throws CancelledException
    Perform extension specific processing of Elf image during program load. The following loading steps will have already been completed:

         1. default processing of all program headers and section headers
         2. memory resolution and loading of all program headers and section headers
         3. Markup completed of Elf header, program headers, section headers, dynamic table,
            string tables, and symbol tables.

    Markup and application of relocation tables will NOT have been done yet.
    Parameters:
      `elfLoadHelper` - load helper object
      `monitor` -
    Throws:
      `CancelledException`

  - ### processGotPlt

    public void processGotPlt(ElfLoadHelper elfLoadHelper, TaskMonitor monitor) throws CancelledException
    Perform extension specific processing of Elf GOT/PLT tables and any other related function relocation mechanism (e.g., function descriptors, etc) after normal REL/RELA relocation fix-ups have been applied.
    Parameters:
      `elfLoadHelper` - load helper object
      `monitor` -
    Throws:
      `CancelledException`

  - ### creatingFunction

    public Address creatingFunction(ElfLoadHelper elfLoadHelper, Address functionAddress)
    Prior to the ELF loader creating a function this method will be invoked to permit an extension to adjust the address and/or apply context to the intended location.
    Parameters:
      `elfLoadHelper` - load helper object
      `functionAddress` - function address
    Returns:
      adjusted function address (required)

  - ### calculateSymbolAddress

    public Address calculateSymbolAddress(ElfLoadHelper elfLoadHelper, ElfSymbol elfSymbol) throws NoValueException
    This method allows an extension to override the default address calculation for loading a symbol. This is generally only neccessary when symbol requires handling of processor-specific flags or section index. This method should return null when default symbol processing is sufficient. `Address.NO_ADDRESS` should be returned if the symbol is external and is not handled by default processing.
    Parameters:
      `elfLoadHelper` - load helper object
      `elfSymbol` - elf symbol
    Returns:
      symbol memory address or null to defer to default implementation
    Throws:
      `NoValueException` - if error logged and address calculation failed

  - ### evaluateElfSymbol

    public Address evaluateElfSymbol(ElfLoadHelper elfLoadHelper, ElfSymbol elfSymbol, Address address, boolean isExternal)
    During symbol processing this method will be invoked to permit an extension to adjust the address and/or apply context to the intended symbol location.
    Parameters:
      `elfLoadHelper` - load helper object
      `elfSymbol` - elf symbol
      `address` - program memory address where symbol will be created.
      `isExternal` - true if symbol treated as external to the program and has been assigned a fake memory address in the EXTERNAL memory block.
    Returns:
      adjusted symbol address or null if extension will handle applying the elfSymbol to the program (must also invoke `ElfLoadHelper.setElfSymbolAddress(ElfSymbol, Address)`, or symbol should not be applied.

  - ### isSegmentWritable

    public Boolean isSegmentWritable(ElfProgramHeader segment)
    Get the write permission for the specified segment.
    Parameters:
      `segment` - program header object
    Returns:
      true if write enabled, else false or null to use standard Elf program header flags to make the determination.

  - ### isSegmentReadable

    public Boolean isSegmentReadable(ElfProgramHeader segment)
    Get the read permission for the specified segment.
    Parameters:
      `segment` - program header object
    Returns:
      true if read enabled, else false or null to use standard Elf program header flags to make the determination.

  - ### isSegmentExecutable

    public Boolean isSegmentExecutable(ElfProgramHeader segment)
    Get the execute permission for the specified segment.
    Parameters:
      `segment` - program header object
    Returns:
      true if execute enabled, else false or null to use standard Elf program header flags to make the determination.

  - ### isSectionWritable

    public Boolean isSectionWritable(ElfSectionHeader section)
    Get the write permission for the specified section.
    Parameters:
      `section` - section header object
    Returns:
      true if write enabled, else false or null to use standard Elf section flags to make the determination.

  - ### isSectionExecutable

    public Boolean isSectionExecutable(ElfSectionHeader section)
    Get the execute permission for the specified section (i.e., instructions permitted).
    Parameters:
      `section` - section header object
    Returns:
      true if execute enabled, else false or null to use standard Elf section flags to make the determination.

  - ### isSectionAllocated

    public Boolean isSectionAllocated(ElfSectionHeader section)
    Determine if the specified section is "allocated" within memory.
    Parameters:
      `section` - section header object
    Returns:
      true if section should be allocated, else false or null to use standard Elf section flags to make the determination.

  - ### getAdjustedLoadSize

    public long getAdjustedLoadSize(ElfProgramHeader elfProgramHeader)
    Return the memory bytes to be loaded from the underlying file for the specified program header. The returned value will be consistent with any byte filtering which may be required.
    Parameters:
      `elfProgramHeader` -
    Returns:
      preferred memory block size in bytes which corresponds to the specified program header

  - ### getAdjustedMemorySize

    public long getAdjustedMemorySize(ElfProgramHeader elfProgramHeader)
    Return the memory segment size in bytes for the specified program header. The returned value will be consistent with any byte filtering which may be required.
    Parameters:
      `elfProgramHeader` -
    Returns:
      preferred memory block size in bytes which corresponds to the specified program header

  - ### getLinkageBlockAlignment

    public int getLinkageBlockAlignment()
    Get the dynamic memory block allocation alignment as addressable units within the default memory space.
    Returns:
      dynamic memory block allocation alignment.

  - ### getPreferredExternalBlockSize

    public int getPreferredExternalBlockSize()
    Get the preferred free range size for the EXTERNAL memory block as addressable units within the default memory space.
    Returns:
      minimum free range size for EXTERNAL memory block as addressable units

  - ### getExternalBlockReserveSize

    public int getExternalBlockReserveSize()
    Get reserve size of the EXTERNAL memory block as addressable units within the default memory space. This size represents the largest expansion size to the block which could occur during relocation processing.
    Returns:
      reserve size of the EXTERNAL memory block as addressable units

  - ### getAdjustedSize

    public long getAdjustedSize(ElfSectionHeader section)
    Returns the memory section size in bytes for the specified section header.

    The returned value will be consistent with any byte filtering and decompression which may be required.

    The default implementation returns the section's `logical size`

    Parameters:
      `section` - the section header
    Returns:
      preferred memory block size in bytes which corresponds to the specified section header

  - ### getFilteredLoadInputStream

    public InputStream getFilteredLoadInputStream(ElfLoadHelper elfLoadHelper, MemoryLoadable loadable, Address start, long dataLength, InputStream dataInput) throws IOException
    Return filtered InputStream for loading a memory block (includes non-loaded OTHER blocks). NOTE: If this method is overriden, the `hasFilteredLoadInputStream(ElfLoadHelper, MemoryLoadable, Address)` must also be overriden in a consistent fashion.
    Parameters:
      `elfLoadHelper` -
      `loadable` - Corresponding ElfSectionHeader or ElfProgramHeader for the memory block to be created.
      `start` - memory load address
      `dataLength` - the in-memory data length in bytes (actual bytes read from dataInput may be more)
      `dataInput` - the source input stream
    Returns:
      filtered input stream or original input stream
    Throws:
      `IOException` - if error initializing filtered stream

  - ### hasFilteredLoadInputStream

    public boolean hasFilteredLoadInputStream(ElfLoadHelper elfLoadHelper, MemoryLoadable loadable, Address start)
    Determine if the use of `getFilteredLoadInputStream(ElfLoadHelper, MemoryLoadable, Address, long, InputStream)` is required when loading a memory block. If a filtered input stream is required this will prevent the use of a direct mapping to file bytes.
    Parameters:
      `elfLoadHelper` -
      `loadable` - Corresponding ElfSectionHeader or ElfProgramHeader for the memory block to be loaded.
      `start` - memory load address
    Returns:
      true if the use of a filtered input stream is required

  - ### getRelocationClass

    public Class<? extends ElfRelocation> getRelocationClass(ElfHeader elfHeader)
    Get the ElfRelocation class which should be used to properly parse the relocation tables.
    Parameters:
      `elfHeader` - ELF header object (for header field access only)
    Returns:
      ElfRelocation class or null for default behavior

  - ### addLoadOptions

    public void addLoadOptions(ElfHeader elf, List<Option> options)
    Add extension-specific load options
    Parameters:
      `elf` - ELF header
      `options` - list to which load options may be added

  - ### getDefaultImageBase

    public long getDefaultImageBase(ElfHeader elfHeader)
    Get the default image base to be used when one cannot be determined.
    Parameters:
      `elfHeader` - ELF header
    Returns:
      default image base

  - ### getSectionSymbolRelativeOffset

    public Long getSectionSymbolRelativeOffset(ElfSectionHeader section, Address sectionBase, ElfSymbol elfSymbol)
    Get the section-relative offset for the specified ELF symbol which is bound to the specified section. If the symbol has an absolute symbol value/offset this method should return null.

    For Harvard Architectures it may be necessary to adjust offset if section was mapped to a non-default data space.

    The default behavior is to return `ElfSymbol.getValue()` if `ElfHeader.isRelocatable()` is true.

    Parameters:
      `section` - ELF section header which is specified by the ELF symbol
      `sectionBase` - memory address where section has been loaded. Could be within overlay space if load conflict occured.
      `elfSymbol` - ELF symbol
    Returns:
      section relative symbol offset or null if symbol value offset is absolute