Skip to content
Tutorials Center
My learning

Topics

Lesson 113 of 132 ยท Advanced Rust

Inline Assembly and SIMD

Learn Rust's lowest-level performance tools: the asm! macro, core::arch intrinsics with runtime feature detection, portable std::simd, and how to help auto-vectorization.

Almost all Rust code never needs to think about individual CPU instructions; the optimizer picks them for you. But a small number of programs do: a cryptography routine that must use a hardware instruction, a media codec that processes sixteen pixels per instruction, an operating-system kernel that must write a special register. Rust gives you three levels of access. Auto-vectorization lets the compiler use wide instructions on ordinary code. SIMD intrinsics and std::simd let you ask for vector operations explicitly. Inline assembly (asm!) lets you write the machine instructions yourself.

Treat these as tools of last resort. They are unsafe, architecture-specific and easy to get wrong, and a good compiler beats hand-written assembly more often than people expect. Use them after profiling and benchmarking show a real hot spot, and test them thoroughly with Miri and sanitizers where possible (Miri cannot run asm!). The examples here run on the server's x86-64 CPU, and every one has a fallback so it still compiles on other architectures.

flowchart TD
    A["Hot loop is too slow"] --> B["Write simple iterator or slice code,<br/>build with --release"]
    B --> C{"Fast enough?"}
    C -->|"yes"| Z["Stop"]
    C -->|"no"| D["Help auto-vectorization:<br/>chunks, no early exits, target-cpu"]
    D --> E{"Fast enough?"}
    E -->|"yes"| Z
    E -->|"no"| F["Portable std::simd (nightly)<br/>or core::arch intrinsics"]
    F --> G{"Need an instruction<br/>no intrinsic exposes?"}
    G -->|"yes"| H["asm!"]
    G -->|"no"| Z

Climb down only as far as the problem forces you to.

Inline assembly with asm!

The asm! macro (stable since Rust 1.59) embeds a block of assembly in a function. You write the template as a string, then declare how Rust values map to registers. On x86 the default syntax is Intel (destination first).

Rust Adding two numbers with asm!

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Read the operands carefully, because this is where bugs live:

  • in(reg) x passes x in some register the compiler chooses.
  • out(reg) y gives you the register's final value in y.
  • inout(reg) z is both: the register starts as z and its final value is stored back.
  • lateout(reg) is like out, but promises the register is written only after all inputs are read, so the compiler may reuse an input register for it.
  • , (or named ) in the template refer to the operands.
  • out("rax") _ or out("rcx") _ declares a register that the code overwrites ("clobbers") without returning a value. Forgetting a clobber is undefined behavior.

Options tell the compiler what the assembly does not do

By default the compiler assumes the assembly may read and write any memory, have side effects, and use the stack. If you can promise less, say so with options(...) and the optimizer can do far more:

Option Promise
pure no side effects; same inputs give same outputs (needs at least one output)
nomem does not read or write memory
readonly reads memory but does not write it
nostack does not push to the stack
preserves_flags does not change the CPU flags
att_syntax the template uses AT&T syntax instead of Intel

A lie in an option is undefined behavior, just like a lie in a SAFETY: comment.

Rust Pure arithmetic: lea and bswap

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Notice the final line: u32::swap_bytes compiles to that very bswap instruction. This is the usual outcome. Before writing assembly, check whether a method such as swap_bytes, leading_zeros, count_ones, rotate_left or trailing_zeros already maps to the instruction you want.

Labels, loops and clobbers

Assembly can contain jumps. Use numeric local labels (2:) and refer to them with a direction suffix (2b for backward, 2f for forward) so repeated expansion of the macro never creates duplicate labels. A loop that sums the numbers n, n-1, ... 1:

Rust A loop in assembly with a local label

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

For anything bigger than a few instructions, write the routine in a separate .s file or use global_asm! / naked functions, or bind a C or assembly library through FFI. Inline assembly interacts with the optimizer, and every extra line is another way to violate a promise you made in the operand list.

SIMD: one instruction, many values

SIMD (single instruction, multiple data) uses wide registers that hold several numbers at once: 128-bit registers hold four i32 or sixteen u8; 256-bit AVX2 registers hold eight i32. One instruction then adds all lanes together.

