Skip to content

Document asm_cfg inline assembly attributes #653

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
PLeVasseur wants to merge 6 commits into
base: main
Choose a base branch
from
Open

Document asm_cfg inline assembly attributes #653

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
1b8f423
docs(inline-assembly): document asm_cfg attributes
PLeVasseur Jan 31, 2026
c632ac1
docs(inline-assembly): tie cfg-false behavior to conditional compilation
PLeVasseur Jan 31, 2026
dfe3535
docs(inline-assembly): use glossary terms in legality rules
PLeVasseur Jan 31, 2026
c890043
docs(inline-assembly): move attribute rules under macros
PLeVasseur Jan 31, 2026
f79bfa7
docs(inline-assembly): avoid line-wrapped legality paragraphs
PLeVasseur Jan 31, 2026
c7f1f37
docs(inline-assembly): expand assembly attribute grammar names
PLeVasseur Jan 31, 2026
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
11 changes: 11 additions & 0 deletions src/changelog.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,17 @@ Language changes in Rust 1.93.0
- No change: this bug was not documented in FLS

- `Stabilize asm_cfg <https://github.com/rust-lang/rust/pull/147736>`_

- Changed syntax: :s:`AssemblyCodeBlock`, :s:`AsmArguments`, :s:`GlobalAsmArguments`
- New syntax: :s:`AssemblyTemplate`, :s:`AssemblyAttributeRegisterArgument`, :s:`AssemblyAttributeAbiClobber`, :s:`AssemblyAttributeAssemblyOption`

- New paragraphs:

- :p:`fls_m0SBtonaNppV`
- :p:`fls_nLBhw2w6uznH`
- :p:`fls_xzDPz2zfRfoI`
- :p:`fls_cTEiqjf6haEg`

- `During const-evaluation, support copying pointers byte-by-byte <https://github.com/rust-lang/rust/pull/148259>`_
- `LUB coercions now correctly handle function item types, and functions with differing safeties <https://github.com/rust-lang/rust/pull/148602>`_
- `Allow const items that contain mutable references to static (which is *very* unsafe, but not *always* UB) <https://github.com/rust-lang/rust/pull/148746>`_
Expand Down
44 changes: 41 additions & 3 deletions src/inline-assembly.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -963,7 +963,10 @@ Assembly Instructions
.. syntax::

AssemblyCodeBlock ::=
AssemblyInstruction ($$,$$ AssemblyInstruction)*
AssemblyTemplate ($$,$$ AssemblyTemplate)*

AssemblyTemplate ::=
OuterAttribute* AssemblyInstruction

AssemblyInstruction ::=
StringLiteral
Expand Down Expand Up @@ -1625,10 +1628,19 @@ Macros: asm, global_asm, and naked_asm
.. syntax::

AsmArguments ::=
$$($$ AssemblyCodeBlock ($$,$$ LabelBlock)? ($$,$$ RegisterArgument)* ($$,$$ AbiClobber)* ($$,$$ AssemblyOption)* $$,$$? $$)$$
$$($$ AssemblyCodeBlock ($$,$$ LabelBlock)? ($$,$$ AssemblyAttributeRegisterArgument)* ($$,$$ AssemblyAttributeAbiClobber)* ($$,$$ AssemblyAttributeAssemblyOption)* $$,$$? $$)$$

GlobalAsmArguments ::=
$$($$ AssemblyCodeBlock ($$,$$ RegisterArgument)* ($$,$$ AssemblyOption)* $$,$$? $$)$$
$$($$ AssemblyCodeBlock ($$,$$ AssemblyAttributeRegisterArgument)* ($$,$$ AssemblyAttributeAssemblyOption)* $$,$$? $$)$$

AssemblyAttributeRegisterArgument ::=
OuterAttribute* RegisterArgument

AssemblyAttributeAbiClobber ::=
OuterAttribute* AbiClobber

AssemblyAttributeAssemblyOption ::=
OuterAttribute* AssemblyOption

LabelBlock ::=
$$block$$ $${$$ StatementList $$}$$
Expand All @@ -1641,6 +1653,18 @@ Macros: asm, global_asm, and naked_asm
:std:`core::arch::global_asm`, and
:std:`core::arch::naked_asm`.

:dp:`fls_m0SBtonaNppV`
The :t:`[assembly instruction]s`, :t:`[register argument]s`, :t:`[ABI clobber]s`, and :t:`[assembly option]s` in :s:`AsmArguments` and :s:`GlobalAsmArguments` may be preceded by :t:`outer attribute` instances.

:dp:`fls_nLBhw2w6uznH`
Only the :t:`attribute` :c:`cfg` and the :t:`attribute` :c:`cfg_attr` are accepted on inline assembly arguments. All other attributes are rejected.

:dp:`fls_xzDPz2zfRfoI`
If a :t:`assembly instruction`, :t:`register argument`, :t:`ABI clobber`, or :t:`assembly option` is annotated with :c:`cfg` or :c:`cfg_attr` and the related :t:`configuration predicate` evaluates to ``false``, the annotated argument is not considered part of the related macro invocation, consistent with :t:`conditional compilation`.

:dp:`fls_cTEiqjf6haEg`
It is a static error for a :t:`register argument`, :t:`ABI clobber`, or :t:`assembly option` to appear before the first :t:`assembly instruction`, even if the argument is ignored by :t:`conditional compilation`.

:dp:`fls_1ikzov7cxic1`
When invoking :t:`macro` :std:`core::arch::asm`, the :s:`DelimitedTokenTree` of
the related :t:`macro invocation` shall follow the syntax of :s:`AsmArguments`.
Expand Down Expand Up @@ -1698,6 +1722,20 @@ The :t:`execution` of an :t:`assembly code block` produced by

.. rubric:: Examples

.. code-block:: rust

unsafe {
core::arch::asm!(
"nop",
#[cfg(target_feature = "sse2")]
"nop",
#[cfg(target_feature = "sse2")]
in(reg) 0_u32,
#[cfg(target_feature = "sse2")]
options(nomem, nostack),
);
}

.. code-block:: rust

fn asm_example() -> u32 {
Expand Down