Package ghidra.app.decompiler

# Class DecompInterface

java.lang.Object
ghidra.app.decompiler.DecompInterface

public class DecompInterface extends Object
This is a self-contained interface to a single decompile process, suitable for an open-ended number of function decompilations for a single program. The interface is persistent. It caches all the initialization data passed to it, and if the underlying decompiler process crashes, it automatically respawns the process and reinitializes it the next time it is needed. The basic usage pattern is as follows

       // Instantiate the interface
       DecompInterface ifc = new DecompInterface();

       // Setup any options or other initialization
       ifc.setOptions(options); // Inform interface of global options
       // ifc.toggleSyntaxTree(false);  // Don't produce syntax trees
       // ifc.toggleCCode(false);       // Don't produce C code
       // ifc.setSimplificationStyle("normalize"); // Alternate analysis style

       // Setup up the actual decompiler process for a
       // particular program, using all the above initialization
       ifc.openProgram(program,language);

       // Make calls to the decompiler:
       DecompileResults res = ifc.decompileFunction(func,0,taskmonitor);

       // Check for error conditions
       if (!res.decompileCompleted()) {
            system.out.println(res.getErrorMessage());
          return;
       }

       // Make use of results
          // Get C code
       ClangTokenGroup tokgroup = res.getCCodeMarkup();
       ...
          // Get the function object/syntax tree
       HighFunction hfunc = res.getHighFunction();
       ...

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `DecompInterface.EncodeDecodeSet`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected DecompInterface.EncodeDecodeSet`
  `baseEncodingSet`
  `protected CompilerSpec`
  `compilerSpec`
  `protected DecompileCallback`
  `decompCallback`
  `protected String`
  `decompileMessage`
  `protected DecompileProcess`
  `decompProcess`
  `protected CancelledListener`
  `monitorListener`
  `protected DecompInterface.EncodeDecodeSet`
  `overlayEncodingSet`
  `protected Program`
  `program`
  `protected StringIngest`
  `stringResponse`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DecompInterface()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `closeProgram()`
  Shutdown any existing decompiler process and free resources.
  `boolean`
  `debugEnabled()`
  `ArrayList<DebugSignature>`
  `debugSignatures(Function func, int timeoutSecs, TaskMonitor monitor)`
  Generate a signature, using the current signature settings, for the given function.
  `DecompileResults`
  `decompileFunction(Function func, int timeoutSecs, TaskMonitor monitor)`
  Decompile function
  `void`
  `dispose()`
  `void`
  `enableDebug(File debugfile)`
  Turn on debugging dump for the next decompiled function
  `int`
  `flushCache()`
  Tell the decompiler to clear any function and symbol information it gathered from the database.
  `SignatureResult`
  `generateSignatures(Function func, boolean keepcalllist, int timeoutSecs, TaskMonitor monitor)`
  Generate a signature, using the current signature settings, for the given function.
  `CompilerSpec`
  `getCompilerSpec()`
  `PcodeDataTypeManager`
  `getDataTypeManager()`
  `Language`
  `getLanguage()`
  `String`
  `getLastMessage()`
  Get the last message produced by the decompiler process.
  `short`
  `getMajorVersion()`
  `short`
  `getMinorVersion()`
  `DecompileOptions`
  `getOptions()`
  Get the options currently in effect for the decompiler
  `Program`
  `getProgram()`
  `int`
  `getSignatureSettings()`
  `String`
  `getSimplificationStyle()`
  Return the identifier for the current simplification style
  `protected void`
  `initializeProcess()`
  This is the main routine for making sure that a decompiler process is active and that it is initialized properly
  `boolean`
  `openProgram(Program prog)`
  This call initializes a new decompiler process to do decompilations for a new program.
  `void`
  `resetDecompiler()`
  Resets the native decompiler process.
  `boolean`
  `setOptions(DecompileOptions options)`
  Set the object controlling the list of global options used by the decompiler.
  `boolean`
  `setSignatureSettings(int value)`
  Set the desired signature generation settings.
  `boolean`
  `setSimplificationStyle(String actionstring)`
  This allows the application to the type of analysis performed by the decompiler, by giving the name of an analysis class.
  `protected DecompInterface.EncodeDecodeSet`
  `setupEncodeDecode(Address addr)`
  Setup the correct Encoder and Decoder to use for the decompilation.
  `void`
  `stopProcess()`
  Stop the decompile process.
  `BlockGraph`
  `structureGraph(BlockGraph ingraph, int timeoutSecs, TaskMonitor monitor)`
  `boolean`
  `toggleCCode(boolean val)`
  Toggle whether or not calls to the decompiler process (via the decompileFunction method) produce C code.
  `boolean`
  `toggleJumpLoads(boolean val)`
  Toggle whether or not the decompiler process should return information about tables used to recover switch statements.
  `boolean`
  `toggleParamMeasures(boolean val)`
  Toggle whether or not calls to the decompiler process (via the decompileFunction method) produce Parameter Measures.
  `boolean`
  `toggleSyntaxTree(boolean val)`
  This method toggles whether or not the decompiler produces a syntax tree (via calls to decompileFunction).
  `protected void`
  `verifyProcess()`

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

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

- ## Field Details

  - ### program

    protected Program program

  - ### decompileMessage

    protected String decompileMessage

  - ### compilerSpec

    protected CompilerSpec compilerSpec

  - ### decompProcess

    protected DecompileProcess decompProcess

  - ### decompCallback

    protected DecompileCallback decompCallback

  - ### baseEncodingSet

    protected DecompInterface.EncodeDecodeSet baseEncodingSet

  - ### overlayEncodingSet

    protected DecompInterface.EncodeDecodeSet overlayEncodingSet

  - ### stringResponse

    protected StringIngest stringResponse

  - ### monitorListener

    protected CancelledListener monitorListener

- ## Constructor Details

  - ### DecompInterface

    public DecompInterface()

- ## Method Details

  - ### enableDebug

    public void enableDebug(File debugfile)
    Turn on debugging dump for the next decompiled function
    Parameters:
      `debugfile` - the file to enable debug dubp

  - ### debugEnabled

    public boolean debugEnabled()
    Returns:
      true if debug has been enabled for the current/next decompilation.

  - ### getSimplificationStyle

    public String getSimplificationStyle()
    Return the identifier for the current simplification style
    Returns:
      the identifier as a String

  - ### getProgram

    public Program getProgram()

  - ### getLanguage

    public Language getLanguage()

  - ### getDataTypeManager

    public PcodeDataTypeManager getDataTypeManager()

  - ### getLastMessage

    public String getLastMessage()
    Get the last message produced by the decompiler process. If the message is non-null, it is probably an error message, but not always. It is better to use the getErrorMessage method off of DecompileResults.
    Returns:
      the message string or null

  - ### initializeProcess

    protected void initializeProcess() throws IOException, DecompileException
    This is the main routine for making sure that a decompiler process is active and that it is initialized properly
    Throws:
      `IOException` - for any problems with the pipe to the decompiler process
      `DecompileException` - for errors initializing decompiler options etc.

  - ### verifyProcess

    protected void verifyProcess() throws IOException, DecompileException
    Throws:
      `IOException`
      `DecompileException`

  - ### openProgram

    public boolean openProgram(Program prog)
    This call initializes a new decompiler process to do decompilations for a new program. This method only needs to be called once per program. Even if the underlying decompiler process crashes, the interface will automatically restart and reinitialize a new process when it needs it, and the openProgram call does not need to be made again. The call can be made multiple times, in which case, each call terminates the process initialized the last time and starts a new process
    Parameters:
      `prog` - = the program on which to perform decompilations
    Returns:
      true if the decompiler process is successfully initialized

  - ### closeProgram

    public void closeProgram()
    Shutdown any existing decompiler process and free resources. The interface cannot be used again to perform decompilations until an openProgram call is made again.

  - ### setSimplificationStyle

    public boolean setSimplificationStyle(String actionstring)
    This allows the application to the type of analysis performed by the decompiler, by giving the name of an analysis class. Right now, there are a few predefined classes. But there soon may be support for applications to define their own class and tailoring the decompiler's behaviour for that class.

    The current predefined analysis class are:

    - "decompile" - this is the default, and performs all analysis steps suitable for producing C code.
    - "normalize" - omits type recovery from the analysis and some of the final clean-up steps involved in making valid C code. It is suitable for creating normalized pcode syntax trees of the dataflow.
    - "firstpass" - does no analysis, but produces an unmodified syntax tree of the dataflow from the
    - "register" - does ???.
    - "paramid" - does required amount of decompilation followed by analysis steps that send parameter measure information for parameter id analysis. raw pcode.

    This property should ideally be set once before the openProgram call is made, but it can be used repeatedly if the application needs to change analysis style in the middle of a sequence of decompiles. Unless the style changes, the method does NOT need to be called repeatedly. Even after a crash, the new decompiler process will automatically configured with the cached style value.

    Parameters:
      `actionstring` - "decompile"|"normalize"|"register"|"firstpass"|"paramid"
    Returns:
      true - if the decompiler process was successfully configured

  - ### toggleSyntaxTree

    public boolean toggleSyntaxTree(boolean val)
    This method toggles whether or not the decompiler produces a syntax tree (via calls to decompileFunction). The default is to always produce a syntax tree, but some applications may only need C code. Ideally this method should be called once before the openProgram call, but it can be used at any time, if the application wants to change before in the middle of a sequence of decompiles. Unless the desired value changes, the method does NOT need to be called repeatedly. Even after a decompiler process crash, the old value is cached and automatically sent to the new process
    Parameters:
      `val` - = true, to produce a syntax tree, false otherwise
    Returns:
      true if the decompiler process, accepted the change of state

  - ### toggleCCode

    public boolean toggleCCode(boolean val)
    Toggle whether or not calls to the decompiler process (via the decompileFunction method) produce C code. The default is to always compute C code, but some applications may only need the syntax tree or other function information. Ideally this method should be called once before the openProgram call, but it can be used at any time, if the application wants to change before in the middle of a sequence of decompiles. Unless the desired value changes, the method does NOT need to be called repeatedly. Even after a decompiler process crash, the old value is cached and automatically sent to the new process
    Parameters:
      `val` - = true, to produce C code, false otherwise
    Returns:
      true if the decompiler process accepted the new state

  - ### toggleParamMeasures

    public boolean toggleParamMeasures(boolean val)
    Toggle whether or not calls to the decompiler process (via the decompileFunction method) produce Parameter Measures. The default is to not compute Parameter Measures. Ideally this method should be called once before the openProgram call, but it can be used at any time, if the application wants to change before in the middle of a sequence of decompiles. Unless the desired value changes, the method does NOT need to be called repeatedly. Even after a decompiler process crash, the old value is cached and automatically sent to the new process
    Parameters:
      `val` - = true, to produce C code, false otherwise
    Returns:
      true if the decompiler process accepted the new state

  - ### toggleJumpLoads

    public boolean toggleJumpLoads(boolean val)
    Toggle whether or not the decompiler process should return information about tables used to recover switch statements. Most compilers implement switch statements using a so called "jumptable" of addresses or offsets. The decompiler can frequently recover this and can return a description of the table
    Parameters:
      `val` - = true, to have the decompiler return table info, false otherwise
    Returns:
      true if the decompiler process accepted the new state

  - ### setOptions

    public boolean setOptions(DecompileOptions options)
    Set the object controlling the list of global options used by the decompiler. Ideally this is called once, before the openProgram call is made. But it can be used at any time, if the options change in the middle of a sequence of decompiles. If there is no change to the options, this method does NOT need to be called repeatedly. Even after recovering from decompiler process crash, the interface keeps the options object around and automatically sends it to the new decompiler process.
    Parameters:
      `options` - the new (or changed) option object
    Returns:
      true if the decompiler process accepted the new options

  - ### getOptions

    public DecompileOptions getOptions()
    Get the options currently in effect for the decompiler
    Returns:
      options that will be passed to the decompiler

  - ### flushCache

    public int flushCache()
    Tell the decompiler to clear any function and symbol information it gathered from the database. Its a good idea to call this after any decompileFunction call, as the decompile process caches and reuses this kind of data, and there is no explicit method for keeping the cache in sync with the data base. Currently the return value has no meaning.
    Returns:
      -1

  - ### structureGraph

    public BlockGraph structureGraph(BlockGraph ingraph, int timeoutSecs, TaskMonitor monitor)

  - ### decompileFunction

    public DecompileResults decompileFunction(Function func, int timeoutSecs, TaskMonitor monitor)
    Decompile function
    Parameters:
      `func` - function to be decompiled
      `timeoutSecs` - if decompile does not complete in this time a null value will be returned and a timeout error set.
      `monitor` - optional task monitor which may be used to cancel decompile
    Returns:
      decompiled function text

  - ### stopProcess

    public void stopProcess()
    Stop the decompile process. NOTE: Subsequent calls made from another thread to this DecompInterface object may fail since the decompiler process is being yanked away.

  - ### resetDecompiler

    public void resetDecompiler()
    Resets the native decompiler process. Call this method when the decompiler's view of a program has been invalidated, such as when a new overlay space has been added.

  - ### dispose

    public void dispose()

  - ### getCompilerSpec

    public CompilerSpec getCompilerSpec()

  - ### setupEncodeDecode

    protected DecompInterface.EncodeDecodeSet setupEncodeDecode(Address addr) throws AddressFormatException
    Setup the correct Encoder and Decoder to use for the decompilation. Generally we use the base versions unless there is an overlay. In which case we switch to special translating encoders and decoders.
    Parameters:
      `addr` - is the address of the function being decompiled
    Returns:
      the set of encoders and decoders that should be used
    Throws:
      `AddressFormatException` - if decompilation is not supported for the (overlay) address

  - ### getMajorVersion

    public short getMajorVersion()
    Returns:
      the major version number of the decompiler

  - ### getMinorVersion

    public short getMinorVersion()
    Returns:
      the minor version number of the decompiler

  - ### getSignatureSettings

    public int getSignatureSettings()
    Returns:
      the signature settings of the decompiler

  - ### setSignatureSettings

    public boolean setSignatureSettings(int value)
    Set the desired signature generation settings.
    Parameters:
      `value` - is the new desired setting
    Returns:
      true if the settings took effect

  - ### generateSignatures

    public SignatureResult generateSignatures(Function func, boolean keepcalllist, int timeoutSecs, TaskMonitor monitor)
    Generate a signature, using the current signature settings, for the given function. The signature is returned as a raw feature vector, `SignatureResult`.
    Parameters:
      `func` - is the given function
      `keepcalllist` - is true if direct call addresses are collected as part of the result
      `timeoutSecs` - is the maximum amount of time to spend decompiling the function
      `monitor` - is the TaskMonitor
    Returns:
      the feature vector

  - ### debugSignatures

    public ArrayList<DebugSignature> debugSignatures(Function func, int timeoutSecs, TaskMonitor monitor)
    Generate a signature, using the current signature settings, for the given function. The signature is returned as a sequence of features (feature vector). Each feature is returned as a separate record with additional metadata describing the information incorporated into it.
    Parameters:
      `func` - is the given function
      `timeoutSecs` - is the maximum number of seconds to spend decompiling the function
      `monitor` - is the TaskMonitor
    Returns:
      the array of feature descriptions