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