src/doc/unstable-book/src/language-features/global-asm.md

   1 # `global_asm`
   2
   3 The tracking issue for this feature is: [#35119]
   4
   5 [#35119]: https://github.com/rust-lang/rust/issues/35119
   6
   7 ------------------------
   8
   9 The `global_asm!` macro allows the programmer to write arbitrary
  10 assembly outside the scope of a function body, passing it through
  11 `rustc` and `llvm` to the assembler. The macro is a no-frills
  12 interface to LLVM's concept of [module-level inline assembly]. That is,
  13 all caveats applicable to LLVM's module-level inline assembly apply
  14 to `global_asm!`.
  15
  16 [module-level inline assembly]: http://llvm.org/docs/LangRef.html#module-level-inline-assembly
  17
  18 `global_asm!` fills a role not currently satisfied by either `asm!`
  19 or `#[naked]` functions. The programmer has _all_ features of the
  20 assembler at their disposal. The linker will expect to resolve any
  21 symbols defined in the inline assembly, modulo any symbols marked as
  22 external. It also means syntax for directives and assembly follow the
  23 conventions of the assembler in your toolchain.
  24
  25 A simple usage looks like this:
  26
  27 ```rust,ignore
  28 # #![feature(global_asm)]
  29 # you also need relevant target_arch cfgs
  30 global_asm!(include_str!("something_neato.s"));
  31 ```
  32
  33 And a more complicated usage looks like this:
  34
  35 ```rust,ignore
  36 # #![feature(global_asm)]
  37 # #![cfg(any(target_arch = "x86", target_arch = "x86_64"))]
  38
  39 pub mod sally {
  40     global_asm!(r#"
  41         .global foo
  42       foo:
  43         jmp baz
  44     "#);
  45
  46     #[no_mangle]
  47     pub unsafe extern "C" fn baz() {}
  48 }
  49
  50 // the symbols `foo` and `bar` are global, no matter where
  51 // `global_asm!` was used.
  52 extern "C" {
  53     fn foo();
  54     fn bar();
  55 }
  56
  57 pub mod harry {
  58     global_asm!(r#"
  59         .global bar
  60       bar:
  61         jmp quux
  62     "#);
  63
  64     #[no_mangle]
  65     pub unsafe extern "C" fn quux() {}
  66 }
  67 ```
  68
  69 You may use `global_asm!` multiple times, anywhere in your crate, in
  70 whatever way suits you. The effect is as if you concatenated all
  71 usages and placed the larger, single usage in the crate root.
  72
  73 ------------------------
  74
  75 If you don't need quite as much power and flexibility as
  76 `global_asm!` provides, and you don't mind restricting your inline
  77 assembly to `fn` bodies only, you might try the
  78 [asm](language-features/asm.html) feature instead.