3 For extremely low-level manipulations and performance reasons, one
4 might wish to control the CPU directly. Rust supports using inline
5 assembly to do this via the `asm!` macro. The syntax roughly matches
17 Any use of `asm` is feature gated (requires `#![feature(asm)]` on the
18 crate to allow) and of course requires an `unsafe` block.
20 > **Note**: the examples here are given in x86/x86-64 assembly, but
21 > all platforms are supported.
25 The `assembly template` is the only required parameter and must be a
26 literal string (i.e. `""`)
31 #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
39 #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
40 fn foo() { /* ... */ }
49 (The `feature(asm)` and `#[cfg]`s are omitted from now on.)
51 Output operands, input operands, clobbers and options are all optional
52 but you must add the right number of `:` if you skip them:
56 # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
57 # fn main() { unsafe {
66 Whitespace also doesn't matter:
70 # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
71 # fn main() { unsafe {
72 asm!("xor %eax, %eax" ::: "{eax}");
78 Input and output operands follow the same format: `:
79 "constraints1"(expr1), "constraints2"(expr2), ..."`. Output operand
80 expressions must be mutable lvalues, or not yet assigned:
84 # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
85 fn add(a: i32, b: i32) -> i32 {
95 # #[cfg(not(any(target_arch = "x86", target_arch = "x86_64")))]
96 # fn add(a: i32, b: i32) -> i32 { a + b }
99 assert_eq!(add(3, 14159), 14162)
103 If you would like to use real operands in this position, however,
104 you are required to put curly braces `{}` around the register that
105 you want, and you are required to put the specific size of the
106 operand. This is useful for very low level programming, where
107 which register you use is important:
111 # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
112 # unsafe fn read_byte_in(port: u16) -> u8 {
114 asm!("in %dx, %al" : "={al}"(result) : "{dx}"(port));
121 Some instructions modify registers which might otherwise have held
122 different values so we use the clobbers list to indicate to the
123 compiler not to assume any values loaded into those registers will
128 # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
129 # fn main() { unsafe {
130 // Put the value 0x200 in eax
131 asm!("mov $$0x200, %eax" : /* no outputs */ : /* no inputs */ : "{eax}");
135 Input and output registers need not be listed since that information
136 is already communicated by the given constraints. Otherwise, any other
137 registers used either implicitly or explicitly should be listed.
139 If the assembly changes the condition code register `cc` should be
140 specified as one of the clobbers. Similarly, if the assembly modifies
141 memory, `memory` should also be specified.
145 The last section, `options` is specific to Rust. The format is comma
146 separated literal strings (i.e. `:"foo", "bar", "baz"`). It's used to
147 specify some extra info about the inline assembly:
149 Current valid options are:
151 1. *volatile* - specifying this is analogous to
152 `__asm__ __volatile__ (...)` in gcc/clang.
153 2. *alignstack* - certain instructions expect the stack to be
154 aligned a certain way (i.e. SSE) and specifying this indicates to
155 the compiler to insert its usual stack alignment code
156 3. *intel* - use intel syntax instead of the default AT&T.
160 # #[cfg(any(target_arch = "x86", target_arch = "x86_64"))]
164 asm!("mov eax, 2" : "={eax}"(result) : : : "intel")
166 println!("eax is currently {}", result);