Stabilize naked_functions

[folkertdev]

tracking issue: #90957
request for stabilization on tracking issue: #90957 (comment)
reference PR: rust-lang/reference#1689

Request for Stabilization

Two years later, we're ready to try this again. Even though this issue is already marked as having passed FCP, given the amount of time that has passed and the changes in implementation strategy, we should follow the process again.

Summary

The naked_functions feature has two main parts: the #[naked] function attribute, and the naked_asm! macro.

An example of a naked function:

const THREE: usize = 3;

#[naked]
pub extern "sysv64" fn add_n(number: usize) -> usize {
    // SAFETY: the validity of the used registers 
    // is guaranteed according to the "sysv64" ABI
    unsafe {
        core::arch::naked_asm!(
            "add rdi, {}",
            "mov rax, rdi",
            "ret",
            const THREE,
        )
    }
}

When the #[naked] attribute is applied to a function, the compiler won't emit a function prologue or epilogue when generating code for this function. This attribute is analogous to __attribute__((naked)) in C. The use of this feature allows the programmer to have precise control over the assembly that is generated for a given function.

The body of a naked function must consist of a single naked_asm! invocation, a heavily restricted variant of the asm! macro: the only legal operands are const and sym, and the only legal options are raw and att_syntax. In lieu of specifying operands, the naked_asm! within a naked function relies on the function's calling convention to determine the validity of registers.

Documentation

The Rust Reference: rust-lang/reference#1153

Tests

• tests/run-make/naked-symbol-visiblity verifies that pub, #[no_mangle] and #[linkage = "..."] work correctly for naked functions
• tests/codegen/naked-fn has tests for function alignment, use of generics, and validates the exact assembly output on linux, macos, windows and thumb
• tests/ui/asm/naked-* tests for incompatible attributes, generating errors around incorrect use of naked_asm!, etc

Interaction with other (unstable) features

fn_align

Combining #[naked] with #[repr(align(N))] works well, and is tested e.g. here

• https://github.com/rust-lang/rust/blob/master/tests/codegen/naked-fn/aligned.rs
• https://github.com/rust-lang/rust/blob/master/tests/codegen/naked-fn/min-function-alignment.rs

It's tested extensively because we do need to explicitly support the repr(align) attribute (and make sure we e.g. don't mistake powers of two for number of bytes).

History

This feature was originally proposed in RFC 1201, filed on 2015-07-10 and accepted on 2016-03-21. Support for this feature was added in #32410, landing on 2016-03-23. Development languished for several years as it was realized that the semantics given in RFC 1201 were insufficiently specific. To address this, a minimal subset of naked functions was specified by RFC 2972, filed on 2020-08-07 and accepted on 2021-11-16. Prior to the acceptance of RFC 2972, all of the stricter behavior specified by RFC 2972 was implemented as a series of warn-by-default lints that would trigger on existing uses of the naked attribute; these lints became hard errors in #93153 on 2022-01-22. As a result, today RFC 2972 has completely superseded RFC 1201 in describing the semantics of the naked attribute.

More recently, the naked_asm! macro was added to replace the earlier use of a heavily restricted asm! invocation. The naked_asm! name is clearer in error messages, and provides a place for documenting the specific requirements of inline assembly in naked functions.

The implementation strategy was changed to emitting a global assembly block. In effect, an extern function

extern "C" fn foo() {
    core::arch::naked_asm!("ret")
}

is emitted as something similar to

core::arch::global_asm!( 
    "foo:",
    "ret"
);

extern "C" {
    fn foo();
}

The codegen approach was chosen over the llvm naked function attribute because:

• the rust compiler can guarantee the behavior (no sneaky additional instructions, no inlining, etc.)
• behavior is the same on all backends (llvm, cranelift, gcc, etc)

Finally, there is now an allow list of compatible attributes on naked functions, so that e.g. #[inline] is rejected with an error. The #[target_feature] attribute on naked functions was later made separately unstable, because implementing it is complex and we did not want to block naked functions themselves on how target features work on them. See also #138568.

relevant PRs for these recent changes

• #[naked]: report incompatible attributes #127853
• add naked_asm! macro for use in #[naked] functions #128651
• codegen #[naked] functions using global asm #128004
• add naked_functions_target_feature unstable feature #138570

