Package ghidra.app.util.bin.format.dwarf

Class DIEAggregate

java.lang.Object
ghidra.app.util.bin.format.dwarf.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 - DIEAggregate containing fragments
      Returns:
      DIEAggregate with the fragments of the source, skipping the first

    • 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 - DebugInfoEntry
      Returns:
      DIEAggregate containing a single DIE

    • 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:
      string hex offset of the head DIE

    • getTag

      public DWARFTag getTag()

    • getCompilationUnit

      public DWARFCompilationUnit getCompilationUnit()

    • getProgram

      public DWARFProgram getProgram()

    • getLastFragment

      public DebugInfoEntry getLastFragment()
      Returns the last DIE fragment, ie. the decl DIE.
      Returns:
      last DIE of this aggregate

    • getHeadFragment

      public DebugInfoEntry getHeadFragment()
      Returns the first DIE fragment, ie. the spec or abstract_origin DIE.
      Returns:
      first DIE of this aggregate

    • 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:
      depth of this instance, from the root of its head DIE fragment, with 0 indicating that this instance was already the root of the compUnit

    • findAttributeInChildren

      public <T extends DWARFAttributeValue> T findAttributeInChildren(DWARFAttribute attribute, DWARFTag 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 - attribute value type
      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(DWARFAttribute attribute, Class<T> clazz)
      Finds a attribute with a matching DWARFAttribute id.

      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:
      DWARFAttributeValue or subclass as specified by the clazz, or null if not found

    • getAttribute

      public DWARFAttributeValue getAttribute(DWARFAttribute attribute)
      Finds a attribute with a matching DWARFAttribute id.

      Returns null if the attribute does not exist.

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

      Parameters:
      attribute - See DWARFAttribute
      Returns:
      DWARFAttributeValue, or null if not found

    • getLong

      public long getLong(DWARFAttribute attribute, long defaultValue)
      Returns the value of the requested attribute, or -defaultValue- if the attribute is missing.
      Parameters:
      attribute - DWARFAttribute id
      defaultValue - value to return if attribute is not present
      Returns:
      long value, or the defaultValue if attribute not present

    • getBool

      public boolean getBool(DWARFAttribute 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 - DWARFAttribute id
      defaultValue - value to return if attribute is not present
      Returns:
      boolean value, or the defaultValue if attribute is not present

    • getString

      public String getString(DWARFAttribute 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 - DWARFAttribute id
      defaultValue - value to return if attribute is not present
      Returns:
      String value, or the defaultValue if attribute is not present

    • getName

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

      Returns:
      name of this DIE aggregate, or null if missing

    • getUnsignedLong

      public long getUnsignedLong(DWARFAttribute 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 - DWARFAttribute id
      defaultValue - value to return if attribute is not present
      Returns:
      unsigned long value, or the defaultValue if attribute is not present

    • getRef

      public DIEAggregate getRef(DWARFAttribute attribute)
      Returns the diea instance pointed to by the requested attribute, or null if the attribute does not exist.

      Parameters:
      attribute - DWARFAttribute id
      Returns:
      DIEAggregate, or the null if attribute is not present

    • 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(DWARFTag 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(DWARFAttribute attribute)
      Returns true if the specified attribute is present.
      Parameters:
      attribute - attribute id
      Returns:
      boolean true if value is present

    • 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(DWARFAttribute attribute, int defaultValue) throws IOException, DWARFExpressionException
      Returns the signed integer value of the requested attribute after resolving any DWARF expression opcodes.

      Parameters:
      attribute - DWARFAttribute id
      defaultValue - value to return if attribute is not present
      Returns:
      int value, or the defaultValue if attribute is not present
      Throws:
      IOException - if error reading value or invalid value type
      DWARFExpressionException - if error evaluating a DWARF expression

    • parseUnsignedLong

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

      Parameters:
      attribute - DWARFAttribute id
      defaultValue - value to return if attribute is not present
      Returns:
      unsigned long value, or the defaultValue if attribute is not present
      Throws:
      IOException - if error reading value or invalid value type
      DWARFExpressionException - if error evaluating a DWARF expression

    • parseDataMemberOffset

      public int parseDataMemberOffset(DWARFAttribute attribute, int defaultValue) throws DWARFExpressionException, IOException
      Returns the unsigned integer value of the requested attribute after resolving any DWARF expression opcodes.
      Parameters:
      attribute - DWARFAttribute id
      defaultValue - value to return if attribute is not present
      Returns:
      unsigned int value, or the defaultValue if attribute is not present
      Throws:
      IOException - if error reading value or invalid value type
      DWARFExpressionException - if error evaluating a DWARF expression

    • getLocationList

      public DWARFLocationList getLocationList(DWARFAttribute attribute) throws IOException
      Parses a location attribute value, which can be a single expression that is valid for any PC, or a list of expressions that are tied to specific ranges.
      Parameters:
      attribute - typically DWARFAttribute.DW_AT_location
      Returns:
      a DWARFLocationList, never null, possibly empty
      Throws:
      IOException - if error reading data

    • getLocation

      public DWARFLocation getLocation(DWARFAttribute attribute, long pc) throws IOException
      Parses a location attribute value, and returns the DWARFLocation instance that covers the specified pc.
      Parameters:
      attribute - typically DWARFAttribute.DW_AT_location
      pc - program counter
      Returns:
      a DWARFLocationList, never null, possibly empty
      Throws:
      IOException - if error reading data

    • 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:
      boolean true if this DIE has a DW_AT_declaration attribute and does NOT have a matching inbound DW_AT_specification reference

    • isPartialDeclaration

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

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • getRangeList

      public DWARFRangeList getRangeList(DWARFAttribute attribute) throws IOException
      Parses a range list.
      Parameters:
      attribute - attribute eg DWARFAttribute.DW_AT_ranges
      Returns:
      list of ranges, or null if attribute is not present
      Throws:
      IOException - if an I/O error occurs

    • getPCRange

      public DWARFRange getPCRange()
      Return the range specified by the low_pc...high_pc attribute values.
      Returns:
      DWARFRange containing low_pc - high_pc, or empty range if the low_pc is not present

    • 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