blazesym 0.2.4

blazesym is a library for address symbolization and related tasks.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

use std::collections::BTreeMap;
use std::collections::HashMap;


/// A single pre-resolved relocation entry.
#[derive(Debug, Clone, Copy)]
struct RelocationEntry {
    /// The pre-resolved addend (for `SHT_RELA`: `sym.st_value + r_addend`,
    /// for `SHT_REL`: `sym.st_value`).
    addend: u64,
    /// Whether this is an implicit-addend (`SHT_REL`) relocation.
    implicit: bool,
}


/// A map from section offsets to pre-resolved relocation addends.
///
/// For a given DWARF section, this maps byte offsets within that section
/// to the relocation that should be applied when reading at that offset.
#[derive(Debug, Clone, Default)]
pub(crate) struct RelocationMap {
    entries: BTreeMap<u64, RelocationEntry>,
}

impl RelocationMap {
    pub(super) fn insert(&mut self, offset: u64, addend: u64, implicit: bool) {
        let _prev = self
            .entries
            .insert(offset, RelocationEntry { addend, implicit });
    }

    pub(crate) fn relocate(&self, offset: u64, value: u64) -> u64 {
        if let Some(entry) = self.entries.get(&offset) {
            if entry.implicit {
                value.wrapping_add(entry.addend)
            } else {
                entry.addend
            }
        } else {
            value
        }
    }
}


/// Holds per-section relocation maps for an ELF file.
///
/// For `ET_REL` files, this contains relocation maps keyed by the target
/// section index. For non-relocatable files, this is empty.
pub(crate) struct SectionRelocations {
    /// Relocation maps keyed by target section index.
    maps: HashMap<usize, RelocationMap>,
    /// A shared empty relocation map for sections without relocations.
    empty: RelocationMap,
}

impl SectionRelocations {
    /// Create an empty `SectionRelocations` (for non-relocatable files).
    pub(crate) fn empty() -> Self {
        Self {
            maps: HashMap::new(),
            empty: RelocationMap::default(),
        }
    }

    pub(super) fn new(maps: HashMap<usize, RelocationMap>) -> Self {
        Self {
            maps,
            empty: RelocationMap::default(),
        }
    }

    /// Get the relocation map for the section at `target_idx`.
    ///
    /// Returns the empty map if no relocations exist for that section.
    pub(crate) fn get(&self, target_idx: usize) -> &RelocationMap {
        self.maps.get(&target_idx).unwrap_or(&self.empty)
    }
}


#[cfg(test)]
mod tests {
    use super::*;


    /// Exercise the `Debug` representation of relocation types.
    #[test]
    fn debug_repr() {
        let map = RelocationMap::default();
        assert_ne!(format!("{map:?}"), "");

        let entry = RelocationEntry {
            addend: 42,
            implicit: false,
        };
        assert_ne!(format!("{entry:?}"), "");
    }

    /// Test explicit (RELA) relocation.
    #[test]
    fn relocate_explicit() {
        let mut map = RelocationMap::default();
        let () = map.insert(0x100, 0xABCD, false);

        assert_eq!(map.relocate(0x100, 999), 0xABCD);
        assert_eq!(map.relocate(0x200, 999), 999);
    }

    /// Test implicit (REL) relocation.
    #[test]
    fn relocate_implicit() {
        let mut map = RelocationMap::default();
        let () = map.insert(0x100, 0x10, true);

        assert_eq!(map.relocate(0x100, 0x20), 0x30);
        assert_eq!(map.relocate(0x200, 0x20), 0x20);
    }

    /// Test wrapping behavior of implicit relocation.
    #[test]
    fn relocate_implicit_wrapping() {
        let mut map = RelocationMap::default();
        let () = map.insert(0x0, 1, true);

        assert_eq!(map.relocate(0x0, u64::MAX), 0);
    }

    /// Check that `SectionRelocations::empty()` returns identity maps
    /// for any index.
    #[test]
    fn section_relocations_empty() {
        let relocs = SectionRelocations::empty();
        assert_eq!(relocs.get(0).relocate(0x0, 42), 42);
        assert_eq!(relocs.get(99).relocate(0x0, 42), 42);
    }

    /// Make sure that `SectionRelocations::new(maps)` returns populated
    /// map for known index and empty map for unknown.
    #[test]
    fn section_relocations_with_maps() {
        let mut map = RelocationMap::default();
        let () = map.insert(0x0, 0xFF, false);

        let mut maps = HashMap::new();
        let _prev = maps.insert(3, map);

        let relocs = SectionRelocations::new(maps);
        assert_eq!(relocs.get(3).relocate(0x0, 0), 0xFF);
        assert_eq!(relocs.get(7).relocate(0x0, 42), 42);
    }
}