Various historical notes

noreturn

RFC 2972 mentions that naked functions

must have a body which contains only a single asm!() statement which:
iii. must contain the noreturn option.

Instead of asm!, the current implementation mandates that the body contain a single naked_asm! statement. The naked_asm! macro is a heavily restricted version of the asm! macro, making it easier to talk about and document the rules of assembly in naked functions and give dedicated error messages.

For naked_asm!, the behavior of the asm!'s noreturn option is implicit. The noreturn option means that it is UB for control flow to fall through the end of the assembly block. With asm!, this option is usually used for blocks that diverge (and thus have no return and can be typed as !). With naked_asm!, the intent is different: usually naked funtions do return, but they must do so from within the assembly block. The noreturn option was used so that the compiler would not itself also insert a ret instruction at the very end.

padding / ud2

A naked_asm! block that violates the safety assumption that control flow must not fall through the end of the assembly block is UB. Because no return instruction is emitted, whatever bytes follow the naked function will be executed, resulting in truly undefined behavior. There has been discussion whether rustc should emit an invalid instruction (e.g. ud2 on x86) after the naked_asm! block to at least fail early in the case of an invalid naked_asm!. It was however decided that it is more useful to guarantee that #[naked] functions NEVER contain any instructions besides those in the naked_asm! block.

unresolved questions

None

r? @Amanieu

I've validated the tests on x86_64 and aarch64

[rustbot]

Some changes occurred in src/doc/unstable-book/src/compiler-flags/sanitizer.md

cc @rust-lang/project-exploit-mitigations, @rcvalle

This PR modifies tests/run-make/. If this PR is trying to port a Makefile
run-make test to use rmake.rs, please update the
run-make port tracking issue
so we can track our progress. You can either modify the tracking issue
directly, or you can comment on the tracking issue and link this PR.

cc @jieyouxu

rust-analyzer is developed in its own repository. If possible, consider making this change to rust-lang/rust-analyzer instead.

cc @rust-lang/rust-analyzer

Some changes occurred in compiler/rustc_codegen_cranelift

cc @bjorn3

[bors]

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

[Amanieu]

r? lang

[Amanieu]

This probably needs a new lang FCP since the old one is probably outdated (the implementation of naked function has changed signficantly).

[tmandry]

Thanks for the thorough report @folkertdev!

@rfcbot fcp merge

[rfcbot]

Team member @tmandry has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se
• @nikomatsakis
• @scottmcm
• @tmandry
• @traviscross

Concerns:

