Skip to content

Commit 810ffe2

Browse files
bstriefolkertdev
authored andcommitted
Add documentation for the naked function attribute
1 parent 074bbab commit 810ffe2

File tree

1 file changed

+86
-1
lines changed

1 file changed

+86
-1
lines changed

src/attributes/codegen.md

Lines changed: 86 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,10 +48,84 @@ r[attributes.codegen.cold]
4848
The *`cold` [attribute]* suggests that the attributed function is unlikely to
4949
be called.
5050

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

54-
55129
The *`no_builtins` [attribute]* may be applied at the crate level to disable
56130
optimizing certain code patterns to invocations of library functions that are
57131
assumed to exist.
@@ -509,13 +583,24 @@ trait object whose methods are attributed.
509583
[`-C target-feature`]: ../../rustc/codegen-options/index.html#target-feature
510584
[`is_x86_feature_detected`]: ../../std/arch/macro.is_x86_feature_detected.html
511585
[`is_aarch64_feature_detected`]: ../../std/arch/macro.is_aarch64_feature_detected.html
586+
[`naked_asm!`]: ../inline-assembly.md
587+
[`inline`]: #the-inline-attribute
512588
[`target_feature` conditional compilation option]: ../conditional-compilation.md#target_feature
589+
[`unused_variables`]: ../../rustc/lints/listing/warn-by-default.html#unused-variables
513590
[attribute]: ../attributes.md
514591
[attributes]: ../attributes.md
592+
[extern function qualifier]: ../items/functions.md#extern-function-qualifier
593+
[FFI-safe]: ../../rustc/lints/listing/warn-by-default.html#improper-ctypes-definitions
594+
[function body]: ../items/functions.md#function-body
515595
[functions]: ../items/functions.md
596+
[operands]: ../inline-assembly.md#operand-type
597+
[option]: ../inline-assembly.md#options
598+
[rules for inline assembly]: ../inline-assembly.md#rules-for-inline-assembly
516599
[target architecture]: ../conditional-compilation.md#target_arch
517600
[trait]: ../items/traits.md
518601
[undefined behavior]: ../behavior-considered-undefined.md
602+
[unsafe block]: ../unsafe-blocks.md
603+
[unsafe function]: ../unsafe-functions.md
519604
[rust-abi]: ../items/external-blocks.md#abi
520605
[`Location`]: core::panic::Location
521606

0 commit comments

Comments
 (0)