Stabilize `-Cmin-function-alignment` #142824

folkertdev · 2025-06-21T11:50:19Z

tracking issue: #82232
split out from: #140261

Request for Stabilization

Summary

The -Cmin-function-alignment=<align> flag specifies the minimum alignment of functions for which code is generated.
The align value must be a power of 2, other values are rejected.

Note that -Zbuild-std (or similar) is required to apply this minimum alignment to standard library functions.
By default, these functions come precompiled and their alignments won't respect the min-function-alignment flag.

This flag is equivalent to:

-fmin-function-alignment for GCC
-falign-functions for Clang

The specified alignment is a minimum. A higher alignment can be specified for specific functions by annotating the function with a #[align(<align>)] attribute.
The attribute's value is ignored when it is lower than the value passed to min-function-alignment.

There are two additional edge cases for this flag:

targets have a minimum alignment for functions (e.g. on x86_64 the lowest that LLVM generates is 16 bytes).
A min-function-alignment value lower than the target's minimum has no effect.
the maximum alignment supported by this flag is 8192. Trying to set a higher value results in an error.

Testing

tests/codegen/min-function-alignment.rs tests the behavior of the -Zmin-function-alignment flag and how it interacts with #[align(N)].
tests/ui/invalid-compile-flags/min-function-alignment.rs tests that incorrect alignments error

History

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