• maybe-unsafe-attribute (Stabilize naked_functions #134213 (comment))
• mention-nop-padding-and-ud2 resolved by Stabilize naked_functions #134213 (comment)
• question-about-noreturn resolved by Stabilize naked_functions #134213 (comment)
• question-about-rust-abi (Stabilize naked_functions #134213 (comment))
• question-about-unwind resolved by Stabilize naked_functions #134213 (comment)
• what-to-do-for-target-feature resolved by Stabilize naked_functions #134213 (comment)

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

cc @rust-lang/lang-advisors: FCP proposed for lang, please feel free to register concerns.
See this document for info about what commands tagged team members can give me.

[tmandry]

Actually, @rust-lang/libs-api does this need your FCP? I think the path of core::arch::naked_asm! is the only part that might.

[jieyouxu]

Question: does #![feature(naked_functions)] have any iteractions with #![feature(fn_align)]? In particular, are there any potential caveats or gotchas that stabilizing naked_functions may have for fn_align in the future?

(The test is irrelevant, I just wanted to force an inline comment)

[folkertdev]

Combining #[naked] with #[repr(align(N))] works well, and is tested e.g. here

• https://github.com/rust-lang/rust/blob/master/tests/codegen/naked-fn/aligned.rs
• https://github.com/rust-lang/rust/blob/master/tests/codegen/naked-fn/min-function-alignment.rs

It's tested extensively because we do need to explicitly support the repr(align) attribute (and make sure we e.g. don't mistake powers of two for number of bytes).

[traviscross]

It'd be worth including what you just mentioned here in the stabilization report.

[veluca93]

@rfcbot concern maybe-unsafe-attribute

When we accepted the relevant RFC, we hadn't yet done unsafe attributes. Looking at it now, I wonder if it shouldn't be #[unsafe(naked)]. It seems a bit strange for it not to be, given what it does. As the Reference PR says:

The naked attribute prevents the compiler from emitting a function prologue and epilogue for the attributed function.

That sounds rather unsafe!

Of course, we could argue that, "well, you can't actually create unsafety without the inner unsafe { .. }", but still.

More radically, we could ask whether maybe naked_asm! should not need to be wrapped in unsafe { .. } at all because we could consider the obligation discharged by the #[unsafe(naked)]. That's almost appealing in a way, since this is the only thing that's allowed in the body, and this macro call can only appear in such bodies, and it would have somewhat better ergonomics by avoiding an additional kind-of-useless level of indentation. E.g.:

#[unsafe(naked)]
#[unsafe(no_mangle)]
pub extern "sysv64" fn f() -> ! {
    core::arch::naked_asm!(
        "ud2",
    )
}

What do we think?

My 2 cents: +1 on making the attribute unsafe; I am not sure if I would then want to see the naked_asm macro not require unsafe (it's somewhat redundant, but as this is wildly unsafe...)

Also, just to make sure I understand correctly, the following would not compile, right?

#[naked]
pub extern "sysv64" fn f() {}

It is obviously unsound, without actually containing an unsafe block, as calling this function would start executing padding bytes, so it should be disallowed.

If that's the case, then it's impossible to write a naked function without writing unsafe inside it, which sounds like a pretty convincing argument to make it an unsafe attribute...

[RalfJung]

Could someone explain the interaction with target features? I would have expected that attribute to be completely useless on a naked function -- if I want to use AVX instructions, I just put them in the asm block, and that implicitly imposes a requirement that AVX must be available, but the compiler doesn't actually have to know about this?

[traviscross]

@rfcbot resolve question-about-unwind

As @Amanieu mentioned, naked functions do support unwinding, and the Reference PR has been updated to reflect and describe this. It looks like this:

#![feature(naked_functions)]

#[unsafe(no_mangle)]
pub extern "sysv64-unwind" fn g() {
    panic!();
}

#[cfg(target_arch = "x86_64")]
#[naked]
#[unsafe(no_mangle)]
pub extern "sysv64-unwind" fn f() {
    unsafe {
        core::arch::naked_asm!(
            ".cfi_startproc",
            "push rbp",
            ".cfi_adjust_cfa_offset 8",
            ".cfi_offset rbp, -16",
            "mov rbp, rsp",
            ".cfi_def_cfa_register rbp",
            "call {f}",
            "pop rbp",
            ".cfi_def_cfa rsp, 8",
            "ret",
            ".cfi_endproc",
            f = sym g,
        )
    }
}

Playground link (with further annotations)

[bjorn3]

Could someone explain the interaction with target features? I would have expected that attribute to be completely useless on a naked function -- if I want to use AVX instructions, I just put them in the asm block, and that implicitly imposes a requirement that AVX must be available, but the compiler doesn't actually have to know about this?

On many targets LLVM refuses to assemble instructions unless the target feature that they got introduced with is enabled. Target features can also affect the exact encoding of instructions I believe.

[veluca93]

Could someone explain the interaction with target features? I would have expected that attribute to be completely useless on a naked function -- if I want to use AVX instructions, I just put them in the asm block, and that implicitly imposes a requirement that AVX must be available, but the compiler doesn't actually have to know about this?

On many targets LLVM refuses to assemble instructions unless the target feature that they got introduced with is enabled. Target features can also affect the exact encoding of instructions I believe.

Isn't that something that can be toggled within a naked_asm block?

[folkertdev]

Isn't that something that can be toggled within a naked_asm block?

In most cases yes, using assembler directives. Those depend on the architecture. E.g.

• x86_64 just accepts anything anywhere
• aarch64 has e.g. .arch_extension neon and .arch_extension noneon
• riscv has .option push and .option pop and then .option +somefeature
• wasm currently has nothing
• arm is a mess with fpu, arch, cpu and arch_extension interacting in a bunch of ways and no clean way of getting back to the original state

To me, the appeal of #[naked] over just some global assembly is that it looks and feels just like a normal function. Target features currently break the illusion by emitting unexpected errors.

It does not seem feasible to me to make target features work seamlessly for naked functions: on wasm LLVM gives us no tools for it, for arm it's horribly complex, and even for the other targets every target feature would need to be tested to make sure it actually works (because rust target features don't map one-to-one with what the assembler understands).

But (and I overlooked this before) #[target_feature] is also relevant for ABI reasons: it influences which registers are used to pass arguments and return values, e.g. https://godbolt.org/z/xW4cW3dor. That is highly relevant for naked functions which rely on the ABI of the function to get at their arguments and put the return value in the right place.

So I think that leaves 2 plausible options

1. allow #[target_feature], but only have it influence ABI (no assembler directives are emitted)
2. keep #[target_feature] on naked functions unstable
   • we could have an allowlist for target features and architectures where we can guarantee correct behavior. This list could at least cover the common vector ABI cases.
   • there could be a custom error pointing to documentation on the right assembler directives for common targets

I have concerns about option 1 because it can cause some extremely confusing errors, e.g. this would error

https://godbolt.org/z/89GhGzqW4

#[naked]
#[no_mangle]
#[target_feature(enable = "aes")]
unsafe extern "C" fn aes_encrypt(a: uint8x16_t, round_key: uint8x16_t) -> uint8x16_t {
    core::arch::naked_asm!(
        "aese v0.16b, v1.16b",  
        "ret",
    );
}

Saying that aes is not enabled, but it clearly is in the source!

error: instruction requires: aes
  |
note: instantiated into assembly here
 --> <inline asm>:6:1
  |
6 | aese v0.16b, v1.16b
  | ^

error: aborting due to 1 previous error; 9 warnings emitted

moreover, the non-naked version of this function does work!

#[no_mangle]
#[target_feature(enable = "aes")]
unsafe extern "C" fn non_naked_inline_asm(a: uint8x16_t, round_key: uint8x16_t) -> uint8x16_t {
    core::arch::asm!(
        "aese {0:v}.16b, {1:v}.16b", 
        "ret",
        in(vreg) a, in(vreg) round_key, options(noreturn)
    );
}

I suppose we could try to parse the LLVM error and try to emit a custom error message mentioning target features (and specifically how they behave on naked functions)? I brought up parsing the error before though #121496 and others seemed sceptical.

[veluca93]

I'm afraid the situation is somewhat more complex than that -- if you use a SIMD type by value without declaring the target feature on the function, nowadays you get a warning, but we're planning for that to become a hard error.

I'd argue that it should be sufficient to write in the documentation of naked_asm that it just emits raw ASM, independent of the context (or some variation thereof) -- I'd imagine that naked functions and naked_asm are fairly niche features, and I think I would be OK with users needing to read the documentation quite carefully.

[onestacked]

Is there any reason for not just moving #[naked] with a #[target_feature] to a separate feature gate and stabilize naked_function without this for now?

[RalfJung]

Okay this seem to mostly be about the technical difficulties of passing targey features to the assemblee then, I have no idea at all about things like that. We can map our tatget feature names to the ones LLVM uses easily, we already do that. Is that not enough? If LLVM does not let us set the targey features on naked functions the same way we set it on all other functions, then we'd have to duplicate a lot of the backend specific logic inside LLVM, right? That sounds terrible.

But (and I overlooked this before) #[target_feature] is also relevant for ABI reasons: it influences which registers are used to pass arguments and return values, e.g. https://godbolt.org/z/xW4cW3dor. That is highly relevant for naked functions which rely on the ABI of the function to get at their arguments and put the return value in the right place.

Every such case is a soundness bug (and we should we emitting a future compat warning already). Some types require certain target features to be passable, but the presence or absence of a target feature must only affect whether the code builds.

[folkertdev]

catching up to some comments

---

Of course, we could argue that, "well, you can't actually create unsafety without the inner unsafe { .. }", but still.

Yes that is what I would argue :)

