@@ -49,77 +49,49 @@ be called.
49
49
r[ attributes.codegen.naked]
50
50
## The ` naked ` attribute
51
51
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.
123
95
124
96
r[ attributes.codegen.no_builtins]
125
97
## The ` no_builtins ` attribute
@@ -576,6 +548,7 @@ trait object whose methods are attributed.
576
548
[ `is_aarch64_feature_detected` ] : ../../std/arch/macro.is_aarch64_feature_detected.html
577
549
[ `naked_asm!` ] : ../inline-assembly.md
578
550
[ `inline` ] : #the-inline-attribute
551
+ [ `track_caller` ] : #the-track-caller-attribute
579
552
[ `target_feature` conditional compilation option ] : ../conditional-compilation.md#target_feature
580
553
[ `unused_variables` ] : ../../rustc/lints/listing/warn-by-default.html#unused-variables
581
554
[ attribute ] : ../attributes.md
0 commit comments