add naked_functions_target_feature unstable feature
#138570
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
rustbot
added
A-attributes
|
Some changes occurred in compiler/rustc_passes/src/check_attr.rs |
This comment has been minimized.
This comment has been minimized.
folkertdev
force-pushed
the
naked-function-target-feature-gate
branch
from
e92560c to
c261426
Compare
|
@bors r+ |
bors
added
S-waiting-on-bors
matthiaskrgr
added a commit
to matthiaskrgr/rust
that referenced
this pull request
Mar 21, 2025
…eature-gate, r=Amanieu add `naked_functions_target_feature` unstable feature tracking issue: rust-lang#138568 tagging rust-lang#134213 rust-lang#90957 This PR puts `#[target_feature(/* ... */)]` on `#[naked]` functions behind its own feature gate, so that naked functions can be stabilized. It turns out that supporting `target_feature` on naked functions is tricky on some targets, so we're splitting it out to not block stabilization of naked functions themselves. See the tracking issue for more information and workarounds. Note that at the time of writing, the `target_features` attribute is ignored when generating code for naked functions. r? `@Amanieu`
bors
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Mar 21, 2025
Rollup of 10 pull requests Successful merges: - rust-lang#138364 (ports the compiler test cases to new rust_intrinsic format) - rust-lang#138570 (add `naked_functions_target_feature` unstable feature) - rust-lang#138623 ([bootstrap] Use llvm_runtimes for compiler-rt) - rust-lang#138627 (Autodiff cleanups) - rust-lang#138669 (tests: accept some noise from LLVM 21 in symbols-all-mangled) - rust-lang#138706 (Improve bootstrap git modified path handling) - rust-lang#138709 (Update GCC submodule) - rust-lang#138717 (Add an attribute that makes the spans from a macro edition 2021, and fix pin on edition 2024 with it) - rust-lang#138721 (Use explicit cpu in some asm and codegen tests.) - rust-lang#138728 (Update `compiler-builtins` to 0.1.152) r? `@ghost` `@rustbot` modify labels: rollup try-job: aarch64-apple try-job: x86_64-msvc-1 try-job: x86_64-gnu try-job: dist-i586-gnu-i586-i686-musl
bors
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Mar 21, 2025
…iaskrgr Rollup of 10 pull requests Successful merges: - rust-lang#138364 (ports the compiler test cases to new rust_intrinsic format) - rust-lang#138570 (add `naked_functions_target_feature` unstable feature) - rust-lang#138623 ([bootstrap] Use llvm_runtimes for compiler-rt) - rust-lang#138627 (Autodiff cleanups) - rust-lang#138669 (tests: accept some noise from LLVM 21 in symbols-all-mangled) - rust-lang#138706 (Improve bootstrap git modified path handling) - rust-lang#138709 (Update GCC submodule) - rust-lang#138717 (Add an attribute that makes the spans from a macro edition 2021, and fix pin on edition 2024 with it) - rust-lang#138721 (Use explicit cpu in some asm and codegen tests.) - rust-lang#138728 (Update `compiler-builtins` to 0.1.152) r? `@ghost` `@rustbot` modify labels: rollup try-job: aarch64-apple try-job: x86_64-msvc-1 try-job: x86_64-gnu try-job: dist-i586-gnu-i586-i686-musl
bors
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Mar 21, 2025
…iaskrgr Rollup of 9 pull requests Successful merges: - rust-lang#138364 (ports the compiler test cases to new rust_intrinsic format) - rust-lang#138570 (add `naked_functions_target_feature` unstable feature) - rust-lang#138623 ([bootstrap] Use llvm_runtimes for compiler-rt) - rust-lang#138627 (Autodiff cleanups) - rust-lang#138669 (tests: accept some noise from LLVM 21 in symbols-all-mangled) - rust-lang#138706 (Improve bootstrap git modified path handling) - rust-lang#138709 (Update GCC submodule) - rust-lang#138717 (Add an attribute that makes the spans from a macro edition 2021, and fix pin on edition 2024 with it) - rust-lang#138721 (Use explicit cpu in some asm and codegen tests.) r? `@ghost` `@rustbot` modify labels: rollup
rust-timer
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Mar 21, 2025
Rollup merge of rust-lang#138570 - folkertdev:naked-function-target-feature-gate, r=Amanieu add `naked_functions_target_feature` unstable feature tracking issue: rust-lang#138568 tagging rust-lang#134213 rust-lang#90957 This PR puts `#[target_feature(/* ... */)]` on `#[naked]` functions behind its own feature gate, so that naked functions can be stabilized. It turns out that supporting `target_feature` on naked functions is tricky on some targets, so we're splitting it out to not block stabilization of naked functions themselves. See the tracking issue for more information and workarounds. Note that at the time of writing, the `target_features` attribute is ignored when generating code for naked functions. r? ``@Amanieu``
traviscross
added
the
F-naked_functions_target_feature
jieyouxu
added a commit
to jieyouxu/rust
that referenced
this pull request
Apr 21, 2025
…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
ChrisDenton
added a commit
to ChrisDenton/rust
that referenced
this pull request
Apr 21, 2025
…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
rust-timer
added a commit
to rust-lang-ci/rust
that referenced
this pull request
Apr 21, 2025
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
github-actions bot
pushed a commit
to rust-lang/miri
that referenced
this pull request
Apr 22, 2025
…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
# for free
to join this conversation on GitHub.
Already have an account?
# to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
tracking issue: #138568
tagging #134213 #90957
This PR puts
#[target_feature(/* ... */)]on#[naked]functions behind its own feature gate, so that naked functions can be stabilized. It turns out that supportingtarget_featureon naked functions is tricky on some targets, so we're splitting it out to not block stabilization of naked functions themselves. See the tracking issue for more information and workarounds.Note that at the time of writing, the
target_featuresattribute is ignored when generating code for naked functions.r? @Amanieu