From 26e4adf7796abc9b68a4ca23b95cf7b58caa7c44 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Sun, 25 Aug 2024 20:30:41 -0400 Subject: [PATCH 1/2] Clarify that the prefix restriction and stateful directives restrictions are required to be obeyed even if the assembly block is never executed. --- src/inline-assembly.md | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/src/inline-assembly.md b/src/inline-assembly.md index 9dd02e2fc..1927cce26 100644 --- a/src/inline-assembly.md +++ b/src/inline-assembly.md @@ -650,13 +650,12 @@ r[asm.rules.not-exactly-once] - You cannot assume that an `asm!` block will appear exactly once in the output binary. The compiler is allowed to instantiate multiple copies of the `asm!` block, for example when the function containing it is inlined in multiple places. -r[asm.rules.x86-prefix-restriction] -- On x86, inline assembly must not end with an instruction prefix (such as `LOCK`) that would apply to instructions generated by the compiler. - - The compiler is currently unable to detect this due to the way inline assembly is compiled, but may catch and reject this in the future. + 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. + ### Correctness and Validity r[asm.validity] @@ -684,6 +683,14 @@ and the rules for assembly may include thousands of pages of architectural refer Programmers should exercise appropriate care, as invoking this `unsafe` capability comes with assuming the responsibility of not violating rules of both the compiler or the architecture. +r[asm.validity.stateful] +If inline assembly includes any "stateful" directive that modifies how subsequent assembly is processed, the block must undo the effects of any such directives before the inline assembly ends. If this constraint is violated, an error may be issued if it can be detected, but otherwise the result of executing the program that contains it is undefined - regardless of whether or not the inline assembly block that contains is eventually evaluated by that execution. + +r[asm.validity.prefix-restriction] +Inline assembly must not end with an instruction prefix (such as `LOCK`) that would apply to instructions generated by the compiler. If this constraint is violated, an error may be issued if it can be detected, but otherwise the result of executing the program that contains it is undefined - regardless of whether or not the inline assembly block that contains is eventually evaluated by that execution. + +> **Note:** The two previous constraints are not currently checked but may be in the future. + ### Directives Support r[asm.directives] @@ -692,8 +699,7 @@ r[asm.directives.subset-supported] Inline assembly supports a subset of the directives supported by both GNU AS and LLVM's internal assembler, given as follows. The result of using other directives is assembler-specific (and may cause an error, or may be accepted as-is). -r[asm.directives.stateful] -If inline assembly includes any "stateful" directive that modifies how subsequent assembly is processed, the block must undo the effects of any such directives before the inline assembly ends. + r[asm.directives.supported-directives] The following directives are guaranteed to be supported by the assembler: From f73f91fb757d4023ff709637ff794942e75876a0 Mon Sep 17 00:00:00 2001 From: Connor Horman Date: Sun, 25 Aug 2024 20:33:00 -0400 Subject: [PATCH 2/2] Remove excess whitespace --- src/inline-assembly.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/src/inline-assembly.md b/src/inline-assembly.md index 1927cce26..bba89c8b4 100644 --- a/src/inline-assembly.md +++ b/src/inline-assembly.md @@ -650,12 +650,9 @@ r[asm.rules.not-exactly-once] - You cannot assume that an `asm!` block will appear exactly once in the output binary. The compiler is allowed to instantiate multiple copies of the `asm!` block, for example when the function containing it is inlined in multiple places. - - 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. - ### Correctness and Validity r[asm.validity] @@ -699,8 +696,6 @@ r[asm.directives.subset-supported] Inline assembly supports a subset of the directives supported by both GNU AS and LLVM's internal assembler, given as follows. The result of using other directives is assembler-specific (and may cause an error, or may be accepted as-is). - - r[asm.directives.supported-directives] The following directives are guaranteed to be supported by the assembler: