fix the allocator example

until https://bugs.llvm.org/show_bug.cgi?id=38435 is fixed

.cargo/config

@@ -1,31 +1,27 @@
 [target.thumbv6m-none-eabi]
 runner = 'arm-none-eabi-gdb'
 rustflags = [
-  "-C", "link-arg=-Tlink.x",
-  "-C", "linker=arm-none-eabi-ld",
-  "-Z", "linker-flavor=ld",
+  "-C", "link-arg=-Wl,-Tlink.x",
+  "-C", "link-arg=-nostartfiles",
 ]
 
 [target.thumbv7m-none-eabi]
 runner = 'arm-none-eabi-gdb'
 rustflags = [
-  "-C", "link-arg=-Tlink.x",
-  "-C", "linker=arm-none-eabi-ld",
-  "-Z", "linker-flavor=ld",
+  "-C", "link-arg=-Wl,-Tlink.x",
+  "-C", "link-arg=-nostartfiles",
 ]
 
 [target.thumbv7em-none-eabi]
 runner = 'arm-none-eabi-gdb'
 rustflags = [
-  "-C", "link-arg=-Tlink.x",
-  "-C", "linker=arm-none-eabi-ld",
-  "-Z", "linker-flavor=ld",
+  "-C", "link-arg=-Wl,-Tlink.x",
+  "-C", "link-arg=-nostartfiles",
 ]
 
 [target.thumbv7em-none-eabihf]
 runner = 'arm-none-eabi-gdb'
 rustflags = [
-  "-C", "link-arg=-Tlink.x",
-  "-C", "linker=arm-none-eabi-ld",
-  "-Z", "linker-flavor=ld",
+  "-C", "link-arg=-Wl,-Tlink.x",
+  "-C", "link-arg=-nostartfiles",
 ]

.gitignore

