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

Class DWARFProgram

java.lang.Object

ghidra.app.util.bin.format.dwarf.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
protected TreeMap<Integer,DWARFCompilationUnit>	compUnitDieIndex
protected List<DWARFCompilationUnit>	compUnits
protected long[]	dieOffsets
protected WeakValueHashMap<Long,DebugInfoEntry>	diesByOffset
static final String	DWARF_BOOKMARK_CAT
static final CategoryPath	DWARF_ROOT_CATPATH
static final String	DWARF_ROOT_NAME
protected BitSet	indexHasRef
protected int[]	parentIndexes
protected static final EnumSet<DWARFAttribute>	REF_ATTRS
protected int[]	siblingIndexes
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
Iterable<DIEAggregate>	allAggregates()	Returns iterable that traverses all DIEAggregates in the program.
void	close()
void	dumpDIEs(PrintStream ps)
long	getAddress(DWARFForm form, long value, DWARFCompilationUnit cu)	Returns an address value.
AddressRange	getAddressRange(DWARFRange range, boolean isCode)
DIEAggregate	getAggregate(long dieOffset)	Returns the DIEAggregate that contains the DebugInfoEntry specified by the offset.
DIEAggregate	getAggregate(DebugInfoEntry die)	Returns the DIEAggregate that contains the specified DebugInfoEntry.
Charset	getCharset()	Returns charset to use when decoding debug strings.
int	getChildCount(int dieIndex)
List<DebugInfoEntry>	getChildrenOf(int dieIndex)	Returns the children of the specified DIE
Address	getCodeAddress(long offset)
List<DWARFCompilationUnit>	getCompilationUnits()
Address	getDataAddress(long offset)
BinaryReader	getDebugLineBR()
int	getDefaultIntSize()
DebugInfoEntry	getDIEByOffset(long dieOffset)	Returns the specified DIE record.
DWARFDataTypeManager	getDwarfDTM()
String	getEntryName(DIEAggregate diea)
List<DWARFFunctionFixup>	getFunctionFixups()
Program	getGhidraProgram()
DWARFImportOptions	getImportOptions()
DWARFImportSummary	getImportSummary()
DWARFLine	getLine(long offset, DWARFCompilationUnit cu, boolean readIfMissing)
DWARFLine	getLine(DIEAggregate diea, DWARFAttribute attribute)	Returns the DWARFLine info pointed to by the specified attribute.
DWARFLocationList	getLocationList(DIEAggregate diea, DWARFAttribute attribute)	Returns the DWARFLocationList pointed to by the specified attribute value.
List<DWARFMacroInfoEntry>	getMacroEntries(DWARFMacroHeader macroHeader)
DWARFMacroHeader	getMacroHeader(long offset, DWARFCompilationUnit cu)
DWARFName	getName(DIEAggregate diea)	Returns a DWARFName for a DIEAggregate.
long	getOffsetOfIndexedElement(DWARFForm form, int index, DWARFCompilationUnit cu)	Returns the raw offset of an indexed item.
int	getParentDepth(int dieIndex)	Returns the depth of the specified DIE.
DebugInfoEntry	getParentOf(int dieIndex)	Returns the parent DIE of the specified (by index) DIE
long	getProgramBaseAddressFixup()	A fixup value that needs to be applied to static addresses of the program.
DWARFRangeList	getRangeList(DIEAggregate diea, DWARFAttribute attribute)	Returns the DWARFRangeList pointed at by the specified attribute.
BinaryReader	getReaderForCompUnit(DWARFCompilationUnit cu)
static DIEAggregate	getReferringTypedef(DIEAggregate diea)	Returns the DIEAggregate of a typedef that points to the specified datatype.
DWARFRegisterMappings	getRegisterMappings()
DWARFName	getRootDNI()
AddressSpace	getStackSpace()
String	getString(DWARFForm form, long offset, DWARFCompilationUnit cu)	Returns a DWARF attribute string value, as specified by a form, offset/index, and the cu.
int	getTotalAggregateCount()	Returns the total number of DIEAggregate objects in the entire program.
List<DIEAggregate>	getTypeReferers(DIEAggregate targetDIEA, DWARFTag tag)	Returns a list of DIEAggregates that refer to the targetDIEA via an attribute of the specified tag type.
DWARFName	getUncategorizedRootDNI()
static boolean	hasDWARFData(Program program, TaskMonitor monitor)	Returns true if the specified program has DWARF information.
protected void	indexDIEAggregates(LongArrayList aggrTargets, TaskMonitor monitor)
protected void	indexDIEATypeRefs(TaskMonitor monitor)
void	init(TaskMonitor monitor)	Reads and indexes available DWARF information.
DWARFAttribute.AttrDef	internAttributeSpec(DWARFAttribute.AttrDef 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()
void	logWarningAt(Address addr, String addrName, String msg)
void	setStringTable(StringTable st)
boolean	stackGrowsNegative()
protected void	updateSiblingIndexes(IntArrayList siblingIndexList, IntArrayList parentIndexList, int index)

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

DWARF_BOOKMARK_CAT

public static final String DWARF_BOOKMARK_CAT

See Also:

• Constant Field Values

REF_ATTRS

protected static final EnumSet<DWARFAttribute> REF_ATTRS

dieOffsets

protected long[] dieOffsets

siblingIndexes

protected int[] siblingIndexes

parentIndexes

protected int[] parentIndexes

compUnitDieIndex

protected TreeMap<Integer,DWARFCompilationUnit> compUnitDieIndex

compUnits

protected List<DWARFCompilationUnit> compUnits

indexHasRef

protected BitSet indexHasRef

diesByOffset

protected WeakValueHashMap<Long,DebugInfoEntry> diesByOffset

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

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

init

public void init(TaskMonitor monitor)
          throws IOException,
DWARFException,
CancelledException

Reads and indexes available DWARF information.

Parameters:

monitor - TaskMonitor

Throws:

IOException - if error reading data

DWARFException - if bad or invalid DWARF information

CancelledException - if cancelled

indexDIEATypeRefs

protected void indexDIEATypeRefs(TaskMonitor monitor)
                          throws CancelledException

Throws:

CancelledException

indexDIEAggregates

protected void indexDIEAggregates(LongArrayList aggrTargets,
 TaskMonitor monitor)
                           throws CancelledException,
DWARFException

Throws:

CancelledException

DWARFException

updateSiblingIndexes

protected void updateSiblingIndexes(IntArrayList siblingIndexList,
 IntArrayList parentIndexList,
 int index)

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()

getCompilationUnits

public List<DWARFCompilationUnit> getCompilationUnits()

isBigEndian

public boolean isBigEndian()

isLittleEndian

public boolean isLittleEndian()

getDebugLineBR

public BinaryReader getDebugLineBR()

getEntryName

public String getEntryName(DIEAggregate diea)

getReferringTypedef

public static DIEAggregate getReferringTypedef(DIEAggregate diea)

Returns the DIEAggregate of a typedef that points to the specified datatype.

Returns null if there is no typedef pointing to the specified DIEA or if there are multiple.

Parameters:

diea - DIEAggregate of a data type that might be the target of typedefs.

Returns:

DIEAggregate of the singular typedef that points to the arg, otherwise null if none or multiple found.

getName

public DWARFName getName(DIEAggregate diea)

Returns a DWARFName for a DIEAggregate.

Parameters:

diea - DIEAggregate

Returns:

DWARFName, never null

getParentOf

public DebugInfoEntry getParentOf(int dieIndex)

Returns the parent DIE of the specified (by index) DIE

Parameters:

dieIndex - index of a DIE record

Returns:

parent DIE, or null if no parent (eg. root DIE)

getParentDepth

public int getParentDepth(int dieIndex)

Returns the depth of the specified DIE.

Parameters:

dieIndex - index of a DIE record

Returns:

parent/child depth of specified record, where 0 is the root DIE

getChildrenOf

public List<DebugInfoEntry> getChildrenOf(int dieIndex)

Returns the children of the specified DIE

Parameters:

dieIndex - index of a DIE record

Returns:

list of DIE instances that are children of the specified DIE

getChildCount

public int getChildCount(int dieIndex)

getDIEByOffset

public DebugInfoEntry getDIEByOffset(long dieOffset)

Returns the specified DIE record.

Parameters:

dieOffset - offset of a DIE record

Returns:

DebugInfoEntry instance, or null if invalid offset

dumpDIEs

public void dumpDIEs(PrintStream ps)

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 dieOffset)

