naked functions #1689

folkertdev · 2024-12-01T15:56:02Z

tracking issue: rust-lang/rust#90957
earlier version: #1153

Pending on rust-lang/rust#128004. Once merged, we'll move for stabliziation.

I'm working off of the original PR to the reference, written 2+ years ago when the reference was less strict. I suspect some refinement and editing will be needed here to satisfy the quality requirements of the spec, and update the text to accurately reflect the current state and the exact guarantees/requirements.

Stabilization PR:

Stabilize naked_functions rust#134213

cc @bstrie @traviscross @Amanieu @bjorn3

src/attributes/codegen.md

src/inline-assembly.md

Amanieu · 2024-12-01T17:40:33Z

src/inline-assembly.md

+- The compiler cannot assume that the instructions in the asm are the ones that will actually end up executed.
+  - This effectively means that the compiler must treat the `naked_asm!` as a black box and only take the interface specification into account, not the instructions themselves.
+  - Runtime code patching is allowed, via target-specific mechanisms.
+  - However there is no guarantee that each `naked_asm!` directly corresponds to a single instance of instructions in the object file: the compiler is free to duplicate or deduplicate `naked_asm!` blocks.


This is not true, naked functions cannot be duplicated/merged, unlike asm!.

and reading this over, in this case it seems important that we do actually guarantee (and hence the compiler can assume) that the instructions in the naked_asm! invocation are exactly the ones that will be executed. or is that too strict?

I think that poses problems on SPIR-V or NVPTX targets. I seem to recall that the loader just inlines the functions at the Shader Assembly level.

@chorman0773 just to be sure, you're referring to Amanieu's comment right?

What we do in rustc (or well, we will once that PR makes it through the queue) is that a naked function

#[naked] extern "C" fn foo() {}

is emitted as something similar to

core::arch::global_asm!( "foo:", "ret" ); extern "C" { fn foo(); }

and we're relying on the compiler (rustc, llvm) not duplicating that bit of global assembly. I suspect we already rely on that in general, because global assembly can define symbols today.

If you still think this is problematic, how could we verify the behavior of this new codegen strategy for the targets you list?

and reading this over, in this case it seems important that we do actually guarantee (and hence the compiler can assume) that the instructions in the naked_asm! invocation are exactly the ones that will be executed. or is that too strict?

No, they may not be the same instructions that are executed since you can still do runtime patching. We only guarantee that assembly code only appears once in the object file for the purposes of symbols.

src/inline-assembly.md

src/attributes/codegen.md

src/inline-assembly.md

folkertdev · 2025-03-07T19:46:19Z

src/inline-assembly.md

+# #[cfg(target_arch = "x86_64")] {
+#[naked]
+extern "C-unwind" fn naked_function() {
+    unsafe {
+        core::arch::naked_asm!(
+            ".cfi_startproc",
+            "push rbp",
+            ".cfi_def_cfa_offset 16",
+            ".cfi_offset rbp, -16",
+            "mov rbp, rsp",
+            ".cfi_def_cfa_register rbp",
+            "",
+            "call {function}",
+            "",
+            "pop rbp",
+            ".cfi_def_cfa rsp, 8",
+            "ret",
+            ".cfi_endproc",
+            function = sym function_that_panics,
+        )
+    }
+}
+
+extern "C-unwind" fn function_that_panics() {
+    panic!("unwind!");
+}
+# }


I don't think I can currently run this because #[naked] is still unstable. So reminder to self: update this before merging.

cc @traviscross

We won't merge this anyway until the stabilization lands, so you can just update it and leave the CI red until then (add the feature flag and test it locally though). That's what we normally do.

Locally I still even get errors like this

Couldn't compile the test. ---- inline-assembly.md - Inline_assembly::Options (line 1360) stdout ---- error[E0658]: label operands for inline assembly are unstable --> inline-assembly.md:1364:32 | 6 | core::arch::asm!("jmp {}", label { | ________________________________^ 7 | | println!(); 8 | | }, options(noreturn)); | |_____^ | = note: see issue #119364 <https://github.com/rust-lang/rust/issues/119364> for more information