@@ -1,4 +1,5 @@
 **/*.rs.bk
+.#*
 .gdb_history
 Cargo.lock
 target/

.travis.yml

@@ -0,0 +1,56 @@
+language: rust
+
+matrix:
+  include:
+    - env: TARGET=thumbv6m-none-eabi
+      rust: nightly
+      addons:
+        apt:
+          packages:
+            - gcc-arm-none-eabi
+
+    - env: TARGET=thumbv7m-none-eabi
+      rust: nightly
+      addons:
+        apt:
+          packages:
+            - gcc-arm-none-eabi
+
+    - env: TARGET=thumbv7em-none-eabi
+      rust: nightly
+      addons:
+        apt:
+          packages:
+            - gcc-arm-none-eabi
+
+    - env: TARGET=thumbv7em-none-eabihf
+      rust: nightly
+      addons:
+        apt:
+          packages:
+            - gcc-arm-none-eabi
+
+before_install: set -e
+
+install:
+  - bash ci/install.sh
+
+script:
+  - bash ci/script.sh
+
+after_script: set +e
+
+cache: cargo
+
+before_cache:
+  # Travis can't cache files that are not readable by "others"
+  - chmod -R a+r $HOME/.cargo
+
+branches:
+  only:
+    - staging
+    - trying
+
+notifications:
+  email:
+    on_success: never

CHANGELOG.md

@@ -5,6 +5,88 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [v0.3.2] - 2018-06-19
+
+### Fixed
+
+- Bumped the panic-semihosting dependency to fix some examples when compiling with latest nightly.
+
+## [v0.3.1] - 2018-05-13
+
+- Document the standard `main` interface issue in the troubleshooting guide.
+
+## [v0.3.0] - 2018-05-12
+
+### Changed
+
+- [breaking-change] `arm-none-eabi-gcc` is now a mandatory dependency as it's required by the
+  `cortex-m-rt` dependency and also the default linker.
+
+- Bumped the `cortex-m` and `cortex-m-rt` dependencies to v0.5.0. Updated all the examples to match
+  the new `cortex-m-rt` API.
+
+- Updated the `allocator` example to compile on a recent nightly.
+
+- Set the number of codegen-units to 1 when compiling in release mode. This produces smaller and
+  faster binaries.
+
+### Removed
+
+- Removed `opt-level = "s"` from `profile.release`. This flag is still unstable.
+
+## [v0.2.7] - 2018-04-24
+
+### Changed
+
+- Bumped the dependency of `cortex-m-rt` to v0.4.0.
+
+## [v0.2.6] - 2018-04-09
+
+### Changed
+
+- The documentation to instruct the user to use Cargo instead of Xargo
+
+## [v0.2.5] - 2018-02-26
+
+### Added
+
+- Comments to Cargo.toml and Xargo.toml to make it easier to try the examples.
+
+### Fixed
+
+- The `allocator` example to use the `#[global_allocator]` feature.
+
+## [v0.2.4] - 2018-01-26
+
+### Changed
+
+- Disable ThinLTO which causes extreme binary size bloat. See rust-lang/rust#47770 for details.
+
+## [v0.2.3] - 2018-01-20
+
+### Changed
+
+- Tweaked docs. Instruction steps are now numbered.
+
+### Removed
+
+- The `CARGO_INCREMENTAL=1` workaround has been removed since it's now controlled via Cargo.toml and
+  we have the setting disabled in the template.
+
+## [v0.2.2] - 2018-01-17
+
+### Added
+
+- Troubleshooting documentation: how to workaround the "Ignoring packet error, continuing..." GDB
+  error.
+
+### Changed
+
+- Disabled incremental compilation and parallel codegen on the dev profile to reduce the changes of
+  running into rust-lang/rust#47074.
+
+- Bumped the version of the `cortex-m-rt` dependency to v0.3.12.
+
 ## [v0.2.1] - 2017-07-14
 
 ### Added
@@ -96,7 +178,17 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 - Initial release
 
-[Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.3.2...HEAD
+[v0.3.2]: https://github.com/japaric/cortex-m-quickstart/compare/v0.3.1...v0.3.2
+[v0.3.1]: https://github.com/japaric/cortex-m-quickstart/compare/v0.3.0...v0.3.1
+[v0.3.0]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.7...v0.3.0
+[v0.2.7]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.6...v0.2.7
+[v0.2.6]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.5...v0.2.6
+[v0.2.5]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.4...v0.2.5
+[v0.2.4]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.3...v0.2.4
+[v0.2.3]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.2...v0.2.3
+[v0.2.2]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.1...v0.2.2
+[v0.2.1]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.0...v0.2.1
 [v0.2.0]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.8...v0.2.0
 [v0.1.8]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.7...v0.1.8
 [v0.1.7]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.6...v0.1.7

Cargo.toml

@@ -6,22 +6,26 @@ keywords = ["arm", "cortex-m", "template"]
 license = "MIT OR Apache-2.0"
 name = "cortex-m-quickstart"
 repository = "https://github.com/japaric/cortex-m-quickstart"
-version = "0.2.2"
+version = "0.3.2"
 
 [dependencies]
-cortex-m = "0.3.0"
-cortex-m-semihosting = "0.2.0"
+cortex-m = "0.5.0"
+cortex-m-rt = "0.5.0"
+cortex-m-semihosting = "0.3.0"
+panic-semihosting = "0.3.0"
 
-[dependencies.cortex-m-rt]
-features = ["abort-on-panic"]
-version = "0.3.12"
+# Uncomment for the panic example.
+# panic-itm = "0.1.1"
 
-# disable both incremental compilation and parallel codegen to reduce the chances of running into
-# rust-lang/rust#47074
-[profile.dev]
-codegen-units = 1
-incremental = false
+# Uncomment for the allocator example.
+# alloc-cortex-m = "0.3.4"
+
+# Uncomment for the device example.
+# [dependencies.stm32f103xx]
+# features = ["rt"]
+# version = "0.10.0"
 
 [profile.release]
+codegen-units = 1 # better optimizations
 debug = true
-lto = true
+lto = true # better optimizations

LICENSE-MIT

@@ -1,4 +1,4 @@
-Copyright (c) 2017 {{toml-escape author}}
+Copyright (c) 2018
 
 Permission is hereby granted, free of charge, to any
 person obtaining a copy of this software and associated

Xargo.toml

@@ -1,6 +0,0 @@
-[dependencies.core]
-stage = 0
-
-[dependencies.compiler_builtins]
-features = ["mem"]
-stage = 1

bors.toml

@@ -0,0 +1,3 @@
+status = [
+  "continuous-integration/travis-ci/push",
+]

ci/install.sh

@@ -0,0 +1,7 @@
+set -euxo pipefail
+
+main() {
+    rustup target add $TARGET
+}
+
+main

ci/script.sh

@@ -0,0 +1,70 @@
+set -euxo pipefail
+
+main() {
+    local td=$(mktemp -d)
+
+    git clone . $td
+    pushd $td
+
+    cat >memory.x <<'EOF'
+MEMORY
+{
+  FLASH : ORIGIN = 0x08000000, LENGTH = 256K
+  RAM : ORIGIN = 0x20000000, LENGTH = 40K
+}
+EOF
+
+    local examples=(
+        crash
+        exception
+        hello
+        minimal
+        panic
+    )
+    for ex in "${examples[@]}"; do
+        cargo build --target $TARGET --example $ex
+        cargo build --target $TARGET --example $ex --release
+    done
+
+    # ITM is not available on Cortex-M0
+    if [ $TARGET != thumbv6m-none-eabi ]; then
+        local ex=itm
+        cargo build --target $TARGET --example $ex
+        cargo build --target $TARGET --example $ex --release
+
+        examples+=( $ex )
+    fi
+
+    # Allocator example needs an extra dependency
+    cat >>Cargo.toml <<'EOF'
+[dependencies.alloc-cortex-m]
+version = "0.3.4"
+EOF
+
+    local ex=allocator
+    cargo build --target $TARGET --example $ex --release
+
+    examples+=( $ex )
+
+    # Device example needs an extra dependency
+    if [ $TARGET = thumbv7m-none-eabi ]; then
+        cat >>Cargo.toml <<'EOF'
+[dependencies.stm32f103xx]
+features = ["rt"]
+version = "0.10.0"
+EOF
+
+        local ex=device
+        cargo build --target $TARGET --example $ex
+        cargo build --target $TARGET --example $ex --release
+
+        examples+=( $ex )
+    fi
+
+    IFS=,;eval arm-none-eabi-size target/$TARGET/release/examples/"{${examples[*]}}"
+
+    popd
+    rm -rf $td
+}
+
+main

examples/allocator.rs

@@ -1,22 +1,6 @@
 //! How to use the heap and a dynamic memory allocator
 //!
-//! To compile this example you'll need to build the collections crate as part
-//! of the Xargo sysroot. To do that change the Xargo.toml file to look like
-//! this:
-//!
-//! ``` text
-//! [dependencies.core]
-//! stage = 0
-//!
-//! [dependencies.collections] # NEW
-//! stage = 0
-//!
-//! [dependencies.compiler_builtins]
-//! stage = 1
-//! ```
-//!
-//! This example depends on the alloc-cortex-m crate so you'll have to add it
-//! to your Cargo.toml:
+//! This example depends on the alloc-cortex-m crate so you'll have to add it to your Cargo.toml:
 //!
 //! ``` text
 //! # or edit the Cargo.toml file manually
@@ -25,55 +9,69 @@
 //!
 //! ---
 
-#[allow(deprecated)]
-#![feature(collections)]
-#![feature(used)]
+#![feature(alloc)]
+#![feature(alloc_error_handler)]
+#![feature(global_allocator)]
+#![feature(lang_items)]
+#![no_main]
 #![no_std]
 
 // This is the allocator crate; you can use a different one
 extern crate alloc_cortex_m;
 #[macro_use]
-extern crate collections;
+extern crate alloc;
 extern crate cortex_m;
-extern crate cortex_m_rt;
-extern crate cortex_m_semihosting;
+#[macro_use]
+extern crate cortex_m_rt as rt;
+extern crate cortex_m_semihosting as sh;
+extern crate panic_semihosting;
 
+use core::alloc::Layout;
 use core::fmt::Write;
 
+use alloc_cortex_m::CortexMHeap;
 use cortex_m::asm;
-use cortex_m_semihosting::hio;
+use rt::ExceptionFrame;
+use sh::hio;
 
-fn main() {
-    // Initialize the allocator
-    unsafe {
-        extern "C" {
-            // Start of the heap
-            static mut _sheap: usize;
-        }
+// this is the allocator the application will use
+#[global_allocator]
+static ALLOCATOR: CortexMHeap = CortexMHeap::empty();
 
-        // Size of the heap in words (1 word = 4 bytes)
-        // NOTE The bigger the heap the greater the chance to run into a stack
-        // overflow (collision between the stack and the heap)
-        const SIZE: isize = 256;
+const HEAP_SIZE: usize = 1024; // in bytes
 
-        // End of the heap
-        let _eheap = (&mut _sheap as *mut _).offset(SIZE);
+entry!(main);
 
-        alloc_cortex_m::init(&mut _sheap, _eheap);
-    }
+fn main() -> ! {
+    // Initialize the allocator BEFORE you use it
+    unsafe { ALLOCATOR.init(rt::heap_start() as usize, HEAP_SIZE) }
 
     // Growable array allocated on the heap
     let xs = vec![0, 1, 2];
 
     let mut stdout = hio::hstdout().unwrap();
     writeln!(stdout, "{:?}", xs).unwrap();
+
+    loop {}
 }
 
-// As we are not using interrupts, we just register a dummy catch all handler
-#[link_section = ".vector_table.interrupts"]
-#[used]
-static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-
-extern "C" fn default_handler() {
+// define what happens in an Out Of Memory (OOM) condition
+#[alloc_error_handler]
+#[no_mangle]
+pub fn alloc_error(layout: Layout) -> ! {
     asm::bkpt();
+
+    loop {}
+}
+
+exception!(HardFault, hard_fault);
+
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
+}
+
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
 }

examples/crash.rs

@@ -1,85 +1,114 @@
 //! Debugging a crash (exception)
 //!
-//! The `cortex-m-rt` crate provides functionality for this through a default
-//! exception handler. When an exception is hit, the default handler will
-//! trigger a breakpoint and in this debugging context the stacked registers
-//! are accessible.
+//! Most crash conditions trigger a hard fault exception, whose handler is defined via
+//! `exception!(HardFault, ..)`. The `HardFault` handler has access to the exception frame, a
+//! snapshot of the CPU registers at the moment of the exception.
 //!
-//! In you run the example below, you'll be able to inspect the state of your
-//! program under the debugger using these commands:
+//! This program crashes and the `HardFault` handler prints to the console the contents of the
+//! `ExceptionFrame` and then triggers a breakpoint. From that breakpoint one can see the backtrace
+//! that led to the exception.
 //!
 //! ``` text
-//! (gdb) # Exception frame = program state during the crash
-//! (gdb) print/x *ef
-//! $1 = cortex_m::exception::ExceptionFrame {
-//!   r0 = 0x2fffffff,
-//!   r1 = 0x2fffffff,
-//!   r2 = 0x0,
-//!   r3 = 0x0,
-//!   r12 = 0x0,
-//!   lr = 0x8000481,
-//!   pc = 0x8000460,
-//!   xpsr = 0x61000000,
-//! }
+//! (gdb) continue
+//! Program received signal SIGTRAP, Trace/breakpoint trap.
+//! __bkpt () at asm/bkpt.s:3
+//! 3         bkpt
 //!
-//! (gdb) # Where did we come from?
 //! (gdb) backtrace
-//! #0  cortex_m_rt::default_handler (ef=0x20004f54) at (..)
-//! #1  <signal handler called>
-//! #2  0x08000460 in core::ptr::read_volatile<u32> (src=0x2fffffff) at (..)
-//! #3  0x08000480 in crash::main () at examples/crash.rs:68
+//! #0  __bkpt () at asm/bkpt.s:3
+//! #1  0x080030b4 in cortex_m::asm::bkpt () at $$/cortex-m-0.5.0/src/asm.rs:19
+//! #2  rust_begin_unwind (args=..., file=..., line=99, col=5) at $$/panic-semihosting-0.2.0/src/lib.rs:87
+//! #3  0x08001d06 in core::panicking::panic_fmt () at libcore/panicking.rs:71
+//! #4  0x080004a6 in crash::hard_fault (ef=0x20004fa0) at examples/crash.rs:99
+//! #5  0x08000548 in UserHardFault (ef=0x20004fa0) at <exception macros>:10
+//! #6  0x0800093a in HardFault () at asm.s:5
+//! Backtrace stopped: previous frame identical to this frame (corrupt stack?)
+//! ```
 //!
-//! (gdb) # Nail down the location of the crash
-//! (gdb) disassemble/m ef.pc
-//! Dump of assembler code for function core::ptr::read_volatile<u32>:
-//! 408     pub unsafe fn read_volatile<T>(src: *const T) -> T {
-//!    0x08000454 <+0>:     sub     sp, #20
-//!    0x08000456 <+2>:     mov     r1, r0
-//!    0x08000458 <+4>:     str     r0, [sp, #8]
-//!    0x0800045a <+6>:     ldr     r0, [sp, #8]
-//!    0x0800045c <+8>:     str     r0, [sp, #12]
+//! In the console output one will find the state of the Program Counter (PC) register at the time
+//! of the exception.
 //!
-//! 409         intrinsics::volatile_load(src)
-//!    0x0800045e <+10>:    ldr     r0, [sp, #12]
-//!    0x08000460 <+12>:    ldr     r0, [r0, #0]
-//!    0x08000462 <+14>:    str     r0, [sp, #16]
-//!    0x08000464 <+16>:    ldr     r0, [sp, #16]
-//!    0x08000466 <+18>:    str     r1, [sp, #4]
-//!    0x08000468 <+20>:    str     r0, [sp, #0]
-//!    0x0800046a <+22>:    b.n     0x800046c <core::ptr::read_volatile<u32>+24>
+//! ``` text
+//! panicked at 'HardFault at ExceptionFrame {
+//!     r0: 0x2fffffff,
+//!     r1: 0x2fffffff,
+//!     r2: 0x080051d4,
+//!     r3: 0x080051d4,
+//!     r12: 0x20000000,
+//!     lr: 0x08000435,
+//!     pc: 0x08000ab6,
+//!     xpsr: 0x61000000
+//! }', examples/crash.rs:106:5
+//! ```
 //!
-//! 410     }
-//!    0x0800046c <+24>:    ldr     r0, [sp, #0]
-//!    0x0800046e <+26>:    add     sp, #20
-//!    0x08000470 <+28>:    bx      lr
+//! This register contains the address of the instruction that caused the exception. In GDB one can
+//! disassemble the program around this address to observe the instruction that caused the
+//! exception.
+//!
+//! ``` text
+//! (gdb) disassemble/m 0x08000ab6
+//! Dump of assembler code for function core::ptr::read_volatile:
+//! 451     pub unsafe fn read_volatile<T>(src: *const T) -> T {
+//!    0x08000aae <+0>:     sub     sp, #16
+//!    0x08000ab0 <+2>:     mov     r1, r0
+//!    0x08000ab2 <+4>:     str     r0, [sp, #8]
+//!
+//! 452         intrinsics::volatile_load(src)
+//!    0x08000ab4 <+6>:     ldr     r0, [sp, #8]
+//! -> 0x08000ab6 <+8>:     ldr     r0, [r0, #0]
+//!    0x08000ab8 <+10>:    str     r0, [sp, #12]
+//!    0x08000aba <+12>:    ldr     r0, [sp, #12]
+//!    0x08000abc <+14>:    str     r1, [sp, #4]
+//!    0x08000abe <+16>:    str     r0, [sp, #0]
+//!    0x08000ac0 <+18>:    b.n     0x8000ac2 <core::ptr::read_volatile+20>
+//!
+//! 453     }
+//!    0x08000ac2 <+20>:    ldr     r0, [sp, #0]
+//!    0x08000ac4 <+22>:    add     sp, #16
+//!    0x08000ac6 <+24>:    bx      lr
 //!
 //! End of assembler dump.
 //! ```
 //!
+//! `ldr r0, [r0, #0]` caused the exception. This instruction tried to load (read) a 32-bit word
+//! from the address stored in the register `r0`. Looking again at the contents of `ExceptionFrame`
+//! we see that the `r0` contained the address `0x2FFF_FFFF` when this instruction was executed.
+//!
 //! ---
 
-#![feature(used)]
+#![no_main]
 #![no_std]
 
 extern crate cortex_m;
-extern crate cortex_m_rt;
+#[macro_use]
+extern crate cortex_m_rt as rt;
+extern crate panic_semihosting;
 
 use core::ptr;
 
-use cortex_m::asm;
+use rt::ExceptionFrame;
 
-fn main() {
-    // Read an invalid memory address
+entry!(main);
+
+fn main() -> ! {
     unsafe {
+        // read an address outside of the RAM region; causes a HardFault exception
         ptr::read_volatile(0x2FFF_FFFF as *const u32);
     }
+
+    loop {}
 }
 
-// As we are not using interrupts, we just register a dummy catch all handler
-#[link_section = ".vector_table.interrupts"]
-#[used]
-static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
+// define the hard fault handler
+exception!(HardFault, hard_fault);
 
-extern "C" fn default_handler() {
-    asm::bkpt();
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
+}
+
+// define the default exception handler
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
 }

examples/device.rs

@@ -1,93 +1,89 @@
 //! Using a device crate
 //!
-//! Crates generated using [`svd2rust`] are referred to as device crates. These
-//! crates provides an API to access the peripherals of a device. When you
-//! depend on one of these crates and the "rt" feature is enabled you don't need
-//! link to the cortex-m-rt crate.
+//! Crates generated using [`svd2rust`] are referred to as device crates. These crates provide an
+//! API to access the peripherals of a device.
 //!
 //! [`svd2rust`]: https://crates.io/crates/svd2rust
 //!
-//! Device crates also provide an `interrupt!` macro to register interrupt
+//! Device crates also provide an `interrupt!` macro (behind the "rt" feature) to register interrupt
 //! handlers.
 //!
-//! This example depends on the [`stm32f103xx`] crate so you'll have to add it
-//! to your Cargo.toml.
+//! This example depends on the [`stm32f103xx`] crate so you'll have to add it to your Cargo.toml.
 //!
 //! [`stm32f103xx`]: https://crates.io/crates/stm32f103xx
 //!
 //! ```
-//! $ edit Cargo.toml && cat $_
+//! $ edit Cargo.toml && tail $_
 //! [dependencies.stm32f103xx]
 //! features = ["rt"]
-//! version = "0.7.0"
+//! version = "0.10.0"
 //! ```
 //!
 //! ---
 
-#![deny(warnings)]
-#![feature(const_fn)]
+#![no_main]
 #![no_std]
 
 extern crate cortex_m;
-extern crate cortex_m_semihosting;
-#[macro_use(exception, interrupt)]
+#[macro_use]
+extern crate cortex_m_rt as rt;
+extern crate cortex_m_semihosting as sh;
+#[macro_use]
 extern crate stm32f103xx;
+extern crate panic_semihosting;
 
-use core::cell::RefCell;
 use core::fmt::Write;
 
-use cortex_m::interrupt::{self, Mutex};
-use cortex_m::peripheral::SystClkSource;
-use cortex_m_semihosting::hio::{self, HStdout};
+use cortex_m::peripheral::syst::SystClkSource;
+use rt::ExceptionFrame;
+use sh::hio::{self, HStdout};
 use stm32f103xx::Interrupt;
 
-static HSTDOUT: Mutex<RefCell<Option<HStdout>>> =
-    Mutex::new(RefCell::new(None));
+entry!(main);
 
-fn main() {
-    interrupt::free(|cs| {
-        let hstdout = HSTDOUT.borrow(cs);
-        if let Ok(fd) = hio::hstdout() {
-            *hstdout.borrow_mut() = Some(fd);
-        }
+fn main() -> ! {
+    let p = cortex_m::Peripherals::take().unwrap();
 
-        let nvic = stm32f103xx::NVIC.borrow(cs);
-        nvic.enable(Interrupt::TIM2);
+    let mut syst = p.SYST;
+    let mut nvic = p.NVIC;
 
-        let syst = stm32f103xx::SYST.borrow(cs);
-        syst.set_clock_source(SystClkSource::Core);
-        syst.set_reload(8_000_000); // 1s
-        syst.enable_counter();
-        syst.enable_interrupt();
-    });
+    nvic.enable(Interrupt::EXTI0);
+
+    // configure the system timer to wrap around every second
+    syst.set_clock_source(SystClkSource::Core);
+    syst.set_reload(8_000_000); // 1s
+    syst.enable_counter();
+
+    loop {
+        // busy wait until the timer wraps around
+        while !syst.has_wrapped() {}
+
+        // trigger the `EXTI0` interrupt
+        nvic.set_pending(Interrupt::EXTI0);
+    }
 }
 
-exception!(SYS_TICK, tick);
+// try commenting out this line: you'll end in `default_handler` instead of in `exti0`
+interrupt!(EXTI0, exti0, state: Option<HStdout> = None);
 
-fn tick() {
-    interrupt::free(|cs| {
-        let hstdout = HSTDOUT.borrow(cs);
-        if let Some(hstdout) = hstdout.borrow_mut().as_mut() {
-            writeln!(*hstdout, "Tick").ok();
-        }
+fn exti0(state: &mut Option<HStdout>) {
+    if state.is_none() {
+        *state = Some(hio::hstdout().unwrap());
+    }
 
-        let nvic = stm32f103xx::NVIC.borrow(cs);
-
-        nvic.set_pending(Interrupt::TIM2);
-    });
+    if let Some(hstdout) = state.as_mut() {
+        hstdout.write_str(".").unwrap();
+    }
 }
 
-interrupt!(TIM2, tock, locals: {
-    tocks: u32 = 0;
-});
+exception!(HardFault, hard_fault);
 
-fn tock(l: &mut TIM2::Locals) {
-    l.tocks += 1;
-
-    interrupt::free(|cs| {
-        let hstdout = HSTDOUT.borrow(cs);
-        if let Some(hstdout) = hstdout.borrow_mut().as_mut() {
-            writeln!(*hstdout, "Tock ({})", l.tocks).ok();
-        }
-    });
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
+}
+
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
 }

examples/exception.rs

@@ -0,0 +1,64 @@
+//! Overriding an exception handler
+//!
+//! You can override an exception handler using the [`exception!`][1] macro.
+//!
+//! [1]: https://docs.rs/cortex-m-rt/0.5.0/cortex_m_rt/macro.exception.html
+//!
+//! ---
+
+#![deny(unsafe_code)]
+#![no_main]
+#![no_std]
+
+extern crate cortex_m;
+#[macro_use]
+extern crate cortex_m_rt as rt;
+extern crate cortex_m_semihosting as sh;
+extern crate panic_semihosting;
+
+use core::fmt::Write;
+
+use cortex_m::peripheral::syst::SystClkSource;
+use cortex_m::Peripherals;
+use rt::ExceptionFrame;
+use sh::hio::{self, HStdout};
+
+entry!(main);
+
+fn main() -> ! {
+    let p = Peripherals::take().unwrap();
+    let mut syst = p.SYST;
+
+    // configures the system timer to trigger a SysTick exception every second
+    syst.set_clock_source(SystClkSource::Core);
+    syst.set_reload(8_000_000); // period = 1s
+    syst.enable_counter();
+    syst.enable_interrupt();
+
+    loop {}
+}
+
+// try commenting out this line: you'll end in `default_handler` instead of in `sys_tick`
+exception!(SysTick, sys_tick, state: Option<HStdout> = None);
+
+fn sys_tick(state: &mut Option<HStdout>) {
+    if state.is_none() {
+        *state = Some(hio::hstdout().unwrap());
+    }
+
+    if let Some(hstdout) = state.as_mut() {
+        hstdout.write_str(".").unwrap();
+    }
+}
+
+exception!(HardFault, hard_fault);
+
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
+}
+
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
+}

examples/hello.rs

@@ -2,28 +2,36 @@
 //!
 //! ---
 
-#![feature(used)]
+#![no_main]
 #![no_std]
 
-extern crate cortex_m;
-extern crate cortex_m_rt;
-extern crate cortex_m_semihosting;
+#[macro_use]
+extern crate cortex_m_rt as rt;
+extern crate cortex_m_semihosting as sh;
+extern crate panic_semihosting;
 
 use core::fmt::Write;
 
-use cortex_m::asm;
-use cortex_m_semihosting::hio;
+use rt::ExceptionFrame;
+use sh::hio;
 
-fn main() {
+entry!(main);
+
+fn main() -> ! {
     let mut stdout = hio::hstdout().unwrap();
     writeln!(stdout, "Hello, world!").unwrap();
+
+    loop {}
 }
 
-// As we are not using interrupts, we just register a dummy catch all handler
-#[link_section = ".vector_table.interrupts"]
-#[used]
-static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
+exception!(HardFault, hard_fault);
 
-extern "C" fn default_handler() {
-    asm::bkpt();
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
+}
+
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
 }

examples/itm.rs

@@ -1,40 +1,54 @@
 //! Sends "Hello, world!" through the ITM port 0
 //!
-//! **IMPORTANT** Not all Cortex-M chips support ITM. You'll have to connect the
-//! microcontroller's SWO pin to the SWD interface. Note that some development
-//! boards don't provide this option.
-//!
 //! ITM is much faster than semihosting. Like 4 orders of magnitude or so.
 //!
-//! You'll need [`itmdump`] to receive the message on the host plus you'll need
-//! to uncomment the `monitor` commands in the `.gdbinit` file.
+//! **NOTE** Cortex-M0 chips don't support ITM.
 //!
-//! [`itmdump`]: https://docs.rs/itm/0.1.1/itm/
+//! You'll have to connect the microcontroller's SWO pin to the SWD interface. Note that some
+//! development boards don't provide this option.
+//!
+//! You'll need [`itmdump`] to receive the message on the host plus you'll need to uncomment two
+//! `monitor` commands in the `.gdbinit` file.
+//!
+//! [`itmdump`]: https://docs.rs/itm/0.2.1/itm/
 //!
 //! ---
 
-#![feature(used)]
+#![no_main]
 #![no_std]
 
 #[macro_use]
 extern crate cortex_m;
-extern crate cortex_m_rt;
+#[macro_use]
+extern crate cortex_m_rt as rt;
+extern crate panic_semihosting;
 
-use cortex_m::{asm, interrupt, peripheral};
+use cortex_m::{asm, Peripherals};
+use rt::ExceptionFrame;
 
-fn main() {
-    interrupt::free(|cs| {
-        let itm = peripheral::ITM.borrow(&cs);
+entry!(main);
 
-        iprintln!(&itm.stim[0], "Hello, world!");
-    });
+fn main() -> ! {
+    let mut p = Peripherals::take().unwrap();
+    let stim = &mut p.ITM.stim[0];
+
+    iprintln!(stim, "Hello, world!");
+
+    loop {
+        asm::bkpt();
+    }
 }
 
-// As we are not using interrupts, we just register a dummy catch all handler
-#[link_section = ".vector_table.interrupts"]
-#[used]
-static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
+// define the hard fault handler
+exception!(HardFault, hard_fault);
 
-extern "C" fn default_handler() {
-    asm::bkpt();
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
+}
+
+// define the default exception handler
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
 }

examples/minimal.rs

@@ -0,0 +1,63 @@
+//! Minimal Cortex-M program
+//!
+//! When executed this program will hit the breakpoint set in `main`.
+//!
+//! All Cortex-M programs need to:
+//!
+//! - Contain the `#![no_main]` and `#![no_std]` attributes. Embedded programs don't use the
+//! standard Rust `main` interface or the Rust standard (`std`) library.
+//!
+//! - Define their entry point using [`entry!`] macro.
+//!
+//! [`entry!`]: https://docs.rs/cortex-m-rt/~0.5/cortex_m_rt/macro.entry.html
+//!
+//! - Define their panicking behavior, i.e. what happens when `panic!` is called. The easiest way to
+//! define a panicking behavior is to link to a [panic handler crate][0]
+//!
+//! [0]: https://crates.io/keywords/panic-impl
+//!
+//! - Define the `HardFault` handler using the [`exception!`] macro. This handler (function) is
+//! called when a hard fault exception is raised by the hardware.
+//!
+//! [`exception!`]: https://docs.rs/cortex-m-rt/~0.5/cortex_m_rt/macro..html
+//!
+//! - Define a default handler using the [`exception!`] macro. This function will be used to handle
+//! all interrupts and exceptions which have not been assigned a specific handler.
+
+#![no_main] // <- IMPORTANT!
+#![no_std]
+
+extern crate cortex_m;
+
+#[macro_use(entry, exception)]
+extern crate cortex_m_rt as rt;
+
+// makes `panic!` print messages to the host stderr using semihosting
+extern crate panic_semihosting;
+
+use cortex_m::asm;
+use rt::ExceptionFrame;
+
+// the program entry point is ...
+entry!(main);
+
+// ... this never ending function
+fn main() -> ! {
+    loop {
+        asm::bkpt();
+    }
+}
+
+// define the hard fault handler
+exception!(HardFault, hard_fault);
+
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
+}
+
+// define the default exception handler
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
+}

examples/override-exception-handler.rs

@@ -1,47 +0,0 @@
-//! Overriding an exception handler
-//!
-//! You can override an exception handler using the [`exception!`][1] macro.
-//!
-//! [1]: https://docs.rs/cortex-m-rt/0.3.2/cortex_m_rt/macro.exception.html
-//!
-//! The default exception handler can be overridden using the
-//! [`default_handler!`][2] macro
-//!
-//! [2]: https://docs.rs/cortex-m-rt/0.3.2/cortex_m_rt/macro.default_handler.html
-//!
-//! ---
-
-#![feature(used)]
-#![no_std]
-
-extern crate cortex_m;
-#[macro_use(exception)]
-extern crate cortex_m_rt;
-
-use core::ptr;
-
-use cortex_m::asm;
-
-fn main() {
-    unsafe {
-        // Invalid memory access
-        ptr::read_volatile(0x2FFF_FFFF as *const u32);
-    }
-}
-
-exception!(HARD_FAULT, handler);
-
-fn handler() {
-    // You'll hit this breakpoint rather than the one in cortex-m-rt
-    asm::bkpt()
-}
-
-// As we are not using interrupts, we just register a dummy catch all handler
-#[allow(dead_code)]
-#[used]
-#[link_section = ".vector_table.interrupts"]
-static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-
-extern "C" fn default_handler() {
-    asm::bkpt();
-}

examples/panic.rs

@@ -1,58 +1,44 @@
-//! Defining the panic handler
+//! Changing the panic handler
 //!
-//! The panic handler can be defined through the `panic_fmt` [language item][1].
-//! Make sure that the "abort-on-panic" feature of the cortex-m-rt crate is
-//! disabled to avoid redefining the language item.
+//! The easiest way to change the panic handler is to use a different [panic handler crate][0].
 //!
-//! [1]: https://doc.rust-lang.org/unstable-book/language-features/lang-items.html
+//! [0]: https://crates.io/keywords/panic-impl
 //!
 //! ---
 
-#![feature(core_intrinsics)]
-#![feature(lang_items)]
-#![feature(used)]
+#![no_main]
 #![no_std]
 
-extern crate cortex_m;
-extern crate cortex_m_rt;
-extern crate cortex_m_semihosting;
+#[macro_use]
+extern crate cortex_m_rt as rt;
 
-use core::fmt::Write;
-use core::intrinsics;
+// Pick one of these two panic handlers:
 
-use cortex_m::asm;
-use cortex_m_semihosting::hio;
+// Reports panic messages to the host stderr using semihosting
+extern crate panic_semihosting;
 
-fn main() {
-    panic!("Oops");
+// Logs panic messages using the ITM (Instrumentation Trace Macrocell)
+// NOTE to use this you need to uncomment the `panic-itm` dependency in Cargo.toml
+// extern crate panic_itm;
+
+use rt::ExceptionFrame;
+
+entry!(main);
+
+fn main() -> ! {
+    panic!("Oops")
 }
 
-#[lang = "panic_fmt"]
-#[no_mangle]
-unsafe extern "C" fn rust_begin_unwind(
-    args: core::fmt::Arguments,
-    file: &'static str,
-    line: u32,
-    col: u32,
-) -> ! {
-    if let Ok(mut stdout) = hio::hstdout() {
-        write!(stdout, "panicked at '")
-            .and_then(|_| {
-                stdout
-                    .write_fmt(args)
-                    .and_then(|_| writeln!(stdout, "', {}:{}", file, line))
-            })
-            .ok();
-    }
+// define the hard fault handler
+exception!(HardFault, hard_fault);
 
-    intrinsics::abort()
+fn hard_fault(ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
 }
 
-// As we are not using interrupts, we just register a dummy catch all handler
-#[link_section = ".vector_table.interrupts"]
-#[used]
-static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
+// define the default exception handler
+exception!(*, default_handler);
 
-extern "C" fn default_handler() {
-    asm::bkpt();
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
 }

gen-examples.sh

@@ -5,13 +5,14 @@ set -ex
 
 main() {
     local examples=(
+        minimal
         hello
         itm
         panic
         crash
-        override-exception-handler
-        device
+        exception
         allocator
+        device
     )
 
     rm -rf src/examples
@@ -19,7 +20,7 @@ main() {
     mkdir src/examples
 
     cat >src/examples/mod.rs <<'EOF'
-//! Examples
+//! Examples sorted in increasing degree of complexity
 // Auto-generated. Do not modify.
 EOF
 

memory.x

@@ -2,8 +2,8 @@ MEMORY
 {
   /* NOTE K = KiBi = 1024 bytes */
   /* TODO Adjust these memory regions to match your device memory layout */
