Skip to content

Update naked to use the attribute template #1908

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 47 additions & 3 deletions src/attributes/codegen.md
Original file line number Diff line number Diff line change
Expand Up @@ -52,15 +52,51 @@ 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.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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does this work

Suggested change
- [Trait definition functions][items.traits] with a body
- [Trait][items.traits] [associated functions][items.associated.fn] with a body

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This wording can be ambiguous, since it is unclear if it is an associated function in a trait definition or a trait impl. The original wording was specifically chosen to avoid that ambiguity and contrast with the previous item.


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.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.

Expand All @@ -82,6 +118,14 @@ 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.

<!-- TODO: Reflexive rules? -->

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

Expand Down