Package ghidra.program.util

# Class RegisterValueStore

java.lang.Object
ghidra.program.util.RegisterValueStore

public class RegisterValueStore extends Object
This is a generalized class for storing register values over ranges. The values include mask bits to indicate which bits within the register are being set. The mask is stored along with the value so the getValue method can indicate back which bits in the value are valid. If existing values already exist at an address, the values are combined according to the masks. Any new value bits that have their associated mask bits on will overwrite any existing bits and the new mask will be anded to the existing mask. Other bits will not be affected. This class takes a RangeMapAdapter that will adapt to some lower level storage. There are current two implementations - one that uses an ObjectRangeMap for storing register values in memory and the other that uses RangeMapDB for storing register values in the database.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `RegisterValueStore(Register register, RangeMapAdapter rangeMap, boolean enableRangeWriteCache)`
  Constructs a new RegisterValueStore.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clearAll()`
  Delete all stored values and free/delete underlying storage.
  `void`
  `clearValue(Address start, Address end, Register register)`
  Clears the address range of any set bits using the mask from the given register value.
  `AddressRangeIterator`
  `getAddressRangeIterator()`
  Returns an AddressRangeIterator that will return address ranges everywhere that register values have been set.
  `AddressRangeIterator`
  `getAddressRangeIterator(Address startAddress, Address endAddress)`
  Returns an AddressRangeIterator that will return address ranges everywhere that register values have been set within the given range.
  `RegisterValue`
  `getValue(Register register, Address address)`
  Returns the RegisterValue (value and mask) associated with the given address.
  `AddressRange`
  `getValueRangeContaining(Address addr)`
  Returns the bounding address-range containing addr and the same value throughout.
  `void`
  `invalidate()`
  Notifies that something changed, may need to invalidate any caches
  `boolean`
  `isEmpty()`
  Returns true if this store has no associated values for any address.
  `void`
  `moveAddressRange(Address fromAddr, Address toAddr, long length, TaskMonitor monitor)`
  Move all register values within an address range to a new range.
  `boolean`
  `setLanguage(LanguageTranslator translator, TaskMonitor monitor)`
  Preserve register values and handle register name/size change.
  `void`
  `setValue(Address start, Address end, RegisterValue newValue)`
  Sets the given register value (contains value and mask) across the given address range.

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

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

- ## Constructor Details

  - ### RegisterValueStore

    public RegisterValueStore(Register register, RangeMapAdapter rangeMap, boolean enableRangeWriteCache)
    Constructs a new RegisterValueStore.
    Parameters:
      `rangeMap` - the rangeMapAdapter that handles the low level storage of byte arrays

- ## Method Details

  - ### moveAddressRange

    public void moveAddressRange(Address fromAddr, Address toAddr, long length, TaskMonitor monitor) throws CancelledException
    Move all register values within an address range to a new range.
    Parameters:
      `fromAddr` - the first address of the range to be moved.
      `toAddr` - the address where to the range is to be moved.
      `length` - the number of addresses to move.
      `monitor` - the task monitor.
    Throws:
      `CancelledException` - if the user canceled the operation via the task monitor.

  - ### setValue

    public void setValue(Address start, Address end, RegisterValue newValue)
    Sets the given register value (contains value and mask) across the given address range. Any existing values in the range that have values that are not part of the input mask are not changed.
    Parameters:
      `start` - the start of the range to set the register value.
      `end` - the end of the range(inclusive) to set the register value.
      `newValue` - the new register value to set.

  - ### clearAll

    public void clearAll()
    Delete all stored values and free/delete underlying storage.

  - ### clearValue

    public void clearValue(Address start, Address end, Register register)
    Clears the address range of any set bits using the mask from the given register value. existing values in the range that have values that are not part of the input mask are not changed. If register is null, just clear all the values in range
    Parameters:
      `start` - the start of the range to clear the register value bits.
      `end` - the end of the range(inclusive) to clear the register value bits.
      `register` - the register whos mask to use. If null, clear all values in the given range.

  - ### getValue

    public RegisterValue getValue(Register register, Address address)
    Returns the RegisterValue (value and mask) associated with the given address.
    Parameters:
      `register` - register (base or child) for which context value should be returned
      `address` - the address at which to get the RegisterValue.
    Returns:
      the RegisterValue

  - ### getAddressRangeIterator

    public AddressRangeIterator getAddressRangeIterator(Address startAddress, Address endAddress)
    Returns an AddressRangeIterator that will return address ranges everywhere that register values have been set within the given range.
    Parameters:
      `startAddress` - the start address to get stored register values.
      `endAddress` - the end address to get stored register values.
    Returns:
      an AddressRangeIterator that will return address ranges everywhere that register values have been set within the given range.

  - ### getAddressRangeIterator

    public AddressRangeIterator getAddressRangeIterator()
    Returns an AddressRangeIterator that will return address ranges everywhere that register values have been set.
    Returns:
      an AddressRangeIterator that will return address ranges everywhere that register values have been set.

  - ### isEmpty

    public boolean isEmpty()
    Returns true if this store has no associated values for any address.
    Returns:
      true if this store has no associated values for any address.

  - ### setLanguage

    public boolean setLanguage(LanguageTranslator translator, TaskMonitor monitor) throws CancelledException
    Preserve register values and handle register name/size change.
    Parameters:
      `translator` -
      `monitor` -
    Returns:
      true if translated successfully, false if register not mapped value storage should be discarded.
    Throws:
      `CancelledException`

  - ### getValueRangeContaining

    public AddressRange getValueRangeContaining(Address addr)
    Returns the bounding address-range containing addr and the same value throughout. This range will be limited by any value change associated with the base register.
    Parameters:
      `addr` - the contained address
    Returns:
      single value address-range containing addr

  - ### invalidate

    public void invalidate()
    Notifies that something changed, may need to invalidate any caches