内联汇编

Rust 通过 asm! 宏提供对内联汇编的支持。它可以用来在编译器生成的汇编输出中嵌入手写的汇编代码。通常情况下，这应该是不必要的，但在需要性能或时间的情况下，这可能是唯一的选择。访问底层硬件原语，例如在内核代码中，也可能需要此功能。

**注意**：这里的例子是用 x86/x86-64 汇编给出的，但也支持其他架构。

内联汇编目前支持以下架构

• x86 和 x86-64
• ARM
• AArch64
• RISC-V

基本用法

让我们从最简单的例子开始

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

unsafe {
    asm!("nop");
}
}
}

这将在编译器生成的汇编中插入一条 NOP（无操作）指令。请注意，所有 asm! 调用都必须在一个 unsafe 块中，因为它们可以插入任意指令并破坏各种不变量。要插入的指令在 asm! 宏的第一个参数中列出，作为一个字符串字面量。

输入和输出

现在插入一条什么都不做的指令相当无聊。让我们做一些实际操作数据的事情

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let x: u64;
unsafe {
    asm!("mov {}, 5", out(reg) x);
}
assert_eq!(x, 5);
}
}

这将把值 5 写入 u64 变量 x 中。你可以看到，我们用来指定指令的字符串字面量实际上是一个模板字符串。它遵循与 Rust 格式字符串 相同的规则。然而，插入到模板中的参数看起来与你熟悉的有点不同。首先，我们需要指定变量是内联汇编的输入还是输出。在这种情况下，它是一个输出。我们通过编写 out 来声明这一点。我们还需要指定汇编期望变量在哪种寄存器中。在这种情况下，我们通过指定 reg 将其放入一个任意的通用寄存器中。编译器将选择一个合适的寄存器插入到模板中，并在内联汇编执行完毕后从那里读取变量。

让我们看另一个也使用输入的例子

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
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);
}
}

这将把 5 加到变量 i 中的输入上，并将结果写入变量 o 中。这种汇编的特殊方式是首先将 i 中的值复制到输出中，然后将 5 加到其中。

这个例子展示了几件事

首先，我们可以看到 asm! 允许多个模板字符串参数；每个参数都被视为一行独立的汇编代码，就像它们都被连接在一起，中间用换行符隔开一样。这使得格式化汇编代码变得很容易。

其次，我们可以看到输入是通过编写 in 而不是 out 来声明的。

第三，我们可以看到我们可以像在任何格式字符串中一样指定参数编号或名称。对于内联汇编模板来说，这特别有用，因为参数经常被多次使用。对于更复杂的内联汇编，通常建议使用此功能，因为它提高了可读性，并允许在不改变参数顺序的情况下重新排序指令。

我们可以进一步完善上面的例子，以避免 mov 指令

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let mut x: u64 = 3;
unsafe {
    asm!("add {0}, 5", inout(reg) x);
}
assert_eq!(x, 8);
}
}

我们可以看到，inout 用于指定一个既是输入又是输出的参数。这与分别指定输入和输出不同，因为它保证将两者分配给同一个寄存器。

也可以为 inout 操作数的输入和输出部分指定不同的变量

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let x: u64 = 3;
let y: u64;
unsafe {
    asm!("add {0}, 5", inout(reg) x => y);
}
assert_eq!(y, 8);
}
}

延迟输出操作数

Rust 编译器在分配操作数方面比较保守。它假设 out 可以随时写入，因此不能与任何其他参数共享其位置。然而，为了保证最佳性能，重要的是尽可能少地使用寄存器，这样就不必在内联汇编块周围保存和重新加载它们。为了实现这一点，Rust 提供了一个 lateout 说明符。这可以用于任何只在所有输入都被消耗后才写入的输出。还有一个 inlateout 变体说明符。

下面是一个在 release 模式或其他优化情况下*不能*使用 inlateout 的例子

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
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);
}
}

在未优化的情况下（例如 Debug 模式），在上面的例子中，将 inout(reg) a 替换为 inlateout(reg) a 可以继续得到预期的结果。然而，在 release 模式或其他优化情况下，使用 inlateout(reg) a 可能会导致最终值 a = 16，导致断言失败。

这是因为在优化情况下，编译器可以自由地为输入 b 和 c 分配相同的寄存器，因为它知道它们的值相同。此外，当使用 inlateout 时，a 和 c 可以被分配到同一个寄存器，在这种情况下，第一条 add 指令将覆盖从变量 c 的初始加载。这与使用 inout(reg) a 确保为 a 分配一个单独的寄存器的方式形成对比。

