This crate provides a macro to translate tokens into a string which mostly works in [core::arch::asm!] macro.
sh
cargo add asm_block
```rust use asmblock::asmblock;
macrorules! f { ($a: tt, $b: tt, $c: tt, $d: tt, $k: tt, $s: literal, $t: literal, $tmp: tt) => { asmblock! { mov $tmp, $c; add $a, $k; xor $tmp, $d; and $tmp, $b; xor $tmp, $d; lea $a, [$a + $tmp + $t]; rol $a, $s; add $a, $b; } }; }
asm!( f!(eax, ebx, ecx, edx, [ebp + 4], 7, 0xd76aa478, esi), f!({a}, {b}, {c}, {d}, {x0}, 7, 0xd76aa478, {t}), f!({a:e}, {b:e}, {c:e}, {d:e}, [{x} + 4], 7, 0xd76aa478, {t:e}),
a = out(reg) _,
b = out(reg) _,
c = out(reg) _,
d = out(reg) _,
x0 = out(reg) _,
x = out(reg) _,
t = out(reg) _,
); ```
asm_block follows very simple rules and mostly relies on the whitespace leniency
of the underlying assembler.
Transformation rules:
- Convert ; to \n.
- No space before :.
- No space after ..
- No space before and after @.
- Concatenate everything inside a pair of { and } without any space.
- Transcribe all the other tokens as-is (by stringify!), and add a space afterwards.
This should work for most assembly code. We have checked that space after $, #, !, %, :, = won't invalidate an assembly using x86_64 target and aarch64 target.
Consider the following code using x86_64 assembly:
```rust
unsafe fn f() -> u64 {
let mut x = 20;
asm!(
".macro mad x, y",
" mul x, y",
" lea x, [x + y]",
".endm",
"mad {x}, 5",
x = inout(reg) x
);
x
}
If we want to reuse `mad!` in another function, we must copy the verbatim
of the macro and change its name. Otherwise we will encounter compilation
error due to name collision.
rust
unsafe fn f() -> u64 {
let mut x = 20;
asm!(
".macro mad x, y",
" mul x, y",
" lea x, [x + y]",
".endm",
"mad {x}, 5",
x = inout(reg) x
);
x
}
unsafe fn g() -> u64 { let mut x = 10; asm!( // Only compiles if we remove this macro definition // or rename it to another name ".macro mad x, y", " mul x, y", " lea x, [x + y]", ".endm", "mad {x}, 8",
x = inout(reg) x
);
x
}
The above code fails with
text
error: macro 'mad' is already defined
``
If we omit the definition ofmad!ing(), it will compile, but only
wheng()is emitted afterf(). It is unclear which function should house
the definition, so the only sane option is to house it in aglobal_asm!`
code. But again, it is hard to guarantee that the definition is emitted
before the actual use.
It is natural to resort to Rust macro in this case, but due to the fact that
asm! accepts a template string, substituting metavariables becomes
tedious.
```rust
macro_rules! mad {
($x: ident, $y: literal) => {
concat!(
"mul {", stringify!($x), "}, ", stringify!($y), "\n",
"lea {", stringify!($x), "}, [{", stringify!($x), "}+", stringify!($y), "]"
)
};
}
unsafe fn f() -> u64 { let mut x = 20; asm!( mad!(x, 5),
x = inout(reg) x
);
x
}
``
This approach has some multiple drawbacks:
- The definition is very noisy, making it hard to read and comprehend. It is
much worse if the definition becomes longer, and much much worse if
rustfmtattempts to format it.
- It is easy to forget,and\nwhen the definition becomes longer.
-mad!can only accept a named register as the first argument and a
literal as the second argument. We cannot callmad!(x, rbx)or
mad!([rax], rbp), which we would have been able to if we were using the
assembler macro. Trying to fix this by changingidentandliteralto
ttis also problematic, sincestringify!({x})becomes"{ x }"`, and
it is an invalid placeholder.
This crate tries to address this by providing a macro that makes it easier to compose assembly code.
```rust use asmblock::asmblock;
macrorules! mad { ($x: tt, $y: tt) => { asmblock! { mul $x, $y; lea $x, [$x + $y]; } }; }
unsafe fn f() -> u64 { let mut x = 20; asm!( mad!({x}, 5),
x = inout(reg) x
);
x
}
``
Now we are able to make calls likemad!({x}, rbx),mad!([rax], rbp), and
mad!({x:e}, [rsp - 4])`. And this looks much cleaner.
' are
not supported.asm_block!] mostly consumes tokens one by one, so it is possible to run
out of recursion limit if the assembly code is long. User needs
#![recursion_limit = "<a_larger_value>"] when encountering the error.rustfmt will format mad!({x}, 5) into mad!({ x }, 5). While this
won't make any difference in the emitted assembly code, it is confusing to
read when the user is expecting a format placeholder. User can use
#[rustfmt::skip::macros(mad)] to prevent rustfmt from formatting the
interior of mad! calls.; as the comment starter, but we are using it as
instruction delimeter, so assembly comments may not work properly. Users
are strongly suggested to stick to Rust comments.tt cannot capture multiple tokens, so to make mad!(dword ptr [rax],
ebp) possible, calling convention of mad! needs to be changed. For
example
```rust
use asmblock::asmblock;
macrorules! mad {
([{ $($x: tt)+ }], $y: tt) => {
asmblock! {
mul $($x)+, $y;
lea $($x)+, [$($x)+ + $y];
}
};
($x: tt, $y: tt) => { mad!([{ $x }], $y) };
}
``
Butmad!must be called withmad!([{ dword ptr [rax] }], ebp)` instead.
Licensed under either of:
at your option.