global_asm

The tracking issue for this feature is: #35119

The global_asm! macro allows the programmer to write arbitrary assembly outside the scope of a function body, passing it through rustc and llvm to the assembler. That is to say, global_asm! is equivalent to assembling the asm with an external assembler and then linking the resulting object file with the current crate.

global_asm! fills a role not currently satisfied by either asm! or #[naked] functions. The programmer has all features of the assembler at their disposal. The linker will expect to resolve any symbols defined in the inline assembly, modulo any symbols marked as external. It also means syntax for directives and assembly follow the conventions of the assembler in your toolchain.

A simple usage looks like this:

#![feature(global_asm)]
// you also need relevant target_arch cfgs
global_asm!(include_str!("something_neato.s"));

And a more complicated usage looks like this:

#![allow(unused)]
#![feature(global_asm)]
fn main() {
#[cfg(any(target_arch="x86", target_arch="x86_64"))]
mod x86 {

pub mod sally {
    global_asm!(
        ".global foo",
        "foo:",
        "jmp baz",
    );

    #[no_mangle]
    pub unsafe extern "C" fn baz() {}
}

// the symbols `foo` and `bar` are global, no matter where
// `global_asm!` was used.
extern "C" {
    fn foo();
    fn bar();
}

pub mod harry {
    global_asm!(
        ".global bar",
        "bar:",
        "jmp quux",
    );

    #[no_mangle]
    pub unsafe extern "C" fn quux() {}
}
}
}

You may use global_asm! multiple times, anywhere in your crate, in whatever way suits you. However, you should not rely on assembler state (e.g. assembler macros) defined in one global_asm! to be available in another one. It is implementation-defined whether the multiple usages are concatenated into one or assembled separately.

global_asm! also supports const operands like asm!, which allows constants defined in Rust to be used in assembly code:

#![allow(unused)]
#![feature(global_asm)]
fn main() {
#[cfg(any(target_arch="x86", target_arch="x86_64"))]
mod x86 {
const C: i32 = 1234;
global_asm!(
    ".global bar",
    "bar: .word {c}",
    c = const C,
);
}
}

The syntax for passing operands is the same as asm! except that only const operands are allowed. Refer to the asm documentation for more details.

On x86, the assembly code will use intel syntax by default. You can override this by adding options(att_syntax) at the end of the macro arguments list:

#![allow(unused)]
#![feature(global_asm)]
fn main() {
#[cfg(any(target_arch="x86", target_arch="x86_64"))]
mod x86 {
global_asm!("movl ${}, %ecx", const 5, options(att_syntax));
// is equivalent to
global_asm!("mov ecx, {}", const 5);
}
}

If you don't need quite as much power and flexibility as global_asm! provides, and you don't mind restricting your inline assembly to fn bodies only, you might try the asm feature instead.