From f45c6d8fc7097b5186ece9c43c3237d1c58e8dd4 Mon Sep 17 00:00:00 2001
From: Jorge Aparicio <japaricious@gmail.com>
Date: Fri, 7 Apr 2017 01:05:03 -0500
Subject: [PATCH] document some existing unstable features

"msp430-interrupt", "ptx-kernel" and #![compiler_builtins_lib]
---
 .../unstable-book/src/abi-msp430-interrupt.md | 35 ++++++++++++
 src/doc/unstable-book/src/abi-ptx.md          | 56 ++++++++++++++++++-
 .../src/compiler-builtins-lib.md              | 32 ++++++++++-
 .../unstable-book/src/compiler-builtins.md    |  3 +-
 4 files changed, 122 insertions(+), 4 deletions(-)

diff --git a/src/doc/unstable-book/src/abi-msp430-interrupt.md b/src/doc/unstable-book/src/abi-msp430-interrupt.md
index 9b2c7f29897..b10bc41cb14 100644
--- a/src/doc/unstable-book/src/abi-msp430-interrupt.md
+++ b/src/doc/unstable-book/src/abi-msp430-interrupt.md
@@ -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
+```
diff --git a/src/doc/unstable-book/src/abi-ptx.md b/src/doc/unstable-book/src/abi-ptx.md
index 9c1b8868ace..89b2a199279 100644
--- a/src/doc/unstable-book/src/abi-ptx.md
+++ b/src/doc/unstable-book/src/abi-ptx.md
@@ -1,5 +1,59 @@
 # `abi_ptx`
 
-The tracking issue for this feature is: None.
+The tracking issue for this feature
+is: [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;
+}
+```
diff --git a/src/doc/unstable-book/src/compiler-builtins-lib.md b/src/doc/unstable-book/src/compiler-builtins-lib.md
index 8986b968ca6..5da8968fd0c 100644
--- a/src/doc/unstable-book/src/compiler-builtins-lib.md
+++ b/src/doc/unstable-book/src/compiler-builtins-lib.md
@@ -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;
+```
diff --git a/src/doc/unstable-book/src/compiler-builtins.md b/src/doc/unstable-book/src/compiler-builtins.md
index 3ec3cba257a..52fac575b6e 100644
--- a/src/doc/unstable-book/src/compiler-builtins.md
+++ b/src/doc/unstable-book/src/compiler-builtins.md
@@ -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.
 
 ------------------------
-