Skip to content

Commit

Permalink
Update unstable book with global_asm feature
Browse files Browse the repository at this point in the history
  • Loading branch information
mrhota committed Mar 21, 2017
1 parent 817298a commit 9ffc347
Showing 1 changed file with 45 additions and 0 deletions.
45 changes: 45 additions & 0 deletions src/doc/unstable-book/src/global_asm.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# `global_asm`

The tracking issue for this feature is: [#35119]

[#35119]: https://github.com/rust-lang/rust/issues/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 assembly. That is, all
caveats, constraints, injunctions, rules, best practices, terms, and
conditions apply to assembly written with `global_asm!`.

`global_asm!` fills a role currently not satisfied by either `asm!`
or `#[naked]` functions. With it, a programmer may define arbitrary
symbols, assembler macros, functions, or _any_ other low-level
behavior. The programmer has all features of the assembler at their
disposal. This means linker will expect to resolve any symbols
defined by the macro, 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:

```rust,ignore
global_asm!(r#"
.global my_asm_func
.hidden __cancel
my_asm_func:
ret
__other_cancel:
jmp __cancel
"#);
extern "C" {
fn my_asm_func();
fn __other_cancel();
}
fn __cancel() {
// do strange stuff
}
```

0 comments on commit 9ffc347

Please sign in to comment.