nimrod 0.1.0

Parse and inspect Nim-compiled native binaries
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

//! Module init-function scanner.
//!
//! Every Nim module compiles to an `Init000` function (runtime init) and
//! optionally a `DatInit000` (data-segment init) and `HcrInit000`
//! (hot-code-reload init). The function name encodes the module's
//! build-host filesystem path via the `@m`/`@s` token scheme decoded by
//! [`crate::demangle::modpath`]. See RESEARCH.md §7.

use crate::{
    container::Container,
    demangle::modpath::{self, ModulePath},
};

/// Classification of an init function.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum InitKind {
    /// `*Init000` — runtime module initialisation.
    Init,
    /// `*DatInit000` — data-segment initialisation.
    DatInit,
    /// `*HcrInit000` — hot-code-reload initialisation.
    HcrInit,
}

/// A located module init function.
#[derive(Debug, Clone)]
pub struct InitFunction<'a> {
    /// Classification.
    pub kind: InitKind,
    /// The raw symbol name.
    pub symbol_name: &'a str,
    /// Virtual address.
    pub address: u64,
    /// Decoded module path (filesystem path recovered from the mangled
    /// symbol name).
    pub module_path: ModulePath,
}

/// The init-function suffixes, ordered longest-first so that `DatInit000`
/// matches before `Init000`.
const INIT_SUFFIXES: &[(&str, InitKind)] = &[
    ("HcrInit000", InitKind::HcrInit),
    ("DatInit000", InitKind::DatInit),
    ("Init000", InitKind::Init),
];

/// Scans the container's symbol table for Nim module init functions.
///
/// Skips `NimMainModule` (which is an entry shim, not a module init
/// function) and linker-generated suffixed variants (e.g. `.cold.1`).
pub fn scan<'a>(container: &'a Container<'a>) -> Vec<InitFunction<'a>> {
    let mut result = Vec::new();

    for sym in container.symbols() {
        let name = sym.name.as_ref();
        // Skip linker-generated suffixed variants.
        if name.contains(".cold.") || name.contains(".TM_") || name.contains(".part.") {
            continue;
        }

        for &(suffix, kind) in INIT_SUFFIXES {
            if let Some(module_part) = name.strip_suffix(suffix) {
                // Skip the main-module shim `NimMainModule` and prefixed
                // variants (`<prefix>NimMainModule`) — those are entry
                // shims, not module init functions.
                if module_part.is_empty() || module_part.ends_with("NimMain") {
                    continue;
                }

                // The module part includes the trailing `_` separator
                // between the mangled module name and the suffix. But for
                // Init000, the `_` is part of the mangled name's trailing
                // underscore (from mangle substitutions).
                let module_path = modpath::decode(module_part);

                result.push(InitFunction {
                    kind,
                    symbol_name: name,
                    address: sym.vm_addr,
                    module_path,
                });
                break;
            }
        }
    }

    result
}

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

    #[test]
    fn init_kind_eq() {
        assert_eq!(InitKind::Init, InitKind::Init);
        assert_ne!(InitKind::Init, InitKind::DatInit);
    }
}