Stabilize fn_align: #[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 #[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:

#[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 #[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

reference PR: rust-lang/reference#1866

Tests

• tests/codegen/min-function-alignment.rs tests the behavior of the -Zmin-function-alignment flag and how it interacts with #[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).

In rust-lang/rfcs#3806 it was decided to use #[align] for the attribute, rather than the earlier #[repr(align)].

Notes

• Triage meeting 2025-04-23

Resolved questions

Support for per-function alignment in cranelift is blocked on 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?

Cranelift support is not required. There are already many features that it does not support, support for this feature will land eventually.

What should #[align(N)] do for an async fn, maybe this should not be supported for now?

rust-lang/rfcs#3806 specifies that the #[align] is applied to the function that returns the Future.

alignments larger than a page size are not supported for all targets (see #82232 (comment), #70022, #70144). The current upper bound of 2.pow(29) is what LLVM accepts, but maybe we should cap it at a lower number (that can be raised later if the need arises).

This was discussed in rust-lang/rfcs#3806 (comment), but the final RFC text says to mirror #[repr(align(...))]. If the rules for #[repr(align(...))] ever change, #[align] will have to follow suit.

unresolved questions

None

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

[traviscross]

We talked about this at some length in the @rust-lang/lang call today. In particular, we focused on whether to spell this #[repr(align(..))] or #[align(..)].

We looked at @Jules-Bertholet's pre-RFC here:

https://internals.rust-lang.org/t/pre-rfc-align-attribute/21004/27

We were interested, @Jules-Bertholet, in seeing that made into an RFC, and we'd invite you to submit that and nominate it for us.

It does feel to me that #[align(..)] makes more sense on a static than #[repr(align(..))], and in that context, functions seem more like statics to me -- and did to many on the call -- than they do structs.

We did discuss whether maybe it should just be #[align(..)] everywhere, but not all of us were sold on that and thought it possible there might be a distinction worth making. Niko outlined these thoughts in the meeting:

• Observations:
  • It is "odd" to have repr(align) on a function. I don't know why, it just feels weird.
  • Most things in repr don't belong on functions (e.g., repr(C), repr(packed)).
  • But #[align] on functions is fairly niche.
  • It seems odd to write align in two different ways on structs/functions.
  • I think you could split out alignment from the rest of repr (e.g., it is about where the struct is placed vs the layout of its fields, align doesn't impact the latter).
  • I like having repr as the place to go lookup your options to control struct layout and alignment feels "close enough" to that.
• Thought exercise:
  • Imagine the docs on repr if it applies to both functions and structs.
    • They'll say "repr can be used on many kinds of items but the relevant items are different depending on the kind of item". And functions will look totally different.
  • Imagine the docs on repr if align is not part of it.
    • They'll no doubt say "If you want to control alignment, you need the alignment attribute", which feels weird.
• Conclusion:
  • Not sure yet.

For my part, I agree with all of those considerations.

We wanted to open it up for the thoughts of others to see what other good ideas or arguments here might emerge. What do you think?

[Jules-Bertholet]

We were interested in seeing that made into an RFC, and we'd invite you to submit that and nominate it for us.

I’m hesitant to do so at present because I don’t know enough about MSVC to be confident that its alignment-related weirdness won’t be a problem. I don't want the RFC comments to turn into a rehash of the same issues being debated at rust-lang/rfcs#3718. I would want to either see that settled and merged, or for the lang team to agree that they would be interested in the RFC even with those parts left explicitly unresolved.

[folkertdev]

It is "odd" to have repr(align) on a function. I don't know why, it just feels weird.

Yes, 100%.

But #[align] on functions is fairly niche.

Yes, it's mostly embedded and OS projects from what I can tell. These same projects would also get a bunch of mileage out of #[align] on statics though, and I strongly agree that functions feel more like statics.

It seems odd to write align in two different ways on structs/functions.

Accepting #[align = 8] struct Foo; actually seems fine to me.

---

Imagine the docs on repr if it applies to both functions and structs.

I really like this framing!

Currently the reference for the repr(...) attribute lives here at type layout >> representations, and talks about the alignment modifiers. From that section:

For align, if the specified alignment is less than the alignment of the type without the align modifier, then the alignment is unaffected.

The language of this section is in terms of types. That makes sense, and is useful. It can be reworked, but I think including functions and statics here would get messy.

The align modifier can also be applied on an enum. When it is, the effect on the enum’s alignment is the same as if the enum was wrapped in a newtype struct with the same align modifier.

The existing text already has some trouble with struct, union and enum. Adding fn and static in there too in a coherent way would be challenging I think.

There is also https://doc.rust-lang.org/nomicon/other-reprs.html#repralignn, again under the "data layout" heading, but honestly that could probably use some work (an example, talking about addresses, maybe other things).

---

@Jules-Bertholet that's understandable. From my listening in to the conversation, it seemed like what T-lang is looking for is some sort of coherent design for #[align], and reasoning for why it is different from #[repr(align(n))]: adding #[align] just for functions seems like it doesn't pull its weight, but if it can also be use for statics, or even for individual fields, then maybe it is worth adding.

---

A procedural question, given that resolving these questions around the attribute will likely take a while: what would the process be for just stabilizing the -Cmin-function-alignment flag? So far there are no concerns about it, so could I just split that out? Then, would that just require FCP from the compiler team, or is T-lang still involved?

[traviscross]

what would the process be for just stabilizing the -Cmin-function-alignment flag? So far there are no concerns about it, so could I just split that out? Then, would that just require FCP from the compiler team, or is T-lang still involved?

In my view, we'd still want lang on that, as it amounts to adding #[align(..)] to all functions, with all the user-visible semantic guarantees about the language doing that implies.

Probably I'd just suggest giving us a little while to see if we can sort this out as-is.

We were interested in seeing that made into an RFC, and we'd invite you to submit that and nominate it for us.

I’m hesitant to do so at present because I don’t know enough about MSVC to be confident that its alignment-related weirdness won’t be a problem. I don't want the RFC comments to turn into a rehash of the same issues being debated at rust-lang/rfcs#3718. I would want to either see that settled and merged, or for the lang team to agree that they would be interested in the RFC even with those parts left explicitly unresolved.

@Jules-Bertholet, like @folkertdev said, we're mostly interested here in whether there's a coherent notion of #[align(..)] that's separate from #[repr(align(..))], and if so, what that looks like. If perhaps there's a way to narrow the scope of the RFC to help with that and maybe sidestep the other problem, maybe that's worth doing. Otherwise, we can talk about what we might be able to say about the handling of the unresolved question you mention.

[Jules-Bertholet]

RFC is up: rust-lang/rfcs#3806

[traviscross]

@rustbot labels -I-lang-nominated +I-lang-radar

Let's drop the nomination temporarily to first tackle rust-lang/rfcs#3806.

[bors]

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

[rustbot]

Some changes occurred in compiler/rustc_attr_parsing

cc @jdonszelmann

[rustbot]

Some changes occurred in compiler/rustc_codegen_cranelift

cc @bjorn3

[folkertdev]

Now that we've agreed on using #[align] for functions, I think we can move forward here?

I've made a reference PR at rust-lang/reference#1866, and split out one final change to an error message into #142715 so that the stabilization PR can be a bit cleaner.

[traviscross]

If you could, let's please answer each of the unresolved questions in the PR description, or link to the answer for each.

[folkertdev]

I've provided the answers, linking back to the RFC text/discussion.

For the cranelift question I've used my judgement: nobody has objected to going ahead here without cranelift support, that backend has many unsupported features, and support will arrive eventually (i.e. there is no fundamental limitation, it's just not supported yet).

[traviscross]

@Jules-Bertholet: I'm interested in seeing your approving review that everything in this stabilization is what you'd expect given the RFC.

[Jules-Bertholet]

@traviscross LGTM, as far as #[align(…)] goes. (-Cmin-function-alignment isn’t part of the RFC, so I have nothing to say about that.)

[traviscross]

@wesleywiser / @davidtwco / @apiraino: If you could, I'd be interested in your confirmation that all the necessary steps have been taken to lead up to proposing -Cmin-function-alignment=<n> for stabilization. Are you happy handling this together with the lang stabilization in this PR with a dual lang / compiler proposed FCP, or would you prefer to see this broken out or handled otherwise?