-  FLASH : ORIGIN = 0xBAAAAAAD, LENGTH = 0K
-  RAM : ORIGIN = 0xBAAAAAAD, LENGTH = 0K
+  FLASH : ORIGIN = 0x000BAAD0, LENGTH = 0K
+  RAM : ORIGIN = 0xBAAD0000, LENGTH = 0K
 }
 
 /* This is where the call stack will be allocated. */
@@ -18,3 +18,6 @@ MEMORY
 /* This is required only on microcontrollers that store some configuration right
    after the vector table */
 /* _stext = ORIGIN(FLASH) + 0x400; */
+
+/* Size of the heap (in bytes) */
+/* _heap_size = 1024; */

src/examples/_0_hello.rs

@@ -1,33 +0,0 @@
-//! Prints "Hello, world!" on the OpenOCD console using semihosting
-//!
-//! ---
-//!
-//! ```
-//! 
-//! #![feature(used)]
-//! #![no_std]
-//! 
-//! extern crate cortex_m;
-//! extern crate cortex_m_rt;
-//! extern crate cortex_m_semihosting;
-//! 
-//! use core::fmt::Write;
-//! 
-//! use cortex_m::asm;
-//! use cortex_m_semihosting::hio;
-//! 
-//! fn main() {
-//!     let mut stdout = hio::hstdout().unwrap();
-//!     writeln!(stdout, "Hello, world!").unwrap();
-//! }
-//! 
-//! // As we are not using interrupts, we just register a dummy catch all handler
-//! #[link_section = ".vector_table.interrupts"]
-//! #[used]
-//! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-//! 
-//! extern "C" fn default_handler() {
-//!     asm::bkpt();
-//! }
-//! ```
-// Auto-generated. Do not modify.

