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

# Class DWARFProgram

java.lang.Object
ghidra.app.util.bin.format.dwarf4.next.DWARFProgram

All Implemented Interfaces:
  `Closeable`, `AutoCloseable`

public class DWARFProgram extends Object implements Closeable
DWARFProgram encapsulates a `Ghidra program` with DWARF specific reference data used by `DWARFDataTypeImporter` and `DWARFFunctionImporter`, along with some helper functions.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `DEFAULT_NAME_LENGTH_CUTOFF`
  `static final CategoryPath`
  `DWARF_ROOT_CATPATH`
  `static final String`
  `DWARF_ROOT_NAME`
  `static final int`
  `MAX_NAME_LENGTH_CUTOFF`
  `static final int`
  `MIN_NAME_LENGTH_CUTOFF`
  `static final CategoryPath`
  `UNCAT_CATPATH`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DWARFProgram(Program program, DWARFImportOptions importOptions, TaskMonitor monitor)`
  Main constructor for DWARFProgram.
  `DWARFProgram(Program program, DWARFImportOptions importOptions, TaskMonitor monitor, DWARFSectionProvider sectionProvider)`
  Constructor for DWARFProgram.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `cacheDNIByOffset(long offset, DWARFNameInfo dni)`
  `void`
  `checkPreconditions(TaskMonitor monitor)`
  Iterates over all the DWARF DIE records in the program and checks for some pre-known issues, throwing an exception if there is a problem that would prevent a successful run.
  `void`
  `clearDIEIndexes()`
  Releases the memory used by the DIE entries read when invoking `checkPreconditions(TaskMonitor)`.
  `void`
  `close()`
  `DIEAggregate`
  `getAggregate(long offset)`
  Returns the `DIEAggregate` that contains the `DebugInfoEntry` specified by the offset.
  `DIEAggregate`
  `getAggregate(DebugInfoEntry die)`
  Returns the `DIEAggregate` that contains the specified `DebugInfoEntry`.
  `List<DIEAggregate>`
  `getAggregates()`
  Returns the list of all currently loaded `DIEAggregate`s, which will be either just the DIEA of the current CU, or all DIEA if `DWARFImportOptions.isPreloadAllDIEs()`.
  `DWARFAttributeFactory`
  `getAttributeFactory()`
  `Address`
  `getCodeAddress(Number offset)`
  `DWARFCompilationUnit`
  `getCompilationUnitFor(long offset)`
  `List<DWARFCompilationUnit>`
  `getCompilationUnits()`
  `Address`
  `getDataAddress(Number offset)`
  `BinaryReader`
  `getDebugInfo()`
  `BinaryReader`
  `getDebugLine()`
  `BinaryReader`
  `getDebugLocation()`
  `BinaryReader`
  `getDebugRanges()`
  `StringTable`
  `getDebugStrings()`
  `int`
  `getDIECount()`
  Returns the count of the DIE records in this compilation unit.
  `DWARFDataTypeManager`
  `getDwarfDTM()`
  `List<DebugInfoEntry>`
  `getEntries()`
  `DebugInfoEntry`
  `getEntryAtByteOffsetUnchecked(long byteOffset)`
  Returns the entry with the given byte offset.
  `String`
  `getEntryName(DIEAggregate diea)`
  `boolean`
  `getFoundCrossCURefs()`
  `List<DWARFFunctionFixup>`
  `getFunctionFixups()`
  `Program`
  `getGhidraProgram()`
  `DWARFImportOptions`
  `getImportOptions()`
  `DWARFImportSummary`
  `getImportSummary()`
  `DWARFNameInfo`
  `getName(DIEAggregate diea)`
  `long`
  `getProgramBaseAddressFixup()`
  A fixup value that needs to be applied to static addresses of the program.
  `DWARFRegisterMappings`
  `getRegisterMappings()`
  `DWARFNameInfo`
  `getRootDNI()`
  `AddressSpace`
  `getStackSpace()`
  `int`
  `getTotalAggregateCount()`
  Returns the total number of `DIEAggregate` objects in the entire program.
  `int`
  `getTotalDIECount()`
  Returns the total number of DIE records in the entire program.
  `List<DIEAggregate>`
  `getTypeReferers(DIEAggregate targetDIEA, int tag)`
  Returns a list of `DIEAggregate`s that refer to the targetDIEA via an attribute of the specified tag type.
  `DWARFNameInfo`
  `getUncategorizedRootDNI()`
  `static boolean`
  `hasDWARFData(Program program, TaskMonitor monitor)`
  Returns true if the specified `program` has DWARF information.
  `DWARFAttributeSpecification`
  `internAttributeSpec(DWARFAttributeSpecification das)`
  `boolean`
  `isBigEndian()`
  `static boolean`
  `isDWARF(Program program)`
  Returns true if the `program` probably has DWARF information, without doing all the work that querying all registered DWARFSectionProviders would take.
  `boolean`
  `isLittleEndian()`
  `DWARFNameInfo`
  `lookupDNIByOffset(long offset)`
  `void`
  `setAttributeFactory(DWARFAttributeFactory attributeFactory)`
  `void`
  `setCurrentCompilationUnit(DWARFCompilationUnit cu, TaskMonitor monitor)`
  Sets the currently active compilation unit.
  `void`
  `setFoundCrossCURefs(boolean b)`
  `void`
  `setNameLengthCutoff(int nameLenCutoff)`
  Sets the maximum length of symbols and datatypes created during import.
  `boolean`
  `stackGrowsNegative()`

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

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### DWARF_ROOT_NAME

    public static final String DWARF_ROOT_NAME
    See Also:
      - Constant Field Values

  - ### DWARF_ROOT_CATPATH

    public static final CategoryPath DWARF_ROOT_CATPATH

  - ### UNCAT_CATPATH

    public static final CategoryPath UNCAT_CATPATH

  - ### DEFAULT_NAME_LENGTH_CUTOFF

    public static final int DEFAULT_NAME_LENGTH_CUTOFF
    See Also:
      - Constant Field Values

  - ### MAX_NAME_LENGTH_CUTOFF

    public static final int MAX_NAME_LENGTH_CUTOFF
    See Also:
      - Constant Field Values

  - ### MIN_NAME_LENGTH_CUTOFF

    public static final int MIN_NAME_LENGTH_CUTOFF
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### DWARFProgram

    public DWARFProgram(Program program, DWARFImportOptions importOptions, TaskMonitor monitor) throws CancelledException, IOException, DWARFException
    Main constructor for DWARFProgram.

    Auto-detects the DWARFSectionProvider and chains to the next constructor.

    Parameters:
      `program` - Ghidra `Program`.
      `importOptions` - `DWARFImportOptions` to controls options during reading / parsing /importing.
      `monitor` - `TaskMonitor` to control canceling and progress.
    Throws:
      `CancelledException` - if user cancels
      `IOException` - if error reading data
      `DWARFException` - if bad stuff happens.

  - ### DWARFProgram

    public DWARFProgram(Program program, DWARFImportOptions importOptions, TaskMonitor monitor, DWARFSectionProvider sectionProvider) throws CancelledException, IOException, DWARFException
    Constructor for DWARFProgram.
    Parameters:
      `program` - Ghidra `Program`.
      `importOptions` - `DWARFImportOptions` to controls options during reading / parsing /importing.
      `monitor` - `TaskMonitor` to control canceling and progress.
      `sectionProvider` - `DWARFSectionProvider` factory that finds DWARF .debug_* sections wherever they live.
    Throws:
      `CancelledException` - if user cancels
      `IOException` - if error reading data
      `DWARFException` - if bad stuff happens.

- ## Method Details

  - ### isDWARF

    public static boolean isDWARF(Program program)
    Returns true if the `program` probably has DWARF information, without doing all the work that querying all registered DWARFSectionProviders would take.

    If the program is an Elf binary, it must have (at least) ".debug_info" and ".debug_abbr", program sections, or their compressed "z" versions, or ExternalDebugInfo that would point to an external DWARF file.

    If the program is a MachO binary (Mac), it must have a ".dSYM" directory co-located next to the original binary file on the native filesystem (outside of Ghidra). See the DSymSectionProvider for more info.

    Parameters:
      `program` - `Program` to test
    Returns:
      boolean true if program probably has DWARF info, false if not

  - ### hasDWARFData

    public static boolean hasDWARFData(Program program, TaskMonitor monitor)
    Returns true if the specified `program` has DWARF information.

    This is similar to `isDWARF(Program)`, but is a stronger check that is more expensive as it could involve searching for external files.

    Parameters:
      `program` - `Program` to test
      `monitor` - `TaskMonitor` that can be used to cancel
    Returns:
      boolean true if the program has DWARF info, false if not

  - ### close

    public void close() throws IOException
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Throws:
      `IOException`

  - ### getImportOptions

    public DWARFImportOptions getImportOptions()

  - ### getImportSummary

    public DWARFImportSummary getImportSummary()

  - ### getGhidraProgram

    public Program getGhidraProgram()

  - ### getDwarfDTM

    public DWARFDataTypeManager getDwarfDTM()

  - ### isBigEndian

    public boolean isBigEndian()

  - ### isLittleEndian

    public boolean isLittleEndian()

  - ### getEntryName

    public String getEntryName(DIEAggregate diea)

  - ### getName

    public DWARFNameInfo getName(DIEAggregate diea)

  - ### lookupDNIByOffset

    public DWARFNameInfo lookupDNIByOffset(long offset)

  - ### cacheDNIByOffset

    public void cacheDNIByOffset(long offset, DWARFNameInfo dni)

  - ### getAggregate

    public DIEAggregate getAggregate(DebugInfoEntry die)
    Returns the `DIEAggregate` that contains the specified `DebugInfoEntry`.
    Parameters:
      `die` - `DebugInfoEntry` or null
    Returns:
      `DIEAggregate` that contains the specified DIE, or null if DIE null or the aggregate was not found.

  - ### getAggregate

    public DIEAggregate getAggregate(long offset)
    Returns the `DIEAggregate` that contains the `DebugInfoEntry` specified by the offset.
    Parameters:
      `offset` - offset of a DIE record
    Returns:
      `DIEAggregate` that contains the DIE record specified, or null if bad offset.

  - ### getAggregates

    public List<DIEAggregate> getAggregates()
    Returns the list of all currently loaded `DIEAggregate`s, which will be either just the DIEA of the current CU, or all DIEA if `DWARFImportOptions.isPreloadAllDIEs()`.
    Returns:
      List of `DIEAggregate`.

  - ### getTotalDIECount

    public int getTotalDIECount()
    Returns the total number of DIE records in the entire program.
    Returns:
      the total number of DIE records in the entire program.

  - ### getTotalAggregateCount

    public int getTotalAggregateCount()
    Returns the total number of `DIEAggregate` objects in the entire program.
    Returns:
      the total number of `DIEAggregate` objects in the entire program.

  - ### setCurrentCompilationUnit

    public void setCurrentCompilationUnit(DWARFCompilationUnit cu, TaskMonitor monitor) throws CancelledException, IOException, DWARFException
    Sets the currently active compilation unit. Used when 'paging' through the DIE records in a compilation-unit-at-a-time manner, vs the `DWARFImportOptions.isPreloadAllDIEs()` where all DIE/DIEA records are loaded at once.
    Parameters:
      `cu` - `DWARFCompilationUnit` to set as the active element and load it's DIE records.
      `monitor` - `TaskMonitor` to update with status and check for cancelation.
    Throws:
      `CancelledException` - if user cancels
      `IOException` - if error reading data
      `DWARFException` - if error in DWARF record structure

  - ### getCompilationUnits

    public List<DWARFCompilationUnit> getCompilationUnits()

  - ### getCompilationUnitFor

    public DWARFCompilationUnit getCompilationUnitFor(long offset)

  - ### getDebugLocation

    public BinaryReader getDebugLocation()

  - ### getDebugRanges

    public BinaryReader getDebugRanges()

  - ### getDebugInfo

    public BinaryReader getDebugInfo()

  - ### getDebugLine

    public BinaryReader getDebugLine()

  - ### getRegisterMappings

    public DWARFRegisterMappings getRegisterMappings()

  - ### getRootDNI

    public DWARFNameInfo getRootDNI()

  - ### getUncategorizedRootDNI

    public DWARFNameInfo getUncategorizedRootDNI()

  - ### getDebugStrings

    public StringTable getDebugStrings()

  - ### getStackSpace

    public AddressSpace getStackSpace()

  - ### getAttributeFactory

    public DWARFAttributeFactory getAttributeFactory()

  - ### setAttributeFactory

    public void setAttributeFactory(DWARFAttributeFactory attributeFactory)

  - ### getFoundCrossCURefs

    public boolean getFoundCrossCURefs()

  - ### setFoundCrossCURefs

    public void setFoundCrossCURefs(boolean b)

  - ### internAttributeSpec

    public DWARFAttributeSpecification internAttributeSpec(DWARFAttributeSpecification das)

  - ### getEntries

    public List<DebugInfoEntry> getEntries()
    Returns:
      the entries list

  - ### getDIECount

    public int getDIECount() throws IOException, CancelledException
    Returns the count of the DIE records in this compilation unit.

    Only valid if called after `checkPreconditions(TaskMonitor)` and before `clearDIEIndexes()`.

    Returns:
      number of DIE records in the compunit.
    Throws:
      `IOException`
      `CancelledException`

  - ### clearDIEIndexes

    public void clearDIEIndexes()
    Releases the memory used by the DIE entries read when invoking `checkPreconditions(TaskMonitor)`.

  - ### getEntryAtByteOffsetUnchecked

    public DebugInfoEntry getEntryAtByteOffsetUnchecked(long byteOffset)
    Returns the entry with the given byte offset.

    The byte offset corresponds to the byte index in the original file where the entry was defined.

    Returns null if the requested entry does not exist.

    Parameters:
      `byteOffset` - the byte offset
    Returns:
      the entry with the given byte offset

  - ### getTypeReferers

    public List<DIEAggregate> getTypeReferers(DIEAggregate targetDIEA, int tag)
    Returns a list of `DIEAggregate`s that refer to the targetDIEA via an attribute of the specified tag type.
    Parameters:
      `targetDIEA` - `DIEAggregate` that might be pointed to by other DIEAs.
      `tag` - the `DWARFTag` attribute type that is pointing DIEAs are using to refer to the target DIEA.
    Returns:
      list of DIEAs that point to the target, empty list if nothing found.

  - ### checkPreconditions

    public void checkPreconditions(TaskMonitor monitor) throws DWARFPreconditionException, DWARFException, CancelledException, IOException
    Iterates over all the DWARF DIE records in the program and checks for some pre-known issues, throwing an exception if there is a problem that would prevent a successful run.
    Parameters:
      `monitor` - `TaskMonitor` to check for cancel and upate with status.
    Throws:
      `DWARFException` - if DWARF structure error.
      `CancelledException` - if user cancels.
      `IOException` - if error reading data.
      `DWARFPreconditionException`

  - ### setNameLengthCutoff

    public void setNameLengthCutoff(int nameLenCutoff)
    Sets the maximum length of symbols and datatypes created during import.
    Parameters:
      `nameLenCutoff` - int, should not be more than `SymbolUtilities.MAX_SYMBOL_NAME_LENGTH`.

  - ### getProgramBaseAddressFixup

    public long getProgramBaseAddressFixup()
    A fixup value that needs to be applied to static addresses of the program.

    This value is necessary if the program's built-in base address is overridden at import time.

    Returns:
      long value to add to static addresses discovered in DWARF to make it agree with Ghidra's imported program.

  - ### getCodeAddress

    public Address getCodeAddress(Number offset)

  - ### getDataAddress

    public Address getDataAddress(Number offset)

  - ### stackGrowsNegative

    public boolean stackGrowsNegative()

  - ### getFunctionFixups

    public List<DWARFFunctionFixup> getFunctionFixups()