document naked_asm!

Author: folkertdev

src/attributes/codegen.md

@@ -67,7 +67,7 @@ No function prologue or epilogue are generated for the attributed function: the
 of the `naked_asm!` invocation make up the full body of a naked function.
 
 r[attributes.codegen.naked.call-stack]
-The caller must set up the call stack acording to the specified calling convention before
+The caller must set up the call stack according to the specified calling convention before
 executing a naked function, even in contexts where setting up the call stack would ordinarily
 be unnecessary, such as when the function is inlined.
 
@@ -86,7 +86,7 @@ to the specified calling convention imposes additional safety invariants on its
 and therefore must be marked as an [unsafe function].
 
 > ***Note***: a `naked_asm!` invocation may refer to registers that were not specified as operands.
-> for standard `asm!` this is undefined behavior, but `inline_asm!` may rely on the state of registers
+> for standard `asm!` this is undefined behavior, but `naked_asm!` may rely on the state of registers
 > as specified by the calling convention.
 
 r[attributes.codegen.naked.unused-variables]

src/inline-assembly.md

@@ -2,10 +2,11 @@ r[asm]
 # Inline assembly
 
 r[asm.intro]
-Support for inline assembly is provided via the [`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
+[`naked_asm!`]: core::arch::naked_asm
 [`global_asm!`]: core::arch::global_asm
 
 r[asm.stable-targets]
@@ -58,14 +59,15 @@ option := "pure" / "nomem" / "readonly" / "preserves_flags" / "noreturn" / "nost
 options := "options(" option *("," option) [","] ")"
 operand := reg_operand / clobber_abi / options
 asm := "asm!(" format_string *("," format_string) *("," operand) [","] ")"
+naked_asm := "asm!(" format_string *("," format_string) *("," operand) [","] ")"
 global_asm := "global_asm!(" format_string *("," format_string) *("," operand) [","] ")"
 ```
 
 r[asm.scope]
 ## Scope
 
 r[asm.scope.intro]
-Inline assembly can be used in one of two ways.
+Inline assembly can be used in one of three ways.
 
 r[asm.scope.asm]
 With the `asm!` macro, the assembly code is emitted in a function scope and integrated into the compiler-generated assembly code of a function.
@@ -78,6 +80,10 @@ unsafe { core::arch::asm!("/* {} */", in(reg) 0); }
 # }
 ```
 
+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).
+
 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.
@@ -368,8 +374,11 @@ 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.
+
 r[asm.operand-type.global_asm-restriction]
-Since `global_asm!` exists outside a function, it can only use `sym` and `const` operands.
+Because `global_asm!` exists outside a function, it can only use `sym` and `const` operands.
 
 ```rust,compile_fail
 # fn main() {}
@@ -1176,9 +1185,13 @@ unsafe { core::arch::asm!("mov {:e}, 1", out(reg) z, options(noreturn)); }
 # #[cfg(not(target_arch = "x86_64"))] core::compile_error!("Test not supported on this arch");
 ```
 
+r[asm.options.naked_asm-restriction]
+`global_asm!` only supports the `att_syntax` and `raw` options.
+The remaining options are not meaningful because the inline assembly defines the whole function body.
+
 r[asm.options.global_asm-restriction]
 `global_asm!` only supports the `att_syntax` and `raw` options.
-The remaining options are not meaningful for global-scope inline assembly
+The remaining options are not meaningful for global-scope inline assembly.
 
 ```rust,compile_fail
 # fn main() {}
@@ -1331,6 +1344,43 @@ r[asm.rules.x86-prefix-restriction]
 r[asm.rules.preserves_flags]
 > **Note**: As a general rule, the flags covered by `preserves_flags` are those which are *not* preserved when performing a function call.
 
+r[asm.naked-rules]
+## Rules for naked inline assembly
+
+r[asm.naked-rules.intro]
+To avoid undefined behavior, these rules must be followed when using function-scope inline assembly in naked functions (`naked_asm!`):
+
+r[asm.naked-rules.reg-not-input]
+- Any registers not used for function inputs according to the calling convention and function signature will contain an undefined value on entry to the asm block.
+  - An "undefined value" in the context of inline assembly means that the register can (non-deterministically) have any one of the possible values allowed by the architecture.
+    Notably it is not the same as an LLVM `undef` which can have a different value every time you read it (since such a concept does not exist in assembly code).
+
+r[asm.naked-rules.reg-not-output]
+- Any callee-saved registers must have the same value upon exiting the asm block as they had on entry, otherwise behavior is undefined.
+  - Caller-saved registes may be used freely, even if they are not used for the return value.
+
+r[asm.naked-rules.unwind]
+- Behavior is undefined if execution unwinds out of an asm block.
+  - This also applies if the assembly code calls a function which then unwinds.
+
+r[asm.naked-rules.noreturn]
+- Behavior is undefined if execution falls through to the end of the asm block.
+
+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 asm block.
+
+r[asm.naked-rules.black-box]
+- The compiler cannot assume that the instructions in the asm are the ones that will actually end up executed.
+  - This effectively means that the compiler must treat the `naked_asm!` as a black box and only take the interface specification into account, not the instructions themselves.
+  - Runtime code patching is allowed, via target-specific mechanisms.
+  - However there is no guarantee that each `naked_asm!` directly corresponds to a single instance of instructions in the object file: the compiler is free to duplicate or deduplicate `naked_asm!` blocks.
+
+r[asm.naked-rules.not-exactly-once]
+- You cannot assume that an `naked_asm!` block will appear exactly once in the output binary.
+  The compiler is allowed to instantiate multiple copies of the `naked_asm!` block, for example when the function containing it is inlined in multiple places.
+
 r[asm.validity]
 ### Correctness and Validity