22.1. Registers¶

Syntax

RegisterName ::=
    " ExplicitRegisterName "
  | RegisterClassName

ExplicitRegisterName ::=
    a[0-31]
  | ah    | al    | ax
  | b[0-31]
  | bh    | bl    | bp    | bpl   | bx
  | ch    | cl    | cx
  | d[0-31]
  | dh    | di    | dil   | dl    | dx
  | eax   | ebp   | ebx   | ecx   | edi   | edx   | eip   | esi
  | esp
  | f[0-31]
  | fa[0-7]
  | ffr   | fp
  | fs[0-11]
  | ft[0-11]
  | gp
  | h[0-31]
  | ip
  | k[0-7]
  | lr
  | m[0-7]
  | p[0-15]
  | pc
  | q[0-31]
  | r[0-15]
  | r[8-15]d
  | r[8-15]w
  | ra    | rax
  | rb[8-15]
  | rbp   | rbx   | rcx
  | rdi   | rdx   | rfp   | rip   | rsi   | rsp
  | s[0-31]
  | si    | sil   | sl    | sp    | spl
  | st([0-7])
  | t[0-6]
  | tmm[0-7]
  | tp
  | v[0-31]
  | w[0-31]
  | wsp   | wzr
  | x[0-31]
  | xmm[0-31]
  | xzr
  | ymm[0-31]
  | zero
  | zmm[0-31]

Legality Rules

22.1:1 A register is a hardware component capable of holding data that can be read and written.

22.1:2 An input register is a register whose register name is used in a register argument subject to direction modifier in, inout, or inlateout.

22.1:3 An output register is a register whose register name is used in a register argument subject to direction modifier out, lateout, inout, or inlateout.

22.1:4 A register that is not specified as an output register shall have the same value upon exit from an assembly code block as it did upon entry into the assembly code block.

22.1:5 A register name is either the explicit register name of a register, or the register class name of the register class a register belongs to.

22.1:6 An explicit register name is a target-specific string that identifies a register.

22.1:7 An explicit register name may be aliased as follows:

22.1:52 Certain explicit register names are not supported on selected architectures, as follows:

22.1:71 It is a static error to use an unsupported explicit register name.

Undefined Behavior

22.1:72 It is undefined behavior if a register that is not specified as an output register has a different value upon exit from an assembly code block from the value it had upon entry into the assembly code block.

22.2. Register Classes¶

Syntax

RegisterClassName ::=
    dreg
  | dreg_low16
  | dreg_low8
  | freg
  | kreg
  | kreg0
  | mmx_reg
  | preg
  | qreg
  | qreg_low4
  | qreg_low8
  | reg
  | reg_abcd
  | reg_byte
  | sreg
  | sreg_low16
  | tmm_reg
  | vreg
  | vreg_low16
  | x86_reg
  | xmm_reg
  | ymm_reg
  | zmm_reg

Legality Rules

22.2:1 A register class represents a set of registers.

22.2:2 A register class name is a target-specific string that identifies a register class.

22.2:3 Registers are organized into register classes as follows:

22.2:34 If a value has a smaller size than the register it is allocated in, then

• 22.2:35 On RISC-V architectures, if the register belongs to register class freg, then f32 values are NaN-boxed. in a f64 value.

• 22.2:36 Otherwise, for an input register, the upper bits of the register have an undefined value.

• 22.2:37 Otherwise, for an output register, the upper bits are ignored.

22.2:38 If a register argument has direction modifier inout and an input-output register expression, then the input register expression and the output register expression shall have the same type.

22.3. Register Arguments¶

Syntax

RegisterArgument ::=
    (Identifier =)? DirectionModifier ( RegisterName ) RegisterExpression

DirectionModifier ::=
    in
  | inlateout
  | inout
  | lateout
  | out

RegisterExpression ::=
    InputOutputRegisterExpression
  | SimpleRegisterExpression

InputOutputRegisterExpression ::=
    InputRegisterExpression => OutputRegisterExpression
  | InputRegisterExpression => UnderscoreExpression

InputRegisterExpression ::=
    Expression

OutputRegisterExpression ::=
    Expression

SimpleRegisterExpression ::=
    Expression
  | UnderscoreExpression

Legality Rules

22.3:1 A register argument is a construct that configures the input and output of a register, and optionally binds the configuration to an identifier.

22.3:2 A register argument shall be used within an assembly instruction.

22.3:3 A named register argument is a register argument whose configuration is bound to an identifier.

22.3:4 A positional register argument is a register argument whose configuration is not bound to an identifier.

22.3:5 A named register argument shall appear after a positional register argument.

22.3:6 An explicit register argument is a register argument that uses an explicit register name.

22.3:7 An explicit register argument shall appear after a named register argument.

22.3:8 A register class argument is a register argument that uses a register class name.

22.3:9 A register class argument causes an assembler to select a suitable register from the related register class.

22.3:10 A direction modifier is a construct that indicates whether a register argument initializes a register, assigns the value of a register to an expression, or both.

22.3:11 An input register expression is an expression that provides the initial value of a register.

