1 #-------------------------------------------------------------------------------
2 # elftools: dwarf/dwarfinfo.py
4 # DWARFInfo - Main class for accessing DWARF debug information
6 # Eli Bendersky (eliben@gmail.com)
7 # This code is in the public domain
8 #-------------------------------------------------------------------------------
10 from collections
import namedtuple
11 from bisect
import bisect_right
13 from ..construct
.lib
.container
import Container
14 from ..common
.exceptions
import DWARFError
15 from ..common
.utils
import (struct_parse
, dwarf_assert
,
16 parse_cstring_from_stream
)
17 from .structs
import DWARFStructs
18 from .compileunit
import CompileUnit
19 from .abbrevtable
import AbbrevTable
20 from .lineprogram
import LineProgram
21 from .callframe
import CallFrameInfo
22 from .locationlists
import LocationLists
, LocationListsPair
23 from .ranges
import RangeLists
, RangeListsPair
24 from .aranges
import ARanges
25 from .namelut
import NameLUT
26 from .dwarf_util
import _get_base_offset
29 # Describes a debug section
31 # stream: a stream object containing the data of this section
32 # name: section name in the container file
33 # global_offset: the global offset of the section in its container file
34 # size: the size of the section's data, in bytes
35 # address: the virtual address for the section's data
37 # 'name' and 'global_offset' are for descriptional purposes only and
38 # aren't strictly required for the DWARF parsing to work. 'address' is required
39 # to properly decode the special '.eh_frame' format.
41 DebugSectionDescriptor
= namedtuple('DebugSectionDescriptor',
42 'stream name global_offset size address')
45 # Some configuration parameters for the DWARF reader. This exists to allow
46 # DWARFInfo to be independent from any specific file format/container.
49 # boolean flag specifying whether the data in the file is little endian
52 # Machine architecture as a string. For example 'x86' or 'x64'
54 # default_address_size:
55 # The default address size for the container file (sizeof pointer, in bytes)
57 DwarfConfig
= namedtuple('DwarfConfig',
58 'little_endian machine_arch default_address_size')
61 class DWARFInfo(object):
62 """ Acts also as a "context" to other major objects, bridging between
63 various parts of the debug information.
79 debug_str_offsets_sec
,
90 DebugSectionDescriptor for a section. Pass None for sections
91 that don't exist. These arguments are best given with
95 self
.debug_info_sec
= debug_info_sec
96 self
.debug_aranges_sec
= debug_aranges_sec
97 self
.debug_abbrev_sec
= debug_abbrev_sec
98 self
.debug_frame_sec
= debug_frame_sec
99 self
.eh_frame_sec
= eh_frame_sec
100 self
.debug_str_sec
= debug_str_sec
101 self
.debug_loc_sec
= debug_loc_sec
102 self
.debug_ranges_sec
= debug_ranges_sec
103 self
.debug_line_sec
= debug_line_sec
104 self
.debug_addr_sec
= debug_addr_sec
105 self
.debug_str_offsets_sec
= debug_str_offsets_sec
106 self
.debug_line_str_sec
= debug_line_str_sec
107 self
.debug_pubtypes_sec
= debug_pubtypes_sec
108 self
.debug_pubnames_sec
= debug_pubnames_sec
109 self
.debug_loclists_sec
= debug_loclists_sec
110 self
.debug_rnglists_sec
= debug_rnglists_sec
111 self
.debug_sup_sec
= debug_sup_sec
112 self
.gnu_debugaltlink_sec
= gnu_debugaltlink_sec
114 # Sets the supplementary_dwarfinfo to None. Client code can set this
115 # to something else, typically a DWARFInfo file read from an ELFFile
116 # which path is stored in the debug_sup_sec or gnu_debugaltlink_sec.
117 self
.supplementary_dwarfinfo
= None
119 # This is the DWARFStructs the context uses, so it doesn't depend on
120 # DWARF format and address_size (these are determined per CU) - set them
122 self
.structs
= DWARFStructs(
123 little_endian
=self
.config
.little_endian
,
125 address_size
=self
.config
.default_address_size
)
127 # Cache for abbrev tables: a dict keyed by offset
128 self
._abbrevtable
_cache
= {}
129 # Cache for program lines tables: a dict keyed by offset
130 self
._linetable
_cache
= {}
132 # Cache of compile units and map of their offsets for bisect lookup.
133 # Access with .iter_CUs(), .get_CU_containing(), and/or .get_CU_at().
135 self
._cu
_offsets
_map
= []
138 def has_debug_info(self
):
139 """ Return whether this contains debug information.
141 It can be not the case when the ELF only contains .eh_frame, which is
142 encoded DWARF but not actually for debugging.
144 return bool(self
.debug_info_sec
)
146 def get_DIE_from_lut_entry(self
, lut_entry
):
147 """ Get the DIE from the pubnames or putbtypes lookup table entry.
150 A NameLUTEntry object from a NameLUT instance (see
151 .get_pubmames and .get_pubtypes methods).
153 cu
= self
.get_CU_at(lut_entry
.cu_ofs
)
154 return self
.get_DIE_from_refaddr(lut_entry
.die_ofs
, cu
)
156 def get_DIE_from_refaddr(self
, refaddr
, cu
=None):
157 """ Given a .debug_info section offset of a DIE, return the DIE.
160 The refaddr may come from a DW_FORM_ref_addr attribute.
163 The compile unit object, if known. If None a search
164 from the closest offset less than refaddr will be performed.
167 cu
= self
.get_CU_containing(refaddr
)
168 return cu
.get_DIE_from_refaddr(refaddr
)
170 def get_CU_containing(self
, refaddr
):
171 """ Find the CU that includes the given reference address in the
175 Either a refaddr of a DIE (possibly from a DW_FORM_ref_addr
176 attribute) or the section offset of a CU (possibly from an
179 This function will parse and cache CUs until the search criteria
180 is met, starting from the closest known offset lessthan or equal
181 to the given address.
185 'CU lookup but no debug info section')
187 0 <= refaddr
< self
.debug_info_sec
.size
,
188 "refaddr %s beyond .debug_info size" % refaddr
)
190 # The CU containing the DIE we desire will be to the right of the
191 # DIE insert point. If we have a CU address, then it will be a
192 # match but the right insert minus one will still be the item.
193 # The first CU starts at offset 0, so start there if cache is empty.
194 i
= bisect_right(self
._cu
_offsets
_map
, refaddr
)
195 start
= self
._cu
_offsets
_map
[i
- 1] if i
> 0 else 0
197 # parse CUs until we find one containing the desired address
198 for cu
in self
._parse
_CUs
_iter
(start
):
199 if cu
.cu_offset
<= refaddr
< cu
.cu_offset
+ cu
.size
:
202 raise ValueError("CU for reference address %s not found" % refaddr
)
204 def get_CU_at(self
, offset
):
205 """ Given a CU header offset, return the parsed CU.
208 The offset may be from an accelerated access table such as
209 the public names, public types, address range table, or
212 This function will directly parse the CU doing no validation of
213 the offset beyond checking the size of the .debug_info section.
217 'CU lookup but no debug info section')
219 0 <= offset
< self
.debug_info_sec
.size
,
220 "offset %s beyond .debug_info size" % offset
)
222 return self
._cached
_CU
_at
_offset
(offset
)
225 """ Yield all the compile units (CompileUnit objects) in the debug info
227 return self
._parse
_CUs
_iter
()
229 def get_abbrev_table(self
, offset
):
230 """ Get an AbbrevTable from the given offset in the debug_abbrev
233 The only verification done on the offset is that it's within the
234 bounds of the section (if not, an exception is raised).
235 It is the caller's responsibility to make sure the offset actually
236 points to a valid abbreviation table.
238 AbbrevTable objects are cached internally (two calls for the same
239 offset will return the same object).
242 offset
< self
.debug_abbrev_sec
.size
,
243 "Offset '0x%x' to abbrev table out of section bounds" % offset
)
244 if offset
not in self
._abbrevtable
_cache
:
245 self
._abbrevtable
_cache
[offset
] = AbbrevTable(
246 structs
=self
.structs
,
247 stream
=self
.debug_abbrev_sec
.stream
,
249 return self
._abbrevtable
_cache
[offset
]
251 def get_string_from_table(self
, offset
):
252 """ Obtain a string from the string table section, given an offset
253 relative to the section.
255 return parse_cstring_from_stream(self
.debug_str_sec
.stream
, offset
)
257 def get_string_from_linetable(self
, offset
):
258 """ Obtain a string from the string table section, given an offset
259 relative to the section.
261 return parse_cstring_from_stream(self
.debug_line_str_sec
.stream
, offset
)
263 def line_program_for_CU(self
, CU
):
264 """ Given a CU object, fetch the line program it points to from the
266 If the CU doesn't point to a line program, return None.
268 Note about directory and file names. They are returned as two collections
269 in the lineprogram object's header - include_directory and file_entry.
271 In DWARFv5, they have introduced a different, extensible format for those
272 collections. So in a lineprogram v5+, there are two more collections in
273 the header - directories and file_names. Those might contain extra DWARFv5
274 information that is not exposed in include_directory and file_entry.
276 # The line program is pointed to by the DW_AT_stmt_list attribute of
277 # the top DIE of a CU.
278 top_DIE
= CU
.get_top_DIE()
279 if 'DW_AT_stmt_list' in top_DIE
.attributes
:
280 return self
._parse
_line
_program
_at
_offset
(
281 top_DIE
.attributes
['DW_AT_stmt_list'].value
, CU
.structs
)
286 """ Does this dwarf info have a dwarf_frame CFI section?
288 return self
.debug_frame_sec
is not None
290 def CFI_entries(self
):
291 """ Get a list of dwarf_frame CFI entries from the .debug_frame section.
294 stream
=self
.debug_frame_sec
.stream
,
295 size
=self
.debug_frame_sec
.size
,
296 address
=self
.debug_frame_sec
.address
,
297 base_structs
=self
.structs
)
298 return cfi
.get_entries()
300 def has_EH_CFI(self
):
301 """ Does this dwarf info have a eh_frame CFI section?
303 return self
.eh_frame_sec
is not None
305 def EH_CFI_entries(self
):
306 """ Get a list of eh_frame CFI entries from the .eh_frame section.
309 stream
=self
.eh_frame_sec
.stream
,
310 size
=self
.eh_frame_sec
.size
,
311 address
=self
.eh_frame_sec
.address
,
312 base_structs
=self
.structs
,
314 return cfi
.get_entries()
316 def get_pubtypes(self
):
318 Returns a NameLUT object that contains information read from the
319 .debug_pubtypes section in the ELF file.
321 NameLUT is essentially a dictionary containing the CU/DIE offsets of
322 each symbol. See the NameLUT doc string for more details.
325 if self
.debug_pubtypes_sec
:
326 return NameLUT(self
.debug_pubtypes_sec
.stream
,
327 self
.debug_pubtypes_sec
.size
,
332 def get_pubnames(self
):
334 Returns a NameLUT object that contains information read from the
335 .debug_pubnames section in the ELF file.
337 NameLUT is essentially a dictionary containing the CU/DIE offsets of
338 each symbol. See the NameLUT doc string for more details.
341 if self
.debug_pubnames_sec
:
342 return NameLUT(self
.debug_pubnames_sec
.stream
,
343 self
.debug_pubnames_sec
.size
,
348 def get_aranges(self
):
349 """ Get an ARanges object representing the .debug_aranges section of
350 the DWARF data, or None if the section doesn't exist
352 if self
.debug_aranges_sec
:
353 return ARanges(self
.debug_aranges_sec
.stream
,
354 self
.debug_aranges_sec
.size
,
359 def location_lists(self
):
360 """ Get a LocationLists object representing the .debug_loc/debug_loclists section of
361 the DWARF data, or None if this section doesn't exist.
363 If both sections exist, it returns a LocationListsPair.
365 if self
.debug_loclists_sec
and self
.debug_loc_sec
is None:
366 return LocationLists(self
.debug_loclists_sec
.stream
, self
.structs
, 5, self
)
367 elif self
.debug_loc_sec
and self
.debug_loclists_sec
is None:
368 return LocationLists(self
.debug_loc_sec
.stream
, self
.structs
, 4, self
)
369 elif self
.debug_loc_sec
and self
.debug_loclists_sec
:
370 return LocationListsPair(self
.debug_loc_sec
.stream
, self
.debug_loclists_sec
.stream
, self
.structs
, self
)
374 def range_lists(self
):
375 """ Get a RangeLists object representing the .debug_ranges/.debug_rnglists section of
376 the DWARF data, or None if this section doesn't exist.
378 If both sections exist, it returns a RangeListsPair.
380 if self
.debug_rnglists_sec
and self
.debug_ranges_sec
is None:
381 return RangeLists(self
.debug_rnglists_sec
.stream
, self
.structs
, 5, self
)
382 elif self
.debug_ranges_sec
and self
.debug_rnglists_sec
is None:
383 return RangeLists(self
.debug_ranges_sec
.stream
, self
.structs
, 4, self
)
384 elif self
.debug_ranges_sec
and self
.debug_rnglists_sec
:
385 return RangeListsPair(self
.debug_ranges_sec
.stream
, self
.debug_rnglists_sec
.stream
, self
.structs
, self
)
389 def get_addr(self
, cu
, addr_index
):
390 """Provided a CU and an index, retrieves an address from the debug_addr section
392 if not self
.debug_addr_sec
:
393 raise DWARFError('The file does not contain a debug_addr section for indirect address access')
394 # Selectors are not supported, but no assert on that. TODO?
395 cu_addr_base
= _get_base_offset(cu
, 'DW_AT_addr_base')
396 return struct_parse(cu
.structs
.Dwarf_target_addr(''), self
.debug_addr_sec
.stream
, cu_addr_base
+ addr_index
*cu
.header
.address_size
)
398 #------ PRIVATE ------#
400 def _parse_CUs_iter(self
, offset
=0):
401 """ Iterate CU objects in order of appearance in the debug_info section.
404 The offset of the first CU to yield. Additional iterations
405 will return the sequential unit objects.
407 See .iter_CUs(), .get_CU_containing(), and .get_CU_at().
409 if self
.debug_info_sec
is None:
412 while offset
< self
.debug_info_sec
.size
:
413 cu
= self
._cached
_CU
_at
_offset
(offset
)
414 # Compute the offset of the next CU in the section. The unit_length
415 # field of the CU header contains its size not including the length
419 cu
.structs
.initial_length_field_size())
422 def _cached_CU_at_offset(self
, offset
):
423 """ Return the CU with unit header at the given offset into the
424 debug_info section from the cache. If not present, the unit is
425 header is parsed and the object is installed in the cache.
428 The offset of the unit header in the .debug_info section
429 to of the unit to fetch from the cache.
433 # Find the insert point for the requested offset. With bisect_right,
434 # if this entry is present in the cache it will be the prior entry.
435 i
= bisect_right(self
._cu
_offsets
_map
, offset
)
436 if i
>= 1 and offset
== self
._cu
_offsets
_map
[i
- 1]:
437 return self
._cu
_cache
[i
- 1]
439 # Parse the CU and insert the offset and object into the cache.
440 # The ._cu_offsets_map[] contains just the numeric offsets for the
441 # bisect_right search while the parallel indexed ._cu_cache[] holds
442 # the object references.
443 cu
= self
._parse
_CU
_at
_offset
(offset
)
444 self
._cu
_offsets
_map
.insert(i
, offset
)
445 self
._cu
_cache
.insert(i
, cu
)
448 def _parse_CU_at_offset(self
, offset
):
449 """ Parse and return a CU at the given offset in the debug_info stream.
451 # Section 7.4 (32-bit and 64-bit DWARF Formats) of the DWARF spec v3
452 # states that the first 32-bit word of the CU header determines
453 # whether the CU is represented with 32-bit or 64-bit DWARF format.
455 # So we peek at the first word in the CU header to determine its
456 # dwarf format. Based on it, we then create a new DWARFStructs
457 # instance suitable for this CU and use it to parse the rest.
459 initial_length
= struct_parse(
460 self
.structs
.Dwarf_uint32(''), self
.debug_info_sec
.stream
, offset
)
461 dwarf_format
= 64 if initial_length
== 0xFFFFFFFF else 32
464 # Temporary structs for parsing the header
465 # The structs for the rest of the CU depend on the header data.
467 cu_structs
= DWARFStructs(
468 little_endian
=self
.config
.little_endian
,
469 dwarf_format
=dwarf_format
,
473 cu_header
= struct_parse(
474 cu_structs
.Dwarf_CU_header
, self
.debug_info_sec
.stream
, offset
)
476 # structs for the rest of the CU, taking into account bitness and DWARF version
477 cu_structs
= DWARFStructs(
478 little_endian
=self
.config
.little_endian
,
479 dwarf_format
=dwarf_format
,
480 address_size
=cu_header
['address_size'],
481 dwarf_version
=cu_header
['version'])
483 cu_die_offset
= self
.debug_info_sec
.stream
.tell()
485 self
._is
_supported
_version
(cu_header
['version']),
486 "Expected supported DWARF version. Got '%s'" % cu_header
['version'])
492 cu_die_offset
=cu_die_offset
)
494 def _is_supported_version(self
, version
):
495 """ DWARF version supported by this parser
497 return 2 <= version
<= 5
499 def _parse_line_program_at_offset(self
, offset
, structs
):
500 """ Given an offset to the .debug_line section, parse the line program
501 starting at this offset in the section and return it.
502 structs is the DWARFStructs object used to do this parsing.
505 if offset
in self
._linetable
_cache
:
506 return self
._linetable
_cache
[offset
]
508 lineprog_header
= struct_parse(
509 structs
.Dwarf_lineprog_header
,
510 self
.debug_line_sec
.stream
,
513 # DWARF5: resolve names
514 def resolve_strings(self
, lineprog_header
, format_field
, data_field
):
515 if lineprog_header
.get(format_field
, False):
516 data
= lineprog_header
[data_field
]
517 for field
in lineprog_header
[format_field
]:
518 def replace_value(data
, content_type
, replacer
):
520 entry
[content_type
] = replacer(entry
[content_type
])
522 if field
.form
== 'DW_FORM_line_strp':
523 replace_value(data
, field
.content_type
, self
.get_string_from_linetable
)
524 elif field
.form
== 'DW_FORM_strp':
525 replace_value(data
, field
.content_type
, self
.get_string_from_table
)
526 elif field
.form
in ('DW_FORM_strp_sup', 'DW_FORM_GNU_strp_alt'):
527 if self
.supplementary_dwarfinfo
:
528 replace_value(data
, field
.content_type
, self
.supplementary_dwarfinfo
.get_string_fromtable
)
530 replace_value(data
, field
.content_type
, lambda x
: str(x
))
531 elif field
.form
in ('DW_FORM_strp_sup', 'DW_FORM_strx', 'DW_FORM_strx1', 'DW_FORM_strx2', 'DW_FORM_strx3', 'DW_FORM_strx4'):
532 raise NotImplementedError()
534 resolve_strings(self
, lineprog_header
, 'directory_entry_format', 'directories')
535 resolve_strings(self
, lineprog_header
, 'file_name_entry_format', 'file_names')
537 # DWARF5: provide compatible file/directory name arrays for legacy lineprogram consumers
538 if lineprog_header
.get('directories', False):
539 lineprog_header
.include_directory
= tuple(d
.DW_LNCT_path
for d
in lineprog_header
.directories
)
540 if lineprog_header
.get('file_names', False):
541 lineprog_header
.file_entry
= tuple(
543 'name':e
.get('DW_LNCT_path'),
544 'dir_index': e
.get('DW_LNCT_directory_index'),
545 'mtime': e
.get('DW_LNCT_timestamp'),
546 'length': e
.get('DW_LNCT_size')})
547 for e
in lineprog_header
.file_names
)
549 # Calculate the offset to the next line program (see DWARF 6.2.4)
550 end_offset
= ( offset
+ lineprog_header
['unit_length'] +
551 structs
.initial_length_field_size())
553 lineprogram
= LineProgram(
554 header
=lineprog_header
,
555 stream
=self
.debug_line_sec
.stream
,
557 program_start_offset
=self
.debug_line_sec
.stream
.tell(),
558 program_end_offset
=end_offset
)
560 self
._linetable
_cache
[offset
] = lineprogram
563 def parse_debugsupinfo(self
):
565 Extract a filename from either .debug_sup or .gnu_debualtlink sections.
567 if self
.debug_sup_sec
is not None:
568 self
.debug_sup_sec
.stream
.seek(0)
569 suplink
= self
.structs
.Dwarf_debugsup
.parse_stream(self
.debug_sup_sec
.stream
)
570 if suplink
.is_supplementary
== 0:
571 return suplink
.sup_filename
572 if self
.gnu_debugaltlink_sec
is not None:
573 self
.gnu_debugaltlink_sec
.stream
.seek(0)
574 suplink
= self
.structs
.Dwarf_debugaltlink
.parse_stream(self
.gnu_debugaltlink_sec
.stream
)
575 return suplink
.sup_filename