Package ghidra.program.util

Interface LanguageTranslator

All Superinterfaces:
ExtensionPoint
All Known Implementing Classes:
LanguageTranslatorAdapter, ProgramArchitectureTranslator
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 Details

    • 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:
      IllegalStateException - if instance has not been validated
      See Also:

    • 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(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

      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

    • getNewRegisterValue

      RegisterValue getNewRegisterValue(RegisterValue oldValue)
      Get the translated register value
      Parameters:
      oldValue - old register value (may not be null)
      Returns:
      new register value or null if register not mapped
      See Also:

    • isValueTranslationRequired

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

    • 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 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:
      Exception - if a bad exception occurs with the post upgrade fixup
      CancelledException - if upgrade cancelled