然而，下面的例子可以使用 inlateout，因为输出只在所有输入寄存器都被读取后才被修改

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
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 被分配到同一个寄存器，这段汇编代码仍然可以正常工作。

显式寄存器操作数

有些指令要求操作数位于特定的寄存器中。因此，Rust 内联汇编提供了一些更具体的约束说明符。虽然 reg 通常在任何架构上都可用，但显式寄存器是高度特定于架构的。例如，对于 x86，通用寄存器 eax、ebx、ecx、edx、ebp、esi 和 edi 等可以通过它们的名称来寻址。

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

let cmd = 0xd1;
unsafe {
    asm!("out 0x64, eax", in("eax") cmd);
}
}
}

在这个例子中，我们调用 out 指令将 cmd 变量的内容输出到端口 0x64。由于 out 指令只接受 eax（及其子寄存器）作为操作数，所以我们必须使用 eax 约束说明符。

**注意**：与其他操作数类型不同，显式寄存器操作数不能在模板字符串中使用：你不能使用 {}，而应该直接写寄存器名称。此外，它们必须出现在操作数列表的末尾，在所有其他操作数类型之后。

考虑这个使用 x86 mul 指令的例子

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
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
}
}
}

这使用 mul 指令将两个 64 位输入相乘，得到 128 位结果。唯一的显式操作数是一个寄存器，我们从变量 a 填充它。第二个操作数是隐式的，必须是 rax 寄存器，我们从变量 b 填充它。结果的低 64 位存储在 rax 中，我们从中填充变量 lo。高 64 位存储在 rdx 中，我们从中填充变量 hi。

被覆盖的寄存器

在许多情况下，内联汇编会修改不需要作为输出的状态。这通常是因为我们必须在汇编中使用临时寄存器，或者因为指令修改了我们不需要进一步检查的状态。这种状态通常被称为“被覆盖”。我们需要将此情况告知编译器，因为它可能需要在内联汇编块前后保存和恢复此状态。

use std::arch::asm;

#[cfg(target_arch = "x86_64")]
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, the asm needs to preserve the value of it.
    // So we push and pop it around the main asm.
    // 64 bit mode on 64 bit processors does not allow pushing/popping of
    // 32 bit registers (like ebx), so we have to use the extended rbx register instead.

    unsafe {
        asm!(
            "push rbx",
            "cpuid",
            "mov [rdi], ebx",
            "mov [rdi + 4], edx",
            "mov [rdi + 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("rdi") 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);
}

#[cfg(not(target_arch = "x86_64"))]
fn main() {}

在上面的示例中，我们使用 cpuid 指令读取 CPU 制造商 ID。此指令写入 eax，其中包含最大支持的 cpuid 参数，并写入 ebx、edx 和 ecx，其中包含按顺序排列的 ASCII 字节形式的 CPU 制造商 ID。

即使从未读取 eax，我们仍然需要告诉编译器该寄存器已被修改，以便编译器可以保存 asm 之前在这些寄存器中的任何值。这是通过将其声明为输出但使用 _ 而不是变量名来完成的，这表明输出值将被丢弃。

此代码还解决了 ebx 是 LLVM 保留寄存器的限制。这意味着 LLVM 假设它完全控制该寄存器，并且必须在退出 asm 块之前将其恢复到原始状态，因此它不能用作输入或输出，**除非**编译器使用它来满足通用寄存器类（例如 in(reg)）。这使得在使用保留寄存器时 reg 操作数很危险，因为我们可能会在不知不觉中破坏我们的输入或输出，因为它们共享同一个寄存器。

为了解决这个问题，我们使用 rdi 来存储指向输出数组的指针，通过 push 保存 ebx，在 asm 块内部从 ebx 读取到数组中，然后通过 pop 将 ebx 恢复到其原始状态。push 和 pop 使用寄存器的完整 64 位 rbx 版本，以确保保存整个寄存器。在 32 位目标上，代码将在 push/pop 中使用 ebx。

这也可以与通用寄存器类一起使用，以获取在 asm 代码内部使用的临时寄存器

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
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);
}
}

符号操作数和 ABI clobber

默认情况下，asm! 假定任何未指定为输出的寄存器都将由汇编代码保留其内容。asm! 的 clobber_abi 参数告诉编译器根据给定的调用约定 ABI 自动插入必要的 clobber 操作数：任何在该 ABI 中未完全保留的寄存器都将被视为 clobbered。可以提供多个 clobber_abi 参数，并且将插入来自所有指定 ABI 的所有 clobber。

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
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
    }
}
}
}

