1use alloc::string::String;
2use alloc::sync::Arc;
3
4use crate::common::{
5 DebugAddrBase, DebugAddrIndex, DebugInfoOffset, DebugLineStrOffset, DebugLocListsBase,
6 DebugLocListsIndex, DebugRngListsBase, DebugRngListsIndex, DebugStrOffset, DebugStrOffsetsBase,
7 DebugStrOffsetsIndex, DebugTypeSignature, DebugTypesOffset, DwarfFileType, DwoId, Encoding,
8 LocationListsOffset, RangeListsOffset, RawRangeListsOffset, SectionId, UnitSectionOffset,
9};
10use crate::constants;
11use crate::read::{
12 Abbreviations, AbbreviationsCache, AbbreviationsCacheStrategy, AttributeValue, DebugAbbrev,
13 DebugAddr, DebugAranges, DebugCuIndex, DebugInfo, DebugInfoUnitHeadersIter, DebugLine,
14 DebugLineStr, DebugLoc, DebugLocLists, DebugRngLists, DebugStr, DebugStrOffsets, DebugTuIndex,
15 DebugTypes, DebugTypesUnitHeadersIter, DebuggingInformationEntry, EntriesCursor, EntriesRaw,
16 EntriesTree, Error, IncompleteLineProgram, LocListIter, LocationLists, Range, RangeLists,
17 RawLocListIter, RawRngListIter, Reader, ReaderOffset, ReaderOffsetId, Result, RngListIter,
18 Section, UnitHeader, UnitIndex, UnitIndexSectionIterator, UnitOffset, UnitType,
19};
20
21/// All of the commonly used DWARF sections, and other common information.
22#[derive(Debug, Default)]
23pub struct Dwarf<R> {
24 /// The `.debug_abbrev` section.
25 pub debug_abbrev: DebugAbbrev<R>,
26
27 /// The `.debug_addr` section.
28 pub debug_addr: DebugAddr<R>,
29
30 /// The `.debug_aranges` section.
31 pub debug_aranges: DebugAranges<R>,
32
33 /// The `.debug_info` section.
34 pub debug_info: DebugInfo<R>,
35
36 /// The `.debug_line` section.
37 pub debug_line: DebugLine<R>,
38
39 /// The `.debug_line_str` section.
40 pub debug_line_str: DebugLineStr<R>,
41
42 /// The `.debug_str` section.
43 pub debug_str: DebugStr<R>,
44
45 /// The `.debug_str_offsets` section.
46 pub debug_str_offsets: DebugStrOffsets<R>,
47
48 /// The `.debug_types` section.
49 pub debug_types: DebugTypes<R>,
50
51 /// The location lists in the `.debug_loc` and `.debug_loclists` sections.
52 pub locations: LocationLists<R>,
53
54 /// The range lists in the `.debug_ranges` and `.debug_rnglists` sections.
55 pub ranges: RangeLists<R>,
56
57 /// The type of this file.
58 pub file_type: DwarfFileType,
59
60 /// The DWARF sections for a supplementary object file.
61 pub sup: Option<Arc<Dwarf<R>>>,
62
63 /// A cache of previously parsed abbreviations for units in this file.
64 pub abbreviations_cache: AbbreviationsCache,
65}
66
67impl<T> Dwarf<T> {
68 /// Try to load the DWARF sections using the given loader function.
69 ///
70 /// `section` loads a DWARF section from the object file.
71 /// It should return an empty section if the section does not exist.
72 ///
73 /// `section` may either directly return a `Reader` instance (such as
74 /// `EndianSlice`), or it may return some other type and then convert
75 /// that type into a `Reader` using `Dwarf::borrow`.
76 ///
77 /// After loading, the user should set the `file_type` field and
78 /// call `load_sup` if required.
79 pub fn load<F, E>(mut section: F) -> core::result::Result<Self, E>
80 where
81 F: FnMut(SectionId) -> core::result::Result<T, E>,
82 {
83 // Section types are inferred.
84 let debug_loc = Section::load(&mut section)?;
85 let debug_loclists = Section::load(&mut section)?;
86 let debug_ranges = Section::load(&mut section)?;
87 let debug_rnglists = Section::load(&mut section)?;
88 Ok(Dwarf {
89 debug_abbrev: Section::load(&mut section)?,
90 debug_addr: Section::load(&mut section)?,
91 debug_aranges: Section::load(&mut section)?,
92 debug_info: Section::load(&mut section)?,
93 debug_line: Section::load(&mut section)?,
94 debug_line_str: Section::load(&mut section)?,
95 debug_str: Section::load(&mut section)?,
96 debug_str_offsets: Section::load(&mut section)?,
97 debug_types: Section::load(&mut section)?,
98 locations: LocationLists::new(debug_loc, debug_loclists),
99 ranges: RangeLists::new(debug_ranges, debug_rnglists),
100 file_type: DwarfFileType::Main,
101 sup: None,
102 abbreviations_cache: AbbreviationsCache::new(),
103 })
104 }
105
106 /// Load the DWARF sections from the supplementary object file.
107 ///
108 /// `section` operates the same as for `load`.
109 ///
110 /// Sets `self.sup`, replacing any previous value.
111 pub fn load_sup<F, E>(&mut self, section: F) -> core::result::Result<(), E>
112 where
113 F: FnMut(SectionId) -> core::result::Result<T, E>,
114 {
115 self.sup = Some(Arc::new(Self::load(section)?));
116 Ok(())
117 }
118
119 /// Create a `Dwarf` structure that references the data in `self`.
120 ///
121 /// This is useful when `R` implements `Reader` but `T` does not.
122 ///
123 /// ## Example Usage
124 ///
125 /// It can be useful to load DWARF sections into owned data structures,
126 /// such as `Vec`. However, we do not implement the `Reader` trait
127 /// for `Vec`, because it would be very inefficient, but this trait
128 /// is required for all of the methods that parse the DWARF data.
129 /// So we first load the DWARF sections into `Vec`s, and then use
130 /// `borrow` to create `Reader`s that reference the data.
131 ///
132 /// ```rust,no_run
133 /// # fn example() -> Result<(), gimli::Error> {
134 /// # let loader = |name| -> Result<_, gimli::Error> { unimplemented!() };
135 /// # let sup_loader = |name| -> Result<_, gimli::Error> { unimplemented!() };
136 /// // Read the DWARF sections into `Vec`s with whatever object loader you're using.
137 /// let mut owned_dwarf: gimli::Dwarf<Vec<u8>> = gimli::Dwarf::load(loader)?;
138 /// owned_dwarf.load_sup(sup_loader)?;
139 /// // Create references to the DWARF sections.
140 /// let dwarf = owned_dwarf.borrow(|section| {
141 /// gimli::EndianSlice::new(&section, gimli::LittleEndian)
142 /// });
143 /// # unreachable!()
144 /// # }
145 /// ```
146 pub fn borrow<'a, F, R>(&'a self, mut borrow: F) -> Dwarf<R>
147 where
148 F: FnMut(&'a T) -> R,
149 {
150 Dwarf {
151 debug_abbrev: self.debug_abbrev.borrow(&mut borrow),
152 debug_addr: self.debug_addr.borrow(&mut borrow),
153 debug_aranges: self.debug_aranges.borrow(&mut borrow),
154 debug_info: self.debug_info.borrow(&mut borrow),
155 debug_line: self.debug_line.borrow(&mut borrow),
156 debug_line_str: self.debug_line_str.borrow(&mut borrow),
157 debug_str: self.debug_str.borrow(&mut borrow),
158 debug_str_offsets: self.debug_str_offsets.borrow(&mut borrow),
159 debug_types: self.debug_types.borrow(&mut borrow),
160 locations: self.locations.borrow(&mut borrow),
161 ranges: self.ranges.borrow(&mut borrow),
162 file_type: self.file_type,
163 sup: self.sup().map(|sup| Arc::new(sup.borrow(borrow))),
164 abbreviations_cache: AbbreviationsCache::new(),
165 }
166 }
167
168 /// Return a reference to the DWARF sections for supplementary object file.
169 pub fn sup(&self) -> Option<&Dwarf<T>> {
170 self.sup.as_ref().map(Arc::as_ref)
171 }
172}
173
174impl<R: Reader> Dwarf<R> {
175 /// Parse abbreviations and store them in the cache.
176 ///
177 /// This will iterate over the units in `self.debug_info` to determine the
178 /// abbreviations offsets.
179 ///
180 /// Errors during parsing abbreviations are also stored in the cache.
181 /// Errors during iterating over the units are ignored.
182 pub fn populate_abbreviations_cache(&mut self, strategy: AbbreviationsCacheStrategy) {
183 self.abbreviations_cache
184 .populate(strategy, &self.debug_abbrev, self.debug_info.units());
185 }
186
187 /// Iterate the unit headers in the `.debug_info` section.
188 ///
189 /// Can be [used with
190 /// `FallibleIterator`](./index.html#using-with-fallibleiterator).
191 #[inline]
192 pub fn units(&self) -> DebugInfoUnitHeadersIter<R> {
193 self.debug_info.units()
194 }
195
196 /// Construct a new `Unit` from the given unit header.
197 #[inline]
198 pub fn unit(&self, header: UnitHeader<R>) -> Result<Unit<R>> {
199 Unit::new(self, header)
200 }
201
202 /// Iterate the type-unit headers in the `.debug_types` section.
203 ///
204 /// Can be [used with
205 /// `FallibleIterator`](./index.html#using-with-fallibleiterator).
206 #[inline]
207 pub fn type_units(&self) -> DebugTypesUnitHeadersIter<R> {
208 self.debug_types.units()
209 }
210
211 /// Parse the abbreviations for a compilation unit.
212 #[inline]
213 pub fn abbreviations(&self, unit: &UnitHeader<R>) -> Result<Arc<Abbreviations>> {
214 self.abbreviations_cache
215 .get(&self.debug_abbrev, unit.debug_abbrev_offset())
216 }
217
218 /// Return the string offset at the given index.
219 #[inline]
220 pub fn string_offset(
221 &self,
222 unit: &Unit<R>,
223 index: DebugStrOffsetsIndex<R::Offset>,
224 ) -> Result<DebugStrOffset<R::Offset>> {
225 self.debug_str_offsets
226 .get_str_offset(unit.header.format(), unit.str_offsets_base, index)
227 }
228
229 /// Return the string at the given offset in `.debug_str`.
230 #[inline]
231 pub fn string(&self, offset: DebugStrOffset<R::Offset>) -> Result<R> {
232 self.debug_str.get_str(offset)
233 }
234
235 /// Return the string at the given offset in `.debug_line_str`.
236 #[inline]
237 pub fn line_string(&self, offset: DebugLineStrOffset<R::Offset>) -> Result<R> {
238 self.debug_line_str.get_str(offset)
239 }
240
241 /// Return an attribute value as a string slice.
242 ///
243 /// If the attribute value is one of:
244 ///
245 /// - an inline `DW_FORM_string` string
246 /// - a `DW_FORM_strp` reference to an offset into the `.debug_str` section
247 /// - a `DW_FORM_strp_sup` reference to an offset into a supplementary
248 /// object file
249 /// - a `DW_FORM_line_strp` reference to an offset into the `.debug_line_str`
250 /// section
251 /// - a `DW_FORM_strx` index into the `.debug_str_offsets` entries for the unit
252 ///
253 /// then return the attribute's string value. Returns an error if the attribute
254 /// value does not have a string form, or if a string form has an invalid value.
255 pub fn attr_string(&self, unit: &Unit<R>, attr: AttributeValue<R>) -> Result<R> {
256 match attr {
257 AttributeValue::String(string) => Ok(string),
258 AttributeValue::DebugStrRef(offset) => self.debug_str.get_str(offset),
259 AttributeValue::DebugStrRefSup(offset) => {
260 if let Some(sup) = self.sup() {
261 sup.debug_str.get_str(offset)
262 } else {
263 Err(Error::ExpectedStringAttributeValue)
264 }
265 }
266 AttributeValue::DebugLineStrRef(offset) => self.debug_line_str.get_str(offset),
267 AttributeValue::DebugStrOffsetsIndex(index) => {
268 let offset = self.debug_str_offsets.get_str_offset(
269 unit.header.format(),
270 unit.str_offsets_base,
271 index,
272 )?;
273 self.debug_str.get_str(offset)
274 }
275 _ => Err(Error::ExpectedStringAttributeValue),
276 }
277 }
278
279 /// Return the address at the given index.
280 pub fn address(&self, unit: &Unit<R>, index: DebugAddrIndex<R::Offset>) -> Result<u64> {
281 self.debug_addr
282 .get_address(unit.encoding().address_size, unit.addr_base, index)
283 }
284
285 /// Try to return an attribute value as an address.
286 ///
287 /// If the attribute value is one of:
288 ///
289 /// - a `DW_FORM_addr`
290 /// - a `DW_FORM_addrx` index into the `.debug_addr` entries for the unit
291 ///
292 /// then return the address.
293 /// Returns `None` for other forms.
294 pub fn attr_address(&self, unit: &Unit<R>, attr: AttributeValue<R>) -> Result<Option<u64>> {
295 match attr {
296 AttributeValue::Addr(addr) => Ok(Some(addr)),
297 AttributeValue::DebugAddrIndex(index) => self.address(unit, index).map(Some),
298 _ => Ok(None),
299 }
300 }
301
302 /// Return the range list offset for the given raw offset.
303 ///
304 /// This handles adding `DW_AT_GNU_ranges_base` if required.
305 pub fn ranges_offset_from_raw(
306 &self,
307 unit: &Unit<R>,
308 offset: RawRangeListsOffset<R::Offset>,
309 ) -> RangeListsOffset<R::Offset> {
310 if self.file_type == DwarfFileType::Dwo && unit.header.version() < 5 {
311 RangeListsOffset(offset.0.wrapping_add(unit.rnglists_base.0))
312 } else {
313 RangeListsOffset(offset.0)
314 }
315 }
316
317 /// Return the range list offset at the given index.
318 pub fn ranges_offset(
319 &self,
320 unit: &Unit<R>,
321 index: DebugRngListsIndex<R::Offset>,
322 ) -> Result<RangeListsOffset<R::Offset>> {
323 self.ranges
324 .get_offset(unit.encoding(), unit.rnglists_base, index)
325 }
326
327 /// Iterate over the `RangeListEntry`s starting at the given offset.
328 pub fn ranges(
329 &self,
330 unit: &Unit<R>,
331 offset: RangeListsOffset<R::Offset>,
332 ) -> Result<RngListIter<R>> {
333 self.ranges.ranges(
334 offset,
335 unit.encoding(),
336 unit.low_pc,
337 &self.debug_addr,
338 unit.addr_base,
339 )
340 }
341
342 /// Iterate over the `RawRngListEntry`ies starting at the given offset.
343 pub fn raw_ranges(
344 &self,
345 unit: &Unit<R>,
346 offset: RangeListsOffset<R::Offset>,
347 ) -> Result<RawRngListIter<R>> {
348 self.ranges.raw_ranges(offset, unit.encoding())
349 }
350
351 /// Try to return an attribute value as a range list offset.
352 ///
353 /// If the attribute value is one of:
354 ///
355 /// - a `DW_FORM_sec_offset` reference to the `.debug_ranges` or `.debug_rnglists` sections
356 /// - a `DW_FORM_rnglistx` index into the `.debug_rnglists` entries for the unit
357 ///
358 /// then return the range list offset of the range list.
359 /// Returns `None` for other forms.
360 pub fn attr_ranges_offset(
361 &self,
362 unit: &Unit<R>,
363 attr: AttributeValue<R>,
364 ) -> Result<Option<RangeListsOffset<R::Offset>>> {
365 match attr {
366 AttributeValue::RangeListsRef(offset) => {
367 Ok(Some(self.ranges_offset_from_raw(unit, offset)))
368 }
369 AttributeValue::DebugRngListsIndex(index) => self.ranges_offset(unit, index).map(Some),
370 _ => Ok(None),
371 }
372 }
373
374 /// Try to return an attribute value as a range list entry iterator.
375 ///
376 /// If the attribute value is one of:
377 ///
378 /// - a `DW_FORM_sec_offset` reference to the `.debug_ranges` or `.debug_rnglists` sections
379 /// - a `DW_FORM_rnglistx` index into the `.debug_rnglists` entries for the unit
380 ///
381 /// then return an iterator over the entries in the range list.
382 /// Returns `None` for other forms.
383 pub fn attr_ranges(
384 &self,
385 unit: &Unit<R>,
386 attr: AttributeValue<R>,
387 ) -> Result<Option<RngListIter<R>>> {
388 match self.attr_ranges_offset(unit, attr)? {
389 Some(offset) => Ok(Some(self.ranges(unit, offset)?)),
390 None => Ok(None),
391 }
392 }
393
394 /// Return an iterator for the address ranges of a `DebuggingInformationEntry`.
395 ///
396 /// This uses `DW_AT_low_pc`, `DW_AT_high_pc` and `DW_AT_ranges`.
397 pub fn die_ranges(
398 &self,
399 unit: &Unit<R>,
400 entry: &DebuggingInformationEntry<R>,
401 ) -> Result<RangeIter<R>> {
402 let mut low_pc = None;
403 let mut high_pc = None;
404 let mut size = None;
405 let mut attrs = entry.attrs();
406 while let Some(attr) = attrs.next()? {
407 match attr.name() {
408 constants::DW_AT_low_pc => {
409 low_pc = Some(
410 self.attr_address(unit, attr.value())?
411 .ok_or(Error::UnsupportedAttributeForm)?,
412 );
413 }
414 constants::DW_AT_high_pc => match attr.value() {
415 AttributeValue::Udata(val) => size = Some(val),
416 attr => {
417 high_pc = Some(
418 self.attr_address(unit, attr)?
419 .ok_or(Error::UnsupportedAttributeForm)?,
420 );
421 }
422 },
423 constants::DW_AT_ranges => {
424 if let Some(list) = self.attr_ranges(unit, attr.value())? {
425 return Ok(RangeIter(RangeIterInner::List(list)));
426 }
427 }
428 _ => {}
429 }
430 }
431 let range = low_pc.and_then(|begin| {
432 let end = size.map(|size| begin + size).or(high_pc);
433 // TODO: perhaps return an error if `end` is `None`
434 end.map(|end| Range { begin, end })
435 });
436 Ok(RangeIter(RangeIterInner::Single(range)))
437 }
438
439 /// Return an iterator for the address ranges of a `Unit`.
440 ///
441 /// This uses `DW_AT_low_pc`, `DW_AT_high_pc` and `DW_AT_ranges` of the
442 /// root `DebuggingInformationEntry`.
443 pub fn unit_ranges(&self, unit: &Unit<R>) -> Result<RangeIter<R>> {
444 let mut cursor = unit.header.entries(&unit.abbreviations);
445 cursor.next_dfs()?;
446 let root = cursor.current().ok_or(Error::MissingUnitDie)?;
447 self.die_ranges(unit, root)
448 }
449
450 /// Return the location list offset at the given index.
451 pub fn locations_offset(
452 &self,
453 unit: &Unit<R>,
454 index: DebugLocListsIndex<R::Offset>,
455 ) -> Result<LocationListsOffset<R::Offset>> {
456 self.locations
457 .get_offset(unit.encoding(), unit.loclists_base, index)
458 }
459
460 /// Iterate over the `LocationListEntry`s starting at the given offset.
461 pub fn locations(
462 &self,
463 unit: &Unit<R>,
464 offset: LocationListsOffset<R::Offset>,
465 ) -> Result<LocListIter<R>> {
466 match self.file_type {
467 DwarfFileType::Main => self.locations.locations(
468 offset,
469 unit.encoding(),
470 unit.low_pc,
471 &self.debug_addr,
472 unit.addr_base,
473 ),
474 DwarfFileType::Dwo => self.locations.locations_dwo(
475 offset,
476 unit.encoding(),
477 unit.low_pc,
478 &self.debug_addr,
479 unit.addr_base,
480 ),
481 }
482 }
483
484 /// Iterate over the raw `LocationListEntry`s starting at the given offset.
485 pub fn raw_locations(
486 &self,
487 unit: &Unit<R>,
488 offset: LocationListsOffset<R::Offset>,
489 ) -> Result<RawLocListIter<R>> {
490 match self.file_type {
491 DwarfFileType::Main => self.locations.raw_locations(offset, unit.encoding()),
492 DwarfFileType::Dwo => self.locations.raw_locations_dwo(offset, unit.encoding()),
493 }
494 }
495
496 /// Try to return an attribute value as a location list offset.
497 ///
498 /// If the attribute value is one of:
499 ///
500 /// - a `DW_FORM_sec_offset` reference to the `.debug_loc` or `.debug_loclists` sections
501 /// - a `DW_FORM_loclistx` index into the `.debug_loclists` entries for the unit
502 ///
503 /// then return the location list offset of the location list.
504 /// Returns `None` for other forms.
505 pub fn attr_locations_offset(
506 &self,
507 unit: &Unit<R>,
508 attr: AttributeValue<R>,
509 ) -> Result<Option<LocationListsOffset<R::Offset>>> {
510 match attr {
511 AttributeValue::LocationListsRef(offset) => Ok(Some(offset)),
512 AttributeValue::DebugLocListsIndex(index) => {
513 self.locations_offset(unit, index).map(Some)
514 }
515 _ => Ok(None),
516 }
517 }
518
519 /// Try to return an attribute value as a location list entry iterator.
520 ///
521 /// If the attribute value is one of:
522 ///
523 /// - a `DW_FORM_sec_offset` reference to the `.debug_loc` or `.debug_loclists` sections
524 /// - a `DW_FORM_loclistx` index into the `.debug_loclists` entries for the unit
525 ///
526 /// then return an iterator over the entries in the location list.
527 /// Returns `None` for other forms.
528 pub fn attr_locations(
529 &self,
530 unit: &Unit<R>,
531 attr: AttributeValue<R>,
532 ) -> Result<Option<LocListIter<R>>> {
533 match self.attr_locations_offset(unit, attr)? {
534 Some(offset) => Ok(Some(self.locations(unit, offset)?)),
535 None => Ok(None),
536 }
537 }
538
539 /// Call `Reader::lookup_offset_id` for each section, and return the first match.
540 ///
541 /// The first element of the tuple is `true` for supplementary sections.
542 pub fn lookup_offset_id(&self, id: ReaderOffsetId) -> Option<(bool, SectionId, R::Offset)> {
543 None.or_else(|| self.debug_abbrev.lookup_offset_id(id))
544 .or_else(|| self.debug_addr.lookup_offset_id(id))
545 .or_else(|| self.debug_aranges.lookup_offset_id(id))
546 .or_else(|| self.debug_info.lookup_offset_id(id))
547 .or_else(|| self.debug_line.lookup_offset_id(id))
548 .or_else(|| self.debug_line_str.lookup_offset_id(id))
549 .or_else(|| self.debug_str.lookup_offset_id(id))
550 .or_else(|| self.debug_str_offsets.lookup_offset_id(id))
551 .or_else(|| self.debug_types.lookup_offset_id(id))
552 .or_else(|| self.locations.lookup_offset_id(id))
553 .or_else(|| self.ranges.lookup_offset_id(id))
554 .map(|(id, offset)| (false, id, offset))
555 .or_else(|| {
556 self.sup()
557 .and_then(|sup| sup.lookup_offset_id(id))
558 .map(|(_, id, offset)| (true, id, offset))
559 })
560 }
561
562 /// Returns a string representation of the given error.
563 ///
564 /// This uses information from the DWARF sections to provide more information in some cases.
565 pub fn format_error(&self, err: Error) -> String {
566 #[allow(clippy::single_match)]
567 match err {
568 Error::UnexpectedEof(id) => match self.lookup_offset_id(id) {
569 Some((sup, section, offset)) => {
570 return format!(
571 "{} at {}{}+0x{:x}",
572 err,
573 section.name(),
574 if sup { "(sup)" } else { "" },
575 offset.into_u64(),
576 );
577 }
578 None => {}
579 },
580 _ => {}
581 }
582 err.description().into()
583 }
584}
585
586impl<R: Clone> Dwarf<R> {
587 /// Assuming `self` was loaded from a .dwo, take the appropriate
588 /// sections from `parent` (which contains the skeleton unit for this
589 /// dwo) such as `.debug_addr` and merge them into this `Dwarf`.
590 pub fn make_dwo(&mut self, parent: &Dwarf<R>) {
591 self.file_type = DwarfFileType::Dwo;
592 // These sections are always taken from the parent file and not the dwo.
593 self.debug_addr = parent.debug_addr.clone();
594 // .debug_rnglists comes from the DWO, .debug_ranges comes from the
595 // parent file.
596 self.ranges
597 .set_debug_ranges(parent.ranges.debug_ranges().clone());
598 self.sup = parent.sup.clone();
599 }
600}
601
602/// The sections from a `.dwp` file.
603#[derive(Debug)]
604pub struct DwarfPackage<R: Reader> {
605 /// The compilation unit index in the `.debug_cu_index` section.
606 pub cu_index: UnitIndex<R>,
607
608 /// The type unit index in the `.debug_tu_index` section.
609 pub tu_index: UnitIndex<R>,
610
611 /// The `.debug_abbrev.dwo` section.
612 pub debug_abbrev: DebugAbbrev<R>,
613
614 /// The `.debug_info.dwo` section.
615 pub debug_info: DebugInfo<R>,
616
617 /// The `.debug_line.dwo` section.
618 pub debug_line: DebugLine<R>,
619
620 /// The `.debug_str.dwo` section.
621 pub debug_str: DebugStr<R>,
622
623 /// The `.debug_str_offsets.dwo` section.
624 pub debug_str_offsets: DebugStrOffsets<R>,
625
626 /// The `.debug_loc.dwo` section.
627 ///
628 /// Only present when using GNU split-dwarf extension to DWARF 4.
629 pub debug_loc: DebugLoc<R>,
630
631 /// The `.debug_loclists.dwo` section.
632 pub debug_loclists: DebugLocLists<R>,
633
634 /// The `.debug_rnglists.dwo` section.
635 pub debug_rnglists: DebugRngLists<R>,
636
637 /// The `.debug_types.dwo` section.
638 ///
639 /// Only present when using GNU split-dwarf extension to DWARF 4.
640 pub debug_types: DebugTypes<R>,
641
642 /// An empty section.
643 ///
644 /// Used when creating `Dwarf<R>`.
645 pub empty: R,
646}
647
648impl<R: Reader> DwarfPackage<R> {
649 /// Try to load the `.dwp` sections using the given loader function.
650 ///
651 /// `section` loads a DWARF section from the object file.
652 /// It should return an empty section if the section does not exist.
653 pub fn load<F, E>(mut section: F, empty: R) -> core::result::Result<Self, E>
654 where
655 F: FnMut(SectionId) -> core::result::Result<R, E>,
656 E: From<Error>,
657 {
658 Ok(DwarfPackage {
659 cu_index: DebugCuIndex::load(&mut section)?.index()?,
660 tu_index: DebugTuIndex::load(&mut section)?.index()?,
661 // Section types are inferred.
662 debug_abbrev: Section::load(&mut section)?,
663 debug_info: Section::load(&mut section)?,
664 debug_line: Section::load(&mut section)?,
665 debug_str: Section::load(&mut section)?,
666 debug_str_offsets: Section::load(&mut section)?,
667 debug_loc: Section::load(&mut section)?,
668 debug_loclists: Section::load(&mut section)?,
669 debug_rnglists: Section::load(&mut section)?,
670 debug_types: Section::load(&mut section)?,
671 empty,
672 })
673 }
674
675 /// Find the compilation unit with the given DWO identifier and return its section
676 /// contributions.
677 pub fn find_cu(&self, id: DwoId, parent: &Dwarf<R>) -> Result<Option<Dwarf<R>>> {
678 let row = match self.cu_index.find(id.0) {
679 Some(row) => row,
680 None => return Ok(None),
681 };
682 self.cu_sections(row, parent).map(Some)
683 }
684
685 /// Find the type unit with the given type signature and return its section
686 /// contributions.
687 pub fn find_tu(
688 &self,
689 signature: DebugTypeSignature,
690 parent: &Dwarf<R>,
691 ) -> Result<Option<Dwarf<R>>> {
692 let row = match self.tu_index.find(signature.0) {
693 Some(row) => row,
694 None => return Ok(None),
695 };
696 self.tu_sections(row, parent).map(Some)
697 }
698
699 /// Return the section contributions of the compilation unit at the given index.
700 ///
701 /// The index must be in the range `1..cu_index.unit_count`.
702 ///
703 /// This function should only be needed by low level parsers.
704 pub fn cu_sections(&self, index: u32, parent: &Dwarf<R>) -> Result<Dwarf<R>> {
705 self.sections(self.cu_index.sections(index)?, parent)
706 }
707
708 /// Return the section contributions of the compilation unit at the given index.
709 ///
710 /// The index must be in the range `1..tu_index.unit_count`.
711 ///
712 /// This function should only be needed by low level parsers.
713 pub fn tu_sections(&self, index: u32, parent: &Dwarf<R>) -> Result<Dwarf<R>> {
714 self.sections(self.tu_index.sections(index)?, parent)
715 }
716
717 /// Return the section contributions of a unit.
718 ///
719 /// This function should only be needed by low level parsers.
720 pub fn sections(
721 &self,
722 sections: UnitIndexSectionIterator<R>,
723 parent: &Dwarf<R>,
724 ) -> Result<Dwarf<R>> {
725 let mut abbrev_offset = 0;
726 let mut abbrev_size = 0;
727 let mut info_offset = 0;
728 let mut info_size = 0;
729 let mut line_offset = 0;
730 let mut line_size = 0;
731 let mut loc_offset = 0;
732 let mut loc_size = 0;
733 let mut loclists_offset = 0;
734 let mut loclists_size = 0;
735 let mut str_offsets_offset = 0;
736 let mut str_offsets_size = 0;
737 let mut rnglists_offset = 0;
738 let mut rnglists_size = 0;
739 let mut types_offset = 0;
740 let mut types_size = 0;
741 for section in sections {
742 match section.section {
743 SectionId::DebugAbbrev => {
744 abbrev_offset = section.offset;
745 abbrev_size = section.size;
746 }
747 SectionId::DebugInfo => {
748 info_offset = section.offset;
749 info_size = section.size;
750 }
751 SectionId::DebugLine => {
752 line_offset = section.offset;
753 line_size = section.size;
754 }
755 SectionId::DebugLoc => {
756 loc_offset = section.offset;
757 loc_size = section.size;
758 }
759 SectionId::DebugLocLists => {
760 loclists_offset = section.offset;
761 loclists_size = section.size;
762 }
763 SectionId::DebugStrOffsets => {
764 str_offsets_offset = section.offset;
765 str_offsets_size = section.size;
766 }
767 SectionId::DebugRngLists => {
768 rnglists_offset = section.offset;
769 rnglists_size = section.size;
770 }
771 SectionId::DebugTypes => {
772 types_offset = section.offset;
773 types_size = section.size;
774 }
775 SectionId::DebugMacro | SectionId::DebugMacinfo => {
776 // These are valid but we can't parse these yet.
777 }
778 _ => return Err(Error::UnknownIndexSection),
779 }
780 }
781
782 let debug_abbrev = self.debug_abbrev.dwp_range(abbrev_offset, abbrev_size)?;
783 let debug_info = self.debug_info.dwp_range(info_offset, info_size)?;
784 let debug_line = self.debug_line.dwp_range(line_offset, line_size)?;
785 let debug_loc = self.debug_loc.dwp_range(loc_offset, loc_size)?;
786 let debug_loclists = self
787 .debug_loclists
788 .dwp_range(loclists_offset, loclists_size)?;
789 let debug_str_offsets = self
790 .debug_str_offsets
791 .dwp_range(str_offsets_offset, str_offsets_size)?;
792 let debug_rnglists = self
793 .debug_rnglists
794 .dwp_range(rnglists_offset, rnglists_size)?;
795 let debug_types = self.debug_types.dwp_range(types_offset, types_size)?;
796
797 let debug_str = self.debug_str.clone();
798
799 let debug_addr = parent.debug_addr.clone();
800 let debug_ranges = parent.ranges.debug_ranges().clone();
801
802 let debug_aranges = self.empty.clone().into();
803 let debug_line_str = self.empty.clone().into();
804
805 Ok(Dwarf {
806 debug_abbrev,
807 debug_addr,
808 debug_aranges,
809 debug_info,
810 debug_line,
811 debug_line_str,
812 debug_str,
813 debug_str_offsets,
814 debug_types,
815 locations: LocationLists::new(debug_loc, debug_loclists),
816 ranges: RangeLists::new(debug_ranges, debug_rnglists),
817 file_type: DwarfFileType::Dwo,
818 sup: parent.sup.clone(),
819 abbreviations_cache: AbbreviationsCache::new(),
820 })
821 }
822}
823
824/// All of the commonly used information for a unit in the `.debug_info` or `.debug_types`
825/// sections.
826#[derive(Debug)]
827pub struct Unit<R, Offset = <R as Reader>::Offset>
828where
829 R: Reader<Offset = Offset>,
830 Offset: ReaderOffset,
831{
832 /// The header of the unit.
833 pub header: UnitHeader<R, Offset>,
834
835 /// The parsed abbreviations for the unit.
836 pub abbreviations: Arc<Abbreviations>,
837
838 /// The `DW_AT_name` attribute of the unit.
839 pub name: Option<R>,
840
841 /// The `DW_AT_comp_dir` attribute of the unit.
842 pub comp_dir: Option<R>,
843
844 /// The `DW_AT_low_pc` attribute of the unit. Defaults to 0.
845 pub low_pc: u64,
846
847 /// The `DW_AT_str_offsets_base` attribute of the unit. Defaults to 0.
848 pub str_offsets_base: DebugStrOffsetsBase<Offset>,
849
850 /// The `DW_AT_addr_base` attribute of the unit. Defaults to 0.
851 pub addr_base: DebugAddrBase<Offset>,
852
853 /// The `DW_AT_loclists_base` attribute of the unit. Defaults to 0.
854 pub loclists_base: DebugLocListsBase<Offset>,
855
856 /// The `DW_AT_rnglists_base` attribute of the unit. Defaults to 0.
857 pub rnglists_base: DebugRngListsBase<Offset>,
858
859 /// The line number program of the unit.
860 pub line_program: Option<IncompleteLineProgram<R, Offset>>,
861
862 /// The DWO ID of a skeleton unit or split compilation unit.
863 pub dwo_id: Option<DwoId>,
864}
865
866impl<R: Reader> Unit<R> {
867 /// Construct a new `Unit` from the given unit header.
868 #[inline]
869 pub fn new(dwarf: &Dwarf<R>, header: UnitHeader<R>) -> Result<Self> {
870 let abbreviations = dwarf.abbreviations(&header)?;
871 Self::new_with_abbreviations(dwarf, header, abbreviations)
872 }
873
874 /// Construct a new `Unit` from the given unit header and abbreviations.
875 ///
876 /// The abbreviations for this call can be obtained using `dwarf.abbreviations(&header)`.
877 /// The caller may implement caching to reuse the `Abbreviations` across units with the
878 /// same `header.debug_abbrev_offset()` value.
879 #[inline]
880 pub fn new_with_abbreviations(
881 dwarf: &Dwarf<R>,
882 header: UnitHeader<R>,
883 abbreviations: Arc<Abbreviations>,
884 ) -> Result<Self> {
885 let mut unit = Unit {
886 abbreviations,
887 name: None,
888 comp_dir: None,
889 low_pc: 0,
890 str_offsets_base: DebugStrOffsetsBase::default_for_encoding_and_file(
891 header.encoding(),
892 dwarf.file_type,
893 ),
894 // NB: Because the .debug_addr section never lives in a .dwo, we can assume its base is always 0 or provided.
895 addr_base: DebugAddrBase(R::Offset::from_u8(0)),
896 loclists_base: DebugLocListsBase::default_for_encoding_and_file(
897 header.encoding(),
898 dwarf.file_type,
899 ),
900 rnglists_base: DebugRngListsBase::default_for_encoding_and_file(
901 header.encoding(),
902 dwarf.file_type,
903 ),
904 line_program: None,
905 dwo_id: match header.type_() {
906 UnitType::Skeleton(dwo_id) | UnitType::SplitCompilation(dwo_id) => Some(dwo_id),
907 _ => None,
908 },
909 header,
910 };
911 let mut name = None;
912 let mut comp_dir = None;
913 let mut line_program_offset = None;
914 let mut low_pc_attr = None;
915
916 {
917 let mut cursor = unit.header.entries(&unit.abbreviations);
918 cursor.next_dfs()?;
919 let root = cursor.current().ok_or(Error::MissingUnitDie)?;
920 let mut attrs = root.attrs();
921 while let Some(attr) = attrs.next()? {
922 match attr.name() {
923 constants::DW_AT_name => {
924 name = Some(attr.value());
925 }
926 constants::DW_AT_comp_dir => {
927 comp_dir = Some(attr.value());
928 }
929 constants::DW_AT_low_pc => {
930 low_pc_attr = Some(attr.value());
931 }
932 constants::DW_AT_stmt_list => {
933 if let AttributeValue::DebugLineRef(offset) = attr.value() {
934 line_program_offset = Some(offset);
935 }
936 }
937 constants::DW_AT_str_offsets_base => {
938 if let AttributeValue::DebugStrOffsetsBase(base) = attr.value() {
939 unit.str_offsets_base = base;
940 }
941 }
942 constants::DW_AT_addr_base | constants::DW_AT_GNU_addr_base => {
943 if let AttributeValue::DebugAddrBase(base) = attr.value() {
944 unit.addr_base = base;
945 }
946 }
947 constants::DW_AT_loclists_base => {
948 if let AttributeValue::DebugLocListsBase(base) = attr.value() {
949 unit.loclists_base = base;
950 }
951 }
952 constants::DW_AT_rnglists_base | constants::DW_AT_GNU_ranges_base => {
953 if let AttributeValue::DebugRngListsBase(base) = attr.value() {
954 unit.rnglists_base = base;
955 }
956 }
957 constants::DW_AT_GNU_dwo_id => {
958 if unit.dwo_id.is_none() {
959 if let AttributeValue::DwoId(dwo_id) = attr.value() {
960 unit.dwo_id = Some(dwo_id);
961 }
962 }
963 }
964 _ => {}
965 }
966 }
967 }
968
969 unit.name = match name {
970 Some(val) => dwarf.attr_string(&unit, val).ok(),
971 None => None,
972 };
973 unit.comp_dir = match comp_dir {
974 Some(val) => dwarf.attr_string(&unit, val).ok(),
975 None => None,
976 };
977 unit.line_program = match line_program_offset {
978 Some(offset) => Some(dwarf.debug_line.program(
979 offset,
980 unit.header.address_size(),
981 unit.comp_dir.clone(),
982 unit.name.clone(),
983 )?),
984 None => None,
985 };
986 if let Some(low_pc_attr) = low_pc_attr {
987 if let Some(addr) = dwarf.attr_address(&unit, low_pc_attr)? {
988 unit.low_pc = addr;
989 }
990 }
991 Ok(unit)
992 }
993
994 /// Return the encoding parameters for this unit.
995 #[inline]
996 pub fn encoding(&self) -> Encoding {
997 self.header.encoding()
998 }
999
1000 /// Read the `DebuggingInformationEntry` at the given offset.
1001 pub fn entry(&self, offset: UnitOffset<R::Offset>) -> Result<DebuggingInformationEntry<R>> {
1002 self.header.entry(&self.abbreviations, offset)
1003 }
1004
1005 /// Navigate this unit's `DebuggingInformationEntry`s.
1006 #[inline]
1007 pub fn entries(&self) -> EntriesCursor<R> {
1008 self.header.entries(&self.abbreviations)
1009 }
1010
1011 /// Navigate this unit's `DebuggingInformationEntry`s
1012 /// starting at the given offset.
1013 #[inline]
1014 pub fn entries_at_offset(&self, offset: UnitOffset<R::Offset>) -> Result<EntriesCursor<R>> {
1015 self.header.entries_at_offset(&self.abbreviations, offset)
1016 }
1017
1018 /// Navigate this unit's `DebuggingInformationEntry`s as a tree
1019 /// starting at the given offset.
1020 #[inline]
1021 pub fn entries_tree(&self, offset: Option<UnitOffset<R::Offset>>) -> Result<EntriesTree<R>> {
1022 self.header.entries_tree(&self.abbreviations, offset)
1023 }
1024
1025 /// Read the raw data that defines the Debugging Information Entries.
1026 #[inline]
1027 pub fn entries_raw(&self, offset: Option<UnitOffset<R::Offset>>) -> Result<EntriesRaw<R>> {
1028 self.header.entries_raw(&self.abbreviations, offset)
1029 }
1030
1031 /// Copy attributes that are subject to relocation from another unit. This is intended
1032 /// to be used to copy attributes from a skeleton compilation unit to the corresponding
1033 /// split compilation unit.
1034 pub fn copy_relocated_attributes(&mut self, other: &Unit<R>) {
1035 self.low_pc = other.low_pc;
1036 self.addr_base = other.addr_base;
1037 if self.header.version() < 5 {
1038 self.rnglists_base = other.rnglists_base;
1039 }
1040 }
1041
1042 /// Find the dwo name (if any) for this unit, automatically handling the differences
1043 /// between the standardized DWARF 5 split DWARF format and the pre-DWARF 5 GNU
1044 /// extension.
1045 ///
1046 /// The returned value is relative to this unit's `comp_dir`.
1047 pub fn dwo_name(&self) -> Result<Option<AttributeValue<R>>> {
1048 let mut entries = self.entries();
1049 if let None = entries.next_entry()? {
1050 return Ok(None);
1051 }
1052
1053 let entry = entries.current().unwrap();
1054 if self.header.version() < 5 {
1055 entry.attr_value(constants::DW_AT_GNU_dwo_name)
1056 } else {
1057 entry.attr_value(constants::DW_AT_dwo_name)
1058 }
1059 }
1060}
1061
1062impl<T: ReaderOffset> UnitSectionOffset<T> {
1063 /// Convert an offset to be relative to the start of the given unit,
1064 /// instead of relative to the start of the section.
1065 /// Returns `None` if the offset is not within the unit entries.
1066 pub fn to_unit_offset<R>(&self, unit: &Unit<R>) -> Option<UnitOffset<T>>
1067 where
1068 R: Reader<Offset = T>,
1069 {
1070 let (offset, unit_offset) = match (self, unit.header.offset()) {
1071 (
1072 UnitSectionOffset::DebugInfoOffset(offset),
1073 UnitSectionOffset::DebugInfoOffset(unit_offset),
1074 ) => (offset.0, unit_offset.0),
1075 (
1076 UnitSectionOffset::DebugTypesOffset(offset),
1077 UnitSectionOffset::DebugTypesOffset(unit_offset),
1078 ) => (offset.0, unit_offset.0),
1079 _ => return None,
1080 };
1081 let offset = match offset.checked_sub(unit_offset) {
1082 Some(offset) => UnitOffset(offset),
1083 None => return None,
1084 };
1085 if !unit.header.is_valid_offset(offset) {
1086 return None;
1087 }
1088 Some(offset)
1089 }
1090}
1091
1092impl<T: ReaderOffset> UnitOffset<T> {
1093 /// Convert an offset to be relative to the start of the .debug_info section,
1094 /// instead of relative to the start of the given compilation unit.
1095 ///
1096 /// Does not check that the offset is valid.
1097 pub fn to_unit_section_offset<R>(&self, unit: &Unit<R>) -> UnitSectionOffset<T>
1098 where
1099 R: Reader<Offset = T>,
1100 {
1101 match unit.header.offset() {
1102 UnitSectionOffset::DebugInfoOffset(unit_offset: DebugInfoOffset) => {
1103 DebugInfoOffset(unit_offset.0 + self.0).into()
1104 }
1105 UnitSectionOffset::DebugTypesOffset(unit_offset: DebugTypesOffset) => {
1106 DebugTypesOffset(unit_offset.0 + self.0).into()
1107 }
1108 }
1109 }
1110}
1111
1112/// An iterator for the address ranges of a `DebuggingInformationEntry`.
1113///
1114/// Returned by `Dwarf::die_ranges` and `Dwarf::unit_ranges`.
1115#[derive(Debug)]
1116pub struct RangeIter<R: Reader>(RangeIterInner<R>);
1117
1118#[derive(Debug)]
1119enum RangeIterInner<R: Reader> {
1120 Single(Option<Range>),
1121 List(RngListIter<R>),
1122}
1123
1124impl<R: Reader> Default for RangeIter<R> {
1125 fn default() -> Self {
1126 RangeIter(RangeIterInner::Single(None))
1127 }
1128}
1129
1130impl<R: Reader> RangeIter<R> {
1131 /// Advance the iterator to the next range.
1132 pub fn next(&mut self) -> Result<Option<Range>> {
1133 match self.0 {
1134 RangeIterInner::Single(ref mut range: &mut Option) => Ok(range.take()),
1135 RangeIterInner::List(ref mut list: &mut RngListIter) => list.next(),
1136 }
1137 }
1138}
1139
1140#[cfg(feature = "fallible-iterator")]
1141impl<R: Reader> fallible_iterator::FallibleIterator for RangeIter<R> {
1142 type Item = Range;
1143 type Error = Error;
1144
1145 #[inline]
1146 fn next(&mut self) -> ::core::result::Result<Option<Self::Item>, Self::Error> {
1147 RangeIter::next(self)
1148 }
1149}
1150
1151#[cfg(test)]
1152mod tests {
1153 use super::*;
1154 use crate::read::EndianSlice;
1155 use crate::{Endianity, LittleEndian};
1156
1157 /// Ensure that `Dwarf<R>` is covariant wrt R.
1158 #[test]
1159 fn test_dwarf_variance() {
1160 /// This only needs to compile.
1161 fn _f<'a: 'b, 'b, E: Endianity>(x: Dwarf<EndianSlice<'a, E>>) -> Dwarf<EndianSlice<'b, E>> {
1162 x
1163 }
1164 }
1165
1166 /// Ensure that `Unit<R>` is covariant wrt R.
1167 #[test]
1168 fn test_dwarf_unit_variance() {
1169 /// This only needs to compile.
1170 fn _f<'a: 'b, 'b, E: Endianity>(x: Unit<EndianSlice<'a, E>>) -> Unit<EndianSlice<'b, E>> {
1171 x
1172 }
1173 }
1174
1175 #[test]
1176 fn test_send() {
1177 fn assert_is_send<T: Send>() {}
1178 assert_is_send::<Dwarf<EndianSlice<LittleEndian>>>();
1179 assert_is_send::<Unit<EndianSlice<LittleEndian>>>();
1180 }
1181
1182 #[test]
1183 fn test_format_error() {
1184 let mut owned_dwarf = Dwarf::load(|_| -> Result<_> { Ok(vec![1, 2]) }).unwrap();
1185 owned_dwarf
1186 .load_sup(|_| -> Result<_> { Ok(vec![1, 2]) })
1187 .unwrap();
1188 let dwarf = owned_dwarf.borrow(|section| EndianSlice::new(&section, LittleEndian));
1189
1190 match dwarf.debug_str.get_str(DebugStrOffset(1)) {
1191 Ok(r) => panic!("Unexpected str {:?}", r),
1192 Err(e) => {
1193 assert_eq!(
1194 dwarf.format_error(e),
1195 "Hit the end of input before it was expected at .debug_str+0x1"
1196 );
1197 }
1198 }
1199 match dwarf.sup().unwrap().debug_str.get_str(DebugStrOffset(1)) {
1200 Ok(r) => panic!("Unexpected str {:?}", r),
1201 Err(e) => {
1202 assert_eq!(
1203 dwarf.format_error(e),
1204 "Hit the end of input before it was expected at .debug_str(sup)+0x1"
1205 );
1206 }
1207 }
1208 assert_eq!(dwarf.format_error(Error::Io), Error::Io.description());
1209 }
1210}
1211