Package ghidra.app.util.bin.format.dwarf4

Class DIEAggregate

java.lang.Object
ghidra.app.util.bin.format.dwarf4.DIEAggregate
public class DIEAggregate extends 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 Details

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

    • createSingle

      public static DIEAggregate createSingle(DebugInfoEntry die)
      Create a DIEAggregate from a single DIE.

      Mainly useful early in the DWARFCompilationUnit's bootstrapping process when it needs to read values from DIEs.

      Parameters:
      die -
      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 String getHexOffset()
      Returns getOffset() as a hex string.
      Returns:

    • getTag

      public int getTag()

    • getCompilationUnit

      public DWARFCompilationUnit getCompilationUnit()

    • getProgram

      public DWARFProgram getProgram()

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

    • getDeclParent

      public DIEAggregate getDeclParent()

    • getParent

      public DIEAggregate getParent()

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

    • findAttributeInChildren

      public <T extends DWARFAttributeValue> T findAttributeInChildren(int attribute, int childTag, Class<T> clazz)
      Return an attribute that is present in this DIEAggregate, or in any of its direct children (of a specific type)
      Type Parameters:
      T -
      Parameters:
      attribute - the attribute to find
      childTag - the type of children to search
      clazz - type of the attribute to return
      Returns:
      attribute value, or null if not found

    • getAttribute

      public <T extends DWARFAttributeValue> T getAttribute(int attribute, 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:

    • getAttribute

      public DWARFAttributeValue getAttribute(int attribute)

    • 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 String getString(int attribute, 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 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:

    • getRef

      public DIEAggregate getRef(int attribute)

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

    • getTypeRef

      public DIEAggregate getTypeRef()

    • getSourceFile

      public String getSourceFile()
      Returns the name of the source file this item was declared in (DW_AT_decl_file)
      Returns:
      name of file this item was declared in, or null if info not available

    • getChildren

      public List<DebugInfoEntry> getChildren(int childTag)
      Return a list of children that are of a specific DWARF type.

      Parameters:
      childTag - see DWARFTag DW_TAG_* values
      Returns:
      List of children DIEs that match the specified tag

    • hasAttribute

      public boolean hasAttribute(int attribute)

    • getAbstractInstance

      public DIEAggregate getAbstractInstance()
      Return a DIEAggregate that only contains the information present in the "abstract instance" (and lower) DIEs.
      Returns:
      a new DIEAggregate, or null if this DIEA was not split into a concrete and abstract portion

    • parseInt

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

      Parameters:
      attribute -
      defaultValue -
      Returns:
      Throws:
      IOException
      DWARFExpressionException

    • parseUnsignedLong

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

      Parameters:
      attribute -
      defaultValue -
      Returns:
      Throws:
      IOException
      DWARFExpressionException

    • parseDataMemberOffset

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

    • getAsLocation

      public List<DWARFLocation> getAsLocation(int attribute, DWARFRange range) throws 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 - the attribute to evaluate
      range - the address range the location covers (may be discarded if the attribute value is a location list with its own range values)
      Returns:
      list of locations, empty if missing, never null
      Throws:
      IOException

    • evaluateLocation

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

      Parameters:
      location -
      Returns:
      Throws:
      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 String toString()
      Overrides:
      toString in class Object

    • parseDebugRange

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

      The returned list of ranges is sorted.

      Parameters:
      attribute - attribute ie. DWARFAttribute.DW_AT_ranges
      Returns:
      list of ranges, in order
      Throws:
      IOException - if an I/O error occurs

    • readRange

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

      The returned list is not sorted.

      Parameters:
      attribute - attribute ie. DWARFAttribute.DW_AT_ranges
      Returns:
      list of ranges
      Throws:
      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 IOException
      Returns the value of the DW_AT_high_pc attribute, adjusted if necessary by the value of DW_AT_low_pc.

      Returns:
      Throws:
      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 and high pc values are omitted if the CU is empty.

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

    • getFunctionParamList

      public List<DIEAggregate> getFunctionParamList()
      Returns a function's parameter list, taking care to ensure that the params are well ordered (to avoid issues with concrete instance param ordering)
      Returns:
      list of params for this function

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object