Returns the DIEAggregate that contains the DebugInfoEntry specified by the offset.

Parameters:

dieOffset - offset of a DIE record

Returns:

DIEAggregate that contains the DIE record specified, or null if bad offset.

getCharset

public Charset getCharset()

Returns charset to use when decoding debug strings.

Returns:

charset to use when decoding debug strings

getString

public String getString(DWARFForm form,
 long offset,
 DWARFCompilationUnit cu)
                 throws IOException

Returns a DWARF attribute string value, as specified by a form, offset/index, and the cu.

Parameters:

form - DWARFForm

offset - offset or index of the value

cu - DWARFCompilationUnit

Returns:

String value, never null

Throws:

IOException - if invalid form or bad offset/index

getRangeList

public DWARFRangeList getRangeList(DIEAggregate diea,
 DWARFAttribute attribute)
                            throws IOException

Returns the DWARFRangeList pointed at by the specified attribute.

Parameters:

diea - DIEAggregate

attribute - attribute id to find in the DIEA

Returns:

DWARFRangeList, or null if attribute is not present

Throws:

IOException - if error reading range list

getOffsetOfIndexedElement

public long getOffsetOfIndexedElement(DWARFForm form,
 int index,
 DWARFCompilationUnit cu)
                               throws IOException

Returns the raw offset of an indexed item. For DW_FORM_addrx values, the returned value is not fixed up with Ghidra load offset.

