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 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)`
  `long`
  `evaluateLocation(DWARFLocation location)`
  Evaluate the DWARFExpression located in the DWARFLocation object in the context of this DIEA.
  `<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)
  `DIEAggregate`
  `getAbstractInstance()`
  Return a `DIEAggregate` that only contains the information present in the "abstract instance" (and lower) DIEs.
  `List<DWARFLocation>`
  `getAsLocation(int attribute, DWARFRange range)`
  Returns the location list info specified in the attribute.
  `DWARFAttributeValue`
  `getAttribute(int attribute)`
  `<T extends DWARFAttributeValue>
  T`
  `getAttribute(int attribute, Class<T> clazz)`
  Finds a `attribute` with a matching `DWARFAttribute` type
  `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.
  `List<DebugInfoEntry>`
  `getChildren(int 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.
  `long`
  `getHighPC()`
  Returns the value of the DW_AT_high_pc attribute, adjusted if necessary by the value of DW_AT_low_pc.
  `DebugInfoEntry`
  `getLastFragment()`
  Returns the last `DIE` fragment, ie.
  `long`
  `getLong(int attribute, long defaultValue)`
  Returns the value of the requested attribute, or -defaultValue- if the attribute is missing.
  `long`
  `getLowPC(long defaultValue)`
  Returns the value of the DW_AT_low_pc attribute, if it exists.
  `String`
  `getName()`
  Returns the string value of the `dw_at_name` attribute, or null if it is missing.
  `long`
  `getOffset()`
  `long[]`
  `getOffsets()`
  `DIEAggregate`
  `getParent()`
  `DWARFProgram`
  `getProgram()`
  `DIEAggregate`
  `getRef(int attribute)`
  `DebugInfoEntry`
  `getRefDIE(int attribute)`
  Returns the `die` 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(int attribute, String defaultValue)`
  Returns the string value of the requested attribute, or -defaultValue- if the attribute is missing or not the correct type.
  `int`
  `getTag()`
  `DIEAggregate`
  `getTypeRef()`
  `long`
  `getUnsignedLong(int attribute, long defaultValue)`
  Returns the unsigned long integer value of the requested attribute, or -defaultValue- if the attribute is missing.
  `boolean`
  `hasAttribute(int attribute)`
  `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`
  `isFuncDefType()`
  `boolean`
  `isLowPCEqualHighPC()`
  Returns true if the raw lowPc and highPc values are the same.
  `boolean`
  `isNamedType()`
  `boolean`
  `isNameSpaceContainer()`
  Returns true if the children of this DIE are within a new namespace.
  `boolean`
  `isPartialDeclaration()`
  Returns true if this DIE has a DW_AT_declaration attribute.
  `boolean`
  `isStructureType()`
  Returns true if this DIE defines a structure-like element (class, struct, interface, union).
  `int`
  `parseDataMemberOffset(int attribute, int defaultValue)`
  Returns the unsigned integer value of the requested attribute after resolving any DWARF expression opcodes.
  `List<DWARFRange>`
  `parseDebugRange(int attribute)`
  Parses a range list from the debug_ranges section.
  `int`
  `parseInt(int attribute, int defaultValue)`
  Returns the signed integer value of the requested attribute after resolving any DWARF expression opcodes.
  `long`
  `parseUnsignedLong(int attribute, long defaultValue)`
  Returns the unsigned integer value of the requested attribute after resolving any DWARF expression opcodes.
  `List<DWARFRange>`
  `readRange(int attribute)`
  Parses a range list from the debug_ranges section.
  `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` -
    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`