from the edition guide

Rust 1.82 added the ability in all editions to mark certain attributes as unsafe to indicate that they have soundness requirements that must be upheld

There are no soundness requirements to a naked function itself. The requirements are on the naked_asm!, which is already covered by an unsafe block. What additional value does making the attribute itself unsafe have?

---

Also, just to make sure I understand correctly, the following would not compile, right?

#[naked]
pub extern "sysv64" fn f() {}

It is obviously unsound, without actually containing an unsafe block, as calling this function would start executing padding bytes, so it should be disallowed.

Correct, that is tested here:

rust/tests/ui/asm/naked-functions.rs

Lines 79 to 81 in ed897d5

	#[naked]
	pub extern "C" fn missing_assembly() {
	//~^ ERROR naked functions must contain a single `naked_asm!` invocation

---

We can map our target feature names to the ones LLVM uses easily, we already do that. Is that not enough?

Sadly not. LLVM target features are also just made-up names that don't always map to the names that the assembler uses. E.g. the arm trustzone feature is known in the assembler as sec (for security, I guess). Most targets behave much more reasonably but some clearly don't.

---

Is there any reason for not just moving #[naked] with a #[target_feature] to a separate feature gate and stabilize naked_function without this for now?

That is my proposed course of action. So far nobody seems to really be against this approach, so if things stay that way I'll make a PR.

[RalfJung]

LLVM target features are also just made-up names that don't always map to the names that the assembler uses.

And I guess we can't send the naked function "through" LLVM to let it do the translation?

That might be a good feature request for them...

Is there any reason for not just moving #[naked] with a #[target_feature] to a separate feature gate and stabilize naked_function without this for now?

Sounds good to me.

[folkertdev]

And I guess we can't send the naked function "through" LLVM to let it do the translation?

No that was the original design, but it was rejected for various reasons:

• LLVM would insert additional instructions in some cases (or at least did not guarantee that it would not)
• we have non-LLVM backends that would need to handle this logic too

Some further context from the tracking issue:

#90957 (comment)
#90957 (comment)

[RalfJung]

we have non-LLVM backends that would need to handle this logic too

As they should. They have to deal with target feature names anyway for regular code.

Anyway, I am mostly clueless here, just poking a bit in the dark to feel out the design space. @Amanieu knows a lot better than me how to make inline assembly work well. :)

