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 ..construct import CString
  12 from ..common.exceptions import DWARFError
  13 from ..common.utils import struct_parse, dwarf_assert
  14 from .structs import DWARFStructs
  15 from .compileunit import CompileUnit
  16 from .abbrevtable import AbbrevTable
  17 from .dwarfrelocationmanager import DWARFRelocationManager
  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('DebugSectionLocator',
  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 this 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         self.relocation_manager = {}
  59         self.relocation_manager['.debug_info'] = DWARFRelocationManager(
  60                 elffile=self.elffile,
  61                 section_name='.debug_info')
  62
  63         # This is the DWARFStructs the context uses, so it doesn't depend on
  64         # DWARF format and address_size (these are determined per CU) - set them
  65         # to default values.
  66         self.structs = DWARFStructs(
  67             little_endian=self.little_endian,
  68             dwarf_format=32,
  69             address_size=4)
  70
  71         # Populate the list with CUs found in debug_info. For each CU only its
  72         # header is parsed immediately (the abbrev table isn't loaded before
  73         # it's being referenced by one of the CU's DIEs).
  74         # Since there usually aren't many CUs in a single object, this
  75         # shouldn't present a performance problem.
  76         #
  77         self._CU = self._parse_CUs()
  78
  79         # Cache for abbrev tables: a dict keyed by offset
  80         self._abbrevtable_cache = {}
  81
  82     def num_CUs(self):
  83         """ Number of compile units in the debug info
  84         """
  85         return len(self._CU)
  86
  87     def get_CU(self, n):
  88         """ Get the compile unit (CompileUnit object) at index #n
  89         """
  90         return self._CU[n]
  91
  92     def iter_CUs(self):
  93         """ Yield all the compile units (CompileUnit objects) in the debug info
  94         """
  95         for i in range(self.num_CUs()):
  96             yield self.get_CU(i)
  97
  98     def get_abbrev_table(self, offset):
  99         """ Get an AbbrevTable from the given offset in the debug_abbrev
 100             section.
 101
 102             The only verification done on the offset is that it's within the
 103             bounds of the section (if not, an exception is raised).
 104             It is the caller's responsibility to make sure the offset actually
 105             points to a valid abbreviation table.
 106
 107             AbbrevTable objects are cached internally (two calls for the same
 108             offset will return the same object).
 109         """
 110         dwarf_assert(
 111             offset < self.debug_abbrev_loc.size,
 112             "Offset '0x%x' to abbrev table out of section bounds" % offset)
 113         if offset not in self._abbrevtable_cache:
 114             self._abbrevtable_cache[offset] = AbbrevTable(
 115                 structs=self.structs,
 116                 stream=self.stream,
 117                 offset=offset + self.debug_abbrev_loc.offset)
 118         return self._abbrevtable_cache[offset]
 119
 120     def info_offset2absolute(self, offset):
 121         """ Given an offset into the debug_info section, translate it to an
 122             absolute offset into the stream. Raise an exception if the offset
 123             exceeds the section bounds.
 124         """
 125         dwarf_assert(
 126             offset < self.debug_info_loc.size,
 127             "Offset '0x%x' to debug_info out of section bounds" % offset)
 128         return offset + self.debug_info_loc.offset
 129
 130     def get_string_from_table(self, offset):
 131         """ Obtain a string from the string table section, given an offset
 132             relative to the section.
 133         """
 134         return struct_parse(
 135             CString(''),
 136             self.stream,
 137             stream_pos=self.debug_str_loc.offset + offset)
 138
 139     #------ PRIVATE ------#
 140
 141     def _parse_CUs(self):
 142         """ Parse CU entries from debug_info.
 143         """
 144         offset = self.debug_info_loc.offset
 145         section_boundary = self.debug_info_loc.offset + self.debug_info_loc.size
 146         CUlist = []
 147         while offset < section_boundary:
 148             # Section 7.4 (32-bit and 64-bit DWARF Formats) of the DWARF spec v3
 149             # states that the first 32-bit word of the CU header determines
 150             # whether the CU is represented with 32-bit or 64-bit DWARF format.
 151             #
 152             # So we peek at the first word in the CU header to determine its
 153             # dwarf format. Based on it, we then create a new DWARFStructs
 154             # instance suitable for this CU and use it to parse the rest.
 155             #
 156             initial_length = struct_parse(
 157                 self.structs.Dwarf_uint32(''), self.stream, offset)
 158             dwarf_format = 64 if initial_length == 0xFFFFFFFF else 32
 159
 160             # At this point we still haven't read the whole header, so we don't
 161             # know the address_size. Therefore, we're going to create structs
 162             # with a default address_size=4. If, after parsing the header, we
 163             # find out address_size is actually 8, we just create a new structs
 164             # object for this CU.
 165             #
 166             cu_structs = DWARFStructs(
 167                 little_endian=self.little_endian,
 168                 dwarf_format=dwarf_format,
 169                 address_size=4)
 170
 171             cu_header = struct_parse(
 172                 cu_structs.Dwarf_CU_header, self.stream, offset)
 173             if cu_header['address_size'] == 8:
 174                 cu_structs = DWARFStructs(
 175                     little_endian=self.little_endian,
 176                     dwarf_format=dwarf_format,
 177                      address_size=8)
 178
 179             cu_die_offset = self.stream.tell()
 180             dwarf_assert(
 181                 self._is_supported_version(cu_header['version']),
 182                 "Expected supported DWARF version. Got '%s'" % cu_header['version'])
 183             CUlist.append(CompileUnit(
 184                 header=cu_header,
 185                 dwarfinfo=self,
 186                 structs=cu_structs,
 187                 cu_offset=offset,
 188                 cu_die_offset=cu_die_offset))
 189             # Compute the offset of the next CU in the section. The unit_length
 190             # field of the CU header contains its size not including the length
 191             # field itself.
 192             offset = (  offset +
 193                         cu_header['unit_length'] +
 194                         cu_structs.initial_length_field_size())
 195         return CUlist
 196
 197     def _is_supported_version(self, version):
 198         """ DWARF version supported by this parser
 199         """
 200         return 2 <= version <= 3
 201