Package ghidra.app.decompiler.util

# Class FillOutStructureHelper

java.lang.Object
ghidra.app.decompiler.util.FillOutStructureHelper

public class FillOutStructureHelper extends Object
Automatically create a Structure data-type based on references found by the decompiler to a root parameter or other variable. If the parameter is already a Structure pointer, any new references found can optionally be added to the existing Structure data-type. `processStructure(HighVariable, Function, boolean, boolean, DecompInterface)` is the primary entry point to the helper, which computes the new or updated Structure based on an existing decompiled function. Decompilation, if not provided externally, can be performed by calling `computeHighVariable(Address, Function, DecompInterface)`. A decompiler process, if not provided externally, can be started by calling `setUpDecompiler(DecompileOptions)`.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `FillOutStructureHelper.OffsetPcodeOpPair`
  Class to create pair between an offset and its related PcodeOp

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FillOutStructureHelper(Program program, TaskMonitor monitor)`
  Constructor.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `HighVariable`
  `computeHighVariable(Address storageAddress, Function function, DecompInterface decomplib)`
  Decompile a function and return the resulting HighVariable associated with a storage address
  `NoisyStructureBuilder`
  `getComponentMap()`
  Retrieve the component map that was generated when structure was created using decompiler info.
  `List<FillOutStructureHelper.OffsetPcodeOpPair>`
  `getLoadPcodeOps()`
  Retrieve the offset/pcodeOp pairs that are used to load data from the variable used to fill-out structure.
  `List<FillOutStructureHelper.OffsetPcodeOpPair>`
  `getStorePcodeOps()`
  Retrieve the offset/pcodeOp pairs that are used to store data into the variable used to fill-out structure.
  `static Structure`
  `getStructureForExtending(DataType dt)`
  Check if a variable has a data-type that is suitable for being extended.
  `Structure`
  `processStructure(HighVariable var, Function function, boolean createNewStructure, boolean createClassIfNeeded, DecompInterface decomplib)`
  Create or update a Structure data-type given a function and a root pointer variable.
  `DecompInterface`
  `setUpDecompiler(DecompileOptions options)`
  Set up a decompiler interface and prepare for decompiling on the currentProgram.

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

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

- ## Constructor Details

  - ### FillOutStructureHelper

    public FillOutStructureHelper(Program program, TaskMonitor monitor)
    Constructor.
    Parameters:
      `program` - the current program
      `monitor` - task monitor

- ## Method Details

  - ### processStructure

    public Structure processStructure(HighVariable var, Function function, boolean createNewStructure, boolean createClassIfNeeded, DecompInterface decomplib)
    Create or update a Structure data-type given a function and a root pointer variable. The function must already be decompiled, but if a decompiler interface is provided, this method will recursively follow variable references into CALLs, possibly triggering additional decompilation.
    Parameters:
      `var` - is the pointer variable
      `function` - is the function to process
      `createNewStructure` - if true a new Structure with a unique name will always be generated, if false and the variable corresponds to a Structure pointer, the existing Structure will be updated instead.
      `createClassIfNeeded` - if true and variable corresponds to a this pointer without an assigned Ghidra Class (i.e., `void * this`), the function will be assigned to a new unique Ghidra Class namespace with a new identically named Structure returned. If false, a new unique Structure will be created.
      `decomplib` - is the (optional) decompiler interface, which can be used to recursively decompile into CALLs.
    Returns:
      a filled-in Structure or null if one could not be created

  - ### getComponentMap

    public NoisyStructureBuilder getComponentMap()
    Retrieve the component map that was generated when structure was created using decompiler info. Results are not valid until `processStructure(HighVariable, Function, boolean, boolean, DecompInterface)` is invoked.
    Returns:
      componentMap

  - ### getStorePcodeOps

    public List<FillOutStructureHelper.OffsetPcodeOpPair> getStorePcodeOps()
    Retrieve the offset/pcodeOp pairs that are used to store data into the variable used to fill-out structure. Results are not valid until `processStructure(HighVariable, Function, boolean, boolean, DecompInterface)` is invoked.
    Returns:
      the pcodeOps doing the storing to the associated variable

  - ### getLoadPcodeOps

    public List<FillOutStructureHelper.OffsetPcodeOpPair> getLoadPcodeOps()
    Retrieve the offset/pcodeOp pairs that are used to load data from the variable used to fill-out structure. Results are not valid until `processStructure(HighVariable, Function, boolean, boolean, DecompInterface)` is invoked.
    Returns:
      the pcodeOps doing the loading from the associated variable

  - ### computeHighVariable

    public HighVariable computeHighVariable(Address storageAddress, Function function, DecompInterface decomplib)
    Decompile a function and return the resulting HighVariable associated with a storage address
    Parameters:
      `storageAddress` - the storage address of the variable
      `function` - is the function
      `decomplib` - is the active interface to use for decompiling
    Returns:
      the corresponding HighVariable or null

  - ### setUpDecompiler

    public DecompInterface setUpDecompiler(DecompileOptions options)
    Set up a decompiler interface and prepare for decompiling on the currentProgram. The interface can be used to pass to computeHighVariable or to processStructure.
    Parameters:
      `options` - are the options to pass to the decompiler
    Returns:
      the decompiler interface

  - ### getStructureForExtending

    public static Structure getStructureForExtending(DataType dt)
    Check if a variable has a data-type that is suitable for being extended. If so return the structure data-type, otherwise return null. Modulo typedefs, the data-type of the variable must be exactly a "pointer to a structure". Not a "structure" itself, or a "pointer to a pointer to ... a structure".
    Parameters:
      `dt` - is the data-type of the variable to test
    Returns:
      the extendable structure data-type or null