Class VariableStorage

  • All Implemented Interfaces:
    java.lang.Comparable<VariableStorage>
    Direct Known Subclasses:
    DynamicVariableStorage

    public class VariableStorage
    extends java.lang.Object
    implements java.lang.Comparable<VariableStorage>
    encapsulates the ordered list of storage varnodes which correspond to a function parameter or local variable. For big-endian the first element corresponds to the most-significant varnode, while for little-endian the first element corresponds to the least-significant varnode.
    • Field Detail

      • BAD_STORAGE

        public static final VariableStorage BAD_STORAGE
        BAD_STORAGE used to identify variable storage which is no longer valid. This can be caused by various events such as significant language/processor changes or software bugs which prevent variable storage to be properly decoded.
      • UNASSIGNED_STORAGE

        public static final VariableStorage UNASSIGNED_STORAGE
        UNMASSIGNED_STORAGE used to identify parameter storage which is "unmapped" or could not be determined.
      • VOID_STORAGE

        public static final VariableStorage VOID_STORAGE
        VOID_STORAGE used to identify parameter/return storage which is "mapped" with a data-type of void.
      • varnodes

        protected final Varnode[] varnodes
      • program

        protected final Program program
    • Constructor Detail

      • VariableStorage

        protected VariableStorage()
        Construct an empty variable storage for reserved usage (i.e., BAD_STORAGE, UNMAPPED_STORAGE)
      • VariableStorage

        public VariableStorage​(Program program,
                               Varnode... varnodes)
                        throws InvalidInputException
        Construct variable storage
        Parameters:
        program -
        varnodes - one or more ordered storage varnodes
        Throws:
        InvalidInputException - if specified varnodes violate storage restrictions
      • VariableStorage

        public VariableStorage​(Program program,
                               Register... registers)
                        throws InvalidInputException
        Construct register variable storage
        Parameters:
        program -
        registers - one or more ordered registers
        Throws:
        InvalidInputException - if specified registers violate storage restrictions
      • VariableStorage

        public VariableStorage​(Program program,
                               int stackOffset,
                               int size)
                        throws InvalidInputException
        Construct stack variable storage
        Parameters:
        program -
        stackOffset - stack offset
        size - stack element size
        Throws:
        InvalidInputException - if specified registers violate storage restrictions
      • VariableStorage

        public VariableStorage​(Program program,
                               java.util.List<Varnode> varnodes)
                        throws InvalidInputException
        Construct variable storage
        Parameters:
        program -
        varnodes - one or more ordered storage varnodes
        Throws:
        InvalidInputException - if specified varnodes violate storage restrictions
    • Method Detail

      • getProgram

        public Program getProgram()
        Returns:
        program for which this storage is associated
      • size

        public int size()
        Returns:
        the total size of corresponding storage varnodes
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • getVarnodeCount

        public int getVarnodeCount()
        Returns:
        the number of varnodes associated with this variable storage
      • getVarnodes

        public Varnode[] getVarnodes()
        Returns:
        ordered varnodes associated with this variable storage
      • isAutoStorage

        public boolean isAutoStorage()
        Associated with auto-parameters. Parameters whose existence is dictated by a calling-convention may automatically inject additional hidden parameters. If this storage is associated with a auto-parameter, this method will return true.
        Returns:
        true if this storage is associated with an auto-parameter, else false
      • getAutoParameterType

        public AutoParameterType getAutoParameterType()
        If this storage corresponds to a auto-parameter, return the type associated with the auto-parameter.
        Returns:
        auto-parameter type or null if not applicable
      • isForcedIndirect

        public boolean isForcedIndirect()
        If this storage corresponds to parameter which was forced by the associated calling convention to be passed as a pointer instead of its raw type.
        Returns:
        true if this parameter was forced to be passed as a pointer instead of its raw type
      • isBadStorage

        public boolean isBadStorage()
        Returns:
        true if this storage is bad (could not be resolved)
      • isUnassignedStorage

        public boolean isUnassignedStorage()
        Returns:
        true if storage has not been assigned (no varnodes)
      • isValid

        public boolean isValid()
        Returns:
        true if storage is assigned and is not BAD
      • isVoidStorage

        public boolean isVoidStorage()
        Returns:
        true if storage corresponds to the VOID_STORAGE instance
        See Also:
        VOID_STORAGE
      • getFirstVarnode

        public Varnode getFirstVarnode()
        Returns:
        first varnode within the ordered list of varnodes
      • getLastVarnode

        public Varnode getLastVarnode()
        Returns:
        last varnode within the ordered list of varnodes
      • isStackStorage

        public boolean isStackStorage()
        Returns:
        true if storage consists of a single stack varnode
      • hasStackStorage

        public boolean hasStackStorage()
        Returns:
        true if the last varnode for simple or compound storage is a stack varnode
      • isRegisterStorage

        public boolean isRegisterStorage()
        Returns:
        true if this is a simple variable consisting of a single register varnode which will be returned by either the #getFirstStorageVarnode() or getLastStorageVarnode() methods. The register can be obtained using the getRegister() method. Keep in mind that registers may exist in a memory space or the register space.
      • getRegister

        public Register getRegister()
        Returns:
        first storage register associated with this register or compound storage, else null is returned.
        See Also:
        #isRegisterVariable()
      • getRegisters

        public java.util.List<Register> getRegisters()
        Returns:
        storage register(s) associated with this register or compound storage, else null is returned.
        See Also:
        #isRegisterVariable(), isCompoundStorage()
      • getStackOffset

        public int getStackOffset()
        Returns:
        the stack offset associated with simple stack storage or compound storage where the last varnode is stack, see hasStackStorage().
        Throws:
        java.lang.UnsupportedOperationException - if storage does not have a stack varnode
      • isMemoryStorage

        public boolean isMemoryStorage()
        Returns:
        true if storage consists of a single memory varnode which does not correspond to a register.
      • isConstantStorage

        public boolean isConstantStorage()
        Returns:
        true if storage consists of a single constant-space varnode which is used when storing local function constants.
      • isHashStorage

        public boolean isHashStorage()
        Returns:
        true if storage consists of a single hash-space varnode which is used when storing local unique function variables.
      • isUniqueStorage

        public boolean isUniqueStorage()
        Returns:
        true if storage consists of a single unique-space varnode which is used during function analysis. This type of storage is not suitable for database-stored function variables. This type of storage must be properly converted to Hash storage when storing unique function variables.
      • isCompoundStorage

        public boolean isCompoundStorage()
        Returns:
        true if storage consists of two or more storage varnodes
      • getLongHash

        public long getLongHash()
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object
      • equals

        public boolean equals​(java.lang.Object obj)
        This storage is considered equal if it consists of the same storage varnodes.
        Overrides:
        equals in class java.lang.Object
      • intersects

        public boolean intersects​(VariableStorage variableStorage)
        Determine if this variable storage intersects the specified variable storage
        Parameters:
        variableStorage -
        Returns:
        true if any intersection exists between this storage and the specified variable storage
      • intersects

        public boolean intersects​(AddressSetView set)
        Determine if this storage intersects the specified address set
        Parameters:
        set - address set
        Returns:
        true if this storage intersects the specified address set
      • intersects

        public boolean intersects​(Register reg)
        Determine if this storage intersects the specified register
        Parameters:
        set - address set
        Returns:
        true if this storage intersects the specified address set
      • contains

        public boolean contains​(Address address)
        Determine if the specified address is contained within this storage
        Parameters:
        address -
        Returns:
      • compareTo

        public int compareTo​(VariableStorage otherStorage)
        Compare this variable storage with another. A value of 0 indicates that the two objects are equal
        Specified by:
        compareTo in interface java.lang.Comparable<VariableStorage>
        See Also:
        Comparable.compareTo(java.lang.Object)
      • getSerializationString

        public java.lang.String getSerializationString()
        Return a serialization form of this variable storage.
        Returns:
        storage serialization string useful for subsequent reconstruction
      • getSerializationString

        public static java.lang.String getSerializationString​(Varnode... varnodes)
        Generate VariableStorage serialization string
        Parameters:
        varnodes -
        Returns:
        storage serialization string useful for subsequent reconstruction of a VariableStorage object
      • getVarnodes

        public static java.util.List<Varnode> getVarnodes​(AddressFactory addrFactory,
                                                          java.lang.String serialization)
                                                   throws InvalidInputException
        Parse a storage serialization string to produce an array or varnodes
        Parameters:
        addrFactory -
        serialization -
        Returns:
        array of varnodes or null if invalid
        Throws:
        InvalidInputException
      • translateSerialization

        public static java.lang.String translateSerialization​(LanguageTranslator translator,
                                                              java.lang.String serialization)
                                                       throws InvalidInputException
        Perform language translations on VariableStorage serialization string
        Parameters:
        translator - language translator
        serialization - VariableStorage serialization string
        Returns:
        translated serialization string
        Throws:
        InvalidInputException - if serialization has invalid format