Skip to content

Commit 69d5534

Browse files
bstriefolkertdev
authored andcommittedApr 19, 2025
Add naked to the attribute index
1 parent 4ee56d4 commit 69d5534

File tree

2 files changed

+46
-71
lines changed

2 files changed

+46
-71
lines changed
 

‎src/attributes.md

+2
Original file line numberDiff line numberDiff line change
@@ -290,6 +290,7 @@ The following is an index of all built-in attributes.
290290
- Code generation
291291
- [`inline`] --- Hint to inline code.
292292
- [`cold`] --- Hint that a function is unlikely to be called.
293+
- [`naked`] - Prevent the compiler from emitting a function prologue.
293294
- [`no_builtins`] --- Disables use of certain built-in functions.
294295
- [`target_feature`] --- Configure platform-specific code generation.
295296
- [`track_caller`] --- Pass the parent call location to `std::panic::Location::caller()`.
@@ -360,6 +361,7 @@ The following is an index of all built-in attributes.
360361
[`macro_export`]: macros-by-example.md#path-based-scope
361362
[`macro_use`]: macros-by-example.md#the-macro_use-attribute
362363
[`must_use`]: attributes/diagnostics.md#the-must_use-attribute
364+
[`naked`]: attributes/codegen.md#the-naked-attribute
363365
[`no_builtins`]: attributes/codegen.md#the-no_builtins-attribute
364366
[`no_implicit_prelude`]: names/preludes.md#the-no_implicit_prelude-attribute
365367
[`no_link`]: items/extern-crates.md#the-no_link-attribute

‎src/attributes/codegen.md

+44-71
Original file line numberDiff line numberDiff line change
@@ -49,77 +49,49 @@ be called.
4949
r[attributes.codegen.naked]
5050
## The `naked` attribute
5151

