formatting + update to unsafe(naked)

Author: folkertdev

Diff for: src/attributes.md

@@ -45,6 +45,7 @@ The following attributes are unsafe:
 * [`export_name`]
 * [`link_section`]
 * [`no_mangle`]
+* [`naked`]
 
 r[attributes.kind]
 Attributes can be classified into the following kinds:

Diff for: src/attributes/codegen.md

@@ -50,28 +50,22 @@ r[attributes.codegen.naked]
 ## The `naked` attribute
 
 r[attributes.codegen.naked.intro]
-The *`naked` [attribute]* prevents the compiler from emitting a function prologue and
-epilogue for the attributed function.
+The *`naked` [attribute]* prevents the compiler from emitting a function prologue and epilogue for the attributed function.
 
 r[attributes.codegen.naked.body]
-The [function body] must consist of exactly one [`naked_asm!`] macro invocation, which
-may be enclosed within an [unsafe block].
+The [function body] must consist of exactly one [`naked_asm!`] macro invocation.
 
 r[attributes.codegen.naked.prologue-epilogue]
-No function prologue or epilogue are generated for the attributed function: the contents
-of the `naked_asm!` invocation make up the full body of a naked function.
+No function prologue or epilogue are generated for the attributed function: the contents of the `naked_asm!` invocation make up 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 respects the function's calling convention, and that the body either returns or diverges.
 
 r[attributes.codegen.naked.call-stack]
-The asm code will have a valid call stack and register state on entry as per the signature and calling convention of the function.
+The assembly code will have a valid call stack and register state on entry as per the signature and calling convention of the function.
 
 r[attributes.codegen.naked.no-duplication]
-The asm code may not be duplicated by the compiler, except when monomorphizing polymorphic functions.
-This property is important for naked functions that define symbols in the assembly code.
-
-r[attributes.codegen.naked.unsafe-function]
-A naked function that makes use of registers in a way that does not conform
-to the specified calling convention imposes additional safety invariants on its caller,
-and therefore must be marked as an [unsafe function].
+The assembly code may not be duplicated by the compiler, except when monomorphizing polymorphic functions. This property is important for naked functions that define symbols in the assembly code.
 
 r[attributes.codegen.naked.unused-variables]
 The [`unused_variables`] lint is suppressed within naked functions.
@@ -552,8 +546,7 @@ trait object whose methods are attributed.
 [target architecture]: ../conditional-compilation.md#target_arch
 [trait]: ../items/traits.md
 [undefined behavior]: ../behavior-considered-undefined.md
-[unsafe block]: ../unsafe-blocks.md
-[unsafe function]: ../unsafe-functions.md
+[unsafe attribute]: ../attributes.md#r-attributes.safety
 [rust-abi]: ../items/external-blocks.md#abi
 [`Location`]: core::panic::Location
 

Diff for: src/inline-assembly.md

@@ -2,7 +2,7 @@ r[asm]
 # Inline assembly
 
 r[asm.intro]
-Support for inline assembly is provided via the [`asm!`], [`naked_asm!`] and [`global_asm!`] macros.
+Support for inline assembly is provided via the [`asm!`], [`naked_asm!`], and [`global_asm!`] macros.
 It can be used to embed handwritten assembly in the assembly output generated by the compiler.
 
 [`asm!`]: core::arch::asm
@@ -84,6 +84,15 @@ r[asm.scope.naked_asm]
 With the `naked_asm!` macro, the assembly code is emitted in a function scope and constitutes the full assembly code of a function.
 The `naked_asm!` macro is only allowed in [naked functions](attributes/codegen.md#the-naked-attribute).
 
+```rust
+# #[cfg(target_arch = "x86_64")] {
+# #[unsafe(naked)]
+# extern "C" fn wrapper() {
+core::arch::naked_asm!("/* {} */", const 0);
+# }
+# }
+```
+
 r[asm.scope.global_asm]
 With the `global_asm!` macro, the assembly code is emitted in a global scope, outside a function.
 This can be used to hand-write entire functions using assembly code, and generally provides much more freedom to use arbitrary registers and assembler directives.
@@ -391,7 +400,7 @@ assert_eq!(y, 1);
 ```
 
 r[asm.operand-type.naked_asm-restriction]
-Because `naked_asm!` defines a whole function body, it can only use `sym` and `const` operands.
+Because `naked_asm!` defines a whole function body and the compiler cannot emit any additional code to handle operands, it can only use `sym` and `const` operands.
 
 r[asm.operand-type.global_asm-restriction]
 Because `global_asm!` exists outside a function, it can only use `sym` and `const` operands.
@@ -1392,12 +1401,12 @@ r[asm.naked-rules.reg-not-output]
 
 r[asm.naked-rules.noreturn]
 - Behavior is undefined if execution falls through to the end of the `naked_asm!` block.
-    - the assembly code is expected to contain a return instruction or to diverge
+    - every path through the assembly code is expected to terminate with a return instruction or to diverge
 
 r[asm.naked-rules.mem-same-as-ffi]
 - The set of memory locations that assembly code is allowed to read and write are the same as those allowed for an FFI function.
   - Refer to the unsafe code guidelines for the exact rules.
-  - These rules do not apply to memory which is private to the asm code, such as stack space allocated within the `naked_asm!` block.
+  - These rules do not apply to memory which is private to the assembly code, such as stack space allocated within the `naked_asm!` block.
 
 r[asm.naked-rules.black-box]
 - The compiler cannot assume that the instructions in the `naked_asm!` block are the ones that will actually be executed.
@@ -1408,29 +1417,26 @@ r[asm.naked-rules.unwind]
 - Unwinding out of a `naked_asm!` block is allowed.
   - For correct behavior, the appropriate assembler directives that emit unwinding metadata must be used.
 
-<!-- #[naked] is currently unstable, tests would fail if this were marked `rust` -->
-```txt
+```rust
 # #[cfg(target_arch = "x86_64")] {
-#[naked]
+#[unsafe(naked)]
 extern "C-unwind" fn naked_function() {
-    unsafe {
-        core::arch::naked_asm!(
-            ".cfi_startproc",
-            "push rbp",
-            ".cfi_def_cfa_offset 16",
-            ".cfi_offset rbp, -16",
-            "mov rbp, rsp",
-            ".cfi_def_cfa_register rbp",
-            "",
-            "call {function}",
-            "",
-            "pop rbp",
-            ".cfi_def_cfa rsp, 8",
-            "ret",
-            ".cfi_endproc",
-            function = sym function_that_panics,
-        )
-    }
+    core::arch::naked_asm!(
+        ".cfi_startproc",
+        "push rbp",
+        ".cfi_def_cfa_offset 16",
+        ".cfi_offset rbp, -16",
+        "mov rbp, rsp",
+        ".cfi_def_cfa_register rbp",
+        "",
+        "call {function}",
+        "",
+        "pop rbp",
+        ".cfi_def_cfa rsp, 8",
+        "ret",
+        ".cfi_endproc",
+        function = sym function_that_panics,
+    )
 }
 
 extern "C-unwind" fn function_that_panics() {