Skip to content

document cfg conditions on inline assembly templates and operands #2063

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

document cfg conditions on inline assembly templates and operands #2063

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/attributes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,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.
Copy link
Contributor

@petrochenkov petrochenkov Oct 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, it may be a mostly theoretical concern, but attributes are not supported here.
asm! rather have an attribute-like syntax in its DSL - rust-lang/rust#147736 (comment).

The "only cfg and cfg_attr" restriction is unique to all attribute positions and is a direct consequence of the above.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This list is about allowed positions, and with asm_cfg attributes are parsed on template strings and operands, so saying that they are a valid position for attributes feels right.

But yeah they aren't really supported like in the other places listed here.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an interesting question because for example in things like #1890 we document that diagnostics are allowed in all attribute positions. I'm not sure how to resolve that.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are there any diagnostics that are meaningful on a (macro call that expands to a) template string? We could parse and then silently discard them, but actually making the diagnostic attribute do something would be tough I think.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#[rustfmt::skip] could be meaningful, but assembly is not formatted at all currently, so in practice it won't do anything today.

Copy link
Contributor

@ehuss ehuss Oct 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know. You could have something silly like asm!(#[allow(named_asm_labels)] "warned: nop");, but I don't think that is something worth doing.

I'm not suggesting that it is something that should be changed. I'm just trying to think of how we can cleanly fit it in to the reference text.


r[attributes.meta]
## Meta item attribute syntax
Expand Down Expand Up @@ -410,3 +411,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
40 changes: 39 additions & 1 deletion src/inline-assembly.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 ->
Expand Down Expand Up @@ -266,6 +270,40 @@ 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.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you add an example here showing cfg being used?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added

core::arch::naked_asm!(
    #[cfg(not(panic = "abort"))]
    ".cfi_startproc",
    // ...
    "ret",
    #[cfg(not(panic = "abort"))]
    ".cfi_endproc",
);

Loosely based on https://github.com/nbdd0121/unwinding/blob/3bc28cec6c30eade0e1caa094b49db78101b19ef/src/unwinder/arch/aarch64.rs#L66C24-L66C40.

It's tough to come up with simple full examples, so hopefully this conveys the idea.

```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",
);
```

r[asm.attributes.starts-with-template]
Syntactically there must be at least one template string before the first operand.

```rust, ignore
// 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 expected token: `,`
"",
);
```

[`cfg`]: conditional-compilation.md#the-cfg-attribute
[`cfg_attr`]: conditional-compilation.md#the-cfg_attr-attribute

r[asm.operand-type]
## Operand type

Expand Down
Loading