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 Summary

  Modifier and Type
  Method
  Description
  `static DIEAggregate`
  `createFromHead(DebugInfoEntry die)`
  Creates a `DIEAggregate` starting from a 'head' `DebugInfoEntry` instance.
  `static DIEAggregate`
  `createSingle(DebugInfoEntry die)`
  Create a `DIEAggregate` from a single `DIE`.
  `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.
  `boolean`
  `equals(Object obj)`
  `<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)
  `DIEAggregate`
  `getAbstractInstance()`
  Return a `DIEAggregate` that only contains the information present in the "abstract instance" (and lower) DIEs.
  `DWARFAttributeValue`
  `getAttribute(DWARFAttribute attribute)`
  Finds a `attribute` with a matching `DWARFAttribute` id.
  `<T extends DWARFAttributeValue>
  T`
  `getAttribute(DWARFAttribute attribute, Class<T> clazz)`
  Finds a `attribute` with a matching `DWARFAttribute` id.
  `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.
  `List<DebugInfoEntry>`
  `getChildren(DWARFTag childTag)`
  Return a list of children that are of a specific DWARF type.
  `DWARFCompilationUnit`
  `getCompilationUnit()`
  `DIEAggregate`
  `getContainingTypeRef()`
  Returns the DIE pointed to by a DW_AT_containing_type attribute.
  `long`
  `getDeclOffset()`
  `DIEAggregate`
  `getDeclParent()`
  `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.
  `int`
  `getFragmentCount()`
  `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)
  `DebugInfoEntry`
  `getHeadFragment()`
  Returns the first `DIE` fragment, ie.
  `String`
  `getHexOffset()`
  Returns `getOffset()` as a hex string.
  `DebugInfoEntry`
  `getLastFragment()`
  Returns the last `DIE` fragment, ie.
  `DWARFLocation`
  `getLocation(DWARFAttribute attribute, long pc)`
  Parses a location attribute value, and returns the `DWARFLocation` instance that covers the specified pc.
  `DWARFLocationList`
  `getLocationList(DWARFAttribute attribute)`
  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.
  `long`
  `getLong(DWARFAttribute attribute, long defaultValue)`
  Returns the value of the requested attribute, or -defaultValue- if the attribute is missing.
  `String`
  `getName()`
  Returns the string value of the `dw_at_name` attribute, or null if it is missing.
  `long`
  `getOffset()`
  `long[]`
  `getOffsets()`
  `DIEAggregate`
  `getParent()`
  `DWARFRange`
  `getPCRange()`
  Return the range specified by the low_pc...high_pc attribute values.
  `DWARFProgram`
  `getProgram()`
  `DWARFRangeList`
  `getRangeList(DWARFAttribute attribute)`
  Parses a range list.
  `DIEAggregate`
  `getRef(DWARFAttribute attribute)`
  Returns the `diea` instance pointed to by the requested attribute, or null if the attribute does not exist.
  `String`
  `getSourceFile()`
  Returns the name of the source file this item was declared in (DW_AT_decl_file)
  `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.
  `DWARFTag`
  `getTag()`
  `DIEAggregate`
  `getTypeRef()`
  `long`
  `getUnsignedLong(DWARFAttribute attribute, long defaultValue)`
  Returns the unsigned long integer value of the requested attribute, or -defaultValue- if the attribute is missing.
  `boolean`
  `hasAttribute(DWARFAttribute attribute)`
  Returns true if the specified attribute is present.
  `int`
  `hashCode()`
  `boolean`
  `hasOffset(long offset)`
  Returns true if any of the `DIEs` that makeup this aggregate have the specified offset.
  `boolean`
  `isDanglingDeclaration()`
  Returns true if this DIE has a DW_AT_declaration attribute and does NOT have a matching inbound DW_AT_specification reference.
  `boolean`
  `isPartialDeclaration()`
  Returns true if this DIE has a DW_AT_declaration attribute.
  `int`
  `parseDataMemberOffset(DWARFAttribute attribute, int defaultValue)`
  Returns the unsigned integer value of the requested attribute after resolving any DWARF expression opcodes.
  `int`
  `parseInt(DWARFAttribute attribute, int defaultValue)`
  Returns the signed integer value of the requested attribute after resolving any DWARF expression opcodes.
  `long`
  `parseUnsignedLong(DWARFAttribute attribute, long defaultValue)`
  Returns the unsigned integer value of the requested attribute after resolving any DWARF expression opcodes.
  `String`
  `toString()`

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

  `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## 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`