src/examples/_0_minimal.rs

@@ -0,0 +1,67 @@
+//! Minimal Cortex-M program
+//!
+//! When executed this program will hit the breakpoint set in `main`.
+//!
+//! All Cortex-M programs need to:
+//!
+//! - Contain the `#![no_main]` and `#![no_std]` attributes. Embedded programs don't use the
+//! standard Rust `main` interface or the Rust standard (`std`) library.
+//!
+//! - Define their entry point using [`entry!`] macro.
+//!
+//! [`entry!`]: https://docs.rs/cortex-m-rt/~0.5/cortex_m_rt/macro.entry.html
+//!
+//! - Define their panicking behavior, i.e. what happens when `panic!` is called. The easiest way to
+//! define a panicking behavior is to link to a [panic handler crate][0]
+//!
+//! [0]: https://crates.io/keywords/panic-impl
+//!
+//! - Define the `HardFault` handler using the [`exception!`] macro. This handler (function) is
+//! called when a hard fault exception is raised by the hardware.
+//!
+//! [`exception!`]: https://docs.rs/cortex-m-rt/~0.5/cortex_m_rt/macro..html
+//!
+//! - Define a default handler using the [`exception!`] macro. This function will be used to handle
+//! all interrupts and exceptions which have not been assigned a specific handler.
+//!
+//! ```
+//!
+//! #![no_main] // <- IMPORTANT!
+//! #![no_std]
+//!
+//! extern crate cortex_m;
+//!
+//! #[macro_use(entry, exception)]
+//! extern crate cortex_m_rt as rt;
+//!
+//! // makes `panic!` print messages to the host stderr using semihosting
+//! extern crate panic_semihosting;
+//!
+//! use cortex_m::asm;
+//! use rt::ExceptionFrame;
+//!
+//! // the program entry point is ...
+//! entry!(main);
+//!
+//! // ... this never ending function
+//! fn main() -> ! {
+//!     loop {
+//!         asm::bkpt();
+//!     }
+//! }
+//!
+//! // define the hard fault handler
+//! exception!(HardFault, hard_fault);
+//!
+//! fn hard_fault(ef: &ExceptionFrame) -> ! {
+//!     panic!("HardFault at {:#?}", ef);
+//! }
+//!
+//! // define the default exception handler
+//! exception!(*, default_handler);
+//!
+//! fn default_handler(irqn: i16) {
+//!     panic!("Unhandled exception (IRQn = {})", irqn);
+//! }
+//! ```
+// Auto-generated. Do not modify.

src/examples/_1_hello.rs

@@ -0,0 +1,41 @@
+//! Prints "Hello, world!" on the OpenOCD console using semihosting
+//!
+//! ---
+//!
+//! ```
+//!
+//! #![no_main]
+//! #![no_std]
+//!
+//! #[macro_use]
+//! extern crate cortex_m_rt as rt;
+//! extern crate cortex_m_semihosting as sh;
+//! extern crate panic_semihosting;
+//!
+//! use core::fmt::Write;
+//!
+//! use rt::ExceptionFrame;
+//! use sh::hio;
+//!
+//! entry!(main);
+//!
+//! fn main() -> ! {
+//!     let mut stdout = hio::hstdout().unwrap();
+//!     writeln!(stdout, "Hello, world!").unwrap();
+//!
+//!     loop {}
+//! }
+//!
+//! exception!(HardFault, hard_fault);
+//!
+//! fn hard_fault(ef: &ExceptionFrame) -> ! {
+//!     panic!("HardFault at {:#?}", ef);
+//! }
+//!
+//! exception!(*, default_handler);
+//!
+//! fn default_handler(irqn: i16) {
+//!     panic!("Unhandled exception (IRQn = {})", irqn);
+//! }
+//! ```
+// Auto-generated. Do not modify.

src/examples/_1_itm.rs

@@ -1,44 +0,0 @@
-//! Sends "Hello, world!" through the ITM port 0
-//!
-//! **IMPORTANT** Not all Cortex-M chips support ITM. You'll have to connect the
-//! microcontroller's SWO pin to the SWD interface. Note that some development
-//! boards don't provide this option.
-//!
-//! ITM is much faster than semihosting. Like 4 orders of magnitude or so.
-//!
-//! You'll need [`itmdump`] to receive the message on the host plus you'll need
-//! to uncomment the `monitor` commands in the `.gdbinit` file.
-//!
-//! [`itmdump`]: https://docs.rs/itm/0.1.1/itm/
-//!
-//! ---
-//!
-//! ```
-//! 
-//! #![feature(used)]
-//! #![no_std]
-//! 
-//! #[macro_use]
-//! extern crate cortex_m;
-//! extern crate cortex_m_rt;
-//! 
-//! use cortex_m::{asm, interrupt, peripheral};
-//! 
-//! fn main() {
-//!     interrupt::free(|cs| {
-//!         let itm = peripheral::ITM.borrow(&cs);
-//! 
-//!         iprintln!(&itm.stim[0], "Hello, world!");
-//!     });
-//! }
-//! 
-//! // As we are not using interrupts, we just register a dummy catch all handler
-//! #[link_section = ".vector_table.interrupts"]
-//! #[used]
-//! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-//! 
-//! extern "C" fn default_handler() {
-//!     asm::bkpt();
-//! }
-//! ```
-// Auto-generated. Do not modify.

