Package ghidra.app.decompiler

Class DecompInterface

  • public class DecompInterface
extends java.lang.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(xmlOptions); // 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();
   ...

    • Constructor Detail

      • DecompInterface

        public DecompInterface()

    • Method Detail

      • enableDebug

        public void enableDebug​(java.io.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 java.lang.String getSimplificationStyle()
        Return the identifier for the current simplification style
        Returns:
        the identifier as a String

      • getProgram

        public Program getProgram()

      • getLanguage

        public Language getLanguage()

      • getLastMessage

        public java.lang.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 java.io.IOException,
                                 DecompileException
        This is the main routine for making sure that a decompiler process is active and that it is initialized properly
        Throws:
        java.io.IOException - for any problems with the pipe to the decompiler process
        DecompileException - for errors initializing decompiler options etc.

      • 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​(java.lang.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 xmloptions)
        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:
        xmloptions - 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

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