dotscope 0.6.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
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

//! Implementation of `RowReadable` for `StateMachineMethodRaw` metadata table entries.
//!
//! This module provides binary deserialization support for the `StateMachineMethod` table (ID 0x36),
//! enabling reading of state machine method mapping information from Portable PDB files. The
//! StateMachineMethod table maps compiler-generated state machine methods (like MoveNext) back
//! to their original user-written async/await and iterator methods.
//!
//! ## Table Structure (Portable PDB)
//!
//! | Field | Type | Description |
//! |-------|------|-------------|
//! | `MoveNextMethod` | MethodDef table index | Compiler-generated state machine method |
//! | `KickoffMethod` | MethodDef table index | Original user-written method |
//!
//! ## Debugging Context
//!
//! This table is essential for providing proper debugging experiences with modern C# features:
//! - **Async/Await**: Maps async state machine MoveNext methods to original async methods
//! - **Iterator Methods**: Maps iterator state machine methods to yield-returning methods
//! - **Stepping Support**: Enables debuggers to step through user code rather than generated code
//! - **Breakpoint Mapping**: Allows breakpoints in user methods to work correctly
//!
//! ## State Machine Patterns
//!
//! The table handles several compiler-generated patterns:
//! - **Async Methods**: User async method → compiler-generated async state machine
//! - **Iterator Methods**: User yield method → compiler-generated iterator state machine  
//! - **Async Iterators**: User async iterator → compiler-generated async iterator state machine
//!
//! ## Thread Safety
//!
//! The `RowReadable` implementation is stateless and safe for concurrent use across
//! multiple threads during metadata loading operations.
//!
//! ## Related Modules
//!
//! - [`crate::metadata::tables::statemachinemethod::writer`] - Binary serialization support
//! - [`crate::metadata::tables::statemachinemethod`] - High-level StateMachineMethod interface
//! - [`crate::metadata::tables::statemachinemethod::raw`] - Raw structure definition

use crate::{
    metadata::{
        tables::{RowReadable, StateMachineMethodRaw, TableId, TableInfoRef},
        token::Token,
    },
    utils::read_le_at_dyn,
    Result,
};

impl RowReadable for StateMachineMethodRaw {
    const TABLE_ID: TableId = TableId::StateMachineMethod;

    fn row_read(data: &[u8], offset: &mut usize, rid: u32, sizes: &TableInfoRef) -> Result<Self> {
        Ok(StateMachineMethodRaw {
            rid,
            token: Token::new(0x3600_0000 + rid),
            offset: *offset,
            move_next_method: read_le_at_dyn(data, offset, sizes.is_large(TableId::MethodDef))?,
            kickoff_method: read_le_at_dyn(data, offset, sizes.is_large(TableId::MethodDef))?,
        })
    }
}

#[cfg(test)]
mod tests {
    use std::sync::Arc;

    use super::*;
    use crate::metadata::tables::{MetadataTable, TableId, TableInfo};

    #[test]
    fn crafted_short() {
        let data = vec![
            0x01, 0x00, // move_next_method (2 bytes, normal table) - 0x0001
            0x02, 0x00, // kickoff_method (2 bytes, normal table) - 0x0002
        ];

        let sizes = Arc::new(TableInfo::new_test(
            &[(TableId::StateMachineMethod, 1), (TableId::MethodDef, 1000)],
            false,
            false,
            false,
        ));
        let table = MetadataTable::<StateMachineMethodRaw>::new(&data, 1, sizes).unwrap();

        let eval = |row: StateMachineMethodRaw| {
            assert_eq!(row.rid, 1);
            assert_eq!(row.token.value(), 0x36000001);
            assert_eq!(row.move_next_method, 0x0001);
            assert_eq!(row.kickoff_method, 0x0002);
        };

        {
            for row in table.iter() {
                eval(row);
            }
        }

        {
            let row = table.get(1).unwrap();
            eval(row);
        }
    }

    #[test]
    fn crafted_long() {
        let data = vec![
            0x01, 0x01, 0x00, 0x00, // move_next_method (4 bytes, large table) - 0x00000101
            0x02, 0x02, 0x00, 0x00, // kickoff_method (4 bytes, large table) - 0x00000202
        ];

        let sizes = Arc::new(TableInfo::new_test(
            &[
                (TableId::StateMachineMethod, 1),
                (TableId::MethodDef, 100000),
            ],
            false,
            false,
            false,
        ));
        let table = MetadataTable::<StateMachineMethodRaw>::new(&data, 1, sizes).unwrap();

        let eval = |row: StateMachineMethodRaw| {
            assert_eq!(row.rid, 1);
            assert_eq!(row.token.value(), 0x36000001);
            assert_eq!(row.move_next_method, 0x00000101);
            assert_eq!(row.kickoff_method, 0x00000202);
        };

        {
            for row in table.iter() {
                eval(row);
            }
        }

        {
            let row = table.get(1).unwrap();
            eval(row);
        }
    }
}