src/examples/_2_itm.rs

@@ -0,0 +1,58 @@
+//! Sends "Hello, world!" through the ITM port 0
+//!
+//! ITM is much faster than semihosting. Like 4 orders of magnitude or so.
+//!
+//! **NOTE** Cortex-M0 chips don't support ITM.
+//!
+//! You'll have to connect the microcontroller's SWO pin to the SWD interface. Note that some
+//! development boards don't provide this option.
+//!
+//! You'll need [`itmdump`] to receive the message on the host plus you'll need to uncomment two
+//! `monitor` commands in the `.gdbinit` file.
+//!
+//! [`itmdump`]: https://docs.rs/itm/0.2.1/itm/
+//!
+//! ---
+//!
+//! ```
+//!
+//! #![no_main]
+//! #![no_std]
+//!
+//! #[macro_use]
+//! extern crate cortex_m;
+//! #[macro_use]
+//! extern crate cortex_m_rt as rt;
+//! extern crate panic_semihosting;
+//!
+//! use cortex_m::{asm, Peripherals};
+//! use rt::ExceptionFrame;
+//!
+//! entry!(main);
+//!
+//! fn main() -> ! {
+//!     let mut p = Peripherals::take().unwrap();
+//!     let stim = &mut p.ITM.stim[0];
+//!
+//!     iprintln!(stim, "Hello, world!");
+//!
+//!     loop {
+//!         asm::bkpt();
+//!     }
+//! }
+//!
+//! // define the hard fault handler
+//! exception!(HardFault, hard_fault);
+//!
+//! fn hard_fault(ef: &ExceptionFrame) -> ! {
+//!     panic!("HardFault at {:#?}", ef);
+//! }
+//!
+//! // define the default exception handler
+//! exception!(*, default_handler);
+//!
+//! fn default_handler(irqn: i16) {
+//!     panic!("Unhandled exception (IRQn = {})", irqn);
+//! }
+//! ```
+// Auto-generated. Do not modify.

src/examples/_2_panic.rs

@@ -1,62 +0,0 @@
-//! Defining the panic handler
-//!
-//! The panic handler can be defined through the `panic_fmt` [language item][1].
-//! Make sure that the "abort-on-panic" feature of the cortex-m-rt crate is
-//! disabled to avoid redefining the language item.
-//!
-//! [1]: https://doc.rust-lang.org/unstable-book/language-features/lang-items.html
-//!
-//! ---
-//!
-//! ```
-//! 
-//! #![feature(core_intrinsics)]
-//! #![feature(lang_items)]
-//! #![feature(used)]
-//! #![no_std]
-//! 
-//! extern crate cortex_m;
-//! extern crate cortex_m_rt;
-//! extern crate cortex_m_semihosting;
-//! 
-//! use core::fmt::Write;
-//! use core::intrinsics;
-//! 
-//! use cortex_m::asm;
-//! use cortex_m_semihosting::hio;
-//! 
-//! fn main() {
-//!     panic!("Oops");
-//! }
-//! 
-//! #[lang = "panic_fmt"]
-//! #[no_mangle]
-//! unsafe extern "C" fn rust_begin_unwind(
-//!     args: core::fmt::Arguments,
-//!     file: &'static str,
-//!     line: u32,
-//!     col: u32,
-//! ) -> ! {
-//!     if let Ok(mut stdout) = hio::hstdout() {
-//!         write!(stdout, "panicked at '")
-//!             .and_then(|_| {
-//!                 stdout
-//!                     .write_fmt(args)
-//!                     .and_then(|_| writeln!(stdout, "', {}:{}", file, line))
-//!             })
-//!             .ok();
-//!     }
-//! 
-//!     intrinsics::abort()
-//! }
-//! 
-//! // As we are not using interrupts, we just register a dummy catch all handler
-//! #[link_section = ".vector_table.interrupts"]
-//! #[used]
-//! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-//! 
-//! extern "C" fn default_handler() {
-//!     asm::bkpt();
-//! }
-//! ```
-// Auto-generated. Do not modify.

src/examples/_3_crash.rs

@@ -1,89 +0,0 @@
-//! Debugging a crash (exception)
-//!
-//! The `cortex-m-rt` crate provides functionality for this through a default
-//! exception handler. When an exception is hit, the default handler will
-//! trigger a breakpoint and in this debugging context the stacked registers
-//! are accessible.
-//!
-//! In you run the example below, you'll be able to inspect the state of your
-//! program under the debugger using these commands:
-//!
-//! ``` text
-//! (gdb) # Exception frame = program state during the crash
-//! (gdb) print/x *ef
-//! $1 = cortex_m::exception::ExceptionFrame {
-//!   r0 = 0x2fffffff,
-//!   r1 = 0x2fffffff,
-//!   r2 = 0x0,
-//!   r3 = 0x0,
-//!   r12 = 0x0,
-//!   lr = 0x8000481,
-//!   pc = 0x8000460,
-//!   xpsr = 0x61000000,
-//! }
-//!
-//! (gdb) # Where did we come from?
-//! (gdb) backtrace
-//! #0  cortex_m_rt::default_handler (ef=0x20004f54) at (..)
-//! #1  <signal handler called>
-//! #2  0x08000460 in core::ptr::read_volatile<u32> (src=0x2fffffff) at (..)
-//! #3  0x08000480 in crash::main () at examples/crash.rs:68
-//!
-//! (gdb) # Nail down the location of the crash
-//! (gdb) disassemble/m ef.pc
-//! Dump of assembler code for function core::ptr::read_volatile<u32>:
-//! 408     pub unsafe fn read_volatile<T>(src: *const T) -> T {
-//!    0x08000454 <+0>:     sub     sp, #20
-//!    0x08000456 <+2>:     mov     r1, r0
-//!    0x08000458 <+4>:     str     r0, [sp, #8]
-//!    0x0800045a <+6>:     ldr     r0, [sp, #8]
-//!    0x0800045c <+8>:     str     r0, [sp, #12]
-//!
-//! 409         intrinsics::volatile_load(src)
-//!    0x0800045e <+10>:    ldr     r0, [sp, #12]
-//!    0x08000460 <+12>:    ldr     r0, [r0, #0]
-//!    0x08000462 <+14>:    str     r0, [sp, #16]
-//!    0x08000464 <+16>:    ldr     r0, [sp, #16]
-//!    0x08000466 <+18>:    str     r1, [sp, #4]
-//!    0x08000468 <+20>:    str     r0, [sp, #0]
-//!    0x0800046a <+22>:    b.n     0x800046c <core::ptr::read_volatile<u32>+24>
-//!
-//! 410     }
-//!    0x0800046c <+24>:    ldr     r0, [sp, #0]
-//!    0x0800046e <+26>:    add     sp, #20
-//!    0x08000470 <+28>:    bx      lr
-//!
-//! End of assembler dump.
-//! ```
-//!
-//! ---
-//!
-//! ```
-//! 
-//! #![feature(used)]
-//! #![no_std]
-//! 
-//! extern crate cortex_m;
-//! extern crate cortex_m_rt;
-//! 
-//! use core::ptr;
-//! 
-//! use cortex_m::asm;
-//! 
-//! fn main() {
-//!     // Read an invalid memory address
-//!     unsafe {
-//!         ptr::read_volatile(0x2FFF_FFFF as *const u32);
-//!     }
-//! }
-//! 
-//! // As we are not using interrupts, we just register a dummy catch all handler
-//! #[link_section = ".vector_table.interrupts"]
-//! #[used]
-//! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-//! 
-//! extern "C" fn default_handler() {
-//!     asm::bkpt();
-//! }
-//! ```
-// Auto-generated. Do not modify.

src/examples/_3_panic.rs

@@ -0,0 +1,47 @@
+//! Changing the panic handler
+//!
+//! The easiest way to change the panic handler is to use a different [panic handler crate][0].
+//!
+//! [0]: https://crates.io/keywords/panic-impl
+//!
+//! ---
+//!
+//! ```
+//!
+//! #![no_main]
+//! #![no_std]
+//!
+//! #[macro_use]
+//! extern crate cortex_m_rt as rt;
+//!
+//! // Pick one of these two panic handlers:
+//!
+//! // Reports panic messages to the host stderr using semihosting
+//! extern crate panic_semihosting;
+//!
+//! // Logs panic messages using the ITM (Instrumentation Trace Macrocell)
+//! // extern crate panic_itm;
+//!
+//! use rt::ExceptionFrame;
+//!
+//! entry!(main);
+//!
+//! fn main() -> ! {
+//!     panic!("Oops")
+//! }
+//!
+//! // define the hard fault handler
+//! exception!(HardFault, hard_fault);
+//!
+//! fn hard_fault(ef: &ExceptionFrame) -> ! {
+//!     panic!("HardFault at {:#?}", ef);
+//! }
+//!
+//! // define the default exception handler
+//! exception!(*, default_handler);
+//!
+//! fn default_handler(irqn: i16) {
+//!     panic!("Unhandled exception (IRQn = {})", irqn);
+//! }
+//! ```
+// Auto-generated. Do not modify.

src/examples/_4_crash.rs

