Package ghidra.program.model.pcode

# Class AddressXML

java.lang.Object
ghidra.program.model.pcode.AddressXML

public class AddressXML extends Object
Utility class for the myriad ways of marshaling/unmarshaling an address and an optional size, to/from XML for the various configuration files.

An object of the class itself is the most general form, where the specified address

- MAY have an associated size given in bytes
- MAY be in the JOIN address space, with physical pieces making up the logical value explicitly provided

The static buildXML methods write out an `<addr>` tag given component elements without allocating an object. The static readXML methods read XML tags (presented in different forms) and returns an Address object. The static appendAttributes methods write out attributes of an address to an arbitrary XML tag. The static restoreXML methods read an `<addr>` tag and produce a general AddressXML object.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static int`
  `MAX_PIECES`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AddressXML(AddressSpace spc, long off, int sz)`
  Construct an Address range as a space/offset/size
  `AddressXML(AddressSpace spc, long off, int sz, Varnode[] pieces)`
  Construct a logical memory range, representing multiple ranges pieced together.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static Address`
  `decode(Decoder decoder)`
  Create an address from a stream encoding.
  `static Address`
  `decodeFromAttributes(Decoder decoder)`
  Create an address from "space" and "offset" attributes of the current element
  `static VariableStorage`
  `decodeStorageFromAttributes(int size, Decoder decoder, PcodeFactory pcodeFactory)`
  Decode a VariableStorage object from the attributes in the current address element.
  `void`
  `encode(Encoder encoder)`
  Encode this sized address as an `<addr>` element to the stream
  `static void`
  `encode(Encoder encoder, Address addr)`
  Encode the given Address as an `<addr>` element to the stream
  `static void`
  `encode(Encoder encoder, Address addr, int size)`
  Encode the given Address and a size as an `<addr>` element to the stream
  `static void`
  `encode(Encoder encoder, Varnode[] varnodes, long logicalsize)`
  Encode a sequence of Varnodes as a single `<addr>` element to the stream.
  `static void`
  `encodeAttributes(Encoder encoder, Address addr)`
  Encode "space" and "offset" attributes for the current element, describing the given Address to the stream.
  `static void`
  `encodeAttributes(Encoder encoder, Address addr, int size)`
  Encode "space" "offset" and "size" attributes for the current element, describing the given memory range to the stream.
  `static void`
  `encodeAttributes(Encoder encoder, Address startAddr, Address endAddr)`
  Encode a memory range, as "space", "first", and "last" attributes, for the current element, to the stream.
  `final AddressSpace`
  `getAddressSpace()`
  `Address`
  `getFirstAddress()`
  `final Varnode[]`
  `getJoinRecord()`
  Get the array of physical pieces making up this logical address range, if the range is in the JOIN address space.
  `Address`
  `getLastAddress()`
  `final long`
  `getOffset()`
  `final long`
  `getSize()`
  `Varnode`
  `getVarnode()`
  Build a raw Varnode from the Address and size
  `static AddressXML`
  `restoreRangeXml(XmlElement el, CompilerSpec cspec)`
  A memory range is read from attributes of an XML tag.
  `static AddressXML`
  `restoreXml(XmlElement el, CompilerSpec cspec)`
  Restore an Address (as an AddressSpace and an offset) and an optional size from XML tag.
  `static AddressXML`
  `restoreXml(XmlElement el, Language language)`
  Restore an Address (as an AddressSpace and an offset) and an optional size from XML tag.

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

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

- ## Field Details

  - ### MAX_PIECES

    public static int MAX_PIECES

- ## Constructor Details

  - ### AddressXML

    public AddressXML(AddressSpace spc, long off, int sz)
    Construct an Address range as a space/offset/size
    Parameters:
      `spc` - is the address space containing the range
      `off` - is the starting byte offset of the range
      `sz` - is the size of the range in bytes

  - ### AddressXML

    public AddressXML(AddressSpace spc, long off, int sz, Varnode[] pieces)
    Construct a logical memory range, representing multiple ranges pieced together. The logical range is assigned an address in the JOIN address space. The physical pieces making up the logical range are passed in as a sequence of Varnodes representing, in order, the most significant through the least significant portions of the value.
    Parameters:
      `spc` - is the JOIN address space (must have a type of AddressSpace.TYPE_JOIN)
      `off` - is the offset of the logical value within the JOIN space
      `sz` - is the number of bytes in the logical value
      `pieces` - is the array of 1 or more physical pieces

- ## Method Details

  - ### encode

    public void encode(Encoder encoder) throws IOException
    Encode this sized address as an `<addr>` element to the stream
    Parameters:
      `encoder` - is the stream encoder
    Throws:
      `IOException` - for errors in the underlying stream

  - ### restoreXml

    public static AddressXML restoreXml(XmlElement el, CompilerSpec cspec) throws XmlParseException
    Restore an Address (as an AddressSpace and an offset) and an optional size from XML tag. The tag can have any name, but it must either have: - A "name" attribute, indicating a register name OR - A "space" and "offset" attribute, indicating the address space and offset If a register name is given, size is obtained from the register. If an offset is given, the size can optionally be specified using a "size" attribute. If not explicitly described, the size is set to zero. This method supports the "join" address space attached to the compiler specification
    Parameters:
      `el` - is the XML tag
      `cspec` - is the compiler spec for looking up registers
    Returns:
      an AddressXML object containing the recovered space,offset,size
    Throws:
      `XmlParseException` - for problems parsing

  - ### restoreXml

    public static AddressXML restoreXml(XmlElement el, Language language) throws XmlParseException
    Restore an Address (as an AddressSpace and an offset) and an optional size from XML tag. The tag can have any name, but it must either have: - A "name" attribute, indicating a register name OR - A "space" and "offset" attribute, indicating the address space and offset If a register name is given, size is obtained from the register. If an offset is given, the size can optionally be specified using a "size" attribute. If not explicitly described, the size is set to zero.
    Parameters:
      `el` - is the XML tag
      `language` - is the processor language for looking up registers and address spaces
    Returns:
      an AddressXML object containing the recovered space,offset,size
    Throws:
      `XmlParseException` - for problems parsing

  - ### restoreRangeXml

    public static AddressXML restoreRangeXml(XmlElement el, CompilerSpec cspec) throws XmlParseException
    A memory range is read from attributes of an XML tag. The tag must either have: - "name" attribute - indicating a register - "space" attribute - with optional "first" and "last" attributes With the "space" attribute, "first" defaults to 0 and "last" defaults to the last offset in the space.
    Parameters:
      `el` - is the XML element
      `cspec` - is a compiler spec to resolve address spaces and registers
    Returns:
      an AddressXML object representing the range
    Throws:
      `XmlParseException` - if the XML is badly formed

  - ### getAddressSpace

    public final AddressSpace getAddressSpace()
    Returns:
      the space associated of this address

  - ### getOffset

    public final long getOffset()
    Returns:
      the byte offset of this address

  - ### getSize

    public final long getSize()
    Returns:
      the size in bytes associated with this address

  - ### getJoinRecord

    public final Varnode[] getJoinRecord()
    Get the array of physical pieces making up this logical address range, if the range is in the JOIN address space. Otherwise return null.
    Returns:
      the physical pieces or null

  - ### getVarnode

    public Varnode getVarnode()
    Build a raw Varnode from the Address and size
    Returns:
      the new Varnode

  - ### getFirstAddress

    public Address getFirstAddress()
    Returns:
      the first address in the range

  - ### getLastAddress

    public Address getLastAddress()
    Returns:
      the last address in the range

  - ### decodeFromAttributes

    public static Address decodeFromAttributes(Decoder decoder) throws DecoderException
    Create an address from "space" and "offset" attributes of the current element
    Parameters:
      `decoder` - is the stream decoder
    Returns:
      the decoded Address
    Throws:
      `DecoderException` - for any problems decoding the stream

  - ### decodeStorageFromAttributes

    public static VariableStorage decodeStorageFromAttributes(int size, Decoder decoder, PcodeFactory pcodeFactory) throws DecoderException
    Decode a VariableStorage object from the attributes in the current address element. The start of storage corresponds to the decoded address. The size is either passed in or is decoded from a size attribute.
    Parameters:
      `size` - is the desired size of storage or -1 to use the size attribute
      `decoder` - is the stream decoder
      `pcodeFactory` - is used to resolve address spaces, etc.
    Returns:
      the decoded VariableStorage
    Throws:
      `DecoderException` - for any errors in the encoding or problems creating the storage

  - ### decode

    public static Address decode(Decoder decoder) throws DecoderException
    Create an address from a stream encoding. This recognizes elements
    - `<addr>`
    - `<spaceid>`
    - `<iop>` or
    - any element with "space" and "offset" attributes
    An empty `<addr>` element, with no attributes, results in `Address.NO_ADDRESS` being returned.
    Parameters:
      `decoder` - is the stream decoder
    Returns:
      Address created from decode info
    Throws:
      `DecoderException` - for any problems decoding the stream

  - ### encodeAttributes

    public static void encodeAttributes(Encoder encoder, Address addr) throws IOException
    Encode "space" and "offset" attributes for the current element, describing the given Address to the stream.
    Parameters:
      `encoder` - is the stream encoder
      `addr` - is the given Address
    Throws:
      `IOException` - for errors in the underlying stream

  - ### encodeAttributes

    public static void encodeAttributes(Encoder encoder, Address addr, int size) throws IOException
    Encode "space" "offset" and "size" attributes for the current element, describing the given memory range to the stream.
    Parameters:
      `encoder` - is the stream encoder
      `addr` - is the starting Address of the memory range
      `size` - is the size of the memory range
    Throws:
      `IOException` - for errors in the underlying stream

  - ### encodeAttributes

    public static void encodeAttributes(Encoder encoder, Address startAddr, Address endAddr) throws IOException
    Encode a memory range, as "space", "first", and "last" attributes, for the current element, to the stream.
    Parameters:
      `encoder` - is the stream encoder
      `startAddr` - is the first address in the range
      `endAddr` - is the last address in the range
    Throws:
      `IOException` - for errors in the underlying stream

  - ### encode

    public static void encode(Encoder encoder, Address addr) throws IOException
    Encode the given Address as an `<addr>` element to the stream
    Parameters:
      `encoder` - is the stream encoder
      `addr` - -- Address to encode
    Throws:
      `IOException` - for errors in the underlying stream

  - ### encode

    public static void encode(Encoder encoder, Address addr, int size) throws IOException
    Encode the given Address and a size as an `<addr>` element to the stream
    Parameters:
      `encoder` - is the stream encoder
      `addr` - is the given Address
      `size` - is the given size
    Throws:
      `IOException` - for errors in the underlying stream

  - ### encode

    public static void encode(Encoder encoder, Varnode[] varnodes, long logicalsize) throws IOException
    Encode a sequence of Varnodes as a single `<addr>` element to the stream. If there is more than one Varnode, or if the logical size is non-zero, the `<addr>` element will specify the address space as "join" and will have additional "piece" attributes.
    Parameters:
      `encoder` - is the stream encoder
      `varnodes` - is the sequence of storage varnodes
      `logicalsize` - is the logical size value of the varnode
    Throws:
      `IOException` - for errors in the underlying stream