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         # A list of parsed line programs. Populated lazily when the line
  73         # programs are actually requested
  74         self._lineprograms = None
  75
  76     def iter_CUs(self):
  77         """ Yield all the compile units (CompileUnit objects) in the debug info
  78         """
  79         if self._CUs is None:
  80             self._CUs = self._parse_CUs()
  81         return iter(self._CUs)
  82
  83     def iter_line_programs(self):
  84         """ Yield all the line programs (LineProgram ojects) in the debug info
  85         """
  86         if self._lineprograms is None:
  87             self._lineprograms = self._parse_line_programs()
  88         return iter(self._lineprograms)
  89
  90     def get_abbrev_table(self, offset):
  91         """ Get an AbbrevTable from the given offset in the debug_abbrev
  92             section.
  93
  94             The only verification done on the offset is that it's within the
  95             bounds of the section (if not, an exception is raised).
  96             It is the caller's responsibility to make sure the offset actually
  97             points to a valid abbreviation table.
  98
  99             AbbrevTable objects are cached internally (two calls for the same
 100             offset will return the same object).
 101         """
 102         dwarf_assert(
 103             offset < self.debug_abbrev_sec.size,
 104             "Offset '0x%x' to abbrev table out of section bounds" % offset)
 105         if offset not in self._abbrevtable_cache:
 106             self._abbrevtable_cache[offset] = AbbrevTable(
 107                 structs=self.structs,
 108                 stream=self.debug_abbrev_sec.stream,
 109                 offset=offset)
 110         return self._abbrevtable_cache[offset]
 111
 112     def get_string_from_table(self, offset):
 113         """ Obtain a string from the string table section, given an offset
 114             relative to the section.
 115         """
 116         return parse_cstring_from_stream(self.debug_str_sec.stream, offset)
 117
 118     #------ PRIVATE ------#
 119
 120     def _parse_CUs(self):
 121         """ Parse CU entries from debug_info.
 122         """
 123         offset = 0
 124         CUlist = []
 125         while offset < self.debug_info_sec.size:
 126             # Section 7.4 (32-bit and 64-bit DWARF Formats) of the DWARF spec v3
 127             # states that the first 32-bit word of the CU header determines
 128             # whether the CU is represented with 32-bit or 64-bit DWARF format.
 129             #
 130             # So we peek at the first word in the CU header to determine its
 131             # dwarf format. Based on it, we then create a new DWARFStructs
 132             # instance suitable for this CU and use it to parse the rest.
 133             #
 134             initial_length = struct_parse(
 135                 self.structs.Dwarf_uint32(''), self.debug_info_sec.stream, offset)
 136             dwarf_format = 64 if initial_length == 0xFFFFFFFF else 32
 137
 138             # At this point we still haven't read the whole header, so we don't
 139             # know the address_size. Therefore, we're going to create structs
 140             # with a default address_size=4. If, after parsing the header, we
 141             # find out address_size is actually 8, we just create a new structs
 142             # object for this CU.
 143             #
 144             cu_structs = DWARFStructs(
 145                 little_endian=self.little_endian,
 146                 dwarf_format=dwarf_format,
 147                 address_size=4)
 148
 149             cu_header = struct_parse(
 150                 cu_structs.Dwarf_CU_header, self.debug_info_sec.stream, offset)
 151             if cu_header['address_size'] == 8:
 152                 cu_structs = DWARFStructs(
 153                     little_endian=self.little_endian,
 154                     dwarf_format=dwarf_format,
 155                      address_size=8)
 156
 157             cu_die_offset = self.debug_info_sec.stream.tell()
 158             dwarf_assert(
 159                 self._is_supported_version(cu_header['version']),
 160                 "Expected supported DWARF version. Got '%s'" % cu_header['version'])
 161             CUlist.append(CompileUnit(
 162                 header=cu_header,
 163                 dwarfinfo=self,
 164                 structs=cu_structs,
 165                 cu_offset=offset,
 166                 cu_die_offset=cu_die_offset))
 167             # Compute the offset of the next CU in the section. The unit_length
 168             # field of the CU header contains its size not including the length
 169             # field itself.
 170             offset = (  offset +
 171                         cu_header['unit_length'] +
 172                         cu_structs.initial_length_field_size())
 173         return CUlist
 174
 175     def _is_supported_version(self, version):
 176         """ DWARF version supported by this parser
 177         """
 178         return 2 <= version <= 3
 179
 180     def _parse_line_programs(self):
 181         """ Parse line programs from debug_line
 182         """
 183         offset = 0
 184         lineprograms = []
 185         while offset < self.debug_line_sec.size:
 186             # Similarly to CU parsing, peek at the initial_length field of the
 187             # header to figure out the DWARF format for it.
 188             initial_length = struct_parse(
 189                 self.structs.Dwarf_uint32(''),
 190                 self.debug_line_sec.stream,
 191                 offset)
 192             dwarf_format = 64 if initial_length == 0xFFFFFFFF else 32
 193
 194             # Prepare the structs for this line program, based on its format
 195             # and the default endianness. The address_size plays no role for
 196             # line programs so we just give it a default value.
 197             lineprog_structs = DWARFStructs(
 198                 little_endian=self.little_endian,
 199                 dwarf_format=dwarf_format,
 200                 address_size=4)
 201
 202             # Now parse the header fully using up-to-date structs. After this,
 203             # the section stream will point at the beginning of the program
 204             # itself, right after the header.
 205             lineprog_header = struct_parse(
 206                 lineprog_structs.Dwarf_lineprog_header,
 207                 self.debug_line_sec.stream,
 208                 offset)
 209
 210             # Calculate the offset to the next line program (see DWARF 6.2.4)
 211             end_offset = (  offset + lineprog_header['unit_length'] +
 212                             lineprog_structs.initial_length_field_size()))
 213
 214             lineprograms.append(LineProgram(
 215                 header=lineprog_header,
 216                 dwarfinfo=self,
 217                 structs=lineprog_structs,
 218                 program_start_offset=self.debug_line_sec.stream.tell()),
 219                 program_end_offset=end_offset)
 220
 221             offset = end_offset
 222
 223         return lineprograms
 224