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