dotscope 0.7.0

A high-performance, cross-platform framework for analyzing and reverse engineering .NET PE executables
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

//! Block and loop semantic analysis for SSA functions.
//!
//! These methods delegate to the `SemanticAnalyzer` to classify blocks
//! by their role: initialization, condition, body, latch, exit, etc.

use std::collections::HashMap;

use crate::analysis::{
    cfg::{BlockSemantics, LoopSemantics, SemanticAnalyzer},
    ssa::SsaFunction,
    LoopInfo,
};

impl SsaFunction {
    /// Analyzes the semantic role of a specific block.
    ///
    /// Uses the `SemanticAnalyzer` to determine what a block does:
    /// initialization, condition testing, loop body work, variable updates, etc.
    ///
    /// # Arguments
    ///
    /// * `block_idx` - The block index to analyze
    ///
    /// # Returns
    ///
    /// Semantic information about the block including its role and characteristics.
    #[must_use]
    pub fn analyze_block_semantics(&self, block_idx: usize) -> BlockSemantics {
        let mut analyzer = SemanticAnalyzer::new(self);
        analyzer.analyze_block(block_idx).clone()
    }

    /// Analyzes semantic roles of multiple blocks.
    ///
    /// # Arguments
    ///
    /// * `blocks` - The block indices to analyze
    ///
    /// # Returns
    ///
    /// A map of block index to semantic information.
    #[must_use]
    pub fn analyze_blocks_semantics(&self, blocks: &[usize]) -> HashMap<usize, BlockSemantics> {
        let mut analyzer = SemanticAnalyzer::new(self);
        let mut results = HashMap::new();

        for &block in blocks {
            results.insert(block, analyzer.analyze_block(block).clone());
        }

        results
    }

    /// Analyzes the semantic structure of a structural loop.
    ///
    /// Given a `LoopInfo` from dominance-based loop detection, this method
    /// classifies each block within the loop by its semantic role:
    /// init, condition, body, latch, exit.
    ///
    /// # Arguments
    ///
    /// * `loop_info` - Structural loop information from `LoopForest`
    ///
    /// # Returns
    ///
    /// Semantic loop information with classified blocks and execution order.
    #[must_use]
    pub fn analyze_loop_semantics(&self, loop_info: &LoopInfo) -> LoopSemantics {
        let mut analyzer = SemanticAnalyzer::new(self);
        analyzer.analyze_loop(loop_info)
    }

    /// Recovers loop semantics from flattened dispatcher case blocks.
    ///
    /// This is the key method for control flow unflattening. Given the target
    /// blocks from a switch dispatcher, it analyzes each block's semantic role
    /// to reconstruct the original loop structure.
    ///
    /// # Arguments
    ///
    /// * `case_blocks` - Block indices that are case targets of the dispatcher
    /// * `dispatcher_block` - Optional index of the dispatcher block to exclude
    ///
    /// # Returns
    ///
    /// Semantic loop structure with blocks classified and ordered correctly.
    #[must_use]
    pub fn recover_loop_from_cases(
        &self,
        case_blocks: &[usize],
        dispatcher_block: Option<usize>,
    ) -> LoopSemantics {
        let mut analyzer = SemanticAnalyzer::new(self);

        // Mark dispatcher as known if provided
        if let Some(disp) = dispatcher_block {
            analyzer.mark_dispatcher(disp);
        }

        analyzer.recover_loop_from_cases(case_blocks)
    }

    /// Creates a semantic analyzer for this function.
    ///
    /// Use this when you need to perform multiple semantic analyses
    /// and want to benefit from caching.
    ///
    /// # Returns
    ///
    /// A new `SemanticAnalyzer` instance for this function.
    #[must_use]
    pub fn semantic_analyzer(&self) -> SemanticAnalyzer<'_> {
        SemanticAnalyzer::new(self)
    }
}