Expand description
Read DWARF debugging information.
Example Usage
Print out all of the functions in the debuggee program:
// Read the DWARF sections with whatever object loader you're using.
// These closures should return a `Reader` instance (e.g. `EndianSlice`).
let loader = |section: gimli::SectionId| { get_file_section_reader(section.name()) };
let sup_loader = |section: gimli::SectionId| { get_sup_file_section_reader(section.name()) };
let mut dwarf = gimli::Dwarf::load(loader)?;
dwarf.load_sup(sup_loader)?;
// Iterate over all compilation units.
let mut iter = dwarf.units();
while let Some(header) = iter.next()? {
// Parse the abbreviations and other information for this compilation unit.
let unit = dwarf.unit(header)?;
// Iterate over all of this compilation unit's entries.
let mut entries = unit.entries();
while let Some((_, entry)) = entries.next_dfs()? {
// If we find an entry for a function, print it.
if entry.tag() == gimli::DW_TAG_subprogram {
println!("Found a function: {:?}", entry);
}
}
}Full example programs:
-
ddbug, a utility giving insight into code generation by making debugging information readable -
dwprod, a tiny utility to list the compilers used to create each compilation unit within a shared library or executable (viaDW_AT_producer) -
dwarf-validate, a program to validate the integrity of some DWARF and its references between sections and compilation units.
API Structure
-
Basic familiarity with DWARF is assumed.
-
The
Dwarftype contains the commonly used DWARF sections. It has methods that simplify access to debugging data that spans multiple sections. Use of this type is optional, but recommended. -
Each section gets its own type. Consider these types the entry points to the library:
-
DebugAbbrev: The.debug_abbrevsection. -
DebugAddr: The.debug_addrsection. -
DebugAranges: The.debug_arangessection. -
DebugFrame: The.debug_framesection. -
DebugInfo: The.debug_infosection. -
DebugLine: The.debug_linesection. -
DebugLineStr: The.debug_line_strsection. -
DebugLoc: The.debug_locsection. -
DebugLocLists: The.debug_loclistssection. -
DebugPubNames: The.debug_pubnamessection. -
DebugPubTypes: The.debug_pubtypessection. -
DebugRanges: The.debug_rangessection. -
DebugRngLists: The.debug_rnglistssection. -
DebugStr: The.debug_strsection. -
DebugStrOffsets: The.debug_str_offsetssection. -
DebugTypes: The.debug_typessection. -
DebugCuIndex: The.debug_cu_indexsection. -
DebugTuIndex: The.debug_tu_indexsection. -
EhFrame: The.eh_framesection. -
EhFrameHdr: The.eh_frame_hdrsection.
-
-
Each section type exposes methods for accessing the debugging data encoded in that section. For example, the
DebugInfostruct has theunitsmethod for iterating over the compilation units defined within it. -
Offsets into a section are strongly typed: an offset into
.debug_infois theDebugInfoOffsettype. It cannot be used to index into theDebugLinetype becauseDebugLinerepresents the.debug_linesection. There are similar types for offsets relative to a compilation unit rather than a section.
Using with FallibleIterator
The standard library’s Iterator trait and related APIs do not play well
with iterators where the next operation is fallible. One can make the
Iterator’s associated Item type be a Result<T, E>, however the
provided methods cannot gracefully handle the case when an Err is
returned.
This situation led to the
fallible-iterator crate’s
existence. You can read more of the rationale for its existence in its
docs. The crate provides the helpers you have come to expect (eg map,
filter, etc) for iterators that can fail.
gimli’s many lazy parsing iterators are a perfect match for the
fallible-iterator crate’s FallibleIterator trait because parsing is not
done eagerly. Parse errors later in the input might only be discovered after
having iterated through many items.
To use gimli iterators with FallibleIterator, import the crate and trait
into your code:
// Use the `FallibleIterator` trait so its methods are in scope!
use fallible_iterator::FallibleIterator;
use gimli::{DebugAranges, EndianSlice, LittleEndian};
fn find_sum_of_address_range_lengths(aranges: DebugAranges<EndianSlice<LittleEndian>>)
-> gimli::Result<u64>
{
// `DebugAranges::headers` returns a `FallibleIterator`!
aranges.headers()
// `flat_map` is provided by `FallibleIterator`!
.flat_map(|header| Ok(header.entries()))
// `map` is provided by `FallibleIterator`!
.map(|arange| Ok(arange.length()))
// `fold` is provided by `FallibleIterator`!
.fold(0, |sum, len| Ok(sum + len))
}Structs
DebuggingInformationEntry’s type:
its code, tag type, whether it has children, and its set of attributes..debug_aranges section..debug_arange section..debug_aranges section.DebuggingInformationEntry, consisting of a name and
associated value..eh_frame.DW_EH_PE_* encoded pointers..debug_frame or .eh_frame
section.
A Common Information Entry holds information that is shared among many
Frame Description Entries. There is at least one CIE in every non-empty
.debug_frame section.
DebugAbbrev struct represents the abbreviations describing
DebuggingInformationEntrys’ attribute names and forms found in the
.debug_abbrev section..debug_addr section.DebugAranges struct represents the DWARF address range information
found in the .debug_aranges section..debug_cu_index section of a .dwp file.DebugFrame contains the .debug_frame section’s frame unwinding
information required to unwind to and recover registers from older frames on
the stack. For example, this is useful for a debugger that wants to print
locals in a backtrace.DebugInfo struct represents the DWARF debugging information found in
the .debug_info section.DebugLine struct contains the source location to instruction mapping
found in the .debug_line section.DebugLineStr struct represents the DWARF strings
found in the .debug_line_str section..debug_loc section.DebugLocLists struct represents the DWARF data
found in the .debug_loclists section.DebugPubNames struct represents the DWARF public names information
found in the .debug_pubnames section.DebugPubTypes struct represents the DWARF public types information
found in the .debug_info section..debug_ranges section.DebugRngLists struct represents the contents of the
.debug_rnglists section.DebugStr struct represents the DWARF strings
found in the .debug_str section..debug_str_offsets section..debug_tu_index section of a .dwp file.DebugTypes struct represents the DWARF type information
found in the .debug_types section..debug_types section..dwp file.EhFrame contains the frame unwinding information needed during exception
handling found in the .eh_frame section.EhFrameHdr contains the information about the .eh_frame_hdr section..eh_frame_hdr section..eh_frame_hdr section’s binary search table.&[u8] slice with endianity metadata.EntriesTreeNode.LineProgramHeader’s file_names set.FrameDescriptionEntry is a set of CFA instructions for an address range..debug_line section, as defined
in section 6.2.4 of the standard.LineProgram to iterate over the rows in the matrix of line number information..debug_loc or .debug_loclists sections..debug_loc and .debug_loclists sections.ParsedEhFrameHdr contains the parsed information from the .eh_frame_hdr section.FrameDescriptionEntry..debug_pubnames section..debug_pubtypes section..debug_ranges, .debug_rnglists, or .debug_aranges sections.DebuggingInformationEntry..debug_ranges and .debug_rnglists sections.DW_EH_PE_* encoded pointers
in a particular section..debug_info or .debug_types
sections.DebugCuIndex or DebugTuIndex..dwp file.UnitIndex.UnwindTable iteratively evaluates a FrameDescriptionEntry’s
CallFrameInstruction program, yielding the each row one at a time.Enums
DebuggingInformationEntry.CommonInformationEntry (CIE) or a FrameDescriptionEntry (FDE).Evaluation after evaluating a DWARF expression.
The evaluation is either Complete, or it requires more data
to continue, as described by the variant.Traits
Evaluation.LineProgram provides access to a LineProgramHeader and
a way to add files to the files table if necessary. Gimli consumers should
never need to use or see this trait.UnwindContext.UnwindSection..debug_frame or
.eh_frame. See DebugFrame and
EhFrame respectively.Type Definitions
CompleteLineNumberProgram has been renamed to CompleteLineProgram.EndianBuf has been renamed to EndianSlice. For ease of upgrading across
gimli versions, we export this type alias.IncompleteLineNumberProgram has been renamed to IncompleteLineProgram.LineNumberProgram has been renamed to LineProgram.LineNumberProgramHeader has been renamed to LineProgramHeader.LineNumberRow has been renamed to LineRow.LineNumberSequence has been renamed to LineSequence.Opcode has been renamed to LineInstruction.OpcodesIter has been renamed to LineInstructions.StateMachine has been renamed to LineRows.