Package ghidra.program.model.pcode

Class AddressXML

  • public class AddressXML
extends java.lang.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 \ 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 \ tag and produce a general AddressXML object.

    • 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

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void appendAttributes​(java.lang.StringBuilder buf, Address addr)
      Append "space" and "offset" attributes describing the given Address to the XML stream.
      static void appendAttributes​(java.lang.StringBuilder buf, Address addr, int size)
      Append "space" "offset" and "size" attributes describing the given memory range to the XML stream.
      static void appendAttributes​(java.lang.StringBuilder buffer, Address startAddr, Address endAddr)
      Append a memory range, as "space", "first", and "last" attributes, to the XML stream.
      static void buildXML​(java.lang.StringBuilder buf, Address addr)
      Write out the given Address as an \ tag to the XML stream
      static void buildXML​(java.lang.StringBuilder buf, Address addr, int size)
      Write out the given Address and a size as an \ tag to the XML stream
      static void buildXML​(java.lang.StringBuilder buf, Varnode[] varnodes, long logicalsize)
      Write out a sequence of Varnodes as a single \ tag to an XML stream.
      AddressSpace getAddressSpace()  
      Address getFirstAddress()  
      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()  
      long getOffset()  
      long getSize()  
      Varnode getVarnode()
      Build a raw Varnode from the Address and size
      static Address readXML​(XmlElement el, AddressFactory addrFactory)
      Create an address from an XML parse tree node.
      static Address readXML​(java.lang.String addrstring, AddressFactory addrfactory)
      Parse String containing an XML tag representing an Address.
      static Address readXML​(java.lang.String localName, org.xml.sax.Attributes attr, AddressFactory addrFactory)
      Read an Address given an XML tag name and its attributes.
      static int readXMLSize​(java.lang.String addrxml)
      Read the (first) size attribute from an XML tag string as an integer
      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.
      void saveXml​(java.lang.StringBuilder buffer)
      Write this sized address as an \ XML tag.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • 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 Detail

      • saveXml

        public void saveXml​(java.lang.StringBuilder buffer)
        Write this sized address as an \ XML tag.
        Parameters:
        buffer - is the buffer to write to

      • 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

      • readXML

        public static Address readXML​(java.lang.String addrstring,
                              AddressFactory addrfactory)
                       throws PcodeXMLException
        Parse String containing an XML tag representing an Address. The format options are simple enough that we don't try to invoke an actual XML parser but just walk the string. This recognizes - \ - \ or - any tag with a "space" and "offset" attribute
        Parameters:
        addrstring - is the string containing the XML tag
        addrfactory - is the factory that can produce addresses
        Returns:
        the created Address or Address.NO_ADDRESS in some special cases
        Throws:
        PcodeXMLException - for a badly formed Address

      • readXMLSize

        public static int readXMLSize​(java.lang.String addrxml)
        Read the (first) size attribute from an XML tag string as an integer
        Parameters:
        addrxml - is the XML string
        Returns:
        the decoded integer or zero if the attribute doesn't exist

      • readXML

        public static Address readXML​(XmlElement el,
                              AddressFactory addrFactory)
        Create an address from an XML parse tree node. This recognizes XML tags - \ - \ - \ or - any tag with "space" and "offset" attributes An empty \ tag, with no attributes, results in Address.NO_ADDRESS being returned.
        Parameters:
        el - is the parse tree element
        addrFactory - address factory used to create valid addresses
        Returns:
        Address created from XML info

      • readXML

        public static Address readXML​(java.lang.String localName,
                              org.xml.sax.Attributes attr,
                              AddressFactory addrFactory)
        Read an Address given an XML tag name and its attributes. This recognizes XML tags - \ - \ - \ - any tag with "space" or "offset" attributes An empty \ tag, with no attributes, results in Address.NO_ADDRESS being returned.
        Parameters:
        localName - is the name of the tag
        attr - is the collection of attributes for the tag
        addrFactory - is an Address factory
        Returns:
        the scanned address

      • appendAttributes

        public static void appendAttributes​(java.lang.StringBuilder buf,
                                    Address addr)
        Append "space" and "offset" attributes describing the given Address to the XML stream. This assumes the XML tag name has already been emitted.
        Parameters:
        buf - is the XML stream
        addr - is the given Address

      • appendAttributes

        public static void appendAttributes​(java.lang.StringBuilder buf,
                                    Address addr,
                                    int size)
        Append "space" "offset" and "size" attributes describing the given memory range to the XML stream. This assumes the XML tag name has already been emitted.
        Parameters:
        buf - is the XML stream
        addr - is the starting Address of the memory range
        size - is the size of the memory range

      • appendAttributes

        public static void appendAttributes​(java.lang.StringBuilder buffer,
                                    Address startAddr,
                                    Address endAddr)
        Append a memory range, as "space", "first", and "last" attributes, to the XML stream. This assumes the XML tag name has already been emitted.
        Parameters:
        buffer - is the XML stream
        startAddr - is the first address in the range
        endAddr - is the last address in the range

      • buildXML

        public static void buildXML​(java.lang.StringBuilder buf,
                            Address addr)
        Write out the given Address as an \ tag to the XML stream
        Parameters:
        buf - is the XML stream
        addr - -- Address to convert to XML

      • buildXML

        public static void buildXML​(java.lang.StringBuilder buf,
                            Address addr,
                            int size)
        Write out the given Address and a size as an \ tag to the XML stream
        Parameters:
        buf - is the XML stream
        addr - is the given Address
        size - is the given size

      • buildXML

        public static void buildXML​(java.lang.StringBuilder buf,
                            Varnode[] varnodes,
                            long logicalsize)
        Write out a sequence of Varnodes as a single \ tag to an XML stream. If there is more than one Varnode, or if the logical size is non-zero, the \ tag will specify the address space as "join" and will have additional "piece" attributes.
        Parameters:
        buf - is the XML stream
        varnodes - is the sequence of storage varnodes
        logicalsize - is the logical size value of the varnode