elftools/dwarf/dwarfinfo.py

   1 #-------------------------------------------------------------------------------
   2 # elftools: dwarf/dwarfinfo.py
   3 #
   4 # DWARFInfo - Main class for accessing DWARF debug information
   5 #
   6 # Eli Bendersky (eliben@gmail.com)
   7 # This code is in the public domain
   8 #-------------------------------------------------------------------------------
   9 from collections import namedtuple
  10
  11 from ..common.exceptions import DWARFError
  12 from ..common.utils import (struct_parse, dwarf_assert,
  13                             parse_cstring_from_stream)
  14 from .structs import DWARFStructs
  15 from .compileunit import CompileUnit
  16 from .abbrevtable import AbbrevTable
  17 from .lineprogram import LineProgram
  18
  19
  20 # Describes a debug section
  21 #
  22 # stream: a stream object containing the data of this section
  23 # name: section name in the container file
  24 # global_offset: the global offset of the section in its container file
  25 # size: the size of the section's data, in bytes
  26 #
  27 DebugSectionDescriptor = namedtuple('DebugSectionDescriptor',
  28         'stream name global_offset size')
  29
  30
  31 class DWARFInfo(object):
  32     """ Acts also as a "context" to other major objects, bridging between
  33         various parts of the debug infromation.
  34     """
  35     def __init__(self,
  36             elffile,
  37             debug_info_sec,
  38             debug_abbrev_sec,
  39             debug_str_sec,
  40             debug_line_sec):
  41         """ stream:
  42                 A stream (file-like object) that contains debug sections
  43
  44             elffile:
  45                 ELFFile reference
  46
  47             debug_*_sec:
  48                 DebugSectionDescriptor for a section
  49         """
  50         self.elffile = elffile
  51         self.debug_info_sec = debug_info_sec
  52         self.debug_abbrev_sec = debug_abbrev_sec
  53         self.debug_str_sec = debug_str_sec
  54         self.debug_line_sec = debug_line_sec
  55
  56         self.little_endian = self.elffile.little_endian
  57
  58         # This is the DWARFStructs the context uses, so it doesn't depend on
  59         # DWARF format and address_size (these are determined per CU) - set them
  60         # to default values.
  61         self.structs = DWARFStructs(
  62             little_endian=self.little_endian,
  63             dwarf_format=32,
  64             address_size=4)
  65
  66         # A list of CUs. Populated lazily when they're actually requested.
  67         self._CUs = None
  68
  69         # Cache for abbrev tables: a dict keyed by offset
  70         self._abbrevtable_cache = {}
  71
  72     def iter_CUs(self):
  73         """ Yield all the compile units (CompileUnit objects) in the debug info
  74         """
  75         if self._CUs is None:
  76             self._CUs = self._parse_CUs()
  77         return iter(self._CUs)
  78
  79     def get_abbrev_table(self, offset):
  80         """ Get an AbbrevTable from the given offset in the debug_abbrev
  81             section.
  82
  83             The only verification done on the offset is that it's within the
  84             bounds of the section (if not, an exception is raised).
  85             It is the caller's responsibility to make sure the offset actually
  86             points to a valid abbreviation table.
  87
  88             AbbrevTable objects are cached internally (two calls for the same
  89             offset will return the same object).
  90         """
  91         dwarf_assert(
  92             offset < self.debug_abbrev_sec.size,
  93             "Offset '0x%x' to abbrev table out of section bounds" % offset)
  94         if offset not in self._abbrevtable_cache:
  95             self._abbrevtable_cache[offset] = AbbrevTable(
  96                 structs=self.structs,
  97                 stream=self.debug_abbrev_sec.stream,
  98                 offset=offset)
  99         return self._abbrevtable_cache[offset]
 100
 101     def get_string_from_table(self, offset):
 102         """ Obtain a string from the string table section, given an offset
 103             relative to the section.
 104         """
 105         return parse_cstring_from_stream(self.debug_str_sec.stream, offset)
 106
 107     def line_program_for_CU(self, CU):
 108         """ Given a CU object, fetch the line program it points to from the
 109             .debug_line section.
 110             If the CU doesn't point to a line program, return None.
 111         """
 112         # The line program is pointed to by the DW_AT_stmt_list attribute of
 113         # the top DIE of a CU.
 114         top_DIE = CU.get_top_DIE()
 115         if 'DW_AT_stmt_list' in top_DIE.attributes:
 116             return self._parse_line_program_at_offset(
 117                     top_DIE.attributes['DW_AT_stmt_list'], CU.structs)
 118         else:
 119             return None
 120
 121     #------ PRIVATE ------#
 122
 123     def _parse_CUs(self):
 124         """ Parse CU entries from debug_info.
 125         """
 126         offset = 0
 127         CUlist = []
 128         while offset < self.debug_info_sec.size:
 129             # Section 7.4 (32-bit and 64-bit DWARF Formats) of the DWARF spec v3
 130             # states that the first 32-bit word of the CU header determines
 131             # whether the CU is represented with 32-bit or 64-bit DWARF format.
 132             #
 133             # So we peek at the first word in the CU header to determine its
 134             # dwarf format. Based on it, we then create a new DWARFStructs
 135             # instance suitable for this CU and use it to parse the rest.
 136             #
 137             initial_length = struct_parse(
 138                 self.structs.Dwarf_uint32(''), self.debug_info_sec.stream, offset)
 139             dwarf_format = 64 if initial_length == 0xFFFFFFFF else 32
 140
 141             # At this point we still haven't read the whole header, so we don't
 142             # know the address_size. Therefore, we're going to create structs
 143             # with a default address_size=4. If, after parsing the header, we
 144             # find out address_size is actually 8, we just create a new structs
 145             # object for this CU.
 146             #
 147             cu_structs = DWARFStructs(
 148                 little_endian=self.little_endian,
 149                 dwarf_format=dwarf_format,
 150                 address_size=4)
 151
 152             cu_header = struct_parse(
 153                 cu_structs.Dwarf_CU_header, self.debug_info_sec.stream, offset)
 154             if cu_header['address_size'] == 8:
 155                 cu_structs = DWARFStructs(
 156                     little_endian=self.little_endian,
 157                     dwarf_format=dwarf_format,
 158                      address_size=8)
 159
 160             cu_die_offset = self.debug_info_sec.stream.tell()
 161             dwarf_assert(
 162                 self._is_supported_version(cu_header['version']),
 163                 "Expected supported DWARF version. Got '%s'" % cu_header['version'])
 164             CUlist.append(CompileUnit(
 165                 header=cu_header,
 166                 dwarfinfo=self,
 167                 structs=cu_structs,
 168                 cu_offset=offset,
 169                 cu_die_offset=cu_die_offset))
 170             # Compute the offset of the next CU in the section. The unit_length
 171             # field of the CU header contains its size not including the length
 172             # field itself.
 173             offset = (  offset +
 174                         cu_header['unit_length'] +
 175                         cu_structs.initial_length_field_size())
 176         return CUlist
 177
 178     def _is_supported_version(self, version):
 179         """ DWARF version supported by this parser
 180         """
 181         return 2 <= version <= 3
 182
 183     def _parse_line_program_at_offset(self, debug_line_offset, structs):
 184         """ Given an offset to the .debug_line section, parse the line program
 185             starting at this offset in the section and return it.
 186             structs is the DWARFStructs object used to do this parsing.
 187         """
 188         lineprog_header = struct_parse(
 189             structs.Dwarf_lineprog_header,
 190             self.debug_line_sec.stream,
 191             offset)
 192
 193         # Calculate the offset to the next line program (see DWARF 6.2.4)
 194         end_offset = (  offset + lineprog_header['unit_length'] +
 195                         lineprog_structs.initial_length_field_size())
 196
 197         return LineProgram(
 198             header=lineprog_header,
 199             dwarfinfo=self,
 200             structs=lineprog_structs,
 201             program_start_offset=self.debug_line_sec.stream.tell(),
 202             program_end_offset=end_offset)
 203