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 Summary

  Modifier and Type
  Method
  Description
  `void`
  `fixupInstructions(Program program, Language oldLanguage, TaskMonitor monitor)`
  Invoked after Program language upgrade has completed.
  `AddressSpace`
  `getNewAddressSpace(String oldSpaceName)`
  Translate BASE address spaces (Overlay spaces are not handled)
  `CompilerSpecID`
  `getNewCompilerSpecID(CompilerSpecID oldCompilerSpecID)`
  Obtain the new compiler specification ID given the old compiler spec ID.
  `Register`
  `getNewContextRegister()`
  Returns the new processor context register or null if not defined
  `Language`
  `getNewLanguage()`
  Returns new language
  `LanguageID`
  `getNewLanguageID()`
  Returns new language name
  `Register`
  `getNewRegister(Register oldReg)`
  Find new register which corresponds to the specified old register.
  `RegisterValue`
  `getNewRegisterValue(RegisterValue oldValue)`
  Get the translated register value
  `int`
  `getNewVersion()`
  Returns new language version
  `CompilerSpec`
  `getOldCompilerSpec(CompilerSpecID oldCompilerSpecID)`
  Get a compiler spec suitable for use with the old language.
  `Register`
  `getOldContextRegister()`
  Returns the old processor context register or null if not defined
  `Language`
  `getOldLanguage()`
  Returns old language
  `LanguageID`
  `getOldLanguageID()`
  Returns old language name
  `Register`
  `getOldRegister(Address oldAddr, int size)`
  Get the old register at the specified oldAddr.
  `Register`
  `getOldRegisterContaining(Address oldAddr)`
  Get the largest old register which contains the specified oldAddr
  `int`
  `getOldVersion()`
  Returns old language version
  `boolean`
  `isValid()`
  Validate translator to complete initialization and ensure language compatibility.
  `boolean`
  `isValueTranslationRequired(Register oldReg)`
  Returns true if register value translation required for program context.

- ## 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:
      - `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(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

  - ### 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(Register)`

  - ### 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 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