Package ghidra.program.model.listing

# Interface ProgramContext

All Known Implementing Classes:
  `AbstractProgramContext`, `AbstractStoredProgramContext`, `DBTraceProgramViewProgramContext`, `Disassembler.DisassemblerProgramContext`, `OldProgramContextDB`, `ProgramContextImpl`, `ProgramRegisterContextDB`

public interface ProgramContext
Interface to define a processor register context over the address space.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Register`
  `getBaseContextRegister()`
  Returns the base context register.
  `List<Register>`
  `getContextRegisters()`
  Gets the registers for this context that are used for processor context states.
  `RegisterValue`
  `getDefaultDisassemblyContext()`
  `AddressRangeIterator`
  `getDefaultRegisterValueAddressRanges(Register register)`
  Returns an AddressRangeIterator over all addresses that have an associated default value for the given register.
  `AddressRangeIterator`
  `getDefaultRegisterValueAddressRanges(Register register, Address start, Address end)`
  Returns an AddressRangeIterator over all addresses that have an associated default value within the given range for the given register.
  `RegisterValue`
  `getDefaultValue(Register register, Address address)`
  Returns the default value of a register at a given address.
  `RegisterValue`
  `getDisassemblyContext(Address address)`
  Get the disassembly context for a specified address.
  `RegisterValue`
  `getFlowValue(RegisterValue value)`
  Modify register value to eliminate non-flowing bits
  `RegisterValue`
  `getNonDefaultValue(Register register, Address address)`
  Returns the (non-default)value assigned to a register at a given address.
  `RegisterValue`
  `getNonFlowValue(RegisterValue value)`
  Modify register value to only include non-flowing bits
  `Register`
  `getRegister(String name)`
  Get a Register object given the name of a register
  `List<String>`
  `getRegisterNames()`
  Get an alphabetical sorted unmodifiable list of original register names (including context registers).
  `List<Register>`
  `getRegisters()`
  Get all the register descriptions defined for this program context.
  `Register[]`
  `getRegistersWithValues()`
  Returns an array of all registers that at least one value associated with an address.
  `RegisterValue`
  `getRegisterValue(Register register, Address address)`
  Returns a register value and mask for the given register.
  `AddressRangeIterator`
  `getRegisterValueAddressRanges(Register register)`
  Returns an AddressRangeIterator over all addresses that have an associated value for the given register.
  `AddressRangeIterator`
  `getRegisterValueAddressRanges(Register register, Address start, Address end)`
  Returns an AddressRangeIterator over all addresses that have an associated value within the given range for the given register.
  `AddressRange`
  `getRegisterValueRangeContaining(Register register, Address addr)`
  Returns the bounding address-range containing addr and the same RegisterValue throughout.
  `BigInteger`
  `getValue(Register register, Address address, boolean signed)`
  Returns the value assigned to a register at a given address.
  `boolean`
  `hasNonFlowingContext()`
  `boolean`
  `hasValueOverRange(Register reg, BigInteger value, AddressSetView addrSet)`
  Returns true if the given register has the value over the addressSet
  `void`
  `remove(Address start, Address end, Register register)`
  Remove (unset) the register values for a given address range.
  `void`
  `setDefaultDisassemblyContext(RegisterValue value)`
  Set the initial disassembly context to be used when initiating disassmbly
  `void`
  `setRegisterValue(Address start, Address end, RegisterValue value)`
  Sets the register context over the given range to the given value.
  `void`
  `setValue(Register register, Address start, Address end, BigInteger value)`
  Associates a value with a register over a given address range.

- ## Method Details

  - ### hasNonFlowingContext

    boolean hasNonFlowingContext()
    Returns:
      true if one or more non-flowing context registers fields have been defined within the base processor context register.

  - ### getFlowValue

    RegisterValue getFlowValue(RegisterValue value)
    Modify register value to eliminate non-flowing bits
    Parameters:
      `value` - register value to be modified
    Returns:
      value suitable for flowing

  - ### getNonFlowValue

    RegisterValue getNonFlowValue(RegisterValue value)
    Modify register value to only include non-flowing bits
    Parameters:
      `value` - register value to be modified
    Returns:
      new value or null

  - ### getRegister

    Register getRegister(String name)
    Get a Register object given the name of a register
    Parameters:
      `name` - the name of the register.
    Returns:
      The register with the given name or null if no register has that name.

  - ### getRegisters

    List<Register> getRegisters()
    Get all the register descriptions defined for this program context.
    Returns:
      unmodifiable list of defined register descriptions

  - ### getRegistersWithValues

    Register[] getRegistersWithValues()
    Returns an array of all registers that at least one value associated with an address.
    Returns:
      a array of all registers that at least one value associated with an address.

  - ### getValue

    BigInteger getValue(Register register, Address address, boolean signed)
    Returns the value assigned to a register at a given address. This method will return any default value assigned to the register at the given address if no explicit value has been set at that address.
    Parameters:
      `register` - the register for which to get its value.
      `address` - the address at which to get a value.
      `signed` - if true, interprets the fix-bit size register value as a signed value.
    Returns:
      a BigInteger object containing the value of the registe at the given address or null if no value has been assigned.

  - ### getRegisterValue

    RegisterValue getRegisterValue(Register register, Address address)
    Returns a register value and mask for the given register.
    Parameters:
      `register` - the register
      `address` - the address of the value
    Returns:
      a register value and mask for the given register

  - ### setRegisterValue

    void setRegisterValue(Address start, Address end, RegisterValue value) throws ContextChangeException
    Sets the register context over the given range to the given value.
    Parameters:
      `start` - the start address to set values
      `end` - the end address to set values
      `value` - the actual values to store at address
    Throws:
      `ContextChangeException` - if failed to modifiy context across specified range (e.g., instruction exists).

  - ### getNonDefaultValue

    RegisterValue getNonDefaultValue(Register register, Address address)
    Returns the (non-default)value assigned to a register at a given address.
    Parameters:
      `register` - the register for which to get its value.
      `address` - the address at which to get a value.
    Returns:
      a RegisterValue object containing the value of the register at the given address or possibly null if no value has been assigned.

  - ### setValue

    void setValue(Register register, Address start, Address end, BigInteger value) throws ContextChangeException
    Associates a value with a register over a given address range. Any previous values will be overwritten.
    Parameters:
      `register` - the register for which to assign a value.
      `start` - the start address.
      `end` - the end address (inclusive).
      `value` - the value to assign. A value of null will effective clear any existing values.
    Throws:
      `ContextChangeException` - if failed to modifiy context across specified range (e.g., instruction exists).

  - ### getRegisterValueAddressRanges

    AddressRangeIterator getRegisterValueAddressRanges(Register register)
    Returns an AddressRangeIterator over all addresses that have an associated value for the given register. Each range returned will have the same value associated with the register for all addresses in that range.
    Parameters:
      `register` - the register for which to get set value ranges.
    Returns:
      An AddressRangeIterator over all address that have values for the given register.

  - ### getRegisterValueAddressRanges

    AddressRangeIterator getRegisterValueAddressRanges(Register register, Address start, Address end)
    Returns an AddressRangeIterator over all addresses that have an associated value within the given range for the given register. Each range returned will have the same value associated with the register for all addresses in that range.
    Parameters:
      `register` - the register for which to get set value ranges.
      `start` - start of address range to search
      `end` - end of address range to search
    Returns:
      An AddressRangeIterator over all address within the given range that have values for the given register.

  - ### getRegisterValueRangeContaining

    AddressRange getRegisterValueRangeContaining(Register register, Address addr)
    Returns the bounding address-range containing addr and the same RegisterValue throughout. The range returned may be limited by other value changes associated with register's base-register.
    Parameters:
      `register` - program register
      `addr` - program address
    Returns:
      single register-value address-range containing addr

  - ### getDefaultRegisterValueAddressRanges

    AddressRangeIterator getDefaultRegisterValueAddressRanges(Register register)
    Returns an AddressRangeIterator over all addresses that have an associated default value for the given register. Each range returned will have the same default value associated with the register for all addresses in that range.
    Parameters:
      `register` - the register for which to get set default value ranges.
    Returns:
      An AddressRangeIterator over all address that have default values for the given register.

  - ### getDefaultRegisterValueAddressRanges

    AddressRangeIterator getDefaultRegisterValueAddressRanges(Register register, Address start, Address end)
    Returns an AddressRangeIterator over all addresses that have an associated default value within the given range for the given register. Each range returned will have the same default value associated with the register for all addresses in that range.
    Parameters:
      `register` - the register for which to get default value ranges.
      `start` - start of address range to search
      `end` - end of address range to search
    Returns:
      An AddressRangeIterator over all address within the given range that have default values for the given register.

  - ### getContextRegisters

    List<Register> getContextRegisters()
    Gets the registers for this context that are used for processor context states.
    Returns:
      all processor context registers

  - ### remove

    void remove(Address start, Address end, Register register) throws ContextChangeException
    Remove (unset) the register values for a given address range.
    Parameters:
      `start` - starting address.
      `end` - ending adddress.
      `register` - handle to the register to be set.
    Throws:
      `ContextChangeException` - thrown if context change not permitted over specified range (e.g., instructions exist)

  - ### getRegisterNames

    List<String> getRegisterNames()
    Get an alphabetical sorted unmodifiable list of original register names (including context registers). Names correspond to orignal register name and not aliases which may be defined.
    Returns:
      alphabetical sorted unmodifiable list of original register names.

  - ### hasValueOverRange

    boolean hasValueOverRange(Register reg, BigInteger value, AddressSetView addrSet)
    Returns true if the given register has the value over the addressSet
    Parameters:
      `reg` - the register whose value is to be tested.
      `value` - the value to test for.
      `addrSet` - the set of addresses to test
    Returns:
      true if every address in the addrSet has the value.

  - ### getDefaultValue

    RegisterValue getDefaultValue(Register register, Address address)
    Returns the default value of a register at a given address.
    Parameters:
      `register` - the register for which to get a default value.
      `address` - the address at which to get a default value.
    Returns:
      the default value of the register at the given address or null if no default value has been assigned.

  - ### getBaseContextRegister

    Register getBaseContextRegister()
    Returns the base context register.
    Returns:
      the base context register.

  - ### getDefaultDisassemblyContext

    RegisterValue getDefaultDisassemblyContext()
    Returns:
      Get the current default disassembly context to be used when initiating disassmbly

  - ### setDefaultDisassemblyContext

    void setDefaultDisassemblyContext(RegisterValue value)
    Set the initial disassembly context to be used when initiating disassmbly
    Parameters:
      `value` - context register value

  - ### getDisassemblyContext

    RegisterValue getDisassemblyContext(Address address)
    Get the disassembly context for a specified address. This context is formed from the default disassembly context and the context register value stored at the specified address. Those bits specified by the stored context value take precedence.
    Parameters:
      `address` - program address
    Returns:
      disassembly context register value