From 2ca21913f0af8c18b6ba1a9100175148ee801115 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 3 Jun 2025 09:34:54 -0700 Subject: [PATCH 1/7] Add naked example --- src/attributes/codegen.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index d472c4db07..0a4f4a10a9 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -125,6 +125,25 @@ r[attributes.codegen.naked] r[attributes.codegen.naked.intro] The *`naked` [attribute]* prevents the compiler from emitting a function prologue and epilogue for the attributed function. +> [!EXAMPLE] +> ```rust +> # #[cfg(target_arch = "x86_64")] { +> /// Adds 3 to the given number. +> /// +> /// SAFETY: The validity of the used registers +> /// is guaranteed according to the "sysv64" ABI. +> #[unsafe(naked)] +> pub extern "sysv64" fn add_n(number: usize) -> usize { +> core::arch::naked_asm!( +> "add rdi, {}", +> "mov rax, rdi", +> "ret", +> const 3, +> ) +> } +> # } +> ``` + r[attributes.codegen.naked.body] The [function body] must consist of exactly one [`naked_asm!`] macro invocation. From 9b1427f77f40ccc67cc684aff2b8b95daddc9942 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 3 Jun 2025 09:35:10 -0700 Subject: [PATCH 2/7] Add naked attribute template rules --- src/attributes/codegen.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 0a4f4a10a9..9bc6ecaca6 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -144,6 +144,23 @@ The *`naked` [attribute]* prevents the compiler from emitting a function prologu > # } > ``` +r[attributes.codegen.naked.syntax] +The `naked` attribute uses the [MetaWord] syntax and thus does not take any inputs. + +r[attributes.codegen.naked.allowed-positions] +The `naked` attribute may only be applied to: + +- [Free functions][items.fn] +- [Inherent associated functions][items.associated.fn] +- [Trait impl functions][items.impl.trait] +- [Trait definition functions][items.traits] with a body + +r[attributes.codegen.naked.duplicates] +Duplicate instances of the `naked` attribute have no effect. + +> [!NOTE] +> `rustc` currently warns on subsequent duplicate `naked` attributes. + r[attributes.codegen.naked.body] The [function body] must consist of exactly one [`naked_asm!`] macro invocation. From 1c19e28c880151a03a7e97cc25f49b8c7db2ae90 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 3 Jun 2025 09:36:57 -0700 Subject: [PATCH 3/7] Move and reword attributes.codegen.naked.unsafe To follow the attribute template, and to simplify the wording a little. --- src/attributes/codegen.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 9bc6ecaca6..16bbf7049b 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -161,15 +161,15 @@ Duplicate instances of the `naked` attribute have no effect. > [!NOTE] > `rustc` currently warns on subsequent duplicate `naked` attributes. +r[attributes.codegen.naked.unsafe] +The `naked` attribute must be marked with [`unsafe`][attributes.safety] because the body must respect the function's calling convention, uphold its signature, and either return or diverge (i.e., not fall through past the end of the assembly code). + r[attributes.codegen.naked.body] The [function body] must consist of exactly one [`naked_asm!`] macro invocation. r[attributes.codegen.naked.prologue-epilogue] No function prologue or epilogue is generated for the attributed function. The assembly code in the `naked_asm!` block constitutes the full body of a naked function. -r[attributes.codegen.naked.unsafe-attribute] -The `naked` attribute is an [unsafe attribute]. Annotating a function with `#[unsafe(naked)]` comes with the safety obligation that the body must respect the function's calling convention, uphold its signature, and either return or diverge (i.e., not fall through past the end of the assembly code). - r[attributes.codegen.naked.call-stack] The assembly code may assume that the call stack and register state are valid on entry as per the signature and calling convention of the function. From d6bb8a77820ff911b7cabc5233f5365e314cdea9 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 3 Jun 2025 09:37:45 -0700 Subject: [PATCH 4/7] Add attributes.codegen.naked.target_feature naked cannot be used with target_feature. https://github.com/rust-lang/rust/blob/aae43c4532690153af7465227816c93036bb1604/compiler/rustc_passes/src/check_attr.rs#L672-L685 --- src/attributes/codegen.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 16bbf7049b..3bd73aabaa 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -191,6 +191,11 @@ The [`track_caller`](#the-track_caller-attribute) attribute cannot be applied to r[attributes.codegen.naked.testing] The [testing attributes](testing.md) cannot be applied to a naked function. +r[attributes.codegen.naked.target_feature] +The [`target_feature`][attributes.codegen.target_feature] attribute cannot be applied to a naked function. + + + r[attributes.codegen.no_builtins] ## The `no_builtins` attribute From 9c41721ca20eb451309004cdee3ff7c4318d669c Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 3 Jun 2025 09:38:21 -0700 Subject: [PATCH 5/7] Add attributes.codegen.naked.abi Naked attributes cannot have the "Rust" ABI. https://github.com/rust-lang/rust/blob/aae43c4532690153af7465227816c93036bb1604/compiler/rustc_passes/src/check_attr.rs#L641-L652 --- src/attributes/codegen.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 3bd73aabaa..94923c76b7 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -196,6 +196,9 @@ The [`target_feature`][attributes.codegen.target_feature] attribute cannot be ap +r[attributes.codegen.naked.abi] +The function cannot have the ["Rust" ABI][items.extern.abi.rust]. + r[attributes.codegen.no_builtins] ## The `no_builtins` attribute From a2c50ded3014a2995159605d7603e03c50e341e7 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 22 Sep 2025 13:20:22 -0700 Subject: [PATCH 6/7] Minor update of `naked` More closely align with the template, and some minor word tweaks. --- src/attributes/codegen.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 94923c76b7..3e20a5b8ee 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -119,6 +119,7 @@ Only the first use of `cold` on a function has effect. r[attributes.codegen.cold.trait] When `cold` is applied to a function in a [trait], it applies only to the code of the [default definition]. + r[attributes.codegen.naked] ## The `naked` attribute @@ -145,7 +146,7 @@ The *`naked` [attribute]* prevents the compiler from emitting a function prologu > ``` r[attributes.codegen.naked.syntax] -The `naked` attribute uses the [MetaWord] syntax and thus does not take any inputs. +The `naked` attribute uses the [MetaWord] syntax. r[attributes.codegen.naked.allowed-positions] The `naked` attribute may only be applied to: @@ -156,10 +157,10 @@ The `naked` attribute may only be applied to: - [Trait definition functions][items.traits] with a body r[attributes.codegen.naked.duplicates] -Duplicate instances of the `naked` attribute have no effect. +The `naked` attribute may be used any number of times on a form. > [!NOTE] -> `rustc` currently warns on subsequent duplicate `naked` attributes. +> `rustc` lints against any use following the first. r[attributes.codegen.naked.unsafe] The `naked` attribute must be marked with [`unsafe`][attributes.safety] because the body must respect the function's calling convention, uphold its signature, and either return or diverge (i.e., not fall through past the end of the assembly code). From 34d4dbab10c79e8867521c8393d02116a6ad0112 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Mon, 29 Sep 2025 14:33:27 -0700 Subject: [PATCH 7/7] Use more specific link for trait definition function --- src/attributes/codegen.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/attributes/codegen.md b/src/attributes/codegen.md index 3e20a5b8ee..0eaa98b8ca 100644 --- a/src/attributes/codegen.md +++ b/src/attributes/codegen.md @@ -154,7 +154,7 @@ The `naked` attribute may only be applied to: - [Free functions][items.fn] - [Inherent associated functions][items.associated.fn] - [Trait impl functions][items.impl.trait] -- [Trait definition functions][items.traits] with a body +- [Trait definition functions][items.traits.associated-item-decls] with a body r[attributes.codegen.naked.duplicates] The `naked` attribute may be used any number of times on a form.