with these versions in the reference folder (so I don't think there is a rustup override active)

> cargo --version cargo 1.88.0-nightly (d811228b1 2025-04-15) > rustc --version rustc 1.88.0-nightly (191df20fc 2025-04-18)

That feature has been stable on nightly for a while, so I must be missing something. Anyway, I believe the current code to be correct, and CI will catch it before merge if there are minor issues.

I've had trouble with overrides too on the Reference for reasons I haven't yet worked out. Perhaps if you rustup default nightly (or rustup default stage1 or whatnot) it will work for you.

src/attributes/codegen.md

src/inline-assembly.md

this only applies to `asm!` (even though the rule has been removed there since copying it for naked asm

…mbly

src/attributes/codegen.md

src/inline-assembly.md

The unsafe code guidelines document describes itself currently as largely abandoned and indicates that those points that have found consensus are documented in the Reference. Let's not then normatively cite that other document. Let's also remove a line about "these rules do not apply..." where "these" changed meaning when this line was copied from elsewhere. In the original, "these" meant rules about `readonly` and `nomem`, whereas here, it would have seemed to refer to the rules in the UCG, and that wouldn't make sense.

traviscross

OK, with the changes I've pushed, this look OK to me, so we can approve this to unblock the stabilization.

We demonstrate how to correctly unwind from a naked function. The assembler directives and boilerplate for this may be unfamiliar to people, so let's annotate this example heavily and add links to further resources. We'll use the `sysv64-unwind` ABI rather than `C-unwind` just to make things a bit more unambiguous.

…ns, r=tgross35,Amanieu,traviscross Stabilize `naked_functions` tracking issue: rust-lang#90957 request for stabilization on tracking issue: rust-lang#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: ```rust 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](https://en.wikipedia.org/wiki/Function_prologue_and_epilogue) or epilogue when generating code for this function. This attribute is analogous to [`__attribute__((naked))`](https://developer.arm.com/documentation/100067/0608/Compiler-specific-Function--Variable--and-Type-Attributes/--attribute----naked---function-attribute) 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](https://github.com/rust-lang/rust/tree/master/tests/codegen/naked-fn) verifies that `pub`, `#[no_mangle]` and `#[linkage = "..."]` work correctly for naked functions * [tests/codegen/naked-fn](https://github.com/rust-lang/rust/tree/master/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-*](https://github.com/rust-lang/rust/tree/master/tests/ui/asm) tests for incompatible attributes, generating errors around incorrect use of `naked_asm!`, etc ## Interaction with other (unstable) features ### [fn_align](rust-lang#82232) 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](rust-lang/rfcs#1201), filed on 2015-07-10 and accepted on 2016-03-21. Support for this feature was added in [rust-lang#32410](rust-lang#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](rust-lang/rfcs#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 [rust-lang#93153](rust-lang#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 ```rust extern "C" fn foo() { core::arch::naked_asm!("ret") } ``` is emitted as something similar to ```rust 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 rust-lang#138568. relevant PRs for these recent changes - rust-lang#127853 - rust-lang#128651 - rust-lang#128004 - rust-lang#138570 - ### Various historical notes #### `noreturn` [RFC 2972](https://github.com/rust-lang/rfcs/blob/master/text/2972-constrained-naked.md) 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

…ns, r=tgross35,Amanieu,traviscross Stabilize `naked_functions` tracking issue: rust-lang#90957 request for stabilization on tracking issue: rust-lang#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: ```rust 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](https://en.wikipedia.org/wiki/Function_prologue_and_epilogue) or epilogue when generating code for this function. This attribute is analogous to [`__attribute__((naked))`](https://developer.arm.com/documentation/100067/0608/Compiler-specific-Function--Variable--and-Type-Attributes/--attribute----naked---function-attribute) 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](https://github.com/rust-lang/rust/tree/master/tests/codegen/naked-fn) verifies that `pub`, `#[no_mangle]` and `#[linkage = "..."]` work correctly for naked functions * [tests/codegen/naked-fn](https://github.com/rust-lang/rust/tree/master/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-*](https://github.com/rust-lang/rust/tree/master/tests/ui/asm) tests for incompatible attributes, generating errors around incorrect use of `naked_asm!`, etc ## Interaction with other (unstable) features ### [fn_align](rust-lang#82232) 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](rust-lang/rfcs#1201), filed on 2015-07-10 and accepted on 2016-03-21. Support for this feature was added in [rust-lang#32410](rust-lang#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](rust-lang/rfcs#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 [rust-lang#93153](rust-lang#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 ```rust extern "C" fn foo() { core::arch::naked_asm!("ret") } ``` is emitted as something similar to ```rust 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 rust-lang#138568. relevant PRs for these recent changes - rust-lang#127853 - rust-lang#128651 - rust-lang#128004 - rust-lang#138570 - ### Various historical notes #### `noreturn` [RFC 2972](https://github.com/rust-lang/rfcs/blob/master/text/2972-constrained-naked.md) 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

Rollup merge of rust-lang#134213 - folkertdev:stabilize-naked-functions, r=tgross35,Amanieu,traviscross Stabilize `naked_functions` tracking issue: rust-lang#90957 request for stabilization on tracking issue: rust-lang#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: ```rust 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](https://en.wikipedia.org/wiki/Function_prologue_and_epilogue) or epilogue when generating code for this function. This attribute is analogous to [`__attribute__((naked))`](https://developer.arm.com/documentation/100067/0608/Compiler-specific-Function--Variable--and-Type-Attributes/--attribute----naked---function-attribute) 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](https://github.com/rust-lang/rust/tree/master/tests/codegen/naked-fn) verifies that `pub`, `#[no_mangle]` and `#[linkage = "..."]` work correctly for naked functions * [tests/codegen/naked-fn](https://github.com/rust-lang/rust/tree/master/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-*](https://github.com/rust-lang/rust/tree/master/tests/ui/asm) tests for incompatible attributes, generating errors around incorrect use of `naked_asm!`, etc ## Interaction with other (unstable) features ### [fn_align](rust-lang#82232) 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](rust-lang/rfcs#1201), filed on 2015-07-10 and accepted on 2016-03-21. Support for this feature was added in [rust-lang#32410](rust-lang#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](rust-lang/rfcs#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 [rust-lang#93153](rust-lang#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 ```rust extern "C" fn foo() { core::arch::naked_asm!("ret") } ``` is emitted as something similar to ```rust 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 rust-lang#138568. relevant PRs for these recent changes - rust-lang#127853 - rust-lang#128651 - rust-lang#128004 - rust-lang#138570 - ### Various historical notes #### `noreturn` [RFC 2972](https://github.com/rust-lang/rfcs/blob/master/text/2972-constrained-naked.md) 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

…oss35,Amanieu,traviscross Stabilize `naked_functions` tracking issue: rust-lang/rust#90957 request for stabilization on tracking issue: rust-lang/rust#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: ```rust 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](https://en.wikipedia.org/wiki/Function_prologue_and_epilogue) or epilogue when generating code for this function. This attribute is analogous to [`__attribute__((naked))`](https://developer.arm.com/documentation/100067/0608/Compiler-specific-Function--Variable--and-Type-Attributes/--attribute----naked---function-attribute) 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](https://github.com/rust-lang/rust/tree/master/tests/codegen/naked-fn) verifies that `pub`, `#[no_mangle]` and `#[linkage = "..."]` work correctly for naked functions * [tests/codegen/naked-fn](https://github.com/rust-lang/rust/tree/master/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-*](https://github.com/rust-lang/rust/tree/master/tests/ui/asm) tests for incompatible attributes, generating errors around incorrect use of `naked_asm!`, etc ## Interaction with other (unstable) features ### [fn_align](rust-lang/rust#82232) 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](rust-lang/rfcs#1201), filed on 2015-07-10 and accepted on 2016-03-21. Support for this feature was added in [#32410](rust-lang/rust#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](rust-lang/rfcs#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](rust-lang/rust#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 ```rust extern "C" fn foo() { core::arch::naked_asm!("ret") } ``` is emitted as something similar to ```rust 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 rust-lang/rust#138568. relevant PRs for these recent changes - rust-lang/rust#127853 - rust-lang/rust#128651 - rust-lang/rust#128004 - rust-lang/rust#138570 - ### Various historical notes #### `noreturn` [RFC 2972](https://github.com/rust-lang/rfcs/blob/master/text/2972-constrained-naked.md) 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

folkertdev · 2025-04-22T11:53:36Z

Those final changes look good to me. The feature has been stabilized and CI passes here, so I think that should be everything.

For naked functions, let's break out the rules for callee and caller saved registers and name the rule identifiers more clearly. For the caller saved registers, let's drop the caveat about "even if they are not used for the return value", as it doesn't really add anything to the rule.

traviscross · 2025-04-22T18:57:33Z

Thanks to @folkertdev for pushing this forward.

Amanieu reviewed Dec 1, 2024

View reviewed changes

bjorn3 reviewed Dec 2, 2024

View reviewed changes

src/inline-assembly.md Outdated Show resolved Hide resolved

ehuss added S-waiting-on-stabilization Waiting for a stabilization PR to be merged in the main Rust repository S-waiting-on-review Status: The marked PR is awaiting review from a maintainer labels Dec 5, 2024

folkertdev commented Dec 12, 2024

View reviewed changes

src/attributes/codegen.md Outdated Show resolved Hide resolved

folkertdev mentioned this pull request Dec 18, 2024

Stabilize naked_functions rust-lang/rust#134213

Merged

folkertdev force-pushed the stabilize-naked-functions branch from 5deb3b5 to 54695c9 Compare December 18, 2024 20:47

pthariensflame reviewed Dec 20, 2024

View reviewed changes

src/inline-assembly.md Outdated Show resolved Hide resolved

chorman0773 self-requested a review January 9, 2025 16:58

tgross35 mentioned this pull request Jan 10, 2025

Add documentation for the naked function attribute #1153

Closed

This comment has been minimized.

Sign in to view

folkertdev force-pushed the stabilize-naked-functions branch from b2ee83c to 1a8abe7 Compare January 14, 2025 21:16

This comment has been minimized.

Sign in to view

folkertdev force-pushed the stabilize-naked-functions branch from 1a8abe7 to 7fdadec Compare January 29, 2025 09:00

JoelMarcey self-requested a review January 30, 2025 16:36

This comment has been minimized.

Sign in to view

folkertdev force-pushed the stabilize-naked-functions branch 2 times, most recently from d1a523d to 1caf564 Compare February 13, 2025 21:00

folkertdev force-pushed the stabilize-naked-functions branch 2 times, most recently from f92f75f to 54ddde1 Compare March 7, 2025 19:28

folkertdev commented Mar 7, 2025

View reviewed changes

traviscross reviewed Mar 8, 2025

View reviewed changes

src/attributes/codegen.md Outdated Show resolved Hide resolved

This comment has been minimized.

Sign in to view

folkertdev force-pushed the stabilize-naked-functions branch from 54ddde1 to 81ad95f Compare March 18, 2025 09:49

joshtriplett reviewed Mar 26, 2025

View reviewed changes

src/inline-assembly.md Outdated Show resolved Hide resolved

joshtriplett reviewed Mar 26, 2025

View reviewed changes

src/inline-assembly.md Outdated Show resolved Hide resolved

bstrie and others added 4 commits April 19, 2025 12:39

Add documentation for the naked function attribute

4ee56d4

Add naked to the attribute index

69d5534

document naked_asm!

e42068d

mention incompatible attributes

04d5b88

folkertdev added 4 commits April 19, 2025 12:39

remove the rule on unwinding.

5928c4b

this only applies to `asm!` (even though the rule has been removed there since copying it for naked asm

use naked_asm! block to clarify we're talking just about naked asse…

1c3e520

…mbly

reintroduce a section on unwinding out of naked_asm!

0f837d8

formatting + update to unsafe(naked)

c4d68c9

folkertdev force-pushed the stabilize-naked-functions branch from 81ad95f to c4d68c9 Compare April 19, 2025 10:41

traviscross reviewed Apr 20, 2025

View reviewed changes

src/attributes/codegen.md Outdated Show resolved Hide resolved

traviscross reviewed Apr 21, 2025

View reviewed changes

src/inline-assembly.md Outdated Show resolved Hide resolved

traviscross reviewed Apr 21, 2025

View reviewed changes

src/inline-assembly.md Outdated Show resolved Hide resolved

traviscross reviewed Apr 21, 2025

View reviewed changes

src/inline-assembly.md Outdated Show resolved Hide resolved

traviscross added 3 commits April 21, 2025 01:05

Sort some lists of things better

27b569a

Make some editorial improvements

d64c438

traviscross approved these changes Apr 21, 2025

View reviewed changes

traviscross removed the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Apr 21, 2025

folkertdev marked this pull request as ready for review April 22, 2025 11:49

folkertdev closed this Apr 22, 2025

folkertdev reopened this Apr 22, 2025

traviscross force-pushed the stabilize-naked-functions branch from 4d17358 to aca530a Compare April 22, 2025 18:52

traviscross added this pull request to the merge queue Apr 22, 2025

traviscross removed the S-waiting-on-stabilization Waiting for a stabilization PR to be merged in the main Rust repository label Apr 22, 2025

Merged via the queue into rust-lang:master with commit ff6252f Apr 22, 2025
5 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

naked functions #1689

naked functions #1689

folkertdev commented Dec 1, 2024 •

edited by traviscross

Loading

Amanieu Dec 1, 2024

folkertdev Dec 1, 2024

chorman0773 Dec 1, 2024

folkertdev Dec 1, 2024

Amanieu Dec 1, 2024

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

folkertdev Mar 7, 2025

traviscross Mar 8, 2025 •

edited

Loading

folkertdev Apr 19, 2025

traviscross Apr 19, 2025 •

edited

Loading

This comment has been minimized.

traviscross left a comment

folkertdev commented Apr 22, 2025

traviscross commented Apr 22, 2025

naked functions #1689

naked functions #1689

Conversation

folkertdev commented Dec 1, 2024 • edited by traviscross Loading

Amanieu Dec 1, 2024

Choose a reason for hiding this comment

folkertdev Dec 1, 2024

Choose a reason for hiding this comment

chorman0773 Dec 1, 2024

Choose a reason for hiding this comment

folkertdev Dec 1, 2024

Choose a reason for hiding this comment

Amanieu Dec 1, 2024

Choose a reason for hiding this comment

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

folkertdev Mar 7, 2025

Choose a reason for hiding this comment

traviscross Mar 8, 2025 • edited Loading

Choose a reason for hiding this comment

folkertdev Apr 19, 2025

Choose a reason for hiding this comment

traviscross Apr 19, 2025 • edited Loading

Choose a reason for hiding this comment

This comment has been minimized.

traviscross left a comment

Choose a reason for hiding this comment

folkertdev commented Apr 22, 2025

traviscross commented Apr 22, 2025

folkertdev commented Dec 1, 2024 •

edited by traviscross

Loading

traviscross Mar 8, 2025 •

edited

Loading

traviscross Apr 19, 2025 •

edited

Loading