Merge pull request #2063 from folkertdev/asm-cfg

document `cfg` conditions on inline assembly templates and operands

Author: ehuss

src/attributes.md

@@ -107,6 +107,7 @@ Attributes may be applied to many forms in the language:
 * [Function][functions], [closure] and [function pointer]
   parameters accept outer attributes. This includes attributes on variadic parameters
   denoted with `...` in function pointers and [external blocks][variadic functions].
+* [Inline assembly] template strings and operands accept outer attributes. Only certain attributes are accepted semantically; for details, see [asm.attributes.supported-attributes].
 
 r[attributes.meta]
 ## Meta item attribute syntax
@@ -409,3 +410,4 @@ The following is an index of all built-in attributes.
 [variadic functions]: items/external-blocks.html#variadic-functions
 [`diagnostic::on_unimplemented`]: attributes/diagnostics.md#the-diagnosticon_unimplemented-attribute
 [`diagnostic::do_not_recommend`]: attributes/diagnostics.md#the-diagnosticdo_not_recommend-attribute
+[Inline assembly]: inline-assembly.md

src/inline-assembly.md

@@ -49,15 +49,19 @@ r[asm.syntax]
 The following grammar specifies the arguments that can be passed to the `asm!`, `global_asm!` and `naked_asm!` macros.
 
 ```grammar,assembly
-@root AsmArgs -> FormatString (`,` FormatString)* (`,` AsmOperand)* `,`?
+@root AsmArgs -> AsmAttrFormatString (`,` AsmAttrFormatString)* (`,` AsmAttrOperand)* `,`?
 
 FormatString -> STRING_LITERAL | RAW_STRING_LITERAL | MacroInvocation
 
+AsmAttrFormatString -> (OuterAttribute)* FormatString
+
 AsmOperand ->
       ClobberAbi
     | AsmOptions
     | RegOperand
 
+AsmAttrOperand -> (OuterAttribute)* AsmOperand
+
 ClobberAbi -> `clobber_abi` `(` Abi (`,` Abi)* `,`? `)`
 
 AsmOptions ->
@@ -266,6 +270,44 @@ Further constraints on the directives used by inline assembly are indicated by [
 [format-syntax]: std::fmt#syntax
 [rfc-2795]: https://github.com/rust-lang/rfcs/pull/2795
 
+r[asm.attributes]
+## Attributes
+
+r[asm.attributes.supported-attributes]
+Only the [`cfg`] and [`cfg_attr`] attributes are accepted semantically on inline assembly template strings and operands. Other attributes are parsed but rejected when the assembly macro is expanded.
+
+```rust
+# fn main() {}
+# #[cfg(target_arch = "x86_64")]
+core::arch::global_asm!(
+    #[cfg(not(panic = "abort"))]
+    ".cfi_startproc",
+    // ...
+    "ret",
+    #[cfg(not(panic = "abort"))]
+    ".cfi_endproc",
+);
+```
+
+> [!NOTE]
+> In `rustc`, the assembly macros implement handling of these attributes separately from the normal system that handles similar attributes in the language. This accounts for the limited kinds of attributes supported and may give rise to subtle differences in behavior.
+
+r[asm.attributes.starts-with-template]
+Syntactically there must be at least one template string before the first operand.
+
+```rust,compile_fail
+// This is rejected because `a = out(reg) x` does not parse as a
+// template string.
+core::arch::asm!(
+    #[cfg(false)]
+    a = out(reg) x, // ERROR.
+    "",
+);
+```
+
+[`cfg`]: conditional-compilation.md#the-cfg-attribute
+[`cfg_attr`]: conditional-compilation.md#the-cfg_attr-attribute
+
 r[asm.operand-type]
 ## Operand type