@@ -0,0 +1,118 @@
+//! Debugging a crash (exception)
+//!
+//! Most crash conditions trigger a hard fault exception, whose handler is defined via
+//! `exception!(HardFault, ..)`. The `HardFault` handler has access to the exception frame, a
+//! snapshot of the CPU registers at the moment of the exception.
+//!
+//! This program crashes and the `HardFault` handler prints to the console the contents of the
+//! `ExceptionFrame` and then triggers a breakpoint. From that breakpoint one can see the backtrace
+//! that led to the exception.
+//!
+//! ``` text
+//! (gdb) continue
+//! Program received signal SIGTRAP, Trace/breakpoint trap.
+//! __bkpt () at asm/bkpt.s:3
+//! 3         bkpt
+//!
+//! (gdb) backtrace
+//! #0  __bkpt () at asm/bkpt.s:3
+//! #1  0x080030b4 in cortex_m::asm::bkpt () at $$/cortex-m-0.5.0/src/asm.rs:19
+//! #2  rust_begin_unwind (args=..., file=..., line=99, col=5) at $$/panic-semihosting-0.2.0/src/lib.rs:87
+//! #3  0x08001d06 in core::panicking::panic_fmt () at libcore/panicking.rs:71
+//! #4  0x080004a6 in crash::hard_fault (ef=0x20004fa0) at examples/crash.rs:99
+//! #5  0x08000548 in UserHardFault (ef=0x20004fa0) at <exception macros>:10
+//! #6  0x0800093a in HardFault () at asm.s:5
+//! Backtrace stopped: previous frame identical to this frame (corrupt stack?)
+//! ```
+//!
+//! In the console output one will find the state of the Program Counter (PC) register at the time
+//! of the exception.
+//!
+//! ``` text
+//! panicked at 'HardFault at ExceptionFrame {
+//!     r0: 0x2fffffff,
+//!     r1: 0x2fffffff,
+//!     r2: 0x080051d4,
+//!     r3: 0x080051d4,
+//!     r12: 0x20000000,
+//!     lr: 0x08000435,
+//!     pc: 0x08000ab6,
+//!     xpsr: 0x61000000
+//! }', examples/crash.rs:106:5
+//! ```
+//!
+//! This register contains the address of the instruction that caused the exception. In GDB one can
+//! disassemble the program around this address to observe the instruction that caused the
+//! exception.
+//!
+//! ``` text
+//! (gdb) disassemble/m 0x08000ab6
+//! Dump of assembler code for function core::ptr::read_volatile:
+//! 451     pub unsafe fn read_volatile<T>(src: *const T) -> T {
+//!    0x08000aae <+0>:     sub     sp, #16
+//!    0x08000ab0 <+2>:     mov     r1, r0
+//!    0x08000ab2 <+4>:     str     r0, [sp, #8]
+//!
+//! 452         intrinsics::volatile_load(src)
+//!    0x08000ab4 <+6>:     ldr     r0, [sp, #8]
+//! -> 0x08000ab6 <+8>:     ldr     r0, [r0, #0]
+//!    0x08000ab8 <+10>:    str     r0, [sp, #12]
+//!    0x08000aba <+12>:    ldr     r0, [sp, #12]
+//!    0x08000abc <+14>:    str     r1, [sp, #4]
+//!    0x08000abe <+16>:    str     r0, [sp, #0]
+//!    0x08000ac0 <+18>:    b.n     0x8000ac2 <core::ptr::read_volatile+20>
+//!
+//! 453     }
+//!    0x08000ac2 <+20>:    ldr     r0, [sp, #0]
+//!    0x08000ac4 <+22>:    add     sp, #16
+//!    0x08000ac6 <+24>:    bx      lr
+//!
+//! End of assembler dump.
+//! ```
+//!
+//! `ldr r0, [r0, #0]` caused the exception. This instruction tried to load (read) a 32-bit word
+//! from the address stored in the register `r0`. Looking again at the contents of `ExceptionFrame`
+//! we see that the `r0` contained the address `0x2FFF_FFFF` when this instruction was executed.
+//!
+//! ---
+//!
+//! ```
+//!
+//! #![no_main]
+//! #![no_std]
+//!
+//! extern crate cortex_m;
+//! #[macro_use]
+//! extern crate cortex_m_rt as rt;
+//! extern crate panic_semihosting;
+//!
+//! use core::ptr;
+//!
+//! use rt::ExceptionFrame;
+//!
+//! entry!(main);
+//!
+//! fn main() -> ! {
+//!     unsafe {
+//!         // read an address outside of the RAM region; causes a HardFault exception
+//!         ptr::read_volatile(0x2FFF_FFFF as *const u32);
+//!     }
+//!
+//!     loop {}
+//! }
+//!
+//! // define the hard fault handler
+//! exception!(HardFault, hard_fault);
+//!
+//! fn hard_fault(ef: &ExceptionFrame) -> ! {
+//!     panic!("HardFault at {:#?}", ef);
+//! }
+//!
+//! // define the default exception handler
+//! exception!(*, default_handler);
+//!
+//! fn default_handler(irqn: i16) {
+//!     panic!("Unhandled exception (IRQn = {})", irqn);
+//! }
+//! ```
+// Auto-generated. Do not modify.

src/examples/_4_override_exception_handler.rs

@@ -1,51 +0,0 @@
-//! Overriding an exception handler
-//!
-//! You can override an exception handler using the [`exception!`][1] macro.
-//!
-//! [1]: https://docs.rs/cortex-m-rt/0.3.2/cortex_m_rt/macro.exception.html
-//!
-//! The default exception handler can be overridden using the
-//! [`default_handler!`][2] macro
-//!
-//! [2]: https://docs.rs/cortex-m-rt/0.3.2/cortex_m_rt/macro.default_handler.html
-//!
-//! ---
-//!
-//! ```
-//! 
-//! #![feature(used)]
-//! #![no_std]
-//! 
-//! extern crate cortex_m;
-//! #[macro_use(exception)]
-//! extern crate cortex_m_rt;
-//! 
-//! use core::ptr;
-//! 
-//! use cortex_m::asm;
-//! 
-//! fn main() {
-//!     unsafe {
-//!         // Invalid memory access
-//!         ptr::read_volatile(0x2FFF_FFFF as *const u32);
-//!     }
-//! }
-//! 
-//! exception!(HARD_FAULT, handler);
-//! 
-//! fn handler() {
-//!     // You'll hit this breakpoint rather than the one in cortex-m-rt
-//!     asm::bkpt()
-//! }
-//! 
-//! // As we are not using interrupts, we just register a dummy catch all handler
-//! #[allow(dead_code)]
-//! #[used]
-//! #[link_section = ".vector_table.interrupts"]
-//! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-//! 
-//! extern "C" fn default_handler() {
-//!     asm::bkpt();
-//! }
-//! ```
-// Auto-generated. Do not modify.

src/examples/_5_device.rs

@@ -1,97 +0,0 @@
-//! Using a device crate
-//!
-//! Crates generated using [`svd2rust`] are referred to as device crates. These
-//! crates provides an API to access the peripherals of a device. When you
-//! depend on one of these crates and the "rt" feature is enabled you don't need
-//! link to the cortex-m-rt crate.
-//!
-//! [`svd2rust`]: https://crates.io/crates/svd2rust
-//!
-//! Device crates also provide an `interrupt!` macro to register interrupt
-//! handlers.
-//!
-//! This example depends on the [`stm32f103xx`] crate so you'll have to add it
-//! to your Cargo.toml.
-//!
-//! [`stm32f103xx`]: https://crates.io/crates/stm32f103xx
-//!
-//! ```
-//! $ edit Cargo.toml && cat $_
-//! [dependencies.stm32f103xx]
-//! features = ["rt"]
-//! version = "0.7.0"
-//! ```
-//!
-//! ---
-//!
-//! ```
-//! 
-//! #![deny(warnings)]
-//! #![feature(const_fn)]
-//! #![no_std]
-//! 
-//! extern crate cortex_m;
-//! extern crate cortex_m_semihosting;
-//! #[macro_use(exception, interrupt)]
-//! extern crate stm32f103xx;
-//! 
-//! use core::cell::RefCell;
-//! use core::fmt::Write;
-//! 
-//! use cortex_m::interrupt::{self, Mutex};
-//! use cortex_m::peripheral::SystClkSource;
-//! use cortex_m_semihosting::hio::{self, HStdout};
-//! use stm32f103xx::Interrupt;
-//! 
-//! static HSTDOUT: Mutex<RefCell<Option<HStdout>>> =
-//!     Mutex::new(RefCell::new(None));
-//! 
-//! fn main() {
-//!     interrupt::free(|cs| {
-//!         let hstdout = HSTDOUT.borrow(cs);
-//!         if let Ok(fd) = hio::hstdout() {
-//!             *hstdout.borrow_mut() = Some(fd);
-//!         }
-//! 
-//!         let nvic = stm32f103xx::NVIC.borrow(cs);
-//!         nvic.enable(Interrupt::TIM2);
-//! 
-//!         let syst = stm32f103xx::SYST.borrow(cs);
-//!         syst.set_clock_source(SystClkSource::Core);
-//!         syst.set_reload(8_000_000); // 1s
-//!         syst.enable_counter();
-//!         syst.enable_interrupt();
-//!     });
-//! }
-//! 
-//! exception!(SYS_TICK, tick);
-//! 
-//! fn tick() {
-//!     interrupt::free(|cs| {
-//!         let hstdout = HSTDOUT.borrow(cs);
-//!         if let Some(hstdout) = hstdout.borrow_mut().as_mut() {
-//!             writeln!(*hstdout, "Tick").ok();
-//!         }
-//! 
-//!         let nvic = stm32f103xx::NVIC.borrow(cs);
-//! 
-//!         nvic.set_pending(Interrupt::TIM2);
-//!     });
-//! }
-//! 
-//! interrupt!(TIM2, tock, locals: {
-//!     tocks: u32 = 0;
-//! });
-//! 
-//! fn tock(l: &mut TIM2::Locals) {
-//!     l.tocks += 1;
-//! 
-//!     interrupt::free(|cs| {
-//!         let hstdout = HSTDOUT.borrow(cs);
-//!         if let Some(hstdout) = hstdout.borrow_mut().as_mut() {
-//!             writeln!(*hstdout, "Tock ({})", l.tocks).ok();
-//!         }
-//!     });
-//! }
-//! ```
-// Auto-generated. Do not modify.

src/examples/_5_exception.rs

@@ -0,0 +1,68 @@
+//! Overriding an exception handler
+//!
+//! You can override an exception handler using the [`exception!`][1] macro.
+//!
+//! [1]: https://docs.rs/cortex-m-rt/0.5.0/cortex_m_rt/macro.exception.html
+//!
+//! ---
+//!
+//! ```
+//!
+//! #![deny(unsafe_code)]
+//! #![no_main]
+//! #![no_std]
+//!
+//! extern crate cortex_m;
+//! #[macro_use]
+//! extern crate cortex_m_rt as rt;
+//! extern crate cortex_m_semihosting as sh;
+//! extern crate panic_semihosting;
+//!
+//! use core::fmt::Write;
+//!
+//! use cortex_m::peripheral::syst::SystClkSource;
+//! use cortex_m::Peripherals;
+//! use rt::ExceptionFrame;
+//! use sh::hio::{self, HStdout};
+//!
+//! entry!(main);
+//!
+//! fn main() -> ! {
+//!     let p = Peripherals::take().unwrap();
+//!     let mut syst = p.SYST;
+//!
+//!     // configures the system timer to trigger a SysTick exception every second
+//!     syst.set_clock_source(SystClkSource::Core);
+//!     syst.set_reload(8_000_000); // period = 1s
+//!     syst.enable_counter();
+//!     syst.enable_interrupt();
+//!
+//!     loop {}
+//! }
+//!
+//! // try commenting out this line: you'll end in `default_handler` instead of in `sys_tick`
+//! exception!(SysTick, sys_tick, state: Option<HStdout> = None);
+//!
+//! fn sys_tick(state: &mut Option<HStdout>) {
+//!     if state.is_none() {
+//!         *state = Some(hio::hstdout().unwrap());
+//!     }
+//!
+//!     if let Some(hstdout) = state.as_mut() {
+//!         hstdout.write_str(".").unwrap();
+//!     }
+//! }
+//!
+//! exception!(HardFault, hard_fault);
+//!
+//! fn hard_fault(ef: &ExceptionFrame) -> ! {
+//!     panic!("HardFault at {:#?}", ef);
+//! }
+//!
+//! exception!(*, default_handler);
+//!
+//! fn default_handler(irqn: i16) {
+//!     panic!("Unhandled exception (IRQn = {})", irqn);
+//! }
+//! ```
+// Auto-generated. Do not modify.

src/examples/_6_allocator.rs

@@ -1,22 +1,6 @@
 //! How to use the heap and a dynamic memory allocator
 //!
