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();
   ...

  • Field Details

  • 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