22.3:12 An output register expression is an expression that is assigned the value of a register.

22.3:13 An input-output register expression is a construct that specifies both an input register expression and an output register expression.

22.3:14 A simple register expression is either an expression or an underscore expression.

22.3:15 A register expression is either an input-output register expression or a simple register expression.

22.3:16 The type of an input register expression, output register expression, or simple register expression shall depend on the architecture and the target feature in effect, as follows:

22.3:40 If a register argument has direction modifier in and a simple register expression, then

• 22.3:41 Upon entry of an assembly code block, the register contains the value of the simple register expression.

• 22.3:42 On exit from an assembly code block, the register shall contain the same value, unless the register is subject to direction modifier lateout.

22.3:43 If a register argument has direction modifier out and a simple register expression, then

• 22.3:44 Upon entry of an assembly code block, the register contains an undefined value.

• 22.3:45 On exit from an assembly code block, the value of the register is assigned to the simple register expression. The simple register expression shall be a place expression.

• 22.3:46 If the simple register expression is an underscore expression, then the value of the register is discarded.

22.3:47 If a register argument has direction modifier lateout and a simple register expression, then the register argument behaves as a register argument with direction modifier out, except that the register can be reused with direction modifier in.

22.3:48 If a register argument has direction modifier inout and a simple register expression, then

• 22.3:49 Upon entry of an assembly code block, the register contains the value of the simple register expression.

• 22.3:50 On exit from an assembly code block, the value of the register is assigned to the place indicated by the simple register expression. The simple register expression shall be a mutable place expression.

22.3:51 If a register argument has direction modifier inout and an input-output register expression, then

• 22.3:52 Upon entry of an assembly code block, the register contains the value of the input register expression.

• 22.3:53 On exit from an assembly code block, the value of the register is assigned to the place indicated by the output register expression. The output register expression shall be a place expression.

• 22.3:54 If the output register expression is an underscore expression, then the value of the register is discarded.

22.3:55 If a register argument has direction modifier inlateout and a simple register expression, then the register argument behaves as a register argument with direction modifier inout, except that the register can be reused with direction modifier in.

22.3:56 If a register argument has direction modifier inlateout and an input-output register expression, then the register argument behaves as a register argument with direction modifier inout, except that the register can be reused with direction modifier in.

22.3:57 It is a static error to specify a register argument with direction modifier and register expression other than the combinations listed above.

Dynamic Semantics

22.3:58 The evaluation of a register argument proceeds as follows:

• 22.3:59 If a register argument has an input-output register expression, then

  1. 22.3:60 The input register expression is evaluated.

  2. 22.3:61 The output register expression is evaluated.

• 22.3:62 If a register argument has a simple register expression, then the simple register expression is evaluated.

Examples

let mut left_value: i32 = 1;
let right_value: i32 = 2;

unsafe {
    asm!(
        "add {left} {right}",
        left = inout(reg) left_value,
        right = in(reg) right_value,
    );
}

22.4. Assembly Instructions¶

Syntax

AssemblyCodeBlock ::=
    AssemblyInstruction (, AssemblyInstruction)*

AssemblyInstruction ::=
    StringLiteral

Legality Rules

22.4:1 An assembly instruction is a string literal that represents a low-level assembly operation or an assembly directive.

22.4:2 An assembly instruction shall use the syntax of format strings as defined in module std::fmt, and contain zero or more register parameters.

22.4:3 An assembly code block is a sequence of assembly instructions.

22.4:4 When an assembly code block contains multiple assembly instructions, the assembly instructions are treated as concatenated into a single string literal, with character 0x0A (new line) between them.

22.4:5 The set of memory locations that an assembly code block is allowed to read and write are the same as those for an external function, excluding the memory locations that are private to the assembly code block.

22.4:6 A tool is not required to guarantee that an assembly code block appears exactly once in the final assembly output.

22.4:7 A tool is not required to guarantee that two assembly code blocks appear in the same declarative order in the final assembly output, or appear contiguously in successive addresses.

22.4:8 A register parameter is a substring delimited by characters 0x7B (left curly bracket) and 0x7D (right curly bracket) that is substituted with a register argument in an assembly instruction.

22.4:9 On x86 architectures, direction flag DF in register EFLAGS shall be cleared on exit from an assembly code block.

Undefined Behavior

22.4:10 On x86 architectures, it is undefined behavior if direction flag DF in register EFLAGS remains set on exit from an assembly code block.

Examples

"shl {value} 2"

let mut left_value: i32 = 1;
let right_value: i32 = 2;

unsafe {
    asm!(
        "add {left}:e {right}:x",
        left = inout(reg) left_value,
        right = in(reg) right_value,
    );
}

22.5. ABI Clobbers¶

Syntax

AbiClobber ::=
    clobber_abi ( AbiKindList )

AbiKindList ::=
    AbiKind (, AbiKind)* ,?

Legality Rules

22.5:1 An ABI clobber is an argument to macro core::arch::asm which indicates that the values of selected registers might be overwritten during the execution of an assembly code block.

22.5:2 Multiple ABI clobbers may be specified for an assembly code block. Clobber constraints are applied for all unique registers in the union of all specified ABIs.

