Rust 内联汇编(Inline Assembly)完全指南:基于 Rust By Practice 的 asm! 宏实战与原理剖析
Rust 内联汇编(Inline Assembly)完全指南:基于 Rust By Practice 的 asm! 宏实战与原理剖析
导读
本文是 Rust By Practice 项目 Unsafe 章节 中「Inline assembly」一文的深度展开,系统讲解 Rust 通过 std::arch::asm! 宏嵌入手写汇编的全部核心能力:基本用法、输入输出操作数、显式寄存器、clobber 声明、ABI 调用约定、模板修饰符、内存操作数、标签与优化选项。读完本文,你将能够在性能敏感或需要访问底层硬件原语(如内核代码)的场景中,安全、正确地编写并优化自己的内联汇编代码,同时理解编译器如何为操作数分配寄存器、何时可以复用寄存器,以及如何避免标签冲突等常见陷阱。
为什么需要内联汇编
Rust 通过 asm! 宏支持内联汇编(inline assembly),它可以把开发者手写的汇编指令嵌入到编译器生成的汇编输出中。asm! 的使用场景并不常见,但确实存在必须依赖它的场合:
- 性能或时序要求无法通过其他方式满足:某些关键路径需要精确控制指令序列与寄存器使用,编译器自动生成的代码无法达到要求;
- 访问底层硬件原语:例如在内核代码中执行
cpuid、out、fldcw等特权或硬件相关指令; - 与特定指令集的隐式寄存器约定对接:如 x86 的
mul(乘法的 128 位结果固定写入rax:rdx)、out(操作数必须位于eax等)。
本仓库中该章节位于 en/src/unsafe/inline-asm.md,在书籍导航中归属于 Unsafe doing 小节(见 en/src/SUMMARY.md)。章节开头明确说明:示例统一使用 x86/x86-64 汇编,但其他架构同样受支持。
支持的架构
按照原文档,当前 asm! 支持以下架构:
- x86 和 x86-64
- ARM
- AArch64
- RISC-V
注意:所有
asm!调用必须放在unsafe块中。因为内联汇编可能插入任意指令并破坏各种不变量(如借用规则、内存一致性假设),unsafe是把这一责任显式交给开发者的机制。
基本用法:从一条 NOP 开始
最简单的内联汇编例子是插入一条空操作指令:
use std::arch::asm;
unsafe {
asm!("nop");
}
这段代码会在编译器生成的汇编中插入一条 nop(无操作)指令。要点如下:
- 要插入的指令写在
asm!宏的第一个参数中,以字符串字面量的形式给出; asm!允许传入多个模板字符串参数,每个参数会被当作独立的汇编代码行处理,等效于用换行符将它们拼接在一起。这极大方便了汇编代码的格式化与阅读(后面会有实例);- 在
no_std环境下同样可用,只需改用core::arch::asm(原文档的cpuid示例正是使用use core::arch::asm;)。
Rust By Practice 的英文版配置为 2021 edition(见 en/book.toml),因此本文所有示例均符合该 edition 下的稳定特性。
输入与输出操作数:让汇编真正操作数据
插入一条什么都不做的指令显然很无趣。下面让汇编真正作用于数据——把值 5 写入 u64 变量 x:
use std::arch::asm;
let x: u64;
unsafe {
asm!("mov {}, 5", out(reg) x);
}
assert_eq!(x, 5);
这段代码展示了两个核心概念:
- 模板字符串:指定指令的字符串字面量实际上是模板字符串,其插值规则与 Rust 的格式化字符串(format strings)相同——
{}会被实际的操作数替换。 - 操作数声明:模板中插入的参数与普通格式化参数不同,需要同时声明两件事:
- 方向:变量是汇编的输入(
in)还是输出(out)。上例中x是输出,用out声明; - 寄存器类型约束:汇编期望变量放在哪种寄存器中。上例用
reg表示「任意通用寄存器」,编译器会自行挑选一个合适的寄存器插入模板,并在内联汇编执行完毕后从该寄存器中读取值回填到变量。
- 方向:变量是汇编的输入(
同时使用输入与输出
再看一个同时使用输入和输出的例子——把 i 的值加上 5 后写入 o:
use std::arch::asm;
let i: u64 = 3;
let o: u64;
unsafe {
asm!(
"mov {0}, {1}",
"add {0}, 5",
out(reg) o,
in(reg) i,
);
}
assert_eq!(o, 8);
这个例子的执行流程是:先把 i 的值复制到输出寄存器,再对该寄存器加 5。它展示了三个要点:
- 多模板字符串:
"mov {0}, {1}"与"add {0}, 5"是两条独立的汇编行; in声明输入:与out对应,输入用in声明;- 带编号的操作数:
{0}、{1}与格式化字符串一致,支持编号或命名引用。对内联汇编尤为重要,因为同一操作数经常被多次使用。对于复杂的内联汇编,推荐使用编号/命名引用,它既能提升可读性,又允许在不改变参数顺序的前提下重排指令。
inout:既是输入又是输出
上面的例子可以进一步精简,省掉那条 mov 指令:
use std::arch::asm;
let mut x: u64 = 3;
unsafe {
asm!("add {0}, 5", inout(reg) x);
}
assert_eq!(x, 8);
inout 用于声明既是输入又是输出的操作数。它与分别声明 in 和 out 的本质区别在于:inout 保证输入和输出使用同一个寄存器——这正是 add 这类「读改写」指令所要求的语义。
inout 还可以让输入与输出使用不同的变量:
use std::arch::asm;
let x: u64 = 3;
let y: u64;
unsafe {
asm!("add {0}, 5", inout(reg) x => y);
}
assert_eq!(y, 8);
inout(reg) x => y 表示:从 x 读取输入,运算结果写入 y。尽管变量不同,二者仍共享同一个物理寄存器。
延迟输出操作数:lateout 与 inlateout
Rust 编译器对操作数的分配策略是保守的:它假设一个 out 可能在任意时刻被写入,因此不能与其他任何操作数共享位置。但为了获得最优性能,应尽可能少地占用寄存器,避免在 asm! 块周围频繁保存和恢复寄存器。为此 Rust 提供了 lateout 说明符,它适用于只在所有输入都被消费之后才写入的输出;inlateout 则是其输入/输出一体版本。
什么时候不能用 inlateout
看一个 inlateout 不能使用的例子:
use std::arch::asm;
let mut a: u64 = 4;
let b: u64 = 4;
let c: u64 = 4;
unsafe {
asm!(
"add {0}, {1}",
"add {0}, {2}",
inout(reg) a,
in(reg) b,
in(reg) c,
);
}
assert_eq!(a, 12);
此处编译器知道 b 和 c 的值相同,因此可以自由地给它们分配同一个寄存器。但 a 使用的是 inout 而非 inlateout,所以编译器必须为 a 单独分配一个寄存器。如果改用 inlateout,a 和 c 可能被分配到同一个寄存器——那么第一条 add 指令就会先覆盖掉 c 的值,导致第二条 add 计算出错误结果。
什么时候可以放心用 inlateout
下面的例子则可以使用 inlateout,因为输出只在所有输入寄存器被读取之后才被修改:
use std::arch::asm;
let mut a: u64 = 4;
let b: u64 = 4;
unsafe {
asm!("add {0}, {1}", inlateout(reg) a, in(reg) b);
}
assert_eq!(a, 8);
即使 a 和 b 被分配到同一个寄存器,这段汇编依然正确:add 指令在同一个时钟周期内同时读取两个操作数并写回,不存在「先覆盖后读取」的问题。这正是 inlateout 允许编译器复用寄存器的前提。
显式寄存器操作数:满足特定指令的寄存器要求
某些指令要求操作数必须位于特定寄存器中,此时需要使用更具体的约束说明符。reg 在几乎所有架构上都可用,而显式寄存器则高度依赖架构——例如 x86 上可以通过名字寻址 eax、ebx、ecx、edx、ebp、esi、edi 等通用寄存器。
下面用 out 指令把变量 cmd 的内容输出到端口 0x64:
use std::arch::asm;
let cmd = 0xd1;
unsafe {
asm!("out 0x64, eax", in("eax") cmd);
}
由于 out 指令只接受 eax(及其子寄存器)作为操作数,这里必须使用 eax 约束说明符。
注意:与其他操作数类型不同,显式寄存器操作数不能在模板字符串中使用
{}引用——必须直接把寄存器名写进汇编文本。此外,显式寄存器操作数必须放在操作数列表的末尾,位于所有其他操作数类型之后。
实战:用 x86 mul 指令实现 128 位乘法
mul 指令以 rax 作为隐式输入,并把 128 位乘法结果写入 rax:rdx(低 64 位在 rax,高 64 位在 rdx):
use std::arch::asm;
fn mul(a: u64, b: u64) -> u128 {
let lo: u64;
let hi: u64;
unsafe {
asm!(
// The x86 mul instruction takes rax as an implicit input and writes
// the 128-bit result of the multiplication to rax:rdx.
"mul {}",
in(reg) a,
inlateout("rax") b => lo,
lateout("rdx") hi
);
}
((hi as u128) << 64) + lo as u128
}
逐步拆解这个例子:
- 唯一显式列出的操作数是寄存器操作数
{}(由a填充); b通过inlateout("rax") b => lo被放进隐式要求的rax寄存器——注意这里rax既是输入(乘数)又是输出(结果低 64 位),所以用inlateout;hi通过lateout("rdx")接收结果的高 64 位(rdx只被写入,是纯输出);- 最后在 Rust 侧把
hi左移 64 位再与lo拼接,得到完整的u128结果。
这个例子同时展示了「显式寄存器操作数必须位于列表末尾」的规则:in(reg) a 在 inlateout("rax") 之前。
Clobbered 寄存器:向编译器如实交代「被破坏」的状态
很多情况下,内联汇编会修改一些并不需要作为输出的状态。这通常是因为:
- 汇编内部需要使用临时(scratch)寄存器;
- 指令本身会修改某些我们不需要进一步检查的状态。
这些状态被称为「clobbered(被破坏)」。必须把这个事实告知编译器,因为它可能需要在 asm! 块前后保存并恢复这些寄存器。
实战:用 cpuid 读取 CPU 厂商 ID
下面的例子用 cpuid 指令读取 CPU 厂商 ID:
use core::arch::asm;
fn main() {
// three entries of four bytes each
let mut name_buf = [0_u8; 12];
// String is stored as ascii in ebx, edx, ecx in order
// Because ebx is reserved, we get a scratch register and move from
// ebx into it in the asm. The asm needs to preserve the value of
// that register though, so it is pushed and popped around the main asm
// (in 64 bit mode for 64 bit processors, 32 bit processors would use ebx)
unsafe {
asm!(
"push rbx",
"cpuid",
"mov [{0}], ebx",
"mov [{0} + 4], edx",
"mov [{0} + 8], ecx",
"pop rbx",
// We use a pointer to an array for storing the values to simplify
// the Rust code at the cost of a couple more asm instructions
// This is more explicit with how the asm works however, as opposed
// to explicit register outputs such as `out("ecx") val`
// The *pointer itself* is only an input even though it's written behind
in(reg) name_buf.as_mut_ptr(),
// select cpuid 0, also specify eax as clobbered
inout("eax") 0 => _,
// cpuid clobbers these registers too
out("ecx") _,
out("edx") _,
);
}
let name = core::str::from_utf8(&name_buf).unwrap();
println!("CPU Manufacturer ID: {}", name);
}
cpuid 指令的行为:eax 写入「最大支持的 cpuid 参数」,ebx、edx、ecx 按顺序写入厂商 ID 的 ASCII 字节。
这个例子蕴含了多处关键知识:
- 丢弃输出用
_:即使eax从未被读取,也必须告诉编译器该寄存器已被修改(否则编译器可能认为eax在asm!前后保持不变,从而在后续代码中错误地复用其旧值)。做法是把它声明为输出,但用_代替变量名——_表示「输出值将被丢弃」。 - 规避 LLVM 保留寄存器
ebx:LLVM 假定自己完全掌控ebx,并强制要求在退出asm!块前将其恢复到原状,因此ebx不能作为输出使用。解决办法是:先push rbx保存现场,在asm!内部把ebx的值移入一个由编译器分配(out(reg))的临时寄存器,再从临时寄存器写入内存,最后pop rbx恢复现场。 - 32/64 位差异:
push/pop在 64 位目标上使用完整的rbx,确保整个寄存器被保存;在 32 位目标上则应使用ebx。 - 通过指针写内存:
name_buf.as_mut_ptr()是唯一的输入操作数(用in(reg)),汇编通过[{0}]、[{0} + 4]、[{0} + 8]把三个 4 字节的 ASCII 片段连续写入 12 字节的缓冲区。指针本身只是输入——即使它背后指向的内存被写入。
用通用寄存器类获取临时寄存器
同样的思路也适用于通用寄存器类(如 reg),用来在汇编内部获取一个临时(scratch)寄存器:
use std::arch::asm;
// Multiply x by 6 using shifts and adds
let mut x: u64 = 4;
unsafe {
asm!(
"mov {tmp}, {x}",
"shl {tmp}, 1",
"shl {x}, 2",
"add {x}, {tmp}",
x = inout(reg) x,
tmp = out(reg) _,
);
}
assert_eq!(x, 4 * 6);
这里用 x = inout(reg) x 的命名语法为操作数起名,模板中直接以 {x}、{tmp} 引用。tmp = out(reg) _ 让编译器分配一个仅用于 scratch 的寄存器,_ 表示其结果被丢弃。最终 x 等于 4 * 6 = 24:tmp 保存 x << 1(即 2x),x 变为 x << 2(即 4x),相加得 6x。
符号操作数与 ABI Clobbers:调用外部函数
默认情况下,asm! 假设任何未声明为输出的寄存器,其内容都会被汇编代码原样保留。clobber_abi 参数则告诉编译器:根据给定的调用约定(calling convention)ABI,自动插入必要的 clobber 操作数——凡是该 ABI 中不保证保留的寄存器,一律视为被 clobber。可以同时传入多个 clobber_abi,所有指定 ABI 的 clobber 集合都会被合并生效。
下面的例子在汇编中直接调用一个 extern "C" 函数:
use std::arch::asm;
extern "C" fn foo(arg: i32) -> i32 {
println!("arg = {}", arg);
arg * 2
}
fn call_foo(arg: i32) -> i32 {
unsafe {
let result;
asm!(
"call *{}",
// Function pointer to call
in(reg) foo,
// 1st argument in rdi
in("rdi") arg,
// Return value in rax
out("rax") result,
// Mark all registers which are not preserved by the "C" calling
// convention as clobbered.
clobber_abi("C"),
);
result
}
}
要点:
in(reg) foo把函数指针放入一个通用寄存器,模板中通过call *{}间接调用;- 按 SysV AMD64 / x86-64 的 C 调用约定,第一个整数参数放在
rdi(用in("rdi") arg),返回值放在rax(用out("rax") result); - 关键:由于被调用的
foo是普通 C 函数,它内部的println!会自由使用、破坏大量寄存器。如果没有clobber_abi("C"),编译器会假定这些寄存器在asm!后仍保持原值,从而产生致命错误。clobber_abi自动替我们声明了所有「非 callee-saved」的寄存器为 clobbered。
寄存器模板修饰符:按需选择寄存器的「视图」
某些架构的汇编语言对同一个寄存器有多个名字,每个名字通常是该寄存器某一子集的「视图」(例如 64 位寄存器的低 32 位)。默认情况下,编译器总是选择代表完整寄存器大小的名字(x86-64 上是 rax,x86 上是 eax)。
借助模板字符串修饰符,可以覆盖这个默认行为——用法与格式化字符串一致:
use std::arch::asm;
let mut x: u16 = 0xab;
unsafe {
asm!("mov {0:h}, {0:l}", inout(reg_abcd) x);
}
assert_eq!(x, 0xabab);
这个例子的执行细节:
reg_abcd寄存器类把寄存器分配器限定在 x86 的 4 个传统寄存器(ax、bx、cx、dx)内,这 4 个寄存器的前两个字节可以被独立寻址;- 假设分配器把
x放在ax中:修饰符h输出该寄存器的高字节名(ah),修饰符l输出低字节名(al),于是汇编被展开为mov ah, al——把值的低字节复制到高字节; - 结果
0xab变为0xabab。
易错点:如果你对较小的数据类型(如 u16)使用操作数却忘记使用模板修饰符,编译器会发出警告并提示应该使用哪个修饰符——这是开发时发现此类问题的第一道防线。
内存地址操作数:手动构造寻址语法
部分汇编指令要求操作数通过内存地址/内存位置传递,此时必须手动使用目标架构规定的内存地址语法。例如 x86/x86-64 使用 Intel 汇编语法时,需要用 [] 把输入/输出包起来,表示它们是内存操作数:
use std::arch::asm;
fn load_fpu_control_word(control: u16) {
unsafe {
asm!("fldcw [{}]", in(reg) &control, options(nostack));
}
}
这里把 control 的地址(&control)作为输入放入寄存器,模板中的 [{}] 将该寄存器作为内存地址解引用,执行 fldcw(加载 FPU 控制字)指令。options(nostack) 声明这段汇编不会向栈上压入任何数据,其含义将在「Options」一节详述。
标签:只用数字局部标签,警惕复用与内联
标签复用会导致汇编器或链接器报错,也可能引发其他诡异行为。标签复用可能以多种方式发生:
- 显式复用:同一个
asm!块中多次使用同一个标签,或跨多个块重复使用; - 经由内联隐式复用:编译器可以实例化
asm!块的多个副本——例如包含它的函数被内联到多个调用点; - 经由 LTO 隐式复用:LTO(链接时优化)会把其他 crate 的代码放入同一个 codegen 单元,从而带入任意标签。
因此,内联汇编中只应使用 GNU 汇编器的数字局部标签(numeric local labels)。在汇编代码中定义符号可能导致重复符号定义,进而引发汇编器/链接器错误。
此外还有一个 x86 专属的坑:使用默认的 Intel 语法时,受一个 LLVM bug影响,不要使用纯 0 和 1 数字组成的标签(如 0、11、101010),因为它们可能被误解析为二进制数值。使用 options(att_syntax) 可以消除这种歧义,但这会改变整个 asm! 块的语法风格(详见 Options 一节)。
下面是数字局部标签的完整用法示例:
use std::arch::asm;
let mut a = 0;
unsafe {
asm!(
"mov {0}, 10",
"2:",
"sub {0}, 1",
"cmp {0}, 3",
"jle 2f",
"jmp 2b",
"2:",
"add {0}, 2",
out(reg) a
);
}
assert_eq!(a, 5);
执行过程:先把 a 置为 10,循环 sub {0}, 1 直到不大于 3,然后 add {0}, 2——最终 a = 5。
这个例子展示了两个关键规则:
- 同一数字可在同一个内联块中多次用作标签(上例中
2:出现两次); - 引用数字标签时必须加后缀:
b(backward,向前找最近的同名标签)或f(forward,向后找最近的同名标签)。上例中jle 2f跳转到后面的2:,jmp 2b跳回前面的2:。
Options:把汇编的「行为承诺」告诉编译器,换取更优优化
默认情况下,内联汇编块被当作一次带有自定义调用约定的外部 FFI 函数调用对待:它可能读/写内存、有可观察的副作用等。但在许多场景下,我们希望给编译器更多关于汇编实际行为的信息,从而让它更好地优化。
options 作为 asm! 宏的可选最后一个参数传入。回到之前的 add 示例:
use std::arch::asm;
let mut a: u64 = 4;
let b: u64 = 4;
unsafe {
asm!(
"add {0}, {1}",
inlateout(reg) a, in(reg) b,
options(pure, nomem, nostack),
);
}
assert_eq!(a, 8);
这里指定了三个选项,含义分别是:
| 选项 | 含义 | 对优化的影响 |
|---|---|---|
pure |
汇编代码没有可观察的副作用,其输出只取决于输入 | 允许优化器减少内联汇编的调用次数,甚至完全消除它(当其输出未被使用时) |
nomem |
汇编代码不读也不写内存 | 默认情况下编译器会假设内联汇编可以读写任何可达内存(如通过操作数传入的指针、或全局变量);nomem 撤销该假设,为内存相关优化打开空间 |
nostack |
汇编代码不会向栈上压入任何数据 | 允许编译器使用 x86-64 的栈红区(red zone)等优化,避免调整栈指针 |
注意每个选项都是一份「契约承诺」:pure 要求代码真正无副作用,nomem 要求真正不碰内存,nostack 要求真正不动栈——任何违反承诺的行为都会让优化后的代码产生错误结果,因此必须如实声明。
原文档指出,完整的选项列表及其效果以 Rust Reference 的 inline-assembly 章节为准(本仓库未包含该 reference 文档,读者可结合 Rust 官方 Reference 查阅)。
常见陷阱速查
把原文档中的易错点汇总如下,便于编码时自查:
- 忘记
unsafe:asm!的所有调用都必须在unsafe块中。 - 显式寄存器操作数误用
{}:显式寄存器操作数不能出现在模板字符串的{}占位符中,必须直接书写寄存器名,并且必须位于操作数列表末尾。 - 错误使用
inlateout导致寄存器被提前覆盖:只有当输出在所有输入被消费之后才写入时,才能使用inlateout/lateout。 - 遗漏 clobber 声明:任何被汇编修改但没有输出的寄存器(如
cpuid的eax/ecx/edx),都必须用out(...) _或相应机制声明,否则编译器会基于错误的寄存器存活假设生成损坏代码。 - LLVM 保留寄存器(如
ebx):不能直接作为输出,必须push/pop保护。 - 调用外部函数忘记
clobber_abi:调用会破坏大量寄存器的普通函数时,必须用clobber_abi("C")声明所有非 callee-saved 寄存器为 clobbered。 - 小类型忘记模板修饰符:编译器会警告并提示,但主动使用
{0:h}、{0:l}等修饰符更稳妥。 - 标签复用:只使用数字局部标签并配合
b/f后缀;Intel 语法下避免纯0/1组成的标签名。 - options 承诺不实:
pure/nomem/nostack必须与汇编实际行为严格一致。
小结
内联汇编是 Rust 中「最后的性能手段」,本仓库的 en/src/unsafe/inline-asm.md 给出了从零到实战的完整路径:asm! 基本用法 → in/out/inout 操作数 → lateout/inlateout 延迟输出 → 显式寄存器 → clobber 声明与 ABI clobbers → 寄存器模板修饰符 → 内存操作数 → 数字局部标签 → options 优化提示。配合 zh-CN/src/unsafe/inline-asm.md 的中文镜像版本,以及 en/book.toml 中的 2021 edition 配置,你可以在本地用 mdbook serve en/ 构建整本书并逐例运行验证(项目构建方式见仓库 Readme.md)。
掌握这些知识后,无论是编写内核级硬件访问代码、实现手写优化的热路径,还是仅仅读懂现有项目中的 asm!,你都能做到「知其然,更知其所以然」——而最关键的一条原则始终不变:向编译器如实声明汇编的每一步行为,剩下的寄存器分配与优化调度,交给它来完成。