Rust 内联汇编(Inline Assembly)完全指南:基于 Rust By Practice 的 asm! 宏实战与原理剖析

原创2026-09-21 09:14:481,665 阅读
文章标签:文档教程教育

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);

这段代码展示了两个核心概念:

  1. 模板字符串:指定指令的字符串字面量实际上是模板字符串,其插值规则与 Rust 的格式化字符串(format strings)相同——{} 会被实际的操作数替换。
  2. 操作数声明:模板中插入的参数与普通格式化参数不同,需要同时声明两件事:
    • 方向:变量是汇编的输入(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 字节。

这个例子蕴含了多处关键知识:

  1. 丢弃输出用 _:即使 eax 从未被读取,也必须告诉编译器该寄存器已被修改(否则编译器可能认为 eax 在 asm! 前后保持不变,从而在后续代码中错误地复用其旧值)。做法是把它声明为输出,但用 _ 代替变量名——_ 表示「输出值将被丢弃」。
  2. 规避 LLVM 保留寄存器 ebx:LLVM 假定自己完全掌控 ebx,并强制要求在退出 asm! 块前将其恢复到原状,因此 ebx 不能作为输出使用。解决办法是:先 push rbx 保存现场,在 asm! 内部把 ebx 的值移入一个由编译器分配(out(reg))的临时寄存器,再从临时寄存器写入内存,最后 pop rbx 恢复现场。
  3. 32/64 位差异:push/pop 在 64 位目标上使用完整的 rbx,确保整个寄存器被保存;在 32 位目标上则应使用 ebx。
  4. 通过指针写内存: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。

这个例子展示了两个关键规则:

  1. 同一数字可在同一个内联块中多次用作标签(上例中 2: 出现两次);
  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 查阅)。


常见陷阱速查

把原文档中的易错点汇总如下,便于编码时自查:

  1. 忘记 unsafe:asm! 的所有调用都必须在 unsafe 块中。
  2. 显式寄存器操作数误用 {}:显式寄存器操作数不能出现在模板字符串的 {} 占位符中,必须直接书写寄存器名,并且必须位于操作数列表末尾。
  3. 错误使用 inlateout 导致寄存器被提前覆盖:只有当输出在所有输入被消费之后才写入时,才能使用 inlateout/lateout。
  4. 遗漏 clobber 声明:任何被汇编修改但没有输出的寄存器(如 cpuid 的 eax/ecx/edx),都必须用 out(...) _ 或相应机制声明,否则编译器会基于错误的寄存器存活假设生成损坏代码。
  5. LLVM 保留寄存器(如 ebx):不能直接作为输出,必须 push/pop 保护。
  6. 调用外部函数忘记 clobber_abi:调用会破坏大量寄存器的普通函数时,必须用 clobber_abi("C") 声明所有非 callee-saved 寄存器为 clobbered。
  7. 小类型忘记模板修饰符:编译器会警告并提示,但主动使用 {0:h}、{0:l} 等修饰符更稳妥。
  8. 标签复用:只使用数字局部标签并配合 b/f 后缀;Intel 语法下避免纯 0/1 组成的标签名。
  9. 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!,你都能做到「知其然,更知其所以然」——而最关键的一条原则始终不变:向编译器如实声明汇编的每一步行为,剩下的寄存器分配与优化调度,交给它来完成。

登录后查看全文
rust-by-practice