-//! To compile this example you'll need to build the collections crate as part
-//! of the Xargo sysroot. To do that change the Xargo.toml file to look like
-//! this:
-//!
-//! ``` text
-//! [dependencies.core]
-//! stage = 0
-//!
-//! [dependencies.collections] # NEW
-//! stage = 0
-//!
-//! [dependencies.compiler_builtins]
-//! stage = 1
-//! ```
-//!
-//! This example depends on the alloc-cortex-m crate so you'll have to add it
-//! to your Cargo.toml:
+//! This example depends on the alloc-cortex-m crate so you'll have to add it to your Cargo.toml:
 //!
 //! ``` text
 //! # or edit the Cargo.toml file manually
@@ -26,58 +10,70 @@
 //! ---
 //!
 //! ```
-//! 
-//! #[allow(deprecated)]
-//! #![feature(collections)]
-//! #![feature(used)]
+//!
+//! #![feature(alloc)]
+//! #![feature(global_allocator)]
+//! #![feature(lang_items)]
+//! #![no_main]
 //! #![no_std]
-//! 
+//!
 //! // This is the allocator crate; you can use a different one
 //! extern crate alloc_cortex_m;
 //! #[macro_use]
-//! extern crate collections;
+//! extern crate alloc;
 //! extern crate cortex_m;
-//! extern crate cortex_m_rt;
-//! extern crate cortex_m_semihosting;
-//! 
+//! #[macro_use]
+//! extern crate cortex_m_rt as rt;
+//! extern crate cortex_m_semihosting as sh;
+//! extern crate panic_semihosting;
+//!
 //! use core::fmt::Write;
-//! 
+//!
+//! use alloc_cortex_m::CortexMHeap;
 //! use cortex_m::asm;
-//! use cortex_m_semihosting::hio;
-//! 
-//! fn main() {
-//!     // Initialize the allocator
-//!     unsafe {
-//!         extern "C" {
-//!             // Start of the heap
-//!             static mut _sheap: usize;
-//!         }
-//! 
-//!         // Size of the heap in words (1 word = 4 bytes)
-//!         // NOTE The bigger the heap the greater the chance to run into a stack
-//!         // overflow (collision between the stack and the heap)
-//!         const SIZE: isize = 256;
-//! 
-//!         // End of the heap
-//!         let _eheap = (&mut _sheap as *mut _).offset(SIZE);
-//! 
-//!         alloc_cortex_m::init(&mut _sheap, _eheap);
-//!     }
-//! 
+//! use rt::ExceptionFrame;
+//! use sh::hio;
+//!
+//! // this is the allocator the application will use
+//! #[global_allocator]
+//! static ALLOCATOR: CortexMHeap = CortexMHeap::empty();
+//!
+//! const HEAP_SIZE: usize = 1024; // in bytes
+//!
+//! entry!(main);
+//!
+//! fn main() -> ! {
+//!     // Initialize the allocator BEFORE you use it
+//!     unsafe { ALLOCATOR.init(rt::heap_start() as usize, HEAP_SIZE) }
+//!
 //!     // Growable array allocated on the heap
 //!     let xs = vec![0, 1, 2];
-//! 
+//!
 //!     let mut stdout = hio::hstdout().unwrap();
 //!     writeln!(stdout, "{:?}", xs).unwrap();
+//!
+//!     loop {}
 //! }
-//! 
-//! // As we are not using interrupts, we just register a dummy catch all handler
-//! #[link_section = ".vector_table.interrupts"]
-//! #[used]
-//! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
-//! 
-//! extern "C" fn default_handler() {
+//!
+//! // define what happens in an Out Of Memory (OOM) condition
+//! #[lang = "oom"]
+//! #[no_mangle]
+//! pub fn rust_oom() -> ! {
 //!     asm::bkpt();
+//!
+//!     loop {}
+//! }
+//!
+//! exception!(HardFault, hard_fault);
+//!
+//! fn hard_fault(ef: &ExceptionFrame) -> ! {
+//!     panic!("HardFault at {:#?}", ef);
+//! }
+//!
+//! exception!(*, default_handler);
+//!
+//! fn default_handler(irqn: i16) {
+//!     panic!("Unhandled exception (IRQn = {})", irqn);
 //! }
 //! ```
 // Auto-generated. Do not modify.

src/examples/_7_device.rs

@@ -0,0 +1,93 @@
+//! Using a device crate
+//!
+//! Crates generated using [`svd2rust`] are referred to as device crates. These crates provide an
+//! API to access the peripherals of a device.
+//!
+//! [`svd2rust`]: https://crates.io/crates/svd2rust
+//!
+//! Device crates also provide an `interrupt!` macro (behind the "rt" feature) to register interrupt
+//! handlers.
+//!
+//! This example depends on the [`stm32f103xx`] crate so you'll have to add it to your Cargo.toml.
+//!
+//! [`stm32f103xx`]: https://crates.io/crates/stm32f103xx
+//!
+//! ```
+//! $ edit Cargo.toml && tail $_
+//! [dependencies.stm32f103xx]
+//! features = ["rt"]
+//! version = "0.10.0"
+//! ```
+//!
+//! ---
+//!
+//! ```
+//!
+//! #![no_main]
+//! #![no_std]
+//!
+//! extern crate cortex_m;
+//! #[macro_use]
+//! extern crate cortex_m_rt as rt;
+//! extern crate cortex_m_semihosting as sh;
+//! #[macro_use]
+//! extern crate stm32f103xx;
+//! extern crate panic_semihosting;
+//!
+//! use core::fmt::Write;
+//!
+//! use cortex_m::peripheral::syst::SystClkSource;
+//! use rt::ExceptionFrame;
+//! use sh::hio::{self, HStdout};
+//! use stm32f103xx::Interrupt;
+//!
+//! entry!(main);
+//!
+//! fn main() -> ! {
+//!     let p = cortex_m::Peripherals::take().unwrap();
+//!
+//!     let mut syst = p.SYST;
+//!     let mut nvic = p.NVIC;
+//!
+//!     nvic.enable(Interrupt::EXTI0);
+//!
+//!     // configure the system timer to wrap around every second
+//!     syst.set_clock_source(SystClkSource::Core);
+//!     syst.set_reload(8_000_000); // 1s
+//!     syst.enable_counter();
+//!
+//!     loop {
+//!         // busy wait until the timer wraps around
+//!         while !syst.has_wrapped() {}
+//!
+//!         // trigger the `EXTI0` interrupt
+//!         nvic.set_pending(Interrupt::EXTI0);
+//!     }
+//! }
+//!
+//! // try commenting out this line: you'll end in `default_handler` instead of in `exti0`
+//! interrupt!(EXTI0, exti0, state: Option<HStdout> = None);
+//!
+//! fn exti0(state: &mut Option<HStdout>) {
+//!     if state.is_none() {
+//!         *state = Some(hio::hstdout().unwrap());
+//!     }
+//!
+//!     if let Some(hstdout) = state.as_mut() {
+//!         hstdout.write_str(".").unwrap();
+//!     }
+//! }
+//!
+//! exception!(HardFault, hard_fault);
+//!
+//! fn hard_fault(ef: &ExceptionFrame) -> ! {
+//!     panic!("HardFault at {:#?}", ef);
+//! }
+//!
+//! exception!(*, default_handler);
+//!
+//! fn default_handler(irqn: i16) {
+//!     panic!("Unhandled exception (IRQn = {})", irqn);
+//! }
+//! ```
+// Auto-generated. Do not modify.

src/examples/mod.rs

@@ -1,9 +1,10 @@
-//! Examples
+//! Examples sorted in increasing degree of complexity
 // Auto-generated. Do not modify.
-pub mod _0_hello;
-pub mod _1_itm;
-pub mod _2_panic;
-pub mod _3_crash;
-pub mod _4_override_exception_handler;
-pub mod _5_device;
+pub mod _0_minimal;
+pub mod _1_hello;
+pub mod _2_itm;
+pub mod _3_panic;
+pub mod _4_crash;
+pub mod _5_exception;
 pub mod _6_allocator;
+pub mod _7_device;

src/lib.rs

@@ -2,23 +2,35 @@
 //!
 //! # Dependencies
 //!
-//! - Nightly Rust toolchain: `rustup default nightly`
-//! - ARM linker: `sudo apt-get install binutils-arm-none-eabi`
+//! - Nightly Rust toolchain newer than `nightly-2018-04-08`: `rustup default nightly`
 //! - Cargo `clone` subcommand: `cargo install cargo-clone`
-//! - GDB: `sudo apt-get install gdb-arm-none-eabi`
-//! - OpenOCD: `sudo apt-get install OpenOCD`
-//! - Xargo: `cargo install xargo`
+//! - ARM toolchain: `sudo apt-get install gcc-arm-none-eabi` (on Ubuntu)
+//! - GDB: `sudo apt-get install gdb-arm-none-eabi` (on Ubuntu)
+//! - OpenOCD: `sudo apt-get install OpenOCD` (on Ubuntu)
 //! - [Optional] Cargo `add` subcommand: `cargo install cargo-edit`
 //!
 //! # Usage
 //!
-//! - Clone this crate
+//! 0) Figure out the cross compilation *target* to use.
 //!
-//! ``` text
-//! $ cargo clone cortex-m-quickstart && cd $_
+//! - Use `thumbv6m-none-eabi` for ARM Cortex-M0 and Cortex-M0+
+//! - Use `thumbv7m-none-eabi` for ARM Cortex-M3
+//! - Use `thumbv7em-none-eabi` for ARM Cortex-M4 and Cortex-M7 (*no* FPU support)
+//! - Use `thumbv7em-none-eabihf` for ARM Cortex-M4**F** and Cortex-M7**F** (*with* FPU support)
+//!
+//! 1) Install the `rust-std` component for your target, if you haven't done so already
+//!
+//! ``` console
+//! $ rustup target add thumbv7em-none-eabihf
 //! ```
 //!
-//! - Change the crate name, author and version
+//! 2) Clone this crate
+//!
+//! ``` text
+//! $ cargo clone cortex-m-quickstart --vers 0.3.0
+//! ```
+//!
+//! 3) Change the crate name, author and version
 //!
 //! ``` text
 //! $ edit Cargo.toml && head $_
@@ -28,23 +40,25 @@
 //! version = "0.1.0"
 //! ```
 //!
-//! - Specify the memory layout of the target device
+//! 4) Specify the memory layout of the target device
 //!
-//! (Note that some board support crates may provide this file for you (check
-//! the crate documentation). If you are using one that does that then remove
-//! *both* the `memory.x` and `build.rs` files.)
+//! **NOTE** board support crates sometimes provide this file for you (check the crate
+//! documentation). If you are using one that does then remove *both* `memory.x` and `build.rs` from
+//! the root of this crate.
 //!
 //! ``` text
-//! $ edit memory.x && cat $_
+//! $ cat >memory.x <<'EOF'
 //! MEMORY
 //! {
 //!   /* NOTE K = KiBi = 1024 bytes */
 //!   FLASH : ORIGIN = 0x08000000, LENGTH = 256K
 //!   RAM : ORIGIN = 0x20000000, LENGTH = 40K
 //! }