寄存器模板修饰符

在某些情况下，需要精确控制将寄存器名称插入模板字符串的方式。当架构的汇编语言对同一个寄存器有多个名称时，就需要这样做，每个名称通常是寄存器子集的“视图”（例如，64 位寄存器的低 32 位）。

默认情况下，编译器将始终选择引用完整寄存器大小的名称（例如，x86-64 上的 rax，x86 上的 eax 等）。

可以通过在模板字符串操作数上使用修饰符来覆盖此默认值，就像使用格式字符串一样

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
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 寄存器类将寄存器分配器限制为 4 个传统的 x86 寄存器（ax、bx、cx、dx），其中前两个字节可以独立寻址。

假设寄存器分配器已选择在 ax 寄存器中分配 x。h 修饰符将发出该寄存器高字节的寄存器名称，l 修饰符将发出低字节的寄存器名称。因此，asm 代码将扩展为 mov ah, al，它将值的低字节复制到高字节。

如果您将较小的数据类型（例如 u16）与操作数一起使用，并且忘记使用模板修饰符，则编译器将发出警告并建议使用正确的修饰符。

内存地址操作数

有时，汇编指令需要通过内存地址/内存位置传递的操作数。您必须手动使用目标体系结构指定的内存地址语法。例如，在使用 Intel 汇编语法的 x86/x86_64 上，您应该将输入/输出括在 [] 中，以指示它们是内存操作数

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
use std::arch::asm;

fn load_fpu_control_word(control: u16) {
    unsafe {
        asm!("fldcw [{}]", in(reg) &control, options(nostack));
    }
}
}
}

标签

任何对命名标签（本地或其他）的重复使用都可能导致汇编程序或链接器错误，或者可能导致其他奇怪的行为。命名标签的重复使用可以通过多种方式发生，包括

• 显式：在一个 asm! 块中多次使用标签，或者跨块多次使用。
• 通过内联隐式：允许编译器实例化 asm! 块的多个副本，例如，当包含它的函数在多个地方内联时。
• 通过 LTO 隐式：LTO 可能导致来自*其他板条箱*的代码被放置在同一个代码生成单元中，因此可能会引入任意标签。

因此，您应该只在内联汇编代码中使用 GNU 汇编程序**数字**本地标签。在汇编代码中定义符号可能会由于符号定义重复而导致汇编程序和/或链接器错误。

此外，在 x86 上使用默认的 Intel 语法时，由于LLVM 错误，您不应该使用仅由 0 和 1 数字组成的标签，例如 0、11 或 101010，因为它们最终可能会被解释为二进制值。使用 options(att_syntax) 将避免任何歧义，但这会影响*整个* asm! 块的语法。（有关 options 的更多信息，请参见下面的选项。）

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
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);
}
}

这会将 {0} 寄存器值从 10 递减到 3，然后加 2 并将其存储在 a 中。

此示例显示了一些内容

• 首先，同一个数字可以在同一个内联块中多次用作标签。
• 其次，当数字标签用作引用（例如，作为指令操作数）时，应在数字标签后添加后缀“b”（“向后”）或“f”（“向前”）。然后，它将引用此方向上与此数字定义的最近标签。

选项

默认情况下，内联汇编块的处理方式与具有自定义调用约定的外部 FFI 函数调用相同：它可以读取/写入内存、具有可观察的副作用等。但是，在许多情况下，希望为编译器提供有关汇编代码实际操作的更多信息，以便它可以更好地优化。

让我们以我们之前的 add 指令为例

#![allow(unused)]
fn main() {
#[cfg(target_arch = "x86_64")] {
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);
}
}

可以将选项作为可选的最终参数提供给 asm! 宏。我们在这里指定了三个选项

• pure 意味着 asm 代码没有可观察的副作用，并且其输出仅取决于其输入。这允许编译器优化器减少调用内联 asm 的次数，甚至完全消除它。
• nomem 意味着 asm 代码不读取或写入内存。默认情况下，编译器将假定内联汇编可以读取或写入它可以访问的任何内存地址（例如，通过作为操作数传递的指针或全局变量）。
• nostack 意味着 asm 代码不会将任何数据推送到堆栈上。这允许编译器使用优化，例如 x86-64 上的堆栈红色区域，以避免堆栈指针调整。

这些允许编译器更好地优化使用 asm! 的代码，例如通过消除不需要其输出的纯 asm! 块。

有关可用选项及其效果的完整列表，请参阅参考。