You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/attributes/codegen.md
+59-15Lines changed: 59 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -119,41 +119,80 @@ Only the first use of `cold` on a function has effect.
119
119
r[attributes.codegen.cold.trait]
120
120
When `cold` is applied to a function in a [trait], it applies only to the code of the [default definition].
121
121
122
+
<!-- template:attributes -->
122
123
r[attributes.codegen.naked]
123
124
## The `naked` attribute
124
125
125
126
r[attributes.codegen.naked.intro]
126
-
The*`naked` [attribute]* prevents the compiler from emitting a function prologue and epilogue for the attributed function.
127
+
The*`naked` [attribute]* prevents the compiler from emitting a function prologue and epilogue for the attributed function --- a *naked function*.
128
+
129
+
> [!EXAMPLE]
130
+
> ```rust
131
+
> # #[cfg(target_arch = "x86_64")] {
132
+
> /// Adds 3 to the given number.
133
+
> // SAFETY: The body respects the "sysv64" calling convention,
134
+
> // upholds the signature, and does not fall through.
135
+
> #[unsafe(naked)]
136
+
> pubextern "sysv64" fn add_n(number:u64) ->u64 {
137
+
> core::arch::naked_asm!(
138
+
> "add rdi, {}",
139
+
> "mov rax, rdi",
140
+
> "ret",
141
+
> const 3,
142
+
> )
143
+
> }
144
+
> # }
145
+
> ```
146
+
147
+
r[attributes.codegen.naked.syntax]
148
+
The `naked` attribute uses the [MetaWord] syntax.
149
+
150
+
r[attributes.codegen.naked.allowed-positions]
151
+
The `naked` attribute may only be applied to [free functions], [associated functions] in an [inherent impl] or [traitimpl], and associated functions in a [trait definition] when those functions have a [default definition].
152
+
153
+
r[attributes.codegen.naked.duplicates]
154
+
Only the first use of `naked` on a function has effect.
155
+
156
+
> [!NOTE]
157
+
> `rustc` lints against any use following the first.
158
+
159
+
r[attributes.codegen.naked.unsafe]
160
+
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).
127
161
128
162
r[attributes.codegen.naked.body]
129
163
The [function body] must consist of exactly one [`naked_asm!`] macro invocation.
130
164
131
165
r[attributes.codegen.naked.prologue-epilogue]
132
-
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.
133
-
134
-
r[attributes.codegen.naked.unsafe-attribute]
135
-
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).
166
+
The compiler emits no prologue or epilogue for a naked function: the assembly code in the [`naked_asm!`] invocation constitutes its entire body.
136
167
137
168
r[attributes.codegen.naked.call-stack]
138
-
Theassembly code may assume that the call stack and register state are valid on entry asper the signature and calling convention of the function.
169
+
On entry the assembly code may assume that the call stack and register state are valid per the function's signature and calling convention.
139
170
140
171
r[attributes.codegen.naked.no-duplication]
141
-
Theassembly code may not be duplicated by the compiler except when monomorphizing polymorphic functions.
172
+
Thecompiler may not duplicate the assembly code except when monomorphizing a polymorphic function.
142
173
143
174
> [!NOTE]
144
-
> Guaranteeing when the assembly code may or may not be duplicated is importantfor naked functions that define symbols.
175
+
> This guarantee mattersfor naked functions that define symbols.
145
176
146
177
r[attributes.codegen.naked.unused-variables]
147
-
The [`unused_variables`] lint is suppressed within naked functions.
178
+
The [`unused_variables` lint] is suppressed in naked functions.
148
179
149
180
r[attributes.codegen.naked.inline]
150
-
The [`inline`](#the-inline-attribute) attribute cannot by applied to a naked function.
181
+
The [`inline` attribute] cannot be applied to a naked function.
151
182
152
183
r[attributes.codegen.naked.track_caller]
153
-
The [`track_caller`](#the-track_caller-attribute) attribute cannot be applied to a naked function.
184
+
The [`track_caller` attribute] cannot be applied to a naked function.
154
185
155
186
r[attributes.codegen.naked.testing]
156
-
The [testing attributes](testing.md) cannot be applied to a naked function.
187
+
The [testing attributes] cannot be applied to a naked function.
188
+
189
+
r[attributes.codegen.naked.target_feature]
190
+
The [`target_feature` attribute] cannot be applied to a naked function.
191
+
192
+
<!--TODO:Reflexive rules?-->
193
+
194
+
r[attributes.codegen.naked.abi]
195
+
A naked function cannot use the ["Rust" ABI].
157
196
158
197
<!-- template:attributes -->
159
198
r[attributes.codegen.no_builtins]
@@ -851,13 +890,16 @@ If the address of the function is taken as a function pointer, the low bit of th
0 commit comments