Parameters:

form - DWARFForm of the index

index - int index into a lookup table (see addressListTable, locationListTable, rangeListTable, stringsOffsetTable)

cu - DWARFCompilationUnit

Returns:

raw offset of indexed item

Throws:

IOException - if error reading index table

getAddress

public long getAddress(DWARFForm form,
 long value,
 DWARFCompilationUnit cu)
                throws IOException

Returns an address value.

Parameters:

form - the format of the numeric value

value - raw offset or indirect address index (depending on the DWARFForm)

cu - DWARFCompilationUnit

Returns:

address

Throws:

IOException - if error reading indirect lookup tables

getLocationList

public DWARFLocationList getLocationList(DIEAggregate diea,
 DWARFAttribute attribute)
                                  throws IOException

Returns the DWARFLocationList pointed to by the specified attribute value.

Parameters:

diea - DIEAggregate

attribute - attribute id that points to the location list

Returns:

DWARFLocationList, never null

Throws:

IOException - if specified attribute is not the correct type, or if other error reading data

getLine

public DWARFLine getLine(DIEAggregate diea,
 DWARFAttribute attribute)
                  throws IOException

Returns the DWARFLine info pointed to by the specified attribute.

Parameters:

diea - DIEAggregate

attribute - attribute id that points to the line info

Returns:

DWARFLine, never null, see DWARFLine.empty()

Throws:

IOException - if error reading line data

getLine

public DWARFLine getLine(long offset,
 DWARFCompilationUnit cu,
 boolean readIfMissing)
                  throws IOException

Throws:

IOException

getMacroHeader

public DWARFMacroHeader getMacroHeader(long offset,
 DWARFCompilationUnit cu)

getMacroEntries

public List<DWARFMacroInfoEntry> getMacroEntries(DWARFMacroHeader macroHeader)
                                          throws IOException

Throws:

IOException

allAggregates

public Iterable<DIEAggregate> allAggregates()

Returns iterable that traverses all DIEAggregates in the program.

Returns:

sequence of DIEAggregatees

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.

getReaderForCompUnit

public BinaryReader getReaderForCompUnit(DWARFCompilationUnit cu)

getRegisterMappings

public DWARFRegisterMappings getRegisterMappings()

getRootDNI

public DWARFName getRootDNI()

getUncategorizedRootDNI

public DWARFName getUncategorizedRootDNI()

getStackSpace

public AddressSpace getStackSpace()

internAttributeSpec

public DWARFAttribute.AttrDef internAttributeSpec(DWARFAttribute.AttrDef das)

getTypeReferers

public List<DIEAggregate> getTypeReferers(DIEAggregate targetDIEA,
 DWARFTag 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.

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.

getAddressRange

public AddressRange getAddressRange(DWARFRange range,
 boolean isCode)

getCodeAddress

public Address getCodeAddress(long offset)

getDataAddress

public Address getDataAddress(long offset)

stackGrowsNegative

public boolean stackGrowsNegative()

getFunctionFixups

public List<DWARFFunctionFixup> getFunctionFixups()

getDefaultIntSize

public int getDefaultIntSize()

logWarningAt

public void logWarningAt(Address addr,
 String addrName,
 String msg)

setStringTable

public void setStringTable(StringTable st)