+//! EOF
 //! ```
 //!
-//! - Optionally, set a default build target
+//! 5) Optionally, set a default build target. This way you don't have to pass `--target` to each
+//! Cargo invocation.
 //!
 //! ``` text
 //! $ cat >>.cargo/config <<'EOF'
@@ -53,35 +67,31 @@
 //! EOF
 //! ```
 //!
-//! - Very likely, depend on a device or a BSP (Board Support Package) crate.
+//! 6) Optionally, depend on a device, HAL implementation or a board support crate.
 //!
 //! ``` text
-//! # add a device crate, or
-//! $ cargo add stm32f103xx
+//! $ # add a device crate, OR
+//! $ cargo add stm32f30x
 //!
-//! # add a board support crate
-//! $ cargo add blue-pill --git https://github.com/japaric/blue-pill
+//! $ # add a HAL implementation crate, OR
+//! $ cargo add stm32f30x-hal
+//!
+//! $ # add a board support crate
+//! $ cargo add f3
 //! ```
 //!
-//! - Write the application or start from one of the examples
+//! 7) Write the application or start from one of the examples
 //!
 //! ``` text
 //! $ rm -r src/* && cp examples/hello.rs src/main.rs
 //! ```
 //!
-//! - Disable incremental compilation. It doesn't work for embedded development.
-//!   You'll hit nonsensical linker errors if you use it.
+//! 8) Build the application
 //!
 //! ``` text
-//! $ unset CARGO_INCREMENTAL
-//! ```
-//!
-//! - Build the application
-//!
-//! ``` text
-//! # NOTE this command requires `arm-none-eabi-ld` to be in $PATH
-//! $ xargo build --release
+//! $ cargo build --release
 //!
+//! $ # sanity check
 //! $ arm-none-eabi-readelf -A target/thumbv7em-none-eabihf/release/demo
 //! Attribute Section: aeabi
 //! File Attributes
@@ -104,22 +114,19 @@
 //!   Tag_ABI_FP_16bit_format: IEEE 754
 //! ```
 //!
-//! - Flash the program
+//! 9) Flash and debug the program
 //!
 //! ``` text
-//! # Launch OpenOCD on a terminal
+//! $ # Launch OpenOCD on a terminal
 //! $ openocd -f (..)
 //! ```
 //!
 //! ``` text
-//! # Start a debug session in another terminal
-//! $ arm-none-eabi-gdb target/..
+//! $ # Start a debug session in another terminal
+//! $ arm-none-eabi-gdb target/thumbv7em-none-eabihf/release/demo
 //! ```
 //!
-//! **NOTE** As of nightly-2017-05-14 or so and cortex-m-quickstart v0.1.6 you
-//! can simply run `cargo run` or `cargo run --example $example` to build the
-//! program, and immediately start a debug session. IOW, it lets you omit the
-//! `arm-none-eabi-gdb` command.
+//! Alternatively, you can use `cargo run` to build, flash and debug the program in a single step.
 //!
 //! ``` text
 //! $ cargo run --example hello
@@ -128,13 +135,28 @@
 //!
 //! # Examples
 //!
-//! Check the [examples module](./examples/index.html)
+//! Check the [examples module][examples]
+//!
+//! [examples]: ./examples/index.html
 //!
 //! # Troubleshooting
 //!
 //! This section contains fixes for common errors encountered when the
 //! `cortex-m-quickstart` template is misused.
 //!
+//! ## Used the standard `main` interface
+//!
+//! Error message:
+//!
+//! ``` text
+//! $ cargo build
+//!    Compiling demo v0.1.0 (file:///home/japaric/tmp/demo)
+//!
+//! error: requires `start` lang_item
+//! ```
+//!
+//! Solution: Use `#![no_main]` and `entry!` as shown in the [examples].
+//!
 //! ## Forgot to launch an OpenOCD instance
 //!
 //! Error message:
@@ -155,38 +177,32 @@
 //! Error message:
 //!
 //! ``` text
-//! $ xargo build
+//! $ cargo build
 //! Compiling demo v0.1.0 (file:///home/japaric/tmp/demo)
 //! error: linking with `arm-none-eabi-ld` failed: exit code: 1
 //! |
-//! = note: "arm-none-eabi-ld" "-L" (..)
-//! = note: arm-none-eabi-ld: address 0xbaaab838 of hello section `.text' is ..
-//! arm-none-eabi-ld: address 0xbaaab838 of hello section `.text' is ..
-//! arm-none-eabi-ld:
-//! Invalid '.rodata.exceptions' section.
-//! Make sure to place a static with type `cortex_m::exception::Handlers`
-//! in that section (cf. #[link_section]) ONLY ONCE.
+//! = note: "arm-none-eabi-gcc" "-L" (..)
+//! (..)
+//!           (..)/ld: region `FLASH' overflowed by XXX bytes
 //! ```
 //!
-//! Solution: Specify your device memory layout in the `memory.x` linker script.
-//! See [Usage] section.
+//! Solution: Specify your device memory layout in the `memory.x` linker script. See [Usage]
+//! section.
 //!
-//! ## Forgot to set a default build target
+//! ## Didn't set a default build target and forgot to pass `--target` to Cargo
 //!
 //! Error message:
 //!
 //! ``` text
-//! $ xargo build
+//! $ cargo build
 //! (..)
-//! Compiling cortex-m-semihosting v0.1.3
-//! error[E0463]: can't find crate for `std`
+//! error: language item required, but not found: `eh_personality`
 //!
 //! error: aborting due to previous error
 //! ```
 //!
-//! Solution: Set a default build target in the `.cargo/config` file
-//! (see [Usage] section), or call Xargo with `--target` flag:
-//! `xargo build --target thumbv7em-none-eabi`.
+//! Solution: Set a default build target in the `.cargo/config` file (see [Usage] section), or call
+//! Cargo with `--target` flag: `cargo build --target thumbv7em-none-eabi`.
 //!
 //! ## Overwrote the original `.cargo/config` file
 //!
@@ -210,11 +226,10 @@
 //! collect2: error: ld returned 1 exit status
 //! ```
 //!
-//! Solution: You probably overwrote the original `.cargo/config` instead of
-//! appending the default build target (e.g. `cat >` instead of `cat >>`). The
-//! less error prone way to fix this is to remove the `.cargo` directory, clone
-//! a new copy of the template and then copy the `.cargo` directory from that
-//! fresh template into your current project. Don't forget to *append* the
+//! Solution: You probably overwrote the original `.cargo/config` instead of appending the default
+//! build target (e.g. `cat >` instead of `cat >>`). The less error prone way to fix this is to
+//! remove the `.cargo` directory, clone a new copy of the template and then copy the `.cargo`
+//! directory from that fresh template into your current project. Don't forget to *append* the
 //! default build target to `.cargo/config`.
 //!
 //! ## Called OpenOCD with wrong arguments
@@ -229,11 +244,23 @@
 //! in procedure 'ocd_bouncer'
 //! ```
 //!
-//! Solution: Correct the OpenOCD arguments. Check the
-//! `/usr/share/openocd/scripts` directory (exact location varies per
-//! distribution / OS) for a list of scripts that can be used.
+//! Solution: Correct the OpenOCD arguments. Check the `/usr/share/openocd/scripts` directory (exact
+//! location varies per distribution / OS) for a list of scripts that can be used.
 //!
-//! ## Used Cargo instead of Xargo
+//! ## Forgot to install the `rust-std` component
+//!
+//! Error message:
+//!
+//! ``` text
+//! $ cargo build
+//! error[E0463]: can't find crate for `core`
+//!   |
+//!   = note: the `thumbv7m-none-eabi` target may not be installed
+//! ```
+//!
+//! Solution: call `rustup target add thumbv7m-none-eabi` but with the name of your target
+//!
+//! ## Used an old nightly
 //!
 //! Error message:
 //!
@@ -247,44 +274,20 @@
 //! error: aborting due to previous error
 //! ```
 //!
-//! Solution: Use `xargo build`.
+//! Solution: Use a more recent nightly
 //!
 //! ## Used the stable toolchain
 //!
 //! Error message:
 //!
 //! ``` text
-//! $ xargo build
-//! error: failed to run `rustc` to learn about target-specific information
-//!
-//! To learn more, run the command again with --verbose.
+//! $ cargo build
+//! error[E0463]: can't find crate for `core`
+//!   |
+//!   = note: the `thumbv7em-none-eabihf` target may not be installed
 //! ```
 //!
-//! Solution: Switch to the nightly toolchain with `rustup default nightly`.
-//!
-//! ## Used `CARGO_INCREMENTAL=1`
-//!
-//! Error message:
-//!
-//! ``` text
-//! $ xargo build
-//! error: linking with `arm-none-eabi-ld` failed: exit code: 1
-//!     |
-//! = note: "arm-none-eabi-ld" (..)
-//!     = note: arm-none-eabi-ld:
-//! You must specify the exception handlers.
-//!     Create a non `pub` static variable with type
-//!     `cortex_m::exception::Handlers` and place it in the
-//!     '.rodata.exceptions' section. (cf. #[link_section]). Apply the
-//!     `#[used]` attribute to the variable to make it reach the linker.
-//!     arm-none-eabi-ld:
-//! Invalid '.rodata.exceptions' section.
-//!     Make sure to place a static with type `cortex_m::exception::Handlers`
-//!     in that section (cf. #[link_section]) ONLY ONCE.
-//! ```
-//!
-//! Solution: `$ unset CARGO_INCREMENAL`. And to be on the safe side, call
-//! `cargo clean` and thrash the Xargo sysroot: `$ rm -rf ~/.xargo`
+//! Solution: We are not there yet! Switch to the nightly toolchain with `rustup default nightly`.
 //!
 //! ## Used `gdb` instead of `arm-none-eabi-gdb`
 //!
@@ -316,7 +319,7 @@
 //! Error message:
 //!
 //! ``` text
-//! $ xargo run [--example ..]
+//! $ cargo run [--example ..]
 //!
 //! Reading symbols from target/thumbv7em-none-eabihf/debug/cortex-m-quickstart...done.
 //! cortex_m_rt::reset_handler ()
@@ -328,13 +331,13 @@
 //! ```
 //!
 //! Note that when you reach this point OpenOCD will become unresponsive and you'll have to kill it
-//! and start a new OpenOCD process before you can invoke `xargo run` / start GDB.
+//! and start a new OpenOCD process before you can invoke `cargo run` / start GDB.
 //!
 //! Cause: You uncommented the `monitor tpiu ..` line in `.gdbinit` and are using a named pipe to
 //! receive the ITM data (i.e. you ran `mkfifo itm.fifo`). This error occurs when `itmdump -f
 //! itm.fifo` (or equivalent, e.g. `cat itm.fifo`) is not running.
 //!
-//! Solution: Run `itmdump -f itm.fifo` (or equivalently `cat itm.fifo`) *before* invoking `xargo
+//! Solution: Run `itmdump -f itm.fifo` (or equivalently `cat itm.fifo`) *before* invoking `cargo
 //! run` / starting GDB. Note that sometimes `itmdump` will exit when the GDB session ends. In that
 //! case you'll have to run `itmdump` before you start the next GDB session.
 //!