Rollup merge of #41135 - japaric:unstable-docs, r=steveklabnik

document some existing unstable features

"msp430-interrupt", "ptx-kernel" and #![compiler_builtins_lib]

r? @steveklabnik
This commit is contained in:
Tim Neumann 2017-04-08 08:55:08 +02:00 committed by GitHub
commit 29880e678f
4 changed files with 123 additions and 4 deletions

View file

@ -5,3 +5,38 @@ The tracking issue for this feature is: [#38487]
[#38487]: https://github.com/rust-lang/rust/issues/38487
------------------------
In the MSP430 architecture, interrupt handlers have a special calling
convention. You can use the `"msp430-interrupt"` ABI to make the compiler apply
the right calling convention to the interrupt handlers you define.
<!-- NOTE(ignore) this example is specific to the msp430 target -->
``` rust,ignore
#![feature(abi_msp430_interrupt)]
#![no_std]
// Place the interrupt handler at the appropriate memory address
// (Alternatively, you can use `#[used]` and remove `pub` and `#[no_mangle]`)
#[link_section = "__interrupt_vector_10"]
#[no_mangle]
pub static TIM0_VECTOR: extern "msp430-interrupt" fn() = tim0;
// The interrupt handler
extern "msp430-interrupt" fn tim0() {
// ..
}
```
``` text
$ msp430-elf-objdump -CD ./target/msp430/release/app
Disassembly of section __interrupt_vector_10:
0000fff2 <TIM0_VECTOR>:
fff2: 00 c0 interrupt service routine at 0xc000
Disassembly of section .text:
0000c000 <int::tim0>:
c000: 00 13 reti
```

View file

@ -1,5 +1,60 @@
# `abi_ptx`
The tracking issue for this feature is: None.
The tracking issue for this feature is: [#38788]
[#38788]: https://github.com/rust-lang/rust/issues/38788
------------------------
When emitting PTX code, all vanilla Rust functions (`fn`) get translated to
"device" functions. These functions are *not* callable from the host via the
CUDA API so a crate with only device functions is not too useful!
OTOH, "global" functions *can* be called by the host; you can think of them
as the real public API of your crate. To produce a global function use the
`"ptx-kernel"` ABI.
<!-- NOTE(ignore) this example is specific to the nvptx targets -->
``` rust,ignore
#![feature(abi_ptx)]
#![no_std]
pub unsafe extern "ptx-kernel" fn global_function() {
device_function();
}
pub fn device_function() {
// ..
}
```
``` text
$ xargo rustc --target nvptx64-nvidia-cuda --release -- --emit=asm
$ cat $(find -name '*.s')
//
// Generated by LLVM NVPTX Back-End
//
.version 3.2
.target sm_20
.address_size 64
// .globl _ZN6kernel15global_function17h46111ebe6516b382E
.visible .entry _ZN6kernel15global_function17h46111ebe6516b382E()
{
ret;
}
// .globl _ZN6kernel15device_function17hd6a0e4993bbf3f78E
.visible .func _ZN6kernel15device_function17hd6a0e4993bbf3f78E()
{
ret;
}
```

View file

@ -1,5 +1,35 @@
# `compiler_builtins_lib`
This feature is internal to the Rust compiler and is not intended for general use.
The tracking issue for this feature is: None.
------------------------
This feature is required to link to the `compiler_builtins` crate which contains
"compiler intrinsics". Compiler intrinsics are software implementations of basic
operations like multiplication of `u64`s. These intrinsics are only required on
platforms where these operations don't directly map to a hardware instruction.
You should never need to explicitly link to the `compiler_builtins` crate when
building "std" programs as `compiler_builtins` is already in the dependency
graph of `std`. But you may need it when building `no_std` **binary** crates. If
you get a *linker* error like:
``` text
$PWD/src/main.rs:11: undefined reference to `__aeabi_lmul'
$PWD/src/main.rs:11: undefined reference to `__aeabi_uldivmod'
```
That means that you need to link to this crate.
When you link to this crate, make sure it only appears once in your crate
dependency graph. Also, it doesn't matter where in the dependency graph, you
place the `compiler_builtins` crate.
<!-- NOTE(ignore) doctests don't support `no_std` binaries -->
``` rust,ignore
#![feature(compiler_builtins_lib)]
#![no_std]
extern crate compiler_builtins;
```

View file

@ -1,6 +1,5 @@
# `compiler_builtins`
The tracking issue for this feature is: None.
This feature is internal to the Rust compiler and is not intended for general use.
------------------------