proxygen: folly::symbolizer::Dwarf Class Reference

#include <Dwarf.h>

Classes
struct	DIEAbbreviation

class	LineNumberVM

struct	LocationInfo

class	Path

class	Section

Public Types
enum	LocationInfoMode { LocationInfoMode::DISABLED, LocationInfoMode::FAST, LocationInfoMode::FULL }

Public Member Functions
	Dwarf (const ElfFile *elf)

bool	findAddress (uintptr_t address, LocationInfo &info, LocationInfoMode mode) const

Private Types
typedef boost::variant< uint64_t, folly::StringPiece >	AttributeValue

Private Member Functions
void	init ()

bool	findLocation (uintptr_t address, StringPiece &infoEntry, LocationInfo &info) const

DIEAbbreviation	getAbbreviation (uint64_t code, uint64_t offset) const

AttributeValue	readAttributeValue (folly::StringPiece &sp, uint64_t form, bool is64Bit) const

bool	getSection (const char name, folly::StringPiece section) const

folly::StringPiece	getStringFromStringSection (uint64_t offset) const

Static Private Member Functions
static bool	findDebugInfoOffset (uintptr_t address, StringPiece aranges, uint64_t &offset)

static bool	readAbbreviation (folly::StringPiece &sp, DIEAbbreviation &abbr)

static DIEAbbreviation::Attribute	readAttribute (folly::StringPiece &sp)

Private Attributes
const ElfFile *	elf_

folly::StringPiece	info_

folly::StringPiece	abbrev_

folly::StringPiece	aranges_

folly::StringPiece	line_

folly::StringPiece	strings_

Detailed Description

DWARF record parser.

We only implement enough DWARF functionality to convert from PC address to file and line number information.