[bors]

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

[bors]

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

[folkertdev]

The #[target_feature] attribute on naked functions is now separately guarded by the naked_functions_target_feature feature. I think that should resolve the concern here around target features.

tracking issue: #138568
PR: #138570

---

Looking at the other concerns, noreturn has been added to the historical notes in the stabilization report, and padding/ud2 are now mentioned there too. Unless there is something else, I think these are also resolved?

The current remaining concerns are then:

• question-about-rust-abi: looks like the consensus is that using the rust abi should not be explicitly disallowed, even though it is extremely unsafe to use it? Note that to use it, you must use extern "Rust" fn, a standard fn triggers a lint.
• maybe-unsafe-attribute: it's been discussed. I don't personally see much value in it, but if anyone wants to really argue in favor, please do?

---

As they should. They have to deal with target feature names anyway for regular code.

Ah, I misunderstood this earlier. What I meant is that we could have used llvm's native support for naked functions, which has the downsides that I and Amanieu mentioned.

I think you propose to still use global assembly, but somehow inform the backend of the target features. That would be neat, but can't currently be done even in LLVM.

[onestacked]

Is there a practical reason to allow extern "Rust" fn?

I think unless there is a specific need for it it would be best to disallow it (From an mostly outsider perspective, I'm not really familiar with the state of Rust ABI and the current state of naked functions).
From what I understand Rust ABI is not stable, so I don't expect it to be very useful but I might be missing something?

[tgross35]

Linting on extern "Rust" fn seems reasonable to me, but I don't think we should forbid it. It's useful for experimentation and possibly internal tests, if nothing else.

[traviscross]

The #[target_feature] attribute on naked functions is now separately guarded by the naked_functions_target_feature feature. I think that should resolve the concern here around target features.

tracking issue: #138568
PR: #138570

Sounds right. Thanks for filing the new tracking issue.

@rfcbot resolve what-to-do-for-target-feature

---

Looking at the other concerns, noreturn has been added to the historical notes in the stabilization report, and padding/ud2 are now mentioned there too. Unless there is something else, I think these are also resolved?

They are. Thanks for adding these notes. The rationales and outcomes there seem right to me.

@rfcbot resolve question-about-noreturn
@rfcbot resolve mention-nop-padding-and-ud2

---

The current remaining concerns are then...

These probably need to be discussed with the team. We'll take them up in a lang call.