22.5:3 The effects of an ABI clobber depend on the ABI in effect, as follows:

22.5:11 On x86 architectures, the x87 floating-point register stack shall remain unchanged unless all st([0-7]) registers have been clobbered.

22.5:12 On x86 architectures, if all x87 registers are clobbered, then the x87 register stack is presumed empty upon entry of an assembly code block. The x87 register stack shall be empty on exit from an assembly code block.

Examples

clobber_abi("C", "system")

22.6. Assembly Options¶

Syntax

AssemblyOption ::=
    options ( OptionList )

OptionList ::=
    Option (, Option)* ,?

Option ::=
    att_syntax
  | nomem
  | noreturn
  | nostack
  | preserves_flags
  | pure
  | raw
  | readonly

Legality Rules

22.6:1 An assembly option is used to specify a characteristic of or a restriction on the related assembly code block.

22.6:2 Assembly option att_syntax is applicable only to x86 architectures and causes the assembler to use the .att_syntax prefix mode which prefixes registers with %.

22.6:3 Assembly option nomem indicates that the assembly code block does not read or write memory.

22.6:4 Assembly option noreturn indicates that the assembly code block does not return, preventing the dropping of variables.

22.6:5 Assembly option nostack indicates that the assembly code block does not push on the stack, or write to the stack red-zone (if supported).

22.6:6 If assembly option nostack is not in effect, then an assembly code block is allowed to use stack space below the stack pointer. Upon entry of an assembly code block, the stack pointer is suitably aligned according to the target ABI for call expressions. The stack pointer shall be restored to its original value on exit from the assembly code block.

22.6:7 Assembly option preserves_flags indicates that the assembly code block does not modify the flags register.

22.6:8 If assembly option preserves_flags is in effect, then the values of the following flags registers shall be restored on exit from an assembly code block:

22.6:14 Assembly option pure indicates that the assembly code block has no side effects, and its outputs depend only on direct inputs.

22.6:15 Assembly option raw causes assembly instructions to be parsed raw, without any special handling of register parameters.

22.6:16 Assembly option readonly indicates that the assembly code block does not write memory.

22.6:17 Assembly options att_syntax and raw shall appear only in GlobalAsmArguments.

22.6:18 Assembly options nomem and readonly shall not be used together.

22.6:19 Assembly option noreturn shall not be specified on an assembly code block that has output registers.

22.6:20 Assembly option pure shall appear with either assembly option nomem or assembly option readonly.

22.6:21 Assembly option pure shall not be specified on an assembly code block that either lacks output registers or all register expressions of output registers are underscore expressions.

Undefined Behavior

22.6:22 It is undefined behavior if an assembly code block subject to assembly option pure has side effects other than its direct outputs.

22.6:23 It is undefined behavior if control reaches the end of an assembly code block subject to assembly option noreturn.

Examples

options(nomem, pure)

22.7. Macros asm and global_asm¶

Syntax

AsmArguments ::=
    ( AssemblyCodeBlock (, RegisterArgument)* (, AbiClobber)* (, AssemblyOption)* ,? )

GlobalAsmArguments ::=
    ( AssemblyCodeBlock (, RegisterArgument)* (, AssemblyOption)* ,? )

Legality Rules

22.7:1 Assembly code blocks are embedded within Rust source code using macros core::arch::asm and core::arch::global_asm.

22.7:2 When invoking macro core::arch::asm, the DelimitedTokenTree of the related macro invocation shall follow the syntax of AsmArguments.

22.7:3 Invoking macro core::arch::asm causes the related assembly code block to be integrated into the generated assembly of the function where the macro invocation took place. A tool is free to encapsulate the assembly code block in a separate function and generate a call expression to it.

22.7:4 When invoking macro core::arch::global_asm, the DelimitedTokenTree of the related macro invocation shall follow the syntax of GlobalAsmArguments.

22.7:5 Invoking macro core::arch::global_asm causes the related assembly code block to be emitted outside the function where the macro invocation took place.

Dynamic Semantics

22.7:6 The evaluation of a macro invocation to macro core::arch::asm or macro core::arch::global_asm evaluates register arguments in declarative order.

22.7:7 The execution of an assembly code block produced by inline assembly proceeds as follows:

1. 22.7:8 All input registers are initialized to the values provided by the respective register arguments, in an undefined order.

2. 22.7:9 The assembly instructions of the assembly code block are executed in declarative order.

3. 22.7:10 The values of all output registers are assigned to the register expressions provided by the respective register arguments, in an undefined order.

Examples

fn asm_example() -> u32 {
    let basepri;
    unsafe {
        asm!("
            mrs {}, BASEPRI
        ",
        out(reg) basepri,
        options(nomem, nostack, preserves_flags))
    }
    basepri
}

global_asm!("
    do_nothing:
        push {r7, lr}
        mov  r7, sp
        pop  {r7, pc}
    ",
    options(raw)
);

fn global_asm_example() {
    extern "C" {
        fn do_nothing();
    }

    unsafe { do_nothing() }
}