Rust exposes it in two ways. core::arch (also available as std::arch) has intrinsics, thin wrappers that map to specific instructions per architecture: std::arch::x86_64::_mm_add_epi32, std::arch::aarch64::vaddq_s32, and so on. They are the stable way to write SIMD today. std::simd ("portable SIMD") is a friendlier, architecture-neutral API, but it is still nightly-only (#![feature(portable_simd)]), so we show it read-only.

Intrinsics and target features

On x86-64, SSE2 is part of the baseline instruction set, so those intrinsics always exist there. Newer extensions (SSE4.2, AVX2, AVX-512) are target features that a particular CPU may or may not have. Calling an AVX2 instruction on a CPU without it crashes with an illegal instruction, so you must either compile for a known CPU or detect features at run time.

Rust Summing i32 values four lanes at a time with SSE2

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The pattern is the same in every SIMD routine: process full vectors in the main loop, handle the leftover tail with scalar code, and test the awkward sizes (empty, shorter than one vector, one past a multiple).

Runtime detection and dispatch

To use a newer instruction set safely, compile the fast version with #[target_feature(enable = "avx2")] and pick it at run time with is_x86_feature_detected!. Calling such a function from code that does not enable the same feature is unsafe, because calling it on the wrong CPU is undefined behavior (we declare it unsafe fn here for clarity).

Rust Dispatching on CPU features at run time

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The detection macro caches its answer, so calling it in a hot function is cheap. For the whole binary you can instead build for a specific CPU with RUSTFLAGS="-C target-cpu=native" (fast, but the binary may crash on older machines) or -C target-feature=+avx2.

Portable SIMD with std::simd

On nightly, std::simd gives you vector types such as Simd<f32, 8> with ordinary operators, and the compiler maps them to whatever the target supports. Read-only, as it needs a nightly toolchain:

Rust
// Read-only: requires nightly Rust
#![feature(portable_simd)]
use std::simd::prelude::*;

fn dot(a: &[f32], b: &[f32]) -> f32 {
    let mut acc = f32x8::splat(0.0);
    let (a_chunks, a_tail) = a.as_chunks::<8>();
    let (b_chunks, b_tail) = b.as_chunks::<8>();
    for (x, y) in a_chunks.iter().zip(b_chunks) {
        acc += f32x8::from_array(*x) * f32x8::from_array(*y);
    }
    let tail: f32 = a_tail.iter().zip(b_tail).map(|(x, y)| x * y).sum();
    acc.reduce_sum() + tail
}

The API also has masks (simd_lt, select), shuffles (swizzle), gathers and lane-wise comparisons. When it stabilizes it will be the recommended way to write portable SIMD; until then, use intrinsics per architecture, or a crate such as wide or pulp on stable.

Letting the compiler vectorize

Often you do not need any of the above. LLVM's auto-vectorizer turns simple loops into SIMD code when it can prove it is valid. You help it by writing loops it can understand:

  • Work on slices with simple indexing or iterators, not linked structures.
  • Avoid early exits (break, ?, return) inside the hot loop; they block vectorization.
  • Keep the loop body free of function calls the compiler cannot inline.
  • For floating-point sums, note that a + b + c is not associative, so the compiler will not reorder a sum of floats unless you do. Accumulate into several independent partial sums yourself.
  • Prefer chunks_exact and fixed-size arrays so lengths are known to be a multiple of the vector width.
Rust Independent accumulators for floating-point sums

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

To see what the compiler actually produced, look at the assembly: paste a small function into the Compiler Explorer (godbolt.org) with -C opt-level=3, or run cargo asm (the cargo-show-asm tool) on your own project. Look for vector registers (xmm, ymm, zmm on x86; v0... on ARM) and instructions with p or v prefixes such as paddd and vaddps. Verify the speedup with a benchmark, because wider instructions are not always faster once memory bandwidth is the limit.

Rules of thumb

  1. Measure first. Most code is not limited by arithmetic.
  2. Keep a scalar reference and test the fast path against it on awkward lengths and random data (see Property Testing and Fuzzing).
  3. Always provide a fallback for other architectures and CPUs without the feature, using cfg and run-time detection.
  4. Document every unsafe with the exact feature, alignment and bounds argument.
  5. Prefer a maintained crate (memchr, simdutf8, sha2, base64, bytecount) that already contains tuned and tested SIMD, before writing your own.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. In asm!, what does inout(reg) x mean?

    inout is both an input and an output using the same register: it begins with your value and the result is written back to the variable.
  2. 2. What happens if you declare options(nomem) on assembly that actually writes to memory?

    Options are promises the compiler uses to optimize. Breaking one is undefined behavior, just like breaking any other unsafe contract.
  3. 3. Why must a function using AVX2 instructions be called only after is_x86_feature_detected!("avx2") (or on a CPU known to have it)?

    Target features are not guaranteed everywhere. Detection at run time (or building for a known CPU) makes the call valid.
  4. 4. Which is the main reason the compiler will not auto-vectorize a plain f32 sum by reordering additions?

    Rounding makes (a + b) + c differ from a + (b + c). You get speed by writing several partial sums yourself, accepting the changed rounding.
  5. 5. What is the status of std::simd (portable SIMD) at the time of this tutorial?

    std::simd still needs a nightly compiler. On stable, use core::arch intrinsics or a crate such as wide.

Summary

  • Prefer simple, vectorizer-friendly code built with --release; reach for explicit SIMD or assembly only after measuring.
  • asm! embeds machine instructions: declare operands (in, out, inout, lateout), clobbers, and honest options such as pure, nomem and nostack.
  • core::arch intrinsics are the stable way to write SIMD; handle the tail of the data, and detect CPU features at run time with is_x86_feature_detected! and #[target_feature].
  • std::simd is the portable API but is nightly-only for now.
  • Float sums are not reordered automatically; use independent accumulators or chunks to help the compiler.
  • Keep a scalar reference, a fallback, tests for odd lengths, and a benchmark that proves the gain.

Next: Project: Guessing Game