Skip to content

Commit 9ffc347

Browse files
committed
Update unstable book with global_asm feature
1 parent 817298a commit 9ffc347

File tree

1 file changed

+45
-0
lines changed

1 file changed

+45
-0
lines changed
+45
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
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 assembly. That is, all
13+
caveats, constraints, injunctions, rules, best practices, terms, and
14+
conditions apply to assembly written with `global_asm!`.
15+
16+
`global_asm!` fills a role currently not satisfied by either `asm!`
17+
or `#[naked]` functions. With it, a programmer may define arbitrary
18+
symbols, assembler macros, functions, or _any_ other low-level
19+
behavior. The programmer has all features of the assembler at their
20+
disposal. This means linker will expect to resolve any symbols
21+
defined by the macro, modulo any symbols marked as external. It also
22+
means syntax for directives and assembly follow the conventions of
23+
the assembler in your toolchain.
24+
25+
A simple usage looks like this:
26+
27+
```rust,ignore
28+
global_asm!(r#"
29+
.global my_asm_func
30+
.hidden __cancel
31+
my_asm_func:
32+
ret
33+
__other_cancel:
34+
jmp __cancel
35+
"#);
36+
37+
extern "C" {
38+
fn my_asm_func();
39+
fn __other_cancel();
40+
}
41+
42+
fn __cancel() {
43+
// do strange stuff
44+
}
45+
```

0 commit comments

Comments
 (0)