Interface ElfLoadHelper


  • public interface ElfLoadHelper
    ElfLoadHelper exposes loader methods useful to ElfExtension implementations.
    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      AddressRange allocateLinkageBlock​(int alignment, int size, java.lang.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​(java.lang.String name, Address functionAddr, Address indirectPointerAddr)
      Create an external function within the UNKNOWN space and a corresponding thunk at the internalFunctionAddr.
      Function createOneByteFunction​(java.lang.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, java.lang.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
      java.lang.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
      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​(java.lang.String msg)
      Output loader log message
      void log​(java.lang.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 Detail

      • getProgram

        Program getProgram()
        Get program object
        Returns:
        program object
      • getElfHeader

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

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

        void log​(java.lang.String msg)
        Output loader log message
        Parameters:
        msg - text message
      • log

        void log​(java.lang.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 -
      • createOneByteFunction

        Function createOneByteFunction​(java.lang.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​(java.lang.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
        Parameters:
        address - location of undefined data to create
        length - size of the undefined data item
      • 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 or null if not successful
      • 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,
                            java.lang.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
      • 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

        java.lang.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.
        Returns:
        the .got section address offset
      • allocateLinkageBlock

        AddressRange allocateLinkageBlock​(int alignment,
                                          int size,
                                          java.lang.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