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#1689
(Previous PR: 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 resolved by 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 resolved by 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.

[bors]

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

[U007D]

Therefore it makes sense to move the unsafe outward to the attribute and say that what we mean in doing that is to extend the scope of discharge to the entire function, exactly as if we had item-level unsafe, as above. So we'll write:

#[unsafe(naked)]
extern "sysv64" fn f() {
    naked_asm! {
        ..
    }
}

Pleasingly, this also avoids some rightward drift.

I, too, would prefer to write the above.

I'm concerned though, that this may be inconsistent with other uses of unsafe attributes. Do all unsafe attributes extend the scope of their unsafe over the proceeding item? For example:

#[unsafe(no_mangle)]
pub fn example() { /* Are we within `unsafe` scope here? */ }

(The unsafe attribute docs appear to be silent on this question, at least AFAICT. Until reading this thread, I had not really contemplated the question and (naively?) assumed no unsafe scope-extension.)

If the answer is 'yes', then this is proposal is consistent and I'm in support. But if not, this seems inconsistent with other unsafe attributes and would represent a "wart" or "gotcha" (however small) in the language.

Thoughts?

[traviscross]

I'm concerned though, that this may be inconsistent with other uses of unsafe attributes. Do all unsafe attributes extend the scope of their unsafe over the proceeding item? For example:

#[unsafe(no_mangle)]
pub fn example() { /* Are we within `unsafe` scope here? */ }

In a sense, yes, we are. If we write,

#[unsafe(no_mangle)]
pub extern "C" fn malloc(x: isize) -> *mut c_void { .. }

then whether the resulting program is valid is going to necessarily depend on the body of that function. Even if we don't use unsafe anywhere within that body, we still have a safety obligation to discharge that extends across the signature and the entire body (setting aside what might be our build obligations also).

It's similar here. Removing the function prelude, like stepping on malloc, binds together the function signature and its body into one safety obligation that we're discharging together.

[traviscross]

On the procedurals here, @folkertdev, I've been watching with interest the dance we're doing in:

• Make #[naked] an unsafe attribute #139753
• Allow (but don't require) #[unsafe(naked)] so that compiler-builtins can upgrade to it #139797
• use #[naked] as an unsafe attribute compiler-builtins#817
• try using #[cfg(bootstrap)] for #[unsafe(naked)] compiler-builtins#821
• Update compiler-builtins to 0.1.155 #139934

Once this is all settled, please give this PR a @rustbot ready.

@tgross35: Since you've been involved in those steps, I'd be interested in seeing your approving review on the implementation details of this PR.

And, @Amanieu, as always on asm-related matters, I'd be interested to see your approving review here as well.

Once it's ready, I'll give it a final look over myself and, if it has these approving reviews, give it the r= directly, or assign it off for that.

[tgross35]

I did take a thorough look at this before and it all seems correct to my knowledge. I'll re-review once #139753 lands, but I am very much +1 on having this stabilized.

The only usage comment I have is that it would be nice if we could #[cfg] within naked_asm! somehow so small platform-specific changes don't mean the entire function needs to be duplicated. Definitely something for after stabilization though, since it affects global_asm as well.

[folkertdev]

I just found this

rust/compiler/rustc_passes/src/check_attr.rs

Lines 693 to 699 in 191df20

	// FIXME(#80564): We permit struct fields, match arms and macro defs to have an
	// `#[naked]` attribute with just a lint, because we previously
	// erroneously allowed it and some crates used it accidentally, to be compatible
	// with crates depending on them, we can't throw an error here.
	Target::Field | Target::Arm | Target::MacroDef => {
	self.inline_attr_str_error_with_macro_def(hir_id, attr, "naked")
	}

There are similar comments on a number of other attributes, but is this something that could/should be fixed as we stabilize this attribute?

[traviscross]

There are similar comments on a number of other attributes, but is this something that could/should be fixed as we stabilize this attribute?

Good catch. Yes. Specifically, this is a hard error currently (without the feature flag):

struct S {
    #[naked] //~ ERROR
    field: (),
}

I can't imagine that we'd want this to become allowed on stable due to us stabilizing naked_functions.

[traviscross]

I'm surprised about some of the other places this exception is made also in the code. I can't imagine that we want it for #[marker] either, and I'd be surprised if any nightly users had actually relied on that or that we would particularly care even if they had. It and any other exceptions for unstable attributes seem likely to set up a stabilization hazard for us, and I'd be curious to hear if there are any reasons that all such cases shouldn't be removed.

[traviscross]

cc #80564

[Amanieu]

The stabilization PR LGTM, so r=me.

[rustbot]

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

cc @jdonszelmann

[folkertdev]

I believe everything is in now, I've just rebased on master.

@rustbot ready

Thanks everyone for the help here!

[tgross35]

LGTM as well

[greaka]

The only usage comment I have is that it would be nice if we could #[cfg] within naked_asm! somehow so small platform-specific changes don't mean the entire function needs to be duplicated.

Is there an issue to follow this specifically? It's already a problem when using global_asm.

[traviscross]

Thanks for those reviews. Looks like we haven't quite finished reviewing the Reference PR, so we'll do that quickly and then move this along.