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

Class DWARFProgram

java.lang.Object

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

All Implemented Interfaces:

java.io.Closeable, java.lang.AutoCloseable

public class DWARFProgram
extends java.lang.Object
implements java.io.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 int	DEFAULT_NAME_LENGTH_CUTOFF
static java.lang.String	DWARF_ROOT_NAME
static int	MAX_NAME_LENGTH_CUTOFF
static int	MIN_NAME_LENGTH_CUTOFF

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.
java.util.List<DIEAggregate>	getAggregates()	Returns the list of all currently loaded DIEAggregates, which will be either just the DIEA of the current CU, or all DIEA if DWARFImportOptions.isPreloadAllDIEs().
DWARFAttributeFactory	getAttributeFactory()
DWARFCompilationUnit	getCompilationUnitFor(long offset)
java.util.List<DWARFCompilationUnit>	getCompilationUnits()
BinaryReader	getDebugInfo()
BinaryReader	getDebugLine()
BinaryReader	getDebugLocation()
BinaryReader	getDebugRanges()
StringTable	getDebugStrings()
int	getDIECount()	Returns the count of the DIE records in this compilation unit.
java.util.List<DebugInfoEntry>	getEntries()
DebugInfoEntry	getEntryAtByteOffsetUnchecked(long byteOffset)	Returns the entry with the given byte offset.
java.lang.String	getEntryName(DIEAggregate diea)
boolean	getFoundCrossCURefs()
Program	getGhidraProgram()
DWARFImportOptions	getImportOptions()
DWARFNameInfo	getName(DIEAggregate diea)
long	getProgramBaseAddressFixup()	A fixup value that needs to be applied to static addresses of the program.
DWARFRegisterMappings	getRegisterMappings()
DWARFNameInfo	getRootDNI()
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.
java.util.List<DIEAggregate>	getTypeReferers(DIEAggregate targetDIEA, int tag)	Returns a list of DIEAggregates that refer to the targetDIEA via an attribute of the specified tag type.
DWARFNameInfo	getUncategorizedRootDNI()
DWARFAttributeSpecification	internAttributeSpec(DWARFAttributeSpecification das)
boolean	isBigEndian()
static boolean	isDWARF(Program program)	Returns true if the program probably has DWARF information.
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.

Methods inherited from class java.lang.Object

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

Field Detail

DWARF_ROOT_NAME

public static final java.lang.String DWARF_ROOT_NAME

See Also:

Constant Field Values

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 Detail

DWARFProgram

public DWARFProgram(Program program,
                    DWARFImportOptions importOptions,
                    TaskMonitor monitor)
             throws CancelledException,
                    java.io.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

java.io.IOException - if error reading data

DWARFException - if bad stuff happens.

DWARFProgram

public DWARFProgram(Program program,
                    DWARFImportOptions importOptions,
                    TaskMonitor monitor,
                    DWARFSectionProvider sectionProvider)
             throws CancelledException,
                    java.io.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

java.io.IOException - if error reading data

DWARFException - if bad stuff happens.

Method Detail

isDWARF

public static boolean isDWARF(Program program)

Returns true if the program probably has DWARF information.

If the program is an Elf binary, it must have (at least) ".debug_info" and ".debug_abbr" program sections.

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

Parameters:

program - Program to test

Returns:

boolean true if program has DWARF info, false if not

close

public void close()
           throws java.io.IOException

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

Throws:

java.io.IOException

getImportOptions

public DWARFImportOptions getImportOptions()

getGhidraProgram

public Program getGhidraProgram()

isBigEndian

public boolean isBigEndian()

isLittleEndian

public boolean isLittleEndian()

getEntryName

public java.lang.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 java.util.List<DIEAggregate> getAggregates()

Returns the list of all currently loaded DIEAggregates, 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,
                                      java.io.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

java.io.IOException - if error reading data

DWARFException - if error in DWARF record structure

getCompilationUnits

public java.util.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()

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 java.util.List<DebugInfoEntry> getEntries()

Returns:

the entries list

getDIECount

public int getDIECount()
                throws java.io.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:

java.io.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 java.util.List<DIEAggregate> getTypeReferers(DIEAggregate targetDIEA,
                                                    int tag)

Returns a list of DIEAggregates 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,
                               java.io.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.

java.io.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.