Package ghidra.program.model.listing
Class VariableUtilities
java.lang.Object
ghidra.program.model.listing.VariableUtilities
-
Nested Class Summary
-
Method Summary
Modifier and TypeMethodDescriptionstatic DataType
checkDataType
(DataType dataType, boolean voidOK, int defaultSize, DataTypeManager dtMgr) Check the specified datatype for use as a return, parameter or variable type.static DataType
checkDataType
(DataType dataType, boolean voidOK, int defaultSize, Program program) Check the specified datatype for use as a return, parameter or variable type.static DataType
checkDataType
(DataType dataType, boolean voidOK, DataTypeManager dtMgr) Check the specified datatype for use as a return, parameter or variable type.static VariableStorage
checkStorage
(Function function, VariableStorage storage, DataType dataType, boolean allowSizeMismatch) Perform variable storage checks using the specified datatype.static void
checkStorage
(VariableStorage storage, DataType dataType, boolean allowSizeMismatch) Perform variable storage checks using the specified datatype.static void
checkVariableConflict
(Function function, Variable var, VariableStorage newStorage, boolean deleteConflictingVariables) Check for variable storage conflict and optionally remove conflicting variables.static void
checkVariableConflict
(List<? extends Variable> existingVariables, Variable var, VariableStorage newStorage, VariableUtilities.VariableConflictHandler conflictHandler) Check for variable storage conflict and optionally remove conflicting variables.static int
Compare two variables without using the instance specific compareTo method.static boolean
equivalentVariableArrays
(Variable[] vars1, Variable[] vars2) static boolean
equivalentVariables
(Variable var1, Variable var2) static Structure
Find the structure data type which corresponds to the specified function's class namespace within the function's program.static Structure
findExistingClassStruct
(GhidraClass classNamespace, DataTypeManager dataTypeManager) Find the structure data type which corresponds to the specified class namespace within the specified data type manager.static Structure
findOrCreateClassStruct
(Function function) Find the structure data type which corresponds to the specified function's class namespace within the function's program.static Structure
findOrCreateClassStruct
(GhidraClass classNamespace, DataTypeManager dataTypeManager) Find the structure data type which corresponds to the specified class namespace within the specified data type manager.static DataType
getAutoDataType
(Function function, DataType returnDataType, VariableStorage storage) Determine the appropriate data type for an automatic parameterstatic Integer
getBaseStackParamOffset
(Function function) Determine the minimum stack offset for parametersstatic int
getPrecedence
(Variable var) Get a precedence value for the specified variable.static ParameterImpl
getThisParameter
(Function function, PrototypeModel convention) Deprecated.should rely on auto-param instead - try not to use this method which may be eliminatedstatic VariableStorage
resizeStorage
(VariableStorage curStorage, DataType dataType, boolean alignStack, Function function) Perform resize variable storage to desired newSize.static boolean
storageMatches
(List<? extends Variable> vars, Variable... otherVars) Compare storage varnodes for two lists of variables.static boolean
storageMatches
(List<Variable> vars, List<Variable> otherVars) Compare storage varnodes for two lists of variables.
-
Method Details
-
getPrecedence
Get a precedence value for the specified variable. This value can be used to assist with LocalVariable.compareTo(Variable var)- Parameters:
var
- function variable- Returns:
- numeric precedence
-
storageMatches
Compare storage varnodes for two lists of variables. No check is done to ensure that storage is considered good/valid (i.e., BAD_STORAGE, UNASSIGNED_STORAGE and VOID_STORAGE all have an empty varnode list and would be considered a match)- Parameters:
vars
- function variablesotherVars
- other function variables- Returns:
- true if the exact sequence of variable storage varnodes matches across two lists of variables.
-
storageMatches
Compare storage varnodes for two lists of variables. No check is done to ensure that storage is considered good/valid (i.e., BAD_STORAGE, UNASSIGNED_STORAGE and VOID_STORAGE all have an empty varnode list and would be considered a match)- Parameters:
vars
- function variablesotherVars
- other function variables- Returns:
- true if the exact sequence of variable storage varnodes matches across two lists of variables.
-
compare
Compare two variables without using the instance specific compareTo method.- Parameters:
v1
- a function variablev2
- another function variable- Returns:
- a negative value if v1 < v2, 0 if equal, and positive if v1 > v2
-
getAutoDataType
public static DataType getAutoDataType(Function function, DataType returnDataType, VariableStorage storage) Determine the appropriate data type for an automatic parameter- Parameters:
function
- function whose auto param datatype is to be determinedreturnDataType
- function's formal return datatypestorage
- variable storage for an auto-parameter (isAutoStorage should be true)- Returns:
- auto-parameter data type
-
checkStorage
public static void checkStorage(VariableStorage storage, DataType dataType, boolean allowSizeMismatch) throws InvalidInputException Perform variable storage checks using the specified datatype.- Parameters:
storage
- variable storage whose size must match the specified data type sizedataType
- a datatype checked usingcheckDataType(DataType, boolean, int, Program)
allowSizeMismatch
- if true size mismatch will be ignore- Throws:
InvalidInputException
- if specified storage is not suitable for datatype
-
checkStorage
public static VariableStorage checkStorage(Function function, VariableStorage storage, DataType dataType, boolean allowSizeMismatch) throws InvalidInputException Perform variable storage checks using the specified datatype.- Parameters:
function
- if specified and variable storage size does not match the data-type size an attempt will be made to resize the specified storage.storage
- variable storagedataType
- a datatype checked usingcheckDataType(DataType, boolean, int, Program)
allowSizeMismatch
- if true size mismatch will be ignore- Returns:
- original storage or resized storage with the correct size.
- Throws:
InvalidInputException
- if specified storage is not suitable for datatype
-
checkDataType
public static DataType checkDataType(DataType dataType, boolean voidOK, int defaultSize, DataTypeManager dtMgr) throws InvalidInputException Check the specified datatype for use as a return, parameter or variable type. It may not be suitable for other uses. The following datatypes will be mutated into a default pointer datatype:- Function definition datatype
- An unsized/zero-element array
- Parameters:
dataType
- datatype to be checkedvoidOK
- true if checking return datatype and void is allow, else false.defaultSize
- Undefined datatype size to be used if specified datatype is null. A value less than 1 will result in the DEFAULT data type being returned (i.e., "undefined").dtMgr
- target datatype manager (null permitted which will adopt default data organization)- Returns:
- cloned/mutated datatype suitable for function parameters and variables (including function return data type).
- Throws:
InvalidInputException
- if an unacceptable datatype was specified
-
checkDataType
public static DataType checkDataType(DataType dataType, boolean voidOK, int defaultSize, Program program) throws InvalidInputException Check the specified datatype for use as a return, parameter or variable type. It may not be suitable for other uses. The following datatypes will be mutated into a default pointer datatype:- Function definition datatype
- An unsized/zero-element array
- Parameters:
dataType
- datatype to be checkedvoidOK
- true if checking return datatype and void is allow, else false.defaultSize
- Undefined datatype size to be used if specified datatype is null. A value less than 1 will result in the DEFAULT data type being returned (i.e., "undefined").program
- target program- Returns:
- cloned/mutated datatype suitable for function parameters and variables (including function return data type).
- Throws:
InvalidInputException
- if an unacceptable datatype was specified
-
checkDataType
public static DataType checkDataType(DataType dataType, boolean voidOK, DataTypeManager dtMgr) throws InvalidInputException Check the specified datatype for use as a return, parameter or variable type. It may not be suitable for other uses. The following datatypes will be mutated into a default pointer datatype:- Function definition datatype
- An unsized/zero-element array
- Parameters:
dataType
- datatype to be checked. If null is specified the DEFAULT datatype will be returned.voidOK
- true if checking return datatype and void is allow, else false.dtMgr
- target datatype manager (null permitted which will adopt default data organization)- Returns:
- cloned/mutated datatype suitable for function parameters and variables (including function return data type).
- Throws:
InvalidInputException
- if an unacceptable datatype was specified
-
resizeStorage
public static VariableStorage resizeStorage(VariableStorage curStorage, DataType dataType, boolean alignStack, Function function) throws InvalidInputException Perform resize variable storage to desired newSize. This method has limited ability to grow storage if current storage does not have a stack component or if other space constraints are exceeded.- Parameters:
curStorage
- current variable storagedataType
- variable datatypealignStack
- if false no attempt is made to align stack usage for big-endianfunction
- function which corresponds to resized variable storage- Returns:
- resize storage
- Throws:
InvalidInputException
- if unable to resize storage to specified size.
-
checkVariableConflict
public static void checkVariableConflict(Function function, Variable var, VariableStorage newStorage, boolean deleteConflictingVariables) throws VariableSizeException Check for variable storage conflict and optionally remove conflicting variables.- Parameters:
function
- function which corresponds to specified variablevar
- existing function variable or null for new variablenewStorage
- new/updated variable storagedeleteConflictingVariables
- if true function's conflicting variables may be deleted- Throws:
VariableSizeException
- if deleteConflictingVariables is false and another variable conflicts
-
checkVariableConflict
public static void checkVariableConflict(List<? extends Variable> existingVariables, Variable var, VariableStorage newStorage, VariableUtilities.VariableConflictHandler conflictHandler) throws VariableSizeException Check for variable storage conflict and optionally remove conflicting variables.- Parameters:
existingVariables
- variables to check (may contain null entries)var
- function variablenewStorage
- variable storageconflictHandler
- variable conflict handler- Throws:
VariableSizeException
- if another variable conflicts
-
getBaseStackParamOffset
Determine the minimum stack offset for parameters- Parameters:
function
- function whose stack use is to be examined- Returns:
- stack parameter offset or null if it could not be determined
-
getThisParameter
@Deprecated public static ParameterImpl getThisParameter(Function function, PrototypeModel convention) Deprecated.should rely on auto-param instead - try not to use this method which may be eliminatedGenerate a suitable 'this' parameter for the specified function- Parameters:
function
- function for which athis
parameter is to be generatedconvention
- function calling convention- Returns:
- this parameter or null of calling convention is not a 'thiscall' or some other error prevents it
-
findOrCreateClassStruct
public static Structure findOrCreateClassStruct(GhidraClass classNamespace, DataTypeManager dataTypeManager) Find the structure data type which corresponds to the specified class namespace within the specified data type manager. The preferred structure will utilize a namespace-based category path, however, the match criteria can be fuzzy and relies primarily on the class name. A properly named class structure must reside within a category whose trailing path either matches the class namespace or the class-parent's namespace. Preference is given to it residing within the class-parent's namespace. If a match is not found an empty placeholder structure will be instantiated and returned. A newly instantiated structure will not be added to the data type manager and may refer to a non-existing category path which corresponds to the class-parent's namespace. If an unrelated data-type already exists matching the class name and category, null is returned.- Parameters:
classNamespace
- class namespacedataTypeManager
- data type manager which should be searched and whose data organization should be used.- Returns:
- new or existing structure whose name matches the specified class namespace
-
findOrCreateClassStruct
Find the structure data type which corresponds to the specified function's class namespace within the function's program. The preferred structure will utilize a namespace-based category path, however, the match criteria can be fuzzy and relies primarily on the class name. A properly named class structure must reside within a category whose trailing path either matches the class namespace or the class-parent's namespace. Preference is given to it residing within the class-parent's namespace. If a match is not found an empty placeholder structure will be instantiated and returned. A newly instantiated structure will not be added to the data type manager and may refer to a non-existing category path which corresponds to the class-parent's namespace. If the function is not part of a class, or if an unrelated data-type already exists with the class's name and category, null is returned.- Parameters:
function
- function's whose class namespace is the basis for the structure- Returns:
- new or existing structure whose name matches the function's class namespace or null if function not contained within a class namespace.
-
findExistingClassStruct
public static Structure findExistingClassStruct(GhidraClass classNamespace, DataTypeManager dataTypeManager) Find the structure data type which corresponds to the specified class namespace within the specified data type manager. The preferred structure will utilize a namespace-based category path, however, the match criteria can be fuzzy and relies primarily on the class name. A properly named class structure must reside within a category whose trailing path either matches the class namespace or the class-parent's namespace. Preference is given to it residing within the class-parent's namespace.- Parameters:
classNamespace
- class namespacedataTypeManager
- data type manager which should be searched.- Returns:
- existing structure whose name matches the specified class namespace or null if not found.
-
findExistingClassStruct
Find the structure data type which corresponds to the specified function's class namespace within the function's program. The preferred structure will utilize a namespace-based category path, however, the match criteria can be fuzzy and relies primarily on the class name. A properly named class structure must reside within a category whose trailing path either matches the class namespace or the class-parent's namespace. Preference is given to it residing within the class-parent's namespace.- Parameters:
func
- the function.- Returns:
- existing structure whose name matches the specified function's class namespace or null if not found.
-
equivalentVariableArrays
-
equivalentVariables
-