asm-rs 0.2.0

Pure Rust multi-architecture runtime assembly engine
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
153
154
155
156
157
158
159

//! Preprocessor example — demonstrates macros, loops, and conditional assembly.
//!
//! Run with: `cargo run --example preprocessor`

use asm_rs::{Arch, Assembler};

fn main() {
    println!("=== asm_rs preprocessor example ===\n");

    // --- Macro definitions ---
    println!("1. Macro-generated function prologue/epilogue:");
    let mut asm = Assembler::new(Arch::X86_64);
    asm.emit(
        r#"
.macro prologue frame_size=0
    push rbp
    mov rbp, rsp
    .if \frame_size
    sub rsp, \frame_size
    .endif
.endm

.macro epilogue frame_size=0
    .if \frame_size
    add rsp, \frame_size
    .endif
    pop rbp
    ret
.endm

func:
    prologue 0x20
    # ... function body ...
    xor eax, eax
    epilogue 0x20
"#,
    )
    .unwrap();
    let result = asm.finish().unwrap();
    println!("   Listing:");
    for line in result.listing().lines() {
        println!("   {}", line);
    }

    // --- .rept for NOP sleds ---
    println!("\n2. .rept for padding:");
    let mut asm = Assembler::new(Arch::X86_64);
    asm.emit(
        r#"
start:
    nop
.rept 5
    nop
.endr
    ret
"#,
    )
    .unwrap();
    let result = asm.finish().unwrap();
    print_hex("   ", result.bytes());
    println!("   ({} bytes)", result.len());

    // --- .irp for register push/pop ---
    println!("\n3. .irp for register save/restore:");
    let mut asm = Assembler::new(Arch::X86_64);
    asm.emit(
        r#"
.macro save_regs regs:vararg
.irp reg, \regs
    push \reg
.endr
.endm

.macro restore_regs regs:vararg
.irp reg, \regs
    pop \reg
.endr
.endm

save_regs rbx, r12, r13, r14, r15
    # ... callee-saved registers saved ...
    nop
restore_regs r15, r14, r13, r12, rbx
    ret
"#,
    )
    .unwrap();
    let result = asm.finish().unwrap();
    println!("   Listing:");
    for line in result.listing().lines() {
        println!("   {}", line);
    }

    // --- Conditional assembly ---
    println!("\n4. Conditional assembly with .ifdef:");
    let mut asm = Assembler::new(Arch::X86_64);
    asm.define_preprocessor_symbol("DEBUG", 1);
    asm.emit(
        r#"
.ifdef DEBUG
    int 3       # breakpoint in debug builds
.endif
    xor eax, eax
    ret
"#,
    )
    .unwrap();
    let result = asm.finish().unwrap();
    println!("   With DEBUG defined:");
    print_hex("   ", result.bytes());

    let mut asm = Assembler::new(Arch::X86_64);
    // No DEBUG symbol defined
    asm.emit(
        r#"
.ifdef DEBUG
    int 3
.endif
    xor eax, eax
    ret
"#,
    )
    .unwrap();
    let result = asm.finish().unwrap();
    println!("   Without DEBUG:");
    print_hex("   ", result.bytes());

    // --- Nested constructs ---
    println!("\n5. Nested .rept inside .irp:");
    let mut asm = Assembler::new(Arch::X86_64);
    asm.emit(
        r#"
.irp reg, rax, rbx
.rept 2
    push \reg
.endr
.endr
    ret
"#,
    )
    .unwrap();
    let result = asm.finish().unwrap();
    print_hex("   ", result.bytes());
    println!("   ({} bytes: 2x push rax, 2x push rbx, ret)", result.len());

    println!("\n=== Done! ===");
}

fn print_hex(prefix: &str, bytes: &[u8]) {
    print!("{}", prefix);
    for (i, b) in bytes.iter().enumerate() {
        if i > 0 && i % 16 == 0 {
            println!();
            print!("{}", prefix);
        }
        print!("{:02X} ", b);
    }
    println!();
}