Update global_asm! documentation
This commit is contained in:
parent
5a229e0e20
commit
0df83f8e5e
@ -8,12 +8,9 @@ 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. The macro is a no-frills
|
||||
interface to LLVM's concept of [module-level inline assembly]. That is,
|
||||
all caveats applicable to LLVM's module-level inline assembly apply
|
||||
to `global_asm!`.
|
||||
|
||||
[module-level inline assembly]: http://llvm.org/docs/LangRef.html#module-level-inline-assembly
|
||||
`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
|
||||
@ -69,8 +66,44 @@ pub mod harry {
|
||||
```
|
||||
|
||||
You may use `global_asm!` multiple times, anywhere in your crate, in
|
||||
whatever way suits you. The effect is as if you concatenated all
|
||||
usages and placed the larger, single usage in the crate root.
|
||||
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:
|
||||
|
||||
```rust,no_run
|
||||
#![feature(global_asm)]
|
||||
# #[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](asm.md) 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:
|
||||
|
||||
```rust,no_run
|
||||
#![feature(global_asm)]
|
||||
# #[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);
|
||||
# }
|
||||
```
|
||||
|
||||
------------------------
|
||||
|
||||
|
Loading…
x
Reference in New Issue
Block a user