This means (although they're not part of the public API of this class), we can parse Debug Information Entries (DIEs), abbreviations, attributes (of all forms), and we can interpret bytecode for the line number VM.

We can interpret DWARF records of version 2, 3, or 4, although we don't actually support many of the version 4 features (such as VLIW, multiple operations per instruction)

Note that the DWARF record parser does not allocate heap memory at all. This is on purpose: you can use the parser from memory-constrained situations (such as an exception handler for std::out_of_memory) If it weren't for this requirement, some things would be much simpler: the Path class would be unnecessary and would be replaced with a std::string; the list of file names in the line number VM would be kept as a vector of strings instead of re-executing the program to look for DW_LNE_define_file instructions, etc.

Definition at line 52 of file Dwarf.h.

Member Typedef Documentation

typedef boost::variant<uint64_t, folly::StringPiece> folly::symbolizer::Dwarf::AttributeValue

private

Definition at line 275 of file Dwarf.h.

Member Enumeration Documentation

enum folly::symbolizer::Dwarf::LocationInfoMode

strong

Enumerator
DISABLED
FAST
FULL

Definition at line 111 of file Dwarf.h.

                               {
     // Don't resolve location info.
     DISABLED,
     // Perform CU lookup using .debug_aranges (might be incomplete).
     FAST,
     // Scan all CU in .debug_info (slow!) on .debug_aranges lookup failure.
     FULL,
   };

Constructor & Destructor Documentation

folly::symbolizer::Dwarf::Dwarf ( const ElfFile * elf )

explicit

Create a DWARF parser around an ELF file.

Definition at line 32 of file Dwarf.cpp.

References init().

                                : elf_(elf) {
   init();
 }

Member Function Documentation

bool folly::symbolizer::Dwarf::findAddress	(	uintptr_t	address,
		LocationInfo &	info,
		LocationInfoMode	mode
	)		const

Find the file and line number information corresponding to address.

Definition at line 575 of file Dwarf.cpp.

References folly::Range< Iter >::advance(), aranges_, DISABLED, elf_, folly::Range< Iter >::empty(), FAST, findDebugInfoOffset(), findLocation(), FULL, folly::symbolizer::Dwarf::LocationInfo::hasFileAndLine, info_, and uint64_t.

Referenced by dummy().

                                  {
   locationInfo = LocationInfo();
 
   if (mode == LocationInfoMode::DISABLED) {
     return false;
   }
 
   if (!elf_) { // No file.
     return false;
   }
 
   if (!aranges_.empty()) {
     // Fast path: find the right .debug_info entry by looking up the
     // address in .debug_aranges.
     uint64_t offset = 0;
     if (findDebugInfoOffset(address, aranges_, offset)) {
       // Read compilation unit header from .debug_info
       folly::StringPiece infoEntry(info_);
       infoEntry.advance(offset);
       findLocation(address, infoEntry, locationInfo);
       return locationInfo.hasFileAndLine;
     } else if (mode == LocationInfoMode::FAST) {
       // NOTE: Clang (when using -gdwarf-aranges) doesn't generate entries
       // in .debug_aranges for some functions, but always generates
       // .debug_info entries.  Scanning .debug_info is slow, so fall back to
       // it only if such behavior is requested via LocationInfoMode.
       return false;
     } else {
       DCHECK(mode == LocationInfoMode::FULL);
       // Fall back to the linear scan.
     }
   }
 
   // Slow path (linear scan): Iterate over all .debug_info entries
   // and look for the address in each compilation unit.
   folly::StringPiece infoEntry(info_);
   while (!infoEntry.empty() && !locationInfo.hasFileAndLine) {
     findLocation(address, infoEntry, locationInfo);
   }
   return locationInfo.hasFileAndLine;
 }

bool folly::symbolizer::Dwarf::findDebugInfoOffset	(	uintptr_t	address,
		StringPiece	aranges,
		uint64_t &	offset
	)

staticprivate

Find in .debug_aranges and return the offset in .debug_info for compilation unit to which this address belongs.

Definition at line 442 of file Dwarf.cpp.

References folly::Range< Iter >::data(), FOLLY_SAFE_CHECK, folly::symbolizer::Dwarf::Section::is64Bit(), folly::symbolizer::Dwarf::Section::next(), start, and version.

Referenced by findAddress().

                       {
   Section arangesSection(aranges);
   folly::StringPiece chunk;
   while (arangesSection.next(chunk)) {
     auto version = read<uint16_t>(chunk);
     FOLLY_SAFE_CHECK(version == 2, "invalid aranges version");
 
     offset = readOffset(chunk, arangesSection.is64Bit());
     auto addressSize = read<uint8_t>(chunk);
     FOLLY_SAFE_CHECK(addressSize == sizeof(uintptr_t), "invalid address size");
     auto segmentSize = read<uint8_t>(chunk);
     FOLLY_SAFE_CHECK(segmentSize == 0, "segmented architecture not supported");
 
     // Padded to a multiple of 2 addresses.
     // Strangely enough, this is the only place in the DWARF spec that requires
     // padding.
     skipPadding(chunk, aranges.data(), 2 * sizeof(uintptr_t));
     for (;;) {
       auto start = read<uintptr_t>(chunk);
       auto length = read<uintptr_t>(chunk);
 
       if (start == 0 && length == 0) {
         break;
       }
 
       // Is our address in this range?
       if (address >= start && address < start + length) {
         return true;
       }
     }
   }
   return false;
 }

bool folly::symbolizer::Dwarf::findLocation	(	uintptr_t	address,
		StringPiece &	infoEntry,
		LocationInfo &	locationInfo
	)		const

private

Find the for in the compilation unit represented by the .debug_info entry. Returns whether the address was found. Advances to the next entry in .debug_info.

Definition at line 485 of file Dwarf.cpp.

Referenced by findAddress().

                                       {
   // For each compilation unit compiled with a DWARF producer, a
   // contribution is made to the .debug_info section of the object
   // file. Each such contribution consists of a compilation unit
   // header (see Section 7.5.1.1) followed by a single
   // DW_TAG_compile_unit or DW_TAG_partial_unit debugging information
   // entry, together with its children.
 
   // 7.5.1.1 Compilation Unit Header
   //  1. unit_length (4B or 12B): read by Section::next
   //  2. version (2B)
   //  3. debug_abbrev_offset (4B or 8B): offset into the .debug_abbrev section
   //  4. address_size (1B)
 
   Section debugInfoSection(infoEntry);
   folly::StringPiece chunk;
   FOLLY_SAFE_CHECK(debugInfoSection.next(chunk), "invalid debug info");
 
   auto version = read<uint16_t>(chunk);
   FOLLY_SAFE_CHECK(version >= 2 && version <= 4, "invalid info version");
   uint64_t abbrevOffset = readOffset(chunk, debugInfoSection.is64Bit());
   auto addressSize = read<uint8_t>(chunk);
   FOLLY_SAFE_CHECK(addressSize == sizeof(uintptr_t), "invalid address size");
 
   // We survived so far. The first (and only) DIE should be DW_TAG_compile_unit
   // NOTE: - binutils <= 2.25 does not issue DW_TAG_partial_unit.
   //       - dwarf compression tools like `dwz` may generate it.
   // TODO(tudorb): Handle DW_TAG_partial_unit?
   auto code = readULEB(chunk);
   FOLLY_SAFE_CHECK(code != 0, "invalid code");
   auto abbr = getAbbreviation(code, abbrevOffset);
   FOLLY_SAFE_CHECK(
       abbr.tag == DW_TAG_compile_unit, "expecting compile unit entry");
   // Skip children entries, advance to the next compilation unit entry.
   infoEntry.advance(chunk.end() - infoEntry.begin());
 
   // Read attributes, extracting the few we care about
   bool foundLineOffset = false;
   uint64_t lineOffset = 0;
   folly::StringPiece compilationDirectory;
   folly::StringPiece mainFileName;
 
   DIEAbbreviation::Attribute attr;
   folly::StringPiece attributes = abbr.attributes;
   for (;;) {
     attr = readAttribute(attributes);
     if (attr.name == 0 && attr.form == 0) {
       break;
     }
     auto val = readAttributeValue(chunk, attr.form, debugInfoSection.is64Bit());
     switch (attr.name) {
       case DW_AT_stmt_list:
         // Offset in .debug_line for the line number VM program for this
         // compilation unit
         lineOffset = boost::get<uint64_t>(val);
         foundLineOffset = true;
         break;
       case DW_AT_comp_dir:
         // Compilation directory
         compilationDirectory = boost::get<folly::StringPiece>(val);
         break;
       case DW_AT_name:
         // File name of main file being compiled
         mainFileName = boost::get<folly::StringPiece>(val);
         break;
     }
   }
 
   if (!mainFileName.empty()) {
     locationInfo.hasMainFile = true;
     locationInfo.mainFile = Path(compilationDirectory, "", mainFileName);
   }
 
   if (!foundLineOffset) {
     return false;
   }
 
   folly::StringPiece lineSection(line_);
   lineSection.advance(lineOffset);
   LineNumberVM lineVM(lineSection, compilationDirectory);
 
   // Execute line number VM program to find file and line
   locationInfo.hasFileAndLine =
       lineVM.findAddress(address, locationInfo.file, locationInfo.line);
   return locationInfo.hasFileAndLine;
 }

Dwarf::DIEAbbreviation folly::symbolizer::Dwarf::getAbbreviation	(	uint64_t	code,
		uint64_t	offset
	)		const

private

Definition at line 364 of file Dwarf.cpp.

References abbrev_, folly::Range< Iter >::advance(), folly::symbolizer::Dwarf::DIEAbbreviation::code, FOLLY_SAFE_CHECK, and readAbbreviation().

Referenced by findLocation().

           {
   // Linear search in the .debug_abbrev section, starting at offset
   folly::StringPiece section = abbrev_;
   section.advance(offset);
 
   Dwarf::DIEAbbreviation abbr;
   while (readAbbreviation(section, abbr)) {
     if (abbr.code == code) {
       return abbr;
     }
   }
 
   FOLLY_SAFE_CHECK(false, "could not find abbreviation code");
 }

bool folly::symbolizer::Dwarf::getSection	(	const char *	name,
		folly::StringPiece *	section
	)		const

private

Definition at line 302 of file Dwarf.cpp.

References elf_, folly::symbolizer::ElfFile::getSectionBody(), and folly::symbolizer::ElfFile::getSectionByName().

Referenced by init().

                                                                         {
   const ElfW(Shdr)* elfSection = elf_->getSectionByName(name);
   if (!elfSection) {
     return false;
   }
 #ifdef SHF_COMPRESSED
   if (elfSection->sh_flags & SHF_COMPRESSED) {
     return false;
   }
 #endif
   *section = elf_->getSectionBody(*elfSection);
   return true;
 }

folly::StringPiece folly::symbolizer::Dwarf::getStringFromStringSection ( uint64_t offset ) const

private

Definition at line 431 of file Dwarf.cpp.

References FOLLY_SAFE_CHECK, folly::Range< Iter >::size(), and strings_.

Referenced by readAttributeValue().

                                                                         {
   FOLLY_SAFE_CHECK(offset < strings_.size(), "invalid strp offset");
   folly::StringPiece sp(strings_);
   sp.advance(offset);
   return readNullTerminated(sp);
 }

void folly::symbolizer::Dwarf::init ( )

private

Definition at line 316 of file Dwarf.cpp.

References abbrev_, aranges_, elf_, getSection(), info_, line_, and strings_.

Referenced by Dwarf().

                  {
   // Make sure that all .debug_* sections exist
   if (!getSection(".debug_info", &info_) ||
       !getSection(".debug_abbrev", &abbrev_) ||
       !getSection(".debug_line", &line_) ||
       !getSection(".debug_str", &strings_)) {
     elf_ = nullptr;
     return;
   }
 
   // Optional: fast address range lookup. If missing .debug_info can
   // be used - but it's much slower (linear scan).
   getSection(".debug_aranges", &aranges_);
 }

bool folly::symbolizer::Dwarf::readAbbreviation	(	folly::StringPiece &	sp,
		DIEAbbreviation &	abbr
	)

staticprivate

Definition at line 331 of file Dwarf.cpp.

References folly::Range< Iter >::assign(), folly::symbolizer::Dwarf::DIEAbbreviation::attributes, folly::symbolizer::Dwarf::DIEAbbreviation::code, folly::Range< Iter >::data(), folly::Range< Iter >::empty(), FOLLY_SAFE_CHECK, folly::symbolizer::Dwarf::DIEAbbreviation::hasChildren, readAttribute(), and folly::symbolizer::Dwarf::DIEAbbreviation::tag.

Referenced by getAbbreviation().

                            {
   // abbreviation code
   abbr.code = readULEB(section);
   if (abbr.code == 0) {
     return false;
   }
 
   // abbreviation tag
   abbr.tag = readULEB(section);
 
   // does this entry have children?
   abbr.hasChildren = (read<uint8_t>(section) != DW_CHILDREN_no);
 
   // attributes
   const char* attributeBegin = section.data();
   for (;;) {
     FOLLY_SAFE_CHECK(!section.empty(), "invalid attribute section");
     auto attr = readAttribute(section);
     if (attr.name == 0 && attr.form == 0) {
       break;
     }
   }
 
   abbr.attributes.assign(attributeBegin, section.data());
   return true;
 }

Dwarf::DIEAbbreviation::Attribute folly::symbolizer::Dwarf::readAttribute ( folly::StringPiece & sp )

staticprivate

Definition at line 360 of file Dwarf.cpp.

Referenced by findLocation(), and readAbbreviation().

                                                                        {
   return {readULEB(sp), readULEB(sp)};
 }

Dwarf::AttributeValue folly::symbolizer::Dwarf::readAttributeValue	(	folly::StringPiece &	sp,
		uint64_t	form,
		bool	is64Bit
	)		const

private

Definition at line 380 of file Dwarf.cpp.

References FOLLY_SAFE_CHECK, and getStringFromStringSection().

Referenced by findLocation().

                         {
   switch (form) {
     case DW_FORM_addr:
       return read<uintptr_t>(sp);
     case DW_FORM_block1:
       return readBytes(sp, read<uint8_t>(sp));
     case DW_FORM_block2:
       return readBytes(sp, read<uint16_t>(sp));
     case DW_FORM_block4:
       return readBytes(sp, read<uint32_t>(sp));
     case DW_FORM_block: // fallthrough
     case DW_FORM_exprloc:
       return readBytes(sp, readULEB(sp));
     case DW_FORM_data1: // fallthrough
     case DW_FORM_ref1:
       return read<uint8_t>(sp);
     case DW_FORM_data2: // fallthrough
     case DW_FORM_ref2:
       return read<uint16_t>(sp);
     case DW_FORM_data4: // fallthrough
     case DW_FORM_ref4:
       return read<uint32_t>(sp);
     case DW_FORM_data8: // fallthrough
     case DW_FORM_ref8:
       return read<uint64_t>(sp);
     case DW_FORM_sdata:
       return readSLEB(sp);
     case DW_FORM_udata: // fallthrough
     case DW_FORM_ref_udata:
       return readULEB(sp);
     case DW_FORM_flag:
       return read<uint8_t>(sp);
     case DW_FORM_flag_present:
       return 1;
     case DW_FORM_sec_offset: // fallthrough
     case DW_FORM_ref_addr:
       return readOffset(sp, is64Bit);
     case DW_FORM_string:
       return readNullTerminated(sp);
     case DW_FORM_strp:
       return getStringFromStringSection(readOffset(sp, is64Bit));
     case DW_FORM_indirect: // form is explicitly specified
       return readAttributeValue(sp, readULEB(sp), is64Bit);
     default:
       FOLLY_SAFE_CHECK(false, "invalid attribute form");
   }
 }

Member Data Documentation

folly::StringPiece folly::symbolizer::Dwarf::abbrev_

private

Definition at line 286 of file Dwarf.h.

Referenced by getAbbreviation(), and init().

folly::StringPiece folly::symbolizer::Dwarf::aranges_

private

Definition at line 287 of file Dwarf.h.

Referenced by findAddress(), and init().

const ElfFile* folly::symbolizer::Dwarf::elf_

private

Definition at line 145 of file Dwarf.h.

Referenced by findAddress(), getSection(), and init().

folly::StringPiece folly::symbolizer::Dwarf::info_

private

Definition at line 285 of file Dwarf.h.

Referenced by findAddress(), and init().

folly::StringPiece folly::symbolizer::Dwarf::line_

private

Definition at line 288 of file Dwarf.h.

Referenced by findLocation(), and init().

folly::StringPiece folly::symbolizer::Dwarf::strings_

private

Definition at line 289 of file Dwarf.h.

Referenced by getStringFromStringSection(), and init().

The documentation for this class was generated from the following files:

proxygen/folly/folly/experimental/symbolizer/Dwarf.h
proxygen/folly/folly/experimental/symbolizer/Dwarf.cpp

Classes

Public Types

Public Member Functions

Private Types

Private Member Functions

Static Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation