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