52-
The *`naked` [attribute]* may be applied to a function in order to prevent the compiler
53-
from emitting a function prologue.
54-
55-
### Requirements
56-
57-
Any function marked with the `naked` attribute must meet the following requirements;
58-
failure to do so will result in a compiler error.
59-
60-
* The [function body] must consist of exactly one [`asm!`] macro invocation,
61-
which may be enclosed within an [unsafe block].
62-
* This `asm!` invocation must not contain any [operands]
63-
except for `const` and `sym` operands.
64-
* This `asm!` invocation must specify the `noreturn` [option],
65-
and must not specify any other options except for `att_syntax`.
66-
* The function must not be marked with the [`inline`] attribute.
67-
68-
### Recommendations
69-
70-
Any function marked with the `naked` attribute should adhere to the following recommendations;
71-
failure to do so will result in a compiler warning.
72-
73-
* The function should feature an [extern function qualifier] that is not `extern "Rust"`.
74-
* All arguments and return types of the function should be [FFI-safe].
75-
76-
### Effects
77-
78-
Marking a function with the `naked` attribute has the following effects:
79-
80-
* The compiler will not generate a prologue for this function.
81-
Within the function, all registers will remain precisely as they were set up
82-
by its caller.
83-
* The compiler will suppress the [`unused_variables`] lint for this function.
84-
85-
### Notes
86-
87-
* The [rules for inline assembly] ordinarily consider it undefined behavior to
88-
refer to registers not specified as input operands, or to modify
89-
registers not specified as output operands.
90-
The reason for this is because ordinarily an `asm!` invocation cannot guarantee
91-
the state of the registers surrounding the assembly block.
92-
However, in naked functions the state of the registers is guaranteed
93-
by adherence to the specified calling convention.
94-
Therefore, it is not undefined behavior for the `asm!` invocation in a naked function
95-
to refer to registers without specifying them as operands.
96-
* A naked function that makes use of registers in a way that does not conform
97-
to the specified calling convention imposes additional safety invariants on its caller,
98-
and therefore must be marked as an [unsafe function].
99-
* Implementations may assume that naked functions never unwind.
100-
Unwinding through a naked function is undefined behavior.
101-
* The semantics of naked functions require implementations to set up the call stack
102-
according to the specified calling convention before executing a naked function,
103-
even in contexts where setting up the call stack would ordinarily be unnecessary,
104-
such as when the function is inlined.
105-
An implementation can fulfill this requirement by guaranteeing that naked functions
106-
are never inlined.
107-
However, implementations are not currently required to guarantee that naked functions
108-
are never inlined.
109-
In the future it may become a requirement for implementations to guarantee that
110-
naked functions are never inlined;
111-
users must not rely on any observable behavior that may result from inlining.
112-
* Although implementations are prohibited from generating code for a naked function that
113-
contains any instructions that precede the naked function's `asm!` block,
114-
under some circumstances, implementations may generate code that contains instructions
115-
*after* a naked function's `asm!` block.
116-
In the future it may become a requirement for implementations to guarantee
117-
the absence of any instructions following a naked function's `asm!` block;
118-
users must not rely on the presence of any trailing instructions.
119-
If a user of the `naked` attribute relies on the absence of trailing instructions
120-
for correctness, for the time being it is the user's responsibility to ensure that
121-
the instructions truly are absent,
122-
for example by passing any necessary code generation flags to the compiler.
52+
r[attributes.codegen.naked]
53+
54+
r[attributes.codegen.naked.intro]
55+
The *`naked` [attribute]* prevents the compiler from emitting a function prologue and
56+
epilogue for the attributed function.
57+
58+
r[attributes.codegen.naked.body]
59+
The [function body] must consist of exactly one [`naked_asm!`] macro invocation, which
60+
may be enclosed within an [unsafe block].
61+
62+
r[attributes.codegen.naked.prologue-epilogue]
63+
No function prologue or epilogue are generated for the attributed function: the contents
64+
of the `naked_asm!` invocation make up the full body of a naked function.
65+
66+
r[attributes.codegen.naked.call-stack]
67+
The caller must set up the call stack acording to the specified calling convention before
68+
executing a naked function, even in contexts where setting up the call stack would ordinarily
69+
be unnecessary, such as when the function is inlined.
70+
71+
An implementation can fulfill this requirement by guaranteeing that naked functions
72+
are never inlined. However, implementations are not currently required to guarantee that
73+
naked functions are never inlined.
74+
75+
In the future it may become a requirement for implementations to guarantee that
76+
naked functions are never inlined; users must not rely on any observable behavior
77+
that may result from inlining. according to the specified calling convention before
78+
executing a naked function,
79+
80+
r[attributes.codegen.naked.unsafe-function]
81+
A naked function that makes use of registers in a way that does not conform
82+
to the specified calling convention imposes additional safety invariants on its caller,
83+
and therefore must be marked as an [unsafe function].
84+
85+
> ***Note***: a `naked_asm!` invocation may refer to registers that were not specified as operands.
86+
> for standard `asm!` this is undefined behavior, but `inline_asm!` may rely on the state of registers
87+
> as specified by the calling convention.
88+
89+
r[attributes.codegen.naked.unused-variables]
90+
The [`unused_variables`] lint is suppressed within naked functions.
91+
92+
r[attributes.codegen.naked.no-unwind]
93+
Implementations may assume that naked functions never unwind.
94+
Unwinding through a naked function is undefined behavior.
12395

12496
r[attributes.codegen.no_builtins]
12597
## The `no_builtins` attribute
@@ -576,6 +548,7 @@ trait object whose methods are attributed.
576548
[`is_aarch64_feature_detected`]: ../../std/arch/macro.is_aarch64_feature_detected.html
577549
[`naked_asm!`]: ../inline-assembly.md
578550
[`inline`]: #the-inline-attribute
551+
[`track_caller`]: #the-track-caller-attribute
579552
[`target_feature` conditional compilation option]: ../conditional-compilation.md#target_feature
580553
[`unused_variables`]: ../../rustc/lints/listing/warn-by-default.html#unused-variables
581554
[attribute]: ../attributes.md

0 commit comments

Comments
 (0)
Please sign in to comment.