Class DIEAggregate


  • public class DIEAggregate
    extends java.lang.Object
    DIEAggregate groups related DebugInfoEntry records together in a single interface for querying attribute values.

    Information about program elements are written into the .debug_info as partial snapshots of the element, with later follow-up records that more fully specify the program element.

    (For instance, a declaration-only DIE that introduces the name of a structure type will be found at the beginning of a compilation unit, followed later by a DIE that specifies the contents of the structure type)

    A DIEAggregate groups these DebugInfoEntry records under one interface so a fully specified view of the program element can be presented.

    • Method Detail

      • createFromHead

        public static DIEAggregate createFromHead​(DebugInfoEntry die)
        Creates a DIEAggregate starting from a 'head' DebugInfoEntry instance.

        DW_AT_abstract_origin and DW_AT_specification attributes are followed to find the previous DebugInfoEntry instances.

        Parameters:
        die - starting DIE record
        Returns:
        new DIEAggregate made up of the starting DIE and all DIEs that it points to via abstract_origin and spec attributes.
      • createSkipHead

        public static DIEAggregate createSkipHead​(DIEAggregate source)
        Creates a new DIEAggregate from the contents of the specified DIEA, using all the source's DebugInfoEntry fragments except for the head fragment which is skipped.

        Used when a DIEA is composed of a head DIE with a different TAG type than the rest of the DIEs. (ie. a dw_tag_call_site -> dw_tag_sub DIEA)

        Parameters:
        source -
        Returns:
      • getFragmentCount

        public int getFragmentCount()
      • getOffset

        public long getOffset()
      • getOffsets

        public long[] getOffsets()
      • hasOffset

        public boolean hasOffset​(long offset)
        Returns true if any of the DIEs that makeup this aggregate have the specified offset.
        Parameters:
        offset - DIE offset to search for
        Returns:
        true if this DIEAggregate has a fragment DIE at that offset.
      • getDeclOffset

        public long getDeclOffset()
      • getHexOffset

        public java.lang.String getHexOffset()
        Returns getOffset() as a hex string.
        Returns:
      • getTag

        public int getTag()
      • getLastFragment

        public DebugInfoEntry getLastFragment()
        Returns the last DIE fragment, ie. the decl DIE.
        Returns:
      • getHeadFragment

        public DebugInfoEntry getHeadFragment()
        Returns the first DIE fragment, ie. the spec or abstract_origin DIE.
        Returns:
      • getDepth

        public int getDepth()
        Returns the depth of the head fragment, where depth is defined as the distance between the DIE and the root DIE of the owning compilation unit.

        The root die would return 0, the children of the root will return 1, etc.

        This value matches the nesting value shown when dumping DWARF info using 'readelf'.

        Returns:
      • getAttribute

        public <T extends DWARFAttributeValue> T getAttribute​(int attribute,
                                                              java.lang.Class<T> clazz)
        Finds a attribute with a matching DWARFAttribute type

        Returns null if the attribute does not exist or is wrong java class type.

        Attributes are searched for in each fragment in this aggregate, starting with the 'head' fragment, progressing toward the 'decl' fragment.

        Parameters:
        attribute - See DWARFAttribute
        clazz - must be derived from DWARFAttributeValue
        Returns:
      • getLong

        public long getLong​(int attribute,
                            long defaultValue)
        Returns the value of the requested attribute, or -defaultValue- if the attribute is missing.
        Parameters:
        attribute -
        defaultValue -
        Returns:
      • getBool

        public boolean getBool​(int attribute,
                               boolean defaultValue)
        Returns the boolean value of the requested attribute, or -defaultValue- if the attribute is missing or not the correct type.

        Parameters:
        attribute -
        defaultValue -
        Returns:
      • getString

        public java.lang.String getString​(int attribute,
                                          java.lang.String defaultValue)
        Returns the string value of the requested attribute, or -defaultValue- if the attribute is missing or not the correct type.

        Parameters:
        attribute -
        defaultValue -
        Returns:
      • getName

        public java.lang.String getName()
        Returns the string value of the dw_at_name attribute, or null if it is missing.

        Returns:
      • getUnsignedLong

        public long getUnsignedLong​(int attribute,
                                    long defaultValue)
        Returns the unsigned long integer value of the requested attribute, or -defaultValue- if the attribute is missing.

        The 'unsigned'ness of this method refers to how the binary value is read from the dwarf information (ie. a value with the high bit set is not treated as signed).

        The -defaultValue- parameter can accept a negative value.

        Parameters:
        attribute -
        defaultValue -
        Returns:
      • getRefDIE

        public DebugInfoEntry getRefDIE​(int attribute)
        Returns the die instance pointed to by the requested attribute, or null if the attribute does not exist.

        Parameters:
        attribute -
        Returns:
      • getContainingTypeRef

        public DIEAggregate getContainingTypeRef()
        Returns the DIE pointed to by a DW_AT_containing_type attribute.
        Returns:
        DIEA pointed to by the DW_AT_containing_type attribute, or null if not present.
      • hasAttribute

        public boolean hasAttribute​(int attribute)
      • parseInt

        public int parseInt​(int attribute,
                            int defaultValue)
                     throws java.io.IOException,
                            DWARFExpressionException
        Returns the signed integer value of the requested attribute after resolving any DWARF expression opcodes.

        Parameters:
        attribute -
        defaultValue -
        Returns:
        Throws:
        java.io.IOException
        DWARFExpressionException
      • parseUnsignedLong

        public long parseUnsignedLong​(int attribute,
                                      long defaultValue)
                               throws java.io.IOException,
                                      DWARFExpressionException
        Returns the unsigned integer value of the requested attribute after resolving any DWARF expression opcodes.

        Parameters:
        attribute -
        defaultValue -
        Returns:
        Throws:
        java.io.IOException
        DWARFExpressionException
      • parseDataMemberOffset

        public int parseDataMemberOffset​(int attribute,
                                         int defaultValue)
                                  throws java.io.IOException,
                                         DWARFExpressionException
        Returns the unsigned integer value of the requested attribute after resolving any DWARF expression opcodes.
        Parameters:
        attribute -
        defaultValue -
        Returns:
        Throws:
        java.io.IOException
        DWARFExpressionException
      • getAsLocation

        public java.util.List<DWARFLocation> getAsLocation​(int attribute)
                                                    throws java.io.IOException
        Returns the location list info specified in the attribute.

        Numeric attributes are treated as offsets into the debug_loc section.

        Blob attributes are treated as a single location record for the current CU, using the blob bytes as the DWARF expression of the location record.

        Parameters:
        attribute -
        Returns:
        Throws:
        java.io.IOException
      • evaluateLocation

        public long evaluateLocation​(DWARFLocation location)
                              throws java.io.IOException,
                                     DWARFExpressionException
        Evaluate the DWARFExpression located in the DWARFLocation object in the context of this DIEA.

        Parameters:
        location -
        Returns:
        Throws:
        java.io.IOException
        DWARFExpressionException
      • isDanglingDeclaration

        public boolean isDanglingDeclaration()
        Returns true if this DIE has a DW_AT_declaration attribute and does NOT have a matching inbound DW_AT_specification reference.

        Returns:
      • isPartialDeclaration

        public boolean isPartialDeclaration()
        Returns true if this DIE has a DW_AT_declaration attribute.
        Returns:
      • isNamedType

        public boolean isNamedType()
      • isNameSpaceContainer

        public boolean isNameSpaceContainer()
        Returns true if the children of this DIE are within a new namespace.

        Ie. Namespaces, subprogram, class, interface, struct, union, enum

        Returns:
      • isStructureType

        public boolean isStructureType()
        Returns true if this DIE defines a structure-like element (class, struct, interface, union).
        Returns:
      • isFuncDefType

        public boolean isFuncDefType()
      • toString

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

        public java.util.List<DWARFRange> parseDebugRange​(int attribute)
                                                   throws java.io.IOException
        Parses a range list from the debug_ranges section. See DWARF4 Section 2.17.3 (Non-Contiguous Address Ranges).

        Parameters:
        attribute - attribute ie. DWARFAttribute.DW_AT_ranges
        Returns:
        list of ranges
        Throws:
        java.io.IOException - if an I/O error occurs
      • getLowPC

        public long getLowPC​(long defaultValue)
        Returns the value of the DW_AT_low_pc attribute, if it exists.
        Parameters:
        defaultValue -
        Returns:
      • getHighPC

        public long getHighPC()
                       throws java.io.IOException
        Returns the value of the DW_AT_high_pc attribute, adjusted if necessary by the value of DW_AT_low_pc.

        Returns:
        Throws:
        java.io.IOException - if the DW_AT_high_pc attribute isn't a numeric attribute, or if the DW_AT_low_pc value is needed and is not present.
      • isLowPCEqualHighPC

        public boolean isLowPCEqualHighPC()
        Returns true if the raw lowPc and highPc values are the same.

        This indicates an empty range, in which case the caller may want to take special steps to avoid issues with Ghidra ranges.

        Only seen in extremely old gcc versions. Typically the low & high pc values are omitted if the CU is empty.

        Returns:
        boolean true if the LowPC and HighPC values are present and equal
      • hashCode

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

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object