Package ghidra.program.util

Interface LanguageTranslator

  • All Superinterfaces:
    ExtensionPoint
    All Known Implementing Classes:
    LanguageTranslatorAdapter
    public interface LanguageTranslator
extends ExtensionPoint
    NOTE: ALL LanguageTranslator CLASSES MUST END IN "LanguageTranslator". If not, the ClassSearcher will not find them. LanguageTranslator provides translation capabilities used by Program.setLanguage when converting a program from one language to another or from one version to another.
    Explicit translator implementations must implement the default constructor and should not instantiate Language, AddressSpace, AddressFactory or Register objects until isValid() is invoked.

    • Method Detail

      • isValid

        boolean isValid()
        Validate translator to complete initialization and ensure language compatibility. This method will be invoked by the LanguageTranslatorFactory before handing out this translator.
        Returns:
        true if translator successfully validated

      • getOldLanguage

        Language getOldLanguage()
        Returns old language
        Throws:
        java.lang.IllegalStateException - if instance has not been validated
        See Also:
        isValid()

      • getNewLanguage

        Language getNewLanguage()
        Returns new language

      • getOldLanguageID

        LanguageID getOldLanguageID()
        Returns old language name

      • getNewLanguageID

        LanguageID getNewLanguageID()
        Returns new language name

      • getOldVersion

        int getOldVersion()
        Returns old language version

      • getNewVersion

        int getNewVersion()
        Returns new language version

      • getNewAddressSpace

        AddressSpace getNewAddressSpace​(java.lang.String oldSpaceName)
        Translate BASE address spaces (Overlay spaces are not handled)
        Parameters:
        oldSpaceName - old space name
        Returns:
        corresponding address space in new language

      • getOldRegister

        Register getOldRegister​(Address oldAddr,
                        int size)
        Get the old register at the specified oldAddr. This will null if the specified address is offcut within the register. The smallest register will be returned which is greater than or equal to the specified size.
        Parameters:
        oldAddr - old register address.
        size - minimum register size
        Returns:
        old register or null if suitable register can not be found.
        See Also:
        getOldRegisterContaining(Address)

      • getOldRegisterContaining

        Register getOldRegisterContaining​(Address oldAddr)
        Get the largest old register which contains the specified oldAddr
        Parameters:
        oldAddr - old register address which may be offcut
        Returns:
        old register or null if suitable register can not be found.

      • getOldContextRegister

        Register getOldContextRegister()
        Returns the old processor context register or null if not defined

      • getNewRegister

        Register getNewRegister​(Register oldReg)
        Find new register which corresponds to the specified old register.
        Parameters:
        oldReg - old register
        Returns:
        new register or null if corresponding register not found.

      • getNewContextRegister

        Register getNewContextRegister()
        Returns the new processor context register or null if not defined

      • isValueTranslationRequired

        boolean isValueTranslationRequired​(Register oldReg)
        Returns true if register value translation required for program context.
        Parameters:
        oldReg -
        See Also:
        getNewRegisterValue(RegisterValue)

      • getNewCompilerSpecID

        CompilerSpecID getNewCompilerSpecID​(CompilerSpecID oldCompilerSpecID)
        Obtain the new compiler specification ID given the old compiler spec ID.
        Parameters:
        oldCompilerSpecID - old compiler spec ID.
        Returns:
        new compiler spec ID.

      • getOldCompilerSpec

        CompilerSpec getOldCompilerSpec​(CompilerSpecID oldCompilerSpecID)
                         throws CompilerSpecNotFoundException
        Get a compiler spec suitable for use with the old language. The compiler spec returned is intended for upgrade use only prior to the setLanguage and may be based upon compiler conventions specified in the new compiler spec returned by getNewCompilerSpec given the same compilerSpecID.
        Parameters:
        oldCompilerSpecID - old compiler spec ID.
        Returns:
        compiler spec for use with old language
        Throws:
        CompilerSpecNotFoundException - if new compiler spec not found based upon translator mappings.

      • fixupInstructions

        void fixupInstructions​(Program program,
                       Language oldLanguage,
                       TaskMonitor monitor)
                throws java.lang.Exception,
                       CancelledException
        Invoked after Program language upgrade has completed. Implementation of this method permits the final re-disassembled program to be examined/modified to address more complex language upgrades. This method will only be invoked on the latest translator, which means all complex multi-version post-upgrade concerns must factor in the complete language transition. The program's language information will still reflect the original pre-upgrade state, and if the program is undergoing a schema version upgrade as well, certain complex upgrades may not have been completed (e.g., Function and Variable changes). Program modifications should be restricted to instruction and instruction context changes only.
        Parameters:
        program -
        oldLanguage - the oldest language involved in the current upgrade translation (this is passed since this is the only fixup invocation which must handle the any relevant fixup complexities when transitioning from the specified oldLanguage).
        monitor - task monitor
        Throws:
        java.lang.Exception - if a bad exception occurs with the post upgrade fixup
        CancelledException - if upgrade cancelled