Originally, the maximum allowed alignment was 1 << 29, because this is the highest value the LLVM API accepts. However, on COFF the highest supported alignment is only 8192 (see #142638). Practically speaking, that seems more than sufficient for all known use cases. So for simplicity, for now, we limit the alignment to 8192. The value can be increased on platforms that support it if the need arises.

r? @workingjubilee

the first commit can be split out if that is more convenient.

Caution

Concerns (6 active)

Managed by @rustbot—see help for details.

rustbot · 2025-06-21T11:50:25Z

Some changes occurred to the CTFE machinery

cc @RalfJung, @oli-obk, @lcnr

Some changes occurred to the CTFE / Miri interpreter

cc @rust-lang/miri

Some changes occurred in compiler/rustc_codegen_cranelift

cc @bjorn3

Some changes occurred in compiler/rustc_codegen_ssa

cc @WaffleLapkin

The Miri subtree was changed

cc @rust-lang/miri

bjorn3 · 2025-06-21T12:20:28Z

compiler/rustc_session/src/options.rs

+        // alignment that works on all target platforms. COFF does not support higher alignments.
+        if bytes > 8192 {
+            return false;
+        }


Why should it be limited on all platforms? Can't we error when the alignment exceeds the maximum that the actual target we are compiling for supports? Maybe someone genuinely needs to align to 16k on ELF for whatever reason?

Well, so as we've discovered, alignment is just a mess between clang and llvm. For instance -falign-function only goes up to 1 << 16, although you can manually align a function to a much higher alignment.

For 8192, we know it'll work everywhere, and the logic for when to accept/reject an alignment value is clear.

This flag aligns all functions to the minimum, so I have a hard time seeing a realistic scenario where aligning all functions to 16k is a reasonable thing to do (the limit on individual functions will be handled separately).

So I think the options are:

Limit to 8192 on all platforms, it's consistent and unlikely to cause issues. The limit can be safely raised in the future if a need arises

Follow clang and allow 1 << 16, except when the target object format is COFF, then the limit is 8192.

Accept what llvm accepts: allow 1 << 29, except when the target object format is COFF, then the limit is 8192.

I've picked the most conservative one (again, with the option to relax the limits if the need ever arises), but if there is consensus now on one of the other options that's also fine.

It is my understanding that on Linux kernels we still nominally support, overaligning beyond the page size, typically 4096, is not going to work properly, so it is arguable that even 8192 is too high.

IMO for the long term, hard-coding to 8192 across all platforms seem like a mistake -- especially because then, does this become part of the language or even more problematic, become part of (compiler/language) stability guarantees?

EDIT: or rather, what is a suitable upper bound in this case in terms of stability guarantees? As in, if we stabilize n=8192 as a universal upper bound, if we find out some platform cannot handle that in the future?

RalfJung · 2025-06-21T14:49:16Z

compiler/rustc_const_eval/src/interpret/memory.rs

+                    // the alignment from a `#[align(<n>)]` is used if it specifies a higher alignment.
                    let fn_align = self.tcx.codegen_fn_attrs(instance.def_id()).alignment;
-                    let global_align = self.tcx.sess.opts.unstable_opts.min_function_alignment;
+                    let global_align = self.tcx.sess.opts.cg.min_function_alignment;


(orthogonal to this PR)
it is not great that the logic for merging the per-fn alignment and the global alignment needs to be repeated in each backend.

Maybe codegen_fn_attrs should just take min_function_alignment into account?

In fact, using sess.opts in the interpreter is at best iffy since it means the interpreter can behave differently in different crates in the same crate graph which can cause unsoundness...

Given that function pointers can be odd even when -Cmin-function-alignment is 2 (see here), I don't think it makes sense for the interpreter to do anything with min_function_alignment.

traviscross · 2025-06-22T21:40:13Z

@rustbot labels +T-lang

If the idea with this is that passing -Cmin-function-alignment represents a language-level guarantee, e.g. that a naked function could validly rely on this minimum alignment holding when this flag is passed to prove the soundness of its operations -- that from a language spec standpoint, this is equivalent to marking each function with #[align(..)] -- then I'd suggest that a dual FCP with lang here is proper.

cc @rust-lang/lang

folkertdev · 2025-06-22T21:45:46Z

Yeah that sounds right. There is also a bunch of overlap with rfc 3806.

Specifically, it contains a section that attempts to define what alignment values are accepted. #[align] and -Cmin-function-alignment should accept/reject the same values.

traviscross · 2025-06-22T21:53:24Z

@rust-lang/spec: What thoughts do we have about how to handle compiler flags that affect the language definition?

cc @RalfJung

traviscross · 2025-06-22T22:40:53Z

Here's a question. Since this does have language-level effect, might this be better expressed as a crate-level attribute?

If there's a good reason, given the use case, for this to be a compiler flag instead, probably it'd be good to describe that in some detail.

ojeda · 2025-06-22T22:53:41Z

If it can then be applied via --crate-attr similarly, then that should be fine for our use case.

…-alignment, r=workingjubilee centralize `-Zmin-function-alignment` logic tracking issue: rust-lang#82232 discussed in: rust-lang#142824 (comment) Apply the `-Zmin-function-alignment` value to the alignment field of the function attributes when those are created, so that individual backends don't need to consider it. The one exception right now is cranelift, because it can't yet set the alignment for individual functions, but it can (and does) set the global minimum function alignment. cc `@RalfJung` I think this is an improvement regardless, is there anything else that should be done for miri?

…-alignment, r=workingjubilee centralize `-Zmin-function-alignment` logic tracking issue: rust-lang#82232 discussed in: rust-lang#142824 (comment) Apply the `-Zmin-function-alignment` value to the alignment field of the function attributes when those are created, so that individual backends don't need to consider it. The one exception right now is cranelift, because it can't yet set the alignment for individual functions, but it can (and does) set the global minimum function alignment. cc ``@RalfJung`` I think this is an improvement regardless, is there anything else that should be done for miri?

workingjubilee · 2025-06-23T06:15:18Z

Huh. That could be... interesting to work with, since it would logically apply only to entities that originate from that crate, right?

workingjubilee · 2025-06-23T06:21:57Z

@folkertdev Do any of our tests verify that if you

use this option on the functions described in a crate
one is generic or from a trait or otherwise non-instantiated
you instantiate that function in another crate without this flag

Then the resulting function is instantiated with the correct alignment? Where "correct" is... well, pick an answer, I guess?

Rollup merge of #142854 - folkertdev:centralize-min-function-alignment, r=workingjubilee centralize `-Zmin-function-alignment` logic tracking issue: #82232 discussed in: #142824 (comment) Apply the `-Zmin-function-alignment` value to the alignment field of the function attributes when those are created, so that individual backends don't need to consider it. The one exception right now is cranelift, because it can't yet set the alignment for individual functions, but it can (and does) set the global minimum function alignment. cc ``@RalfJung`` I think this is an improvement regardless, is there anything else that should be done for miri?

bors · 2025-06-23T10:38:24Z

☔ The latest upstream changes (presumably #142901) made this pull request unmergeable. Please resolve the merge conflicts.

folkertdev · 2025-06-23T17:36:56Z

@workingjubilee we don't, currently. I think the expected answer is clear though, because -Zmin-function-alignment is applied to all compiled crates, not just the top-level one?

I'm not sure how that would work with #![min_function_alignment = N], because then library crates could set the value as well? So far I've been thinking of this option as similar to -Ctarget-cpu or -Ctarget-feature: they are not properties of a crate but of the compilation as a whole.

What thoughts do we have about how to handle compiler flags that affect the language definition?

Is setting and then relying on the alignment fundamentally different from -Ctarget-feature=+avx2 and then asserting in the program that avx2 is available?

traviscross · 2025-06-23T22:06:27Z

Is setting and then relying on the alignment fundamentally different from -Ctarget-feature=+avx2 and then asserting in the program that avx2 is available?

It's about whether we like this as a safety argument:

/// SAFETY: The pointee must be a 32-byte aligned function.  It's OK
/// for the low-order bits of the function pointer itself to be
/// non-zero, e.g., if they're used for controlling the processor
/// mode.
unsafe fn f(x: fn()) { todo!() }
fn g() {
    let p = g as fn();
    // SAFETY: We compiled with `-Cmin-function-alignment=32`.
    unsafe { f(p) };
}

For avx2, I'd expect that the safety argument would be made by use of cfg(target_feature = ".."), if is_x86_feature_detected!("avx2") { .. }, etc., rather than by using the argument that it was compiled with -Ctarget-feature=+avx2 in the proof.

jieyouxu · 2025-06-24T00:23:10Z

they are not properties of a crate but of the compilation as a whole.

Wait so, does this need to be handled like Target Modifiers?

Higher alignments are not supported in COFF

jieyouxu · 2025-06-29T03:26:37Z

Actually, let my try to use rustbot's concern functionality to make the existing discussions/concerns more explicit.

jieyouxu · 2025-06-29T03:27:18Z

@rustbot concern per-target-vs-universal-max-alignment

Why should it be limited on all platforms? Can't we error when the alignment exceeds the maximum that the actual target we are compiling for supports? Maybe someone genuinely needs to align to 16k on ELF for whatever reason?

jieyouxu · 2025-06-29T03:30:14Z

@rustbot concern hint-vs-language-guarantee-can-be-relied-upon-for-soundness

We should figure out if this is a hint or a language guarantee -- can this be relied upon for soundness?

jieyouxu · 2025-06-29T03:32:22Z

@rustbot concern applicability-current-crate-or-whole-crate-graph

Looks like the current direction is "for the whole crate graph" (potentially "enforced" via Target Modifiers mechanism), but just noting a concern to make sure this is what we explicitly decide to go with.

jieyouxu · 2025-06-29T03:33:51Z

@rustbot concern carve-out-interface-and-behavioral-stability-guarantees

See #142824 (comment)

folkertdev · 2025-06-29T10:36:37Z

I suppose in theory if -Zbuild-std becomes stabilized this might be less of an issue.

My understanding is that target modifiers effectively require -Zbuild-std. From the RFC:

https://github.com/rust-lang/rfcs/blob/master/text/3716-target-modifiers.md#guide-level-explanation

The requirement that all CUs agree includes stdlib crates (core, alloc, std), so using these flags usually requires that you compile your own standard library with -Zbuild-std or by directly invoking rustc. That said, some flags (e.g., -Cpanic) have mechanisms to avoid this requirement.

I also have another question: would -Cmin-function-alignment (whether hint form, or in some theoretical guarantee form) apply to extern functions? I guess why I'm asking is more for the "if this is intended to become a language guarantee", that can code also assume extern functions follow this min alignment?

You mean foreign functions here right (so, declared in an extern "abi" {} block)? Making that assumption would mean that linking to any foreign function that is not appropriately aligned would be UB.

Such a guarantee/requirement would be really restrictive, especially for the performance use-case. I guess RfL does control it's build process sufficiently to guarantee that external C code also follows the alignment, but in general that seems unlikely?

On the other hand, from the outside it's not really clear whether a symbol is a foreign function, or a vanilla rust function.

jieyouxu · 2025-06-29T10:42:26Z

Yeah, I'm assuming that this flag wouldn't apply to extern functions as a hint or guarantee (I don't really see how it meaningfully can). Or rather, if for whatever reason the intended use case is a language guarantee, then in any case reasoning about min alignment of extern functions seems like "well, the burden of ensuring that said extern fns do have the min alignment falls upon the user, if the user wishes to rely upon that for soundness". I'm asking in case there are... interesting or really weird interactions.

@rustbot resolve interaction-with-extern-functions

(Ignore this, this is purely my skill issue)
@rustbot resolve resolve interaction-with-extern-functions

folkertdev · 2025-06-29T11:03:43Z

Well an implication is that you can't, for an arbitrary function pointer, assume that it is well-aligned, because it may be an extern function

folkertdev · 2025-07-02T12:01:47Z

the PR for making -Zmin-function-alignment a target modifier is up at #143323

Jules-Bertholet · 2025-07-02T21:29:15Z

As discovered in #143206 (comment), it looks like LLVM completely ignores function alignment specifications on WASM.

RalfJung · 2025-07-03T12:55:51Z

As discovered in #143206 (comment), it looks like LLVM completely ignores function alignment specifications on WASM.

That's tracked at #143368 now and yeah I assume it also affects this flag.

RalfJung · 2025-07-03T12:57:40Z

@rustbot concern wasm

RalfJung · 2025-07-03T14:50:42Z

@rustbot concern resolve-interaction-with-fn-ptrs

It seems like this does not actually interact with function pointers in any reasonable way, and in particular does not guarantee anything about the integral value of function pointers (see here).

That means this is entirely unobservable in the language itself, i.e. in pure Rust programs. It can only possibly be exploited by inline asm code that observes the layout of the generated machine code. We should make sure this is suitably documented as it is extremely surprising.

bors · 2025-07-07T05:58:07Z

☔ The latest upstream changes (presumably #143556) made this pull request unmergeable. Please resolve the merge conflicts.

RalfJung · 2025-08-01T07:13:20Z

#144661 also relates to this -- const-eval prematurely considered function alignment as a property observable via function pointers, leading to nonsense behavior (arguably that could even be an unsoundness).

workingjubilee · 2025-09-10T04:48:06Z

@folkertdev Please feel free to ping me about this if you need review/guidance/ideas on addressing these concerns and to of course rustbot-ready it when it is indeed ready. I am just whittling down my queue.

folkertdev · 2025-09-11T10:58:10Z

@rustbot blocked

this is effectively blocked on #143323, which in turn needs some sort of decision on the alignment guarantees and limitations (e.g. what to do on targets where the maximum alignment is lower than what LLVM tells us is allowed).

rustbot assigned workingjubilee Jun 21, 2025

bjorn3 reviewed Jun 21, 2025

View reviewed changes

RalfJung reviewed Jun 21, 2025

View reviewed changes

This was referenced Jun 21, 2025

centralize -Zmin-function-alignment logic #142854

Merged

Stabilize fn_align: #[align(N)] on functions #140261

Open

ojeda mentioned this pull request Jun 22, 2025

Rust unstable features needed for the kernel Rust-for-Linux/linux#2

Open

rustbot added the T-lang Relevant to the language team label Jun 22, 2025

folkertdev added 2 commits June 24, 2025 13:36

limit -Zmin-function-alignment to at most 8192 bytes

ae18cc4

Higher alignments are not supported in COFF

stabilize -Cmin-function-aligmnent

2010f9a

rustbot added the S-waiting-on-concerns Status: Awaiting concerns to be addressed by the author label Jun 29, 2025

Urgau mentioned this pull request Jun 29, 2025

Also support concern resolve to resolve concerns rust-lang/triagebot#2090

Merged

folkertdev mentioned this pull request Jul 2, 2025

make -Zmin-function-alignment a target modifier #143323

Open

zachs18 mentioned this pull request Jul 29, 2025

Issue with function alignment in const combined with is_null on platforms with function pointer value not agreeing with function alignment. #144661

Open

workingjubilee added S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Sep 10, 2025

rustbot added S-blocked Status: Blocked on something else such as an RFC or other implementation work. and removed S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Sep 11, 2025

Dylan-DPC removed S-waiting-on-team DEPRECATED: Use the team-based variants `S-waiting-on-t-lang`, `S-waiting-on-t-compiler`, ... I-lang-radar Items that are on lang's radar and will need eventual work or consideration. labels Sep 25, 2025

Stabilize -Cmin-function-alignment #142824

Are you sure you want to change the base?

Stabilize -Cmin-function-alignment #142824

Uh oh!

Conversation

folkertdev commented Jun 21, 2025 • edited by rustbot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Request for Stabilization

Summary

Testing

History

Concerns (6 active)

Uh oh!

rustbot commented Jun 21, 2025

Uh oh!

bjorn3 Jun 21, 2025

Choose a reason for hiding this comment

Uh oh!

folkertdev Jun 21, 2025

Choose a reason for hiding this comment

Uh oh!

folkertdev Jun 21, 2025

Choose a reason for hiding this comment

Uh oh!

workingjubilee Jun 21, 2025

Choose a reason for hiding this comment

Uh oh!

jieyouxu Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RalfJung Jun 21, 2025

Choose a reason for hiding this comment

Uh oh!

RalfJung Jun 21, 2025

Choose a reason for hiding this comment

Uh oh!

RalfJung Jul 3, 2025

Choose a reason for hiding this comment

Uh oh!

traviscross commented Jun 22, 2025

Uh oh!

folkertdev commented Jun 22, 2025

Uh oh!

traviscross commented Jun 22, 2025

Uh oh!

traviscross commented Jun 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ojeda commented Jun 22, 2025

Uh oh!

workingjubilee commented Jun 23, 2025

Uh oh!

workingjubilee commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bors commented Jun 23, 2025

Uh oh!

folkertdev commented Jun 23, 2025

Uh oh!

traviscross commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jieyouxu commented Jun 24, 2025

Uh oh!

jieyouxu commented Jun 29, 2025

Uh oh!

jieyouxu commented Jun 29, 2025

Uh oh!

jieyouxu commented Jun 29, 2025

Uh oh!

jieyouxu commented Jun 29, 2025

Uh oh!

jieyouxu commented Jun 29, 2025

Uh oh!

folkertdev commented Jun 29, 2025

Uh oh!

jieyouxu commented Jun 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Stabilize `-Cmin-function-alignment` #142824

Stabilize `-Cmin-function-alignment` #142824

folkertdev commented Jun 21, 2025 •

edited by rustbot

Loading

jieyouxu Jun 24, 2025 •

edited

Loading

traviscross commented Jun 22, 2025 •

edited

Loading

workingjubilee commented Jun 23, 2025 •

edited

Loading

traviscross commented Jun 23, 2025 •

edited

Loading

jieyouxu commented Jun 29, 2025 •

edited

Loading