附录E. 高级内联汇编

概览

当你需要一次性指令、与旧 ABI 互操作或访问标准库尚未封装的处理器特性时，内联汇编让你能够越过 Zig 的抽象层。33 Zig 0.15.2 通过对指针转换强制对齐检查与更清晰的约束诊断加固了内联汇编，使其较以前版本更安全且更易调试。v0.15.2

学习目标

• 识别 Zig 的 GNU 风格内联汇编块的结构并将操作数映射到寄存器或内存。
• 应用寄存器和 clobber 约束来编排 Zig 变量与机器指令之间的数据流。
• 用编译期检查保护特定架构的代码片段，使你的构建在不支持的目标上快速失败。

构造汇编块

Zig adopts the familiar GCC/Clang inline assembly layout: a template string followed by colon-separated outputs, inputs, and clobbers. Start with simple arithmetic to get comfortable with operand binding before you reach for more exotic instructions. The first example uses addl to combine two 32-bit values, binding both operands to registers without touching memory. x86_64.zig

// ! 最小化的内联汇编示例，用于添加两个整数。
const std = @import("std");

pub fn addAsm(a: u32, b: u32) u32 {
    var result: u32 = undefined;
    asm volatile ("addl %[lhs], %[rhs]\n\t"
        : [out] "=r" (result),
        : [lhs] "r" (a),
          [rhs] "0" (b),
    );
    return result;
}

test "addAsm produces sum" {
    try std.testing.expectEqual(@as(u32, 11), addAsm(5, 6));
}

$ zig test chapters-data/code/59__advanced-inline-assembly/01_inline_add.zig

All 1 tests passed.

安全的寄存器编排

More complex snippets often need bidirectional operands (read/write) or additional bookkeeping once the instruction finishes. The xchg sequence below swaps two integers entirely in registers, then writes the updated values back to Zig-managed memory. 4 Guarding the function with @compileError prevents accidental use on non-x86 platforms, while the +r constraint indicates that each operand is both read and written. pie.zig

// ! 使用带内存约束的 x86 xchg 指令交换两个字。
const std = @import("std");
const builtin = @import("builtin");

pub fn swapXchg(a: *u32, b: *u32) void {
    if (builtin.cpu.arch != .x86_64) @compileError("swapXchg requires x86_64");

    var lhs = a.*;
    var rhs = b.*;
    asm volatile ("xchgl %[left], %[right]"
        : [left] "+r" (lhs),
          [right] "+r" (rhs),
    );
    a.* = lhs;
    b.* = rhs;
}

test "swapXchg swaps values" {
    var lhs: u32 = 1;
    var rhs: u32 = 2;
    swapXchg(&lhs, &rhs);
    try std.testing.expectEqual(@as(u32, 2), lhs);
    try std.testing.expectEqual(@as(u32, 1), rhs);
}

$ zig test chapters-data/code/59__advanced-inline-assembly/02_xchg_swap.zig

All 1 tests passed.

可观测性与护栏

Once you trust the syntax, inline assembly becomes a precision tool for hardware-provided counters or instructions not yet surfaced elsewhere. Reading the x86 time-stamp counter with rdtsc gives you cycle-level timing while demonstrating multi-output constraints and the new alignment assertions introduced in 0.15.x. 39 The example bundles the low and high halves of the counter into a u64 and falls back to a compile error on non-x86_64 targets.

// ! 使用内联汇编输出读取 x86 时间戳计数器。
const std = @import("std");
const builtin = @import("builtin");

pub fn readTimeStampCounter() u64 {
    if (builtin.cpu.arch != .x86_64) @compileError("rdtsc example requires x86_64");

    var lo: u32 = undefined;
    var hi: u32 = undefined;
    asm volatile ("rdtsc"
        : [low] "={eax}" (lo),
          [high] "={edx}" (hi),
    );
    return (@as(u64, hi) << 32) | @as(u64, lo);
}

test "readTimeStampCounter returns non-zero" {
    const a = readTimeStampCounter();
    const b = readTimeStampCounter();
    // 计数器单调递增；在调用落在同一周期的情况下允许相等。
    try std.testing.expect(b >= a);
}

$ zig test chapters-data/code/59__advanced-inline-assembly/03_rdtsc.zig

All 1 tests passed.

随手可用的模式

• Wrap architecture-specific blocks in if (builtin.cpu.arch != …) @compileError guards so cross-compilation fails early. 41
• 原型阶段优先使用仅寄存器操作数——在逻辑正确后，再有意识地引入内存操作数与 clobber。33
• Treat inline assembly as an escape hatch; if the standard library (or builtins) exposes the instruction, prefer that higher-level API to stay portable. mem.zig

注意与警示

• Inline assembly is target-specific; always document the minimum CPU features required and consider feature probes before executing the block. 29
• Clobber lists matter—forgetting "cc" or "memory" may lead to miscompilations that only surface under optimization. 36
• 在混用 Zig 与外部 ABI 时，请反复确认调用约定与寄存器保留规则；编译器不会为你保存寄存器。builtin.zig

练习

• Add an lfence instruction before rdtsc and measure the impact on stability; compare results in Debug and ReleaseFast builds. 39
• Extend swapXchg with a "memory" clobber and benchmark the difference when swapping values in a tight loop. time.zig
• Rewrite addAsm using a compile-time format string that emits add or sub based on a boolean parameter. 15

替代方案与边界情况

• Some instructions (e.g., privileged system calls) require elevated privileges—wrap them in runtime checks so they never execute inadvertently. 48
• On microarchitectures with out-of-order execution, pair timing reads with fences to avoid skewed measurements. 39
• For portable timing, prefer std.time.Timer or platform APIs and reserve inline assembly for truly architecture-specific hot paths.