Stabilize fn_align: #[repr(align(N))] on functions and -Zmin-function-alignment

[folkertdev]

tracking issue: #82232
closes #82232

Request for Stabilization

Summary

The fn_align feature has two parts:

• the #[repr(align(N))] function attribute specifies the alignment of the generated code of a particular function
• the -Zmin-function-alignment command line flag specifies the minimal alignment of the generated code of all compiled functions.

These could be stabilized separately, but share a lot of the same logic in the compiler and are tracked by the same tracking issue.

An example of specifying function alignment:

#[repr(align(32))]
pub fn align_this() {}

Specifying the alignment of a specific function occasionally comes up in embedded development. For instance in risc-v vector tables, the function pointers stored in it must be aligned to at least 4 bytes (see #75072).

Specifying a global alignment is more commonly done as a performance optimization. This functionality is used in the linux kernel and this feature flag was requested by Rust for Linux #128830.

Semantics

The -Zmin-function-alignment flag is a global mimimum function alignment. It is semantically equivalent to annotating every function with a #[repr(align(N))]. However, this minimum is only applied to functions that are actually codegened, so without -Zbuild-std or similar, this minimum alignment is not applied to standard library functions.

The function alignment is forwarded to the code generation backend, and behaves as follows:

• the highest specified alignment is used
• the alignment follows the same rule as for data types: it must be a power of 2 in the range 1 up to and including 2.pow(29).
• the alignment is a minimum, the alignment may be higher in practice (e.g. x86_64 aligns to 16 by default)

Documentation

Pending resolving some of the open questions.

Tests

• tests/codegen/min-function-alignment.rs tests the behavior of the -Zmin-function-alignment flag and how it interacts with #[repr(align(N))].
• tests/codegen/align_fn.rs test that the attribute produces the expected alignment (in a bunch of different positions: top-level, impl block, trait default method).
• tests/ui/attributes/malformed-fn-align.rs checks that the attribute cannot be applied to trait methods (when they have no body).

History

• Allow specifying alignment for functions #81234
• allow repr(align = x) on inherent methods #110313
• add -Zmin-function-alignment #134030

The -Zmin-function-alignment flag was requested by rust-for-linux #128830. It will be used soon (see #t-compiler/help > ✔ Alignment for function addresses).

Miri supports function alignment since #140072. In const-eval there is no way to observe the address of a function pointer, so no special attention is needed there (see #t-compiler/const-eval > function address alignment).

Notes

• Triage meeting 2025-04-23

unresolved questions

• Is #[repr(align(N))] the right syntax? Perhaps #[align(N)] would be better (suggested at https://internals.rust-lang.org/t/pre-rfc-align-attribute/21004/27)
• Support for per-function alignment in cranelift is blocked on [module] Make it possible to enable isa flags on a per function base bytecodealliance/wasmtime#1104. The -Zmin-function-alignment flag does work. If that's a problem, should we pull apart the global and per-function alignment?
• What should #[repr(align(N))] do for an async fn, maybe this should not be supported for now?

r? @traviscross

@rustbot label +I-lang-nominated

[rustbot]

Some changes occurred to the CTFE / Miri interpreter

cc @rust-lang/miri

Some changes occurred in compiler/rustc_codegen_ssa

cc @WaffleLapkin

Some changes occurred to the CTFE machinery

cc @RalfJung, @oli-obk, @lcnr

The Miri subtree was changed

cc @rust-lang/miri

Some changes occurred in compiler/rustc_passes/src/check_attr.rs

cc @jdonszelmann