use published versions, doc up, update CHANGELOG

.cargo/config

@@ -3,6 +3,11 @@ runner = 'arm-none-eabi-gdb'
 rustflags = [
   "-C", "link-arg=-Wl,-Tlink.x",
   "-C", "link-arg=-nostartfiles",
+
+  # uncomment to use rustc LLD to link programs (a)
+  # "-C", "link-arg=-Tlink.x",
+  # "-C", "linker=lld",
+  # "-Z", "linker-flavor=ld.lld",
 ]
 
 [target.thumbv7m-none-eabi]
@@ -10,6 +15,11 @@ runner = 'arm-none-eabi-gdb'
 rustflags = [
   "-C", "link-arg=-Wl,-Tlink.x",
   "-C", "link-arg=-nostartfiles",
+
+  # uncomment to use rustc LLD to link programs (a)
+  # "-C", "link-arg=-Tlink.x",
+  # "-C", "linker=lld",
+  # "-Z", "linker-flavor=ld.lld",
 ]
 
 [target.thumbv7em-none-eabi]
@@ -17,6 +27,11 @@ runner = 'arm-none-eabi-gdb'
 rustflags = [
   "-C", "link-arg=-Wl,-Tlink.x",
   "-C", "link-arg=-nostartfiles",
+
+  # uncomment to use rustc LLD to link programs (a)
+  # "-C", "link-arg=-Tlink.x",
+  # "-C", "linker=lld",
+  # "-Z", "linker-flavor=ld.lld",
 ]
 
 [target.thumbv7em-none-eabihf]
@@ -24,4 +39,12 @@ runner = 'arm-none-eabi-gdb'
 rustflags = [
   "-C", "link-arg=-Wl,-Tlink.x",
   "-C", "link-arg=-nostartfiles",
+
+  # uncomment to use rustc LLD to link programs (a)
+  # "-C", "link-arg=-Tlink.x",
+  # "-C", "linker=lld",
+  # "-Z", "linker-flavor=ld.lld",
 ]
+
+# (a) you also need to comment out the other two `link-arg` lines. But note that as of v0.6.0 LLD
+# has a bug where it mislinks FFI calls and they up crashing the program at runtime

CHANGELOG.md

@@ -5,6 +5,23 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [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.
+
+- Removed `opt-level = "s"` from `profile.release`. This flag is still unstable.
+
+- Set the number of codegen-units to 1 when compiling in release mode. This produces smaller and
+  faster binaries.
+
 ## [v0.2.7] - 2018-04-24
 
 ### Changed
@@ -149,7 +166,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 - Initial release
 
-[Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.7...HEAD
+[Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.3.0...HEAD
+[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

Cargo.toml

@@ -6,33 +6,24 @@ 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.7"
+version = "0.3.0"
 
 [dependencies]
-# cortex-m-rt = "0.5.0"
+cortex-m = "0.5.0"
-cortex-m-rt = { git = "https://github.com/japaric/cortex-m-rt", branch = "stable" }
+cortex-m-rt = "0.5.0"
-panic-abort = "0.1.1"
+cortex-m-semihosting = "0.3.0"
-# panic-semihosting = "0.1.1"
+panic-itm = "0.1.1"
-panic-semihosting = { git = "https://github.com/japaric/panic-semihosting", branch = "stable" }
+panic-semihosting = "0.2.0"
+
 # Uncomment for the allocator example.
-#alloc-cortex-m = "0.3.3"
+# alloc-cortex-m = "0.3.6"
-
-[dependencies.cortex-m]
-branch = "stable"
-default-features = false
-git = "https://github.com/japaric/cortex-m"
-# version = "0.4.4"
-
-[dependencies.cortex-m-semihosting]
-default-features = false
-version = "0.2.1"
 
 # Uncomment for the device example.
 # [dependencies.stm32f103xx]
 # features = ["rt"]
-# version = "0.9.0"
+# version = "0.10.0"
 
 [profile.release]
+codegen-units = 1 # better optimizations
 debug = true
 lto = true
-opt-level = "s" # TODO remove; this flag requires nightly

examples/allocator.rs

@@ -11,6 +11,7 @@
 
 #![feature(alloc)]
 #![feature(global_allocator)]
+#![feature(lang_items)]
 #![no_main]
 #![no_std]
 
@@ -22,7 +23,7 @@ extern crate cortex_m;
 #[macro_use]
 extern crate cortex_m_rt as rt;
 extern crate cortex_m_semihosting as sh;
-extern crate panic_abort;
+extern crate panic_semihosting;
 
 use core::fmt::Write;
 
@@ -31,15 +32,16 @@ use cortex_m::asm;
 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
 
-main!(main);
+entry!(main);
 
 fn main() -> ! {
-    // Initialize the allocator
+    // Initialize the allocator BEFORE you use it
     unsafe { ALLOCATOR.init(rt::heap_start() as usize, HEAP_SIZE) }
 
     // Growable array allocated on the heap
@@ -51,20 +53,23 @@ fn main() -> ! {
     loop {}
 }
 
-exception!(DefaultHandler, dh);
+// define what happens in an Out Of Memory (OOM) condition
-
+#[lang = "oom"]
-#[inline(always)]
+#[no_mangle]
-fn dh(_nr: u8) {
+pub fn rust_oom() -> ! {
-    asm::bkpt();
-}
-
-exception!(HardFault, hf);
-
-#[inline(always)]
-fn hf(_ef: &ExceptionFrame) -> ! {
     asm::bkpt();
 
     loop {}
 }
 
-interrupts!(DefaultHandler);
+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,11 +1,12 @@
 //! Debugging a crash (exception)
 //!
-//! The `cortex-m-rt` crate provides functionality for this through a default exception handler.
+//! Most crash conditions trigger a hard fault exception, whose handler is defined via
-//! When an exception is hit, the default handler will trigger a breakpoint and in this debugging
+//! `exception!(HardFault, ..)`. The `HardFault` handler has access to the exception frame, a
-//! context the stacked registers are accessible.
+//! 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
+//! This program crashes and the `HardFault` handler prints to the console the contents of the
-//! debugger using these commands:
+//! `ExceptionFrame` and then triggers a breakpoint. From that breakpoint one can see the backtrace
+//! that led to the exception.
 //!
 //! ``` text
 //! (gdb) continue
@@ -13,59 +14,66 @@
 //! __bkpt () at asm/bkpt.s:3
 //! 3         bkpt
 //!
-//! (gdb) finish
+//! (gdb) backtrace
-//! Run till exit from #0  __bkpt () at asm/bkpt.s:3
+//! #0  __bkpt () at asm/bkpt.s:3
-//! Note: automatically using hardware breakpoints for read-only addresses.
+//! #1  0x080030b4 in cortex_m::asm::bkpt () at $$/cortex-m-0.5.0/src/asm.rs:19
-//! crash::hf (_ef=0x20004fa0) at examples/crash.rs:102
+//! #2  rust_begin_unwind (args=..., file=..., line=99, col=5) at $$/panic-semihosting-0.2.0/src/lib.rs:87
-//! 99         asm::bkpt();
+//! #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) # Exception frame = program state during the crash
+//! In the console output one will find the state of the Program Counter (PC) register at the time
-//! (gdb) print/x *_ef
+//! of the exception.
-//! $1 = cortex_m_rt::ExceptionFrame {
+//!
+//! ``` text
+//! panicked at 'HardFault at ExceptionFrame {
 //!     r0: 0x2fffffff,
 //!     r1: 0x2fffffff,
-//!   r2: 0x80006b0,
+//!     r2: 0x080051d4,
-//!   r3: 0x80006b0,
+//!     r3: 0x080051d4,
 //!     r12: 0x20000000,
-//!   lr: 0x800040f,
+//!     lr: 0x08000435,
-//!   pc: 0x800066a,
+//!     pc: 0x08000ab6,
 //!     xpsr: 0x61000000
-//! }
+//! }', examples/crash.rs:106:5
+//! ```
 //!
-//! (gdb) # Where did we come from?
+//! This register contains the address of the instruction that caused the exception. In GDB one can
-//! (gdb) backtrace
+//! disassemble the program around this address to observe the instruction that caused the
-//! #0  crash::hf (_ef=0x20004fa0) at examples/crash.rs:102
+//! exception.
-//! #1  0x080004ac in UserHardFault (ef=0x20004fa0) at <exception macros>:9
-//! #2  <signal handler called>
-//! #3  0x0800066a in core::ptr::read_volatile (src=0x2fffffff) at /checkout/src/libcore/ptr.rs:452
-//! #4  0x0800040e in crash::main () at examples/crash.rs:85
-//! #5  0x08000456 in main () at <main macros>:3
 //!
-//! (gdb) # Nail down the location of the crash
+//! ``` text
-//! (gdb) disassemble/m _ef.pc
+//! (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 {}
+//! 451     pub unsafe fn read_volatile<T>(src: *const T) -> T {
-//!    0x08000662 <+0>:     sub     sp, #16
+//!    0x08000aae <+0>:     sub     sp, #16
-//!    0x08000664 <+2>:     mov     r1, r0
+//!    0x08000ab0 <+2>:     mov     r1, r0
-//!    0x08000666 <+4>:     str     r0, [sp, #8]
+//!    0x08000ab2 <+4>:     str     r0, [sp, #8]
 //!
 //! 452         intrinsics::volatile_load(src)
-//!    0x08000668 <+6>:     ldr     r0, [sp, #8]
+//!    0x08000ab4 <+6>:     ldr     r0, [sp, #8]
-//!    0x0800066a <+8>:     ldr     r0, [r0, #0]
+//! -> 0x08000ab6 <+8>:     ldr     r0, [r0, #0]
-//!    0x0800066c <+10>:    str     r0, [sp, #12]
+//!    0x08000ab8 <+10>:    str     r0, [sp, #12]
-//!    0x0800066e <+12>:    ldr     r0, [sp, #12]
+//!    0x08000aba <+12>:    ldr     r0, [sp, #12]
-//!    0x08000670 <+14>:    str     r1, [sp, #4]
+//!    0x08000abc <+14>:    str     r1, [sp, #4]
-//!    0x08000672 <+16>:    str     r0, [sp, #0]
+//!    0x08000abe <+16>:    str     r0, [sp, #0]
-//!    0x08000674 <+18>:    b.n     0x8000676 <core::ptr::read_volatile+20>
+//!    0x08000ac0 <+18>:    b.n     0x8000ac2 <core::ptr::read_volatile+20>
 //!
 //! 453     }
-//!    0x08000676 <+20>:    ldr     r0, [sp, #0]
+//!    0x08000ac2 <+20>:    ldr     r0, [sp, #0]
-//!    0x08000678 <+22>:    add     sp, #16
+//!    0x08000ac4 <+22>:    add     sp, #16
-//!    0x0800067a <+24>:    bx      lr
+//!    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]
@@ -74,38 +82,33 @@
 extern crate cortex_m;
 #[macro_use]
 extern crate cortex_m_rt as rt;
-extern crate panic_abort;
+extern crate panic_semihosting;
 
 use core::ptr;
 
-use cortex_m::asm;
 use rt::ExceptionFrame;
 
-main!(main);
+entry!(main);
 
-#[inline(always)]
 fn main() -> ! {
     unsafe {
+        // read an address outside of the RAM region; causes a HardFault exception
         ptr::read_volatile(0x2FFF_FFFF as *const u32);
     }
 
     loop {}
 }
 
-exception!(DefaultHandler, dh);
+// define the hard fault handler
+exception!(HardFault, hard_fault);
 
-#[inline(always)]
+fn hard_fault(ef: &ExceptionFrame) -> ! {
-fn dh(_nr: u8) {
+    panic!("HardFault at {:#?}", ef);
-    asm::bkpt();
 }
 
-exception!(HardFault, hf);
+// define the default exception handler
+exception!(*, default_handler);
 
-#[inline(always)]
+fn default_handler(irqn: i16) {
-fn hf(_ef: &ExceptionFrame) -> ! {
+    panic!("Unhandled exception (IRQn = {})", irqn);
-    asm::bkpt();
-
-    loop {}
 }
-
-interrupts!(DefaultHandler);

examples/device.rs

@@ -1,6 +1,6 @@
 //! Using a device crate
 //!
-//! Crates generated using [`svd2rust`] are referred to as device crates. These crates provides an
+//! 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
@@ -19,9 +19,6 @@
 //! version = "0.10.0"
 //! ```
 //!
-//! The `stm32f103xx` crate provides an `interrupts.x` file so you must remove the one in the root
-//! of this crate.
-//!
 //! ---
 
 #![no_main]
@@ -33,17 +30,16 @@ extern crate cortex_m_rt as rt;
 extern crate cortex_m_semihosting as sh;
 #[macro_use]
 extern crate stm32f103xx;
-extern crate panic_abort;
+extern crate panic_semihosting;
 
 use core::fmt::Write;
 
-use cortex_m::asm;
 use cortex_m::peripheral::syst::SystClkSource;
 use rt::ExceptionFrame;
 use sh::hio::{self, HStdout};
 use stm32f103xx::Interrupt;
 
-main!(main);
+entry!(main);
 
 fn main() -> ! {
     let p = cortex_m::Peripherals::take().unwrap();
@@ -53,6 +49,7 @@ fn main() -> ! {
 
     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();
@@ -66,6 +63,7 @@ fn main() -> ! {
     }
 }
 
+// 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>) {
@@ -78,20 +76,14 @@ fn exti0(state: &mut Option<HStdout>) {
     }
 }
 
-exception!(DefaultHandler, deh);
+exception!(HardFault, hard_fault);
 
-#[inline(always)]
+fn hard_fault(ef: &ExceptionFrame) -> ! {
-fn deh(_nr: u8) {
+    panic!("HardFault at {:#?}", ef);
-    asm::bkpt();
 }
 
-exception!(HardFault, hf);
+exception!(*, default_handler);
 
-#[inline(always)]
+fn default_handler(irqn: i16) {
-fn hf(_ef: &ExceptionFrame) -> ! {
+    panic!("Unhandled exception (IRQn = {})", irqn);
-    asm::bkpt();
-
-    loop {}
 }
-
-interrupts!(DefaultHandler);

examples/exception.rs

@@ -14,30 +14,31 @@ extern crate cortex_m;
 #[macro_use]
 extern crate cortex_m_rt as rt;
 extern crate cortex_m_semihosting as sh;
-extern crate panic_abort;
+extern crate panic_semihosting;
 
 use core::fmt::Write;
 
 use cortex_m::peripheral::syst::SystClkSource;
-use cortex_m::{asm, Peripherals};
+use cortex_m::Peripherals;
 use rt::ExceptionFrame;
 use sh::hio::{self, HStdout};
 
-main!(main);
+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); // 1s
+    syst.set_reload(8_000_000); // period = 1s
     syst.enable_counter();
     syst.enable_interrupt();
 
     loop {}
 }
 
-// try commenting out this line: you'll end in `deh` instead of in `sys_tick`
+// 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>) {
@@ -50,20 +51,14 @@ fn sys_tick(state: &mut Option<HStdout>) {
     }
 }
 
-exception!(DefaultHandler, deh);
+exception!(HardFault, hard_fault);
 
-#[inline(always)]
+fn hard_fault(ef: &ExceptionFrame) -> ! {
-fn deh(_nr: u8) {
+    panic!("HardFault at {:#?}", ef);
-    asm::bkpt();
 }
 
-exception!(HardFault, hf);
+exception!(*, default_handler);
 
-#[inline(always)]
+fn default_handler(irqn: i16) {
-fn hf(_ef: &ExceptionFrame) -> ! {
+    panic!("Unhandled exception (IRQn = {})", irqn);
-    asm::bkpt();
-
-    loop {}
 }
-
-interrupts!(DefaultHandler);

examples/hello.rs

@@ -5,19 +5,17 @@
 #![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_abort;
+extern crate panic_semihosting;
 
 use core::fmt::Write;
 
-use cortex_m::asm;
 use rt::ExceptionFrame;
 use sh::hio;
 
-main!(main);
+entry!(main);
 
 fn main() -> ! {
     let mut stdout = hio::hstdout().unwrap();
@@ -26,21 +24,14 @@ fn main() -> ! {
     loop {}
 }
 
-exception!(DefaultHandler, dh);
+exception!(HardFault, hard_fault);
 
-#[inline(always)]
+fn hard_fault(ef: &ExceptionFrame) -> ! {
-fn dh(_nr: u8) {
+    panic!("HardFault at {:#?}", ef);
-    asm::bkpt();
 }
 
-exception!(HardFault, hf);
+exception!(*, default_handler);
 
-#[inline(always)]
+fn default_handler(irqn: i16) {
-fn hf(_ef: &ExceptionFrame) -> ! {
+    panic!("Unhandled exception (IRQn = {})", irqn);
-    asm::bkpt();
-
-    loop {}
 }
-
-// As we are not using interrupts, we just bind them all to the `DefaultHandler` exception handler
-interrupts!(DefaultHandler);

examples/itm.rs

@@ -1,11 +1,13 @@
 //! 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
+//! **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/
@@ -19,37 +21,34 @@
 extern crate cortex_m;
 #[macro_use]
 extern crate cortex_m_rt as rt;
-extern crate panic_abort; // panicking behavior
+extern crate panic_semihosting;
 
 use cortex_m::{asm, Peripherals};
 use rt::ExceptionFrame;
 
-main!(main);
+entry!(main);
 
-#[inline(always)]
 fn main() -> ! {
     let mut p = Peripherals::take().unwrap();
     let stim = &mut p.ITM.stim[0];
 
     iprintln!(stim, "Hello, world!");
 
-    loop {}
+    loop {
-}
-
-exception!(DefaultHandler, dh);
-
-#[inline(always)]
-fn dh(_nr: u8) {
         asm::bkpt();
     }
-
-exception!(HardFault, hf);
-
-#[inline(always)]
-fn hf(_ef: &ExceptionFrame) -> ! {
-    asm::bkpt();
-
-    loop {}
 }
 
-interrupts!(DefaultHandler);
+// 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/minimal.rs

@@ -1,66 +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 `main!`. The entry point doesn't need to be called `main` and
+//! - Define their entry point using [`entry!`] macro.
-//! it doesn't need to be in the root of the crate.
+//!
+//! [`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 implementation crate][0]
+//! define a panicking behavior is to link to a [panic handler crate][0]
 //!
 //! [0]: https://crates.io/keywords/panic-impl
 //!
-//! - Define the `HardFault` handler. This function is called when a hard fault exception is raised
+//! - Define the `HardFault` handler using the [`exception!`] macro. This handler (function) is
-//! by the hardware.
+//! called when a hard fault exception is raised by the hardware.
 //!
-//! - Define a default handler. This function will be used to handle all interrupts and exceptions
+//! [`exception!`]: https://docs.rs/cortex-m-rt/~0.5/cortex_m_rt/macro..html
-//! which have not been assigned a specific handler.
 //!
-//! - Define the device specific interrupt handlers. `interrupts!` can be used to create a generic
+//! - Define a default handler using the [`exception!`] macro. This function will be used to handle
-//! program that works for all Cortex-M devices by binding all the possible interrupt handlers to
+//! all interrupts and exceptions which have not been assigned a specific handler.
-//! the `DefaultHandler`.
 
 #![no_main] // <- IMPORTANT!
 #![no_std]
 
 extern crate cortex_m;
-#[macro_use(main, exception, interrupts)]
+
+#[macro_use(entry, exception)]
 extern crate cortex_m_rt as rt;
-extern crate panic_abort; // panicking behavior
+
+// 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
+// the program entry point is ...
-main!(main);
+entry!(main);
 
-#[inline(always)]
+// ... this never ending function
 fn main() -> ! {
+    loop {
         asm::bkpt();
-
-    loop {}
     }
-
-// define the default exception handler
-exception!(DefaultHandler, deh);
-
-#[inline(always)]
-fn deh(_nr: u8) {
-    asm::bkpt();
 }
 
 // define the hard fault handler
-exception!(HardFault, hf);
+exception!(HardFault, hard_fault);
 
-#[inline(always)]
+fn hard_fault(ef: &ExceptionFrame) -> ! {
-fn hf(_ef: &ExceptionFrame) -> ! {
+    panic!("HardFault at {:#?}", ef);
-    asm::bkpt();
-
-    loop {}
 }
 
-// bind all interrupts to the default exception handler
+// define the default exception handler
-interrupts!(DefaultHandler);
+exception!(*, default_handler);
+
+fn default_handler(irqn: i16) {
+    panic!("Unhandled exception (IRQn = {})", irqn);
+}

examples/panic.rs

@@ -1,7 +1,6 @@
 //! Changing the panic handler
 //!
-//! The easiest way to change the panic handler is to use a different [panic implementation
+//! The easiest way to change the panic handler is to use a different [panic handler crate][0].
-//! crate][0].
 //!
 //! [0]: https://crates.io/keywords/panic-impl
 //!
@@ -10,36 +9,35 @@
 #![no_main]
 #![no_std]
 
-extern crate cortex_m;
 #[macro_use]
 extern crate cortex_m_rt as rt;
-// extern crate panic_abort;
-extern crate panic_semihosting; // reports panic messages to the host stderr using semihosting
 
-use cortex_m::asm;
+// 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;
 
-main!(main);
+entry!(main);
 
-#[inline(always)]
 fn main() -> ! {
     panic!("Oops")
 }
 
-exception!(DefaultHandler, deh);
+// define the hard fault handler
+exception!(HardFault, hard_fault);
 
-#[inline(always)]
+fn hard_fault(ef: &ExceptionFrame) -> ! {
-fn deh(_nr: u8) {
+    panic!("HardFault at {:#?}", ef);
-    asm::bkpt();
 }
 
-exception!(HardFault, hf);
+// define the default exception handler
+exception!(*, default_handler);
 
-#[inline(always)]
+fn default_handler(irqn: i16) {
-fn hf(_ef: &ExceptionFrame) -> ! {
+    panic!("Unhandled exception (IRQn = {})", irqn);
-    asm::bkpt();
-
-    loop {}
 }
-
-interrupts!(DefaultHandler);

gen-examples.sh

@@ -11,8 +11,8 @@ main() {
         panic
         crash
         exception
-        device
         allocator
+        device
     )
 
     rm -rf src/examples
@@ -20,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
 

interrupts.x

@@ -1 +0,0 @@
-/* Remove this file if you are linking to a device crate that provides this file */

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
+  FLASH : ORIGIN = 0x000BAAD0, LENGTH = 0K
-  RAM : ORIGIN = 0xBAAAAAAD, LENGTH = 0K
+  RAM : ORIGIN = 0xBAAD0000, LENGTH = 0K
 }
 
 /* This is where the call stack will be allocated. */

src/examples/_0_minimal.rs

@@ -1,27 +1,28 @@
 //! 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 `main!`. The entry point doesn't need to be called `main` and
+//! - Define their entry point using [`entry!`] macro.
-//! it doesn't need to be in the root of the crate.
+//!
+//! [`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 implementation crate][0]
+//! define a panicking behavior is to link to a [panic handler crate][0]
 //!
 //! [0]: https://crates.io/keywords/panic-impl
 //!
-//! - Define the `HardFault` handler. This function is called when a hard fault exception is raised
+//! - Define the `HardFault` handler using the [`exception!`] macro. This handler (function) is
-//! by the hardware.
+//! called when a hard fault exception is raised by the hardware.
 //!
-//! - Define a default handler. This function will be used to handle all interrupts and exceptions
+//! [`exception!`]: https://docs.rs/cortex-m-rt/~0.5/cortex_m_rt/macro..html
-//! which have not been assigned a specific handler.
 //!
-//! - Define the device specific interrupt handlers. `interrupts!` can be used to create a generic
+//! - Define a default handler using the [`exception!`] macro. This function will be used to handle
-//! program that works for all Cortex-M devices by binding all the possible interrupt handlers to
+//! all interrupts and exceptions which have not been assigned a specific handler.
-//! the `DefaultHandler`.
 //!
 //! ```
 //!
@@ -29,42 +30,38 @@
 //! #![no_std]
 //!
 //! extern crate cortex_m;
-//! #[macro_use(main, exception, interrupts)]
+//!
+//! #[macro_use(entry, exception)]
 //! extern crate cortex_m_rt as rt;
-//! extern crate panic_abort; // panicking behavior
+//!
+//! // 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
+//! // the program entry point is ...
-//! main!(main);
+//! entry!(main);
 //!
-//! #[inline(always)]
+//! // ... this never ending function
 //! fn main() -> ! {
+//!     loop {
 //!         asm::bkpt();
-//! 
-//!     loop {}
 //!     }
-//! 
-//! // define the default exception handler
-//! exception!(DefaultHandler, deh);
-//! 
-//! #[inline(always)]
-//! fn deh(_nr: u8) {
-//!     asm::bkpt();
 //! }
 //!
 //! // define the hard fault handler
-//! exception!(HardFault, hf);
+//! exception!(HardFault, hard_fault);
 //!
-//! #[inline(always)]
+//! fn hard_fault(ef: &ExceptionFrame) -> ! {
-//! fn hf(_ef: &ExceptionFrame) -> ! {
+//!     panic!("HardFault at {:#?}", ef);
-//!     asm::bkpt();
-//! 
-//!     loop {}
 //! }
 //!
-//! // bind all interrupts to the default exception handler
+//! // define the default exception handler
-//! interrupts!(DefaultHandler);
+//! exception!(*, default_handler);
+//!
+//! fn default_handler(irqn: i16) {
+//!     panic!("Unhandled exception (IRQn = {})", irqn);
+//! }
 //! ```
 // Auto-generated. Do not modify.

src/examples/_1_hello.rs

@@ -7,19 +7,17 @@
 //! #![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_abort;
+//! extern crate panic_semihosting;
 //!
 //! use core::fmt::Write;
 //!
-//! use cortex_m::asm;
 //! use rt::ExceptionFrame;
 //! use sh::hio;
 //!
-//! main!(main);
+//! entry!(main);
 //!
 //! fn main() -> ! {
 //!     let mut stdout = hio::hstdout().unwrap();
@@ -28,23 +26,16 @@
 //!     loop {}
 //! }
 //!
-//! exception!(DefaultHandler, dh);
+//! exception!(HardFault, hard_fault);
 //!
-//! #[inline(always)]
+//! fn hard_fault(ef: &ExceptionFrame) -> ! {
-//! fn dh(_nr: u8) {
+//!     panic!("HardFault at {:#?}", ef);
-//!     asm::bkpt();
 //! }
 //!
-//! exception!(HardFault, hf);
+//! exception!(*, default_handler);
 //!
-//! #[inline(always)]
+//! fn default_handler(irqn: i16) {
-//! fn hf(_ef: &ExceptionFrame) -> ! {
+//!     panic!("Unhandled exception (IRQn = {})", irqn);
-//!     asm::bkpt();
-//! 
-//!     loop {}
 //! }
-//! 
-//! // As we are not using interrupts, we just bind them all to the `DefaultHandler` exception handler
-//! interrupts!(DefaultHandler);
 //! ```
 // Auto-generated. Do not modify.

src/examples/_2_itm.rs

@@ -1,11 +1,13 @@
 //! 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
+//! **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/
@@ -21,39 +23,36 @@
 //! extern crate cortex_m;
 //! #[macro_use]
 //! extern crate cortex_m_rt as rt;
-//! extern crate panic_abort; // panicking behavior
+//! extern crate panic_semihosting;
 //!
 //! use cortex_m::{asm, Peripherals};
 //! use rt::ExceptionFrame;
 //!
-//! main!(main);
+//! entry!(main);
 //!
-//! #[inline(always)]
 //! fn main() -> ! {
 //!     let mut p = Peripherals::take().unwrap();
 //!     let stim = &mut p.ITM.stim[0];
 //!
 //!     iprintln!(stim, "Hello, world!");
 //!
-//!     loop {}
+//!     loop {
-//! }
-//! 
-//! exception!(DefaultHandler, dh);
-//! 
-//! #[inline(always)]
-//! fn dh(_nr: u8) {
 //!         asm::bkpt();
 //!     }
-//! 
-//! exception!(HardFault, hf);
-//! 
-//! #[inline(always)]
-//! fn hf(_ef: &ExceptionFrame) -> ! {
-//!     asm::bkpt();
-//! 
-//!     loop {}
 //! }
 //!
-//! interrupts!(DefaultHandler);
+//! // 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/_3_panic.rs

@@ -1,7 +1,6 @@
 //! Changing the panic handler
 //!
-//! The easiest way to change the panic handler is to use a different [panic implementation
+//! The easiest way to change the panic handler is to use a different [panic handler crate][0].
-//! crate][0].
 //!
 //! [0]: https://crates.io/keywords/panic-impl
 //!
@@ -12,38 +11,37 @@
 //! #![no_main]
 //! #![no_std]
 //!
-//! extern crate cortex_m;
 //! #[macro_use]
 //! extern crate cortex_m_rt as rt;
-//! // extern crate panic_abort;
-//! extern crate panic_semihosting; // reports panic messages to the host stderr using semihosting
 //!
-//! use cortex_m::asm;
+//! // 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;
 //!
-//! main!(main);
+//! entry!(main);
 //!
-//! #[inline(always)]
 //! fn main() -> ! {
 //!     panic!("Oops")
 //! }
 //!
-//! exception!(DefaultHandler, deh);
+//! // define the hard fault handler
+//! exception!(HardFault, hard_fault);
 //!
-//! #[inline(always)]
+//! fn hard_fault(ef: &ExceptionFrame) -> ! {
-//! fn deh(_nr: u8) {
+//!     panic!("HardFault at {:#?}", ef);
-//!     asm::bkpt();
 //! }
 //!
-//! exception!(HardFault, hf);
+//! // define the default exception handler
+//! exception!(*, default_handler);
 //!
-//! #[inline(always)]
+//! fn default_handler(irqn: i16) {
-//! fn hf(_ef: &ExceptionFrame) -> ! {
+//!     panic!("Unhandled exception (IRQn = {})", irqn);
-//!     asm::bkpt();
-//! 
-//!     loop {}
 //! }
-//! 
-//! interrupts!(DefaultHandler);
 //! ```
 // Auto-generated. Do not modify.

src/examples/_4_crash.rs

@@ -1,11 +1,12 @@
 //! Debugging a crash (exception)
 //!
-//! The `cortex-m-rt` crate provides functionality for this through a default exception handler.
+//! Most crash conditions trigger a hard fault exception, whose handler is defined via
-//! When an exception is hit, the default handler will trigger a breakpoint and in this debugging
+//! `exception!(HardFault, ..)`. The `HardFault` handler has access to the exception frame, a
-//! context the stacked registers are accessible.
+//! 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
+//! This program crashes and the `HardFault` handler prints to the console the contents of the
-//! debugger using these commands:
+//! `ExceptionFrame` and then triggers a breakpoint. From that breakpoint one can see the backtrace
+//! that led to the exception.
 //!
 //! ``` text
 //! (gdb) continue
@@ -13,59 +14,66 @@
 //! __bkpt () at asm/bkpt.s:3
 //! 3         bkpt
 //!
-//! (gdb) finish
+//! (gdb) backtrace
-//! Run till exit from #0  __bkpt () at asm/bkpt.s:3
+//! #0  __bkpt () at asm/bkpt.s:3
-//! Note: automatically using hardware breakpoints for read-only addresses.
+//! #1  0x080030b4 in cortex_m::asm::bkpt () at $$/cortex-m-0.5.0/src/asm.rs:19
-//! crash::hf (_ef=0x20004fa0) at examples/crash.rs:102
+//! #2  rust_begin_unwind (args=..., file=..., line=99, col=5) at $$/panic-semihosting-0.2.0/src/lib.rs:87
-//! 99         asm::bkpt();
+//! #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) # Exception frame = program state during the crash
+//! In the console output one will find the state of the Program Counter (PC) register at the time
-//! (gdb) print/x *_ef
+//! of the exception.
-//! $1 = cortex_m_rt::ExceptionFrame {
+//!
+//! ``` text
+//! panicked at 'HardFault at ExceptionFrame {
 //!     r0: 0x2fffffff,
 //!     r1: 0x2fffffff,
-//!   r2: 0x80006b0,
+//!     r2: 0x080051d4,
-//!   r3: 0x80006b0,
+//!     r3: 0x080051d4,
 //!     r12: 0x20000000,
-//!   lr: 0x800040f,
+//!     lr: 0x08000435,
-//!   pc: 0x800066a,
+//!     pc: 0x08000ab6,
 //!     xpsr: 0x61000000
-//! }
+//! }', examples/crash.rs:106:5
+//! ```
 //!
-//! (gdb) # Where did we come from?
+//! This register contains the address of the instruction that caused the exception. In GDB one can
-//! (gdb) backtrace
+//! disassemble the program around this address to observe the instruction that caused the
-//! #0  crash::hf (_ef=0x20004fa0) at examples/crash.rs:102
+//! exception.
-//! #1  0x080004ac in UserHardFault (ef=0x20004fa0) at <exception macros>:9
-//! #2  <signal handler called>
-//! #3  0x0800066a in core::ptr::read_volatile (src=0x2fffffff) at /checkout/src/libcore/ptr.rs:452
-//! #4  0x0800040e in crash::main () at examples/crash.rs:85
-//! #5  0x08000456 in main () at <main macros>:3
 //!
-//! (gdb) # Nail down the location of the crash
+//! ``` text
-//! (gdb) disassemble/m _ef.pc
+//! (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 {}
+//! 451     pub unsafe fn read_volatile<T>(src: *const T) -> T {
-//!    0x08000662 <+0>:     sub     sp, #16
+//!    0x08000aae <+0>:     sub     sp, #16
-//!    0x08000664 <+2>:     mov     r1, r0
+//!    0x08000ab0 <+2>:     mov     r1, r0
-//!    0x08000666 <+4>:     str     r0, [sp, #8]
+//!    0x08000ab2 <+4>:     str     r0, [sp, #8]
 //!
 //! 452         intrinsics::volatile_load(src)
-//!    0x08000668 <+6>:     ldr     r0, [sp, #8]
+//!    0x08000ab4 <+6>:     ldr     r0, [sp, #8]
-//!    0x0800066a <+8>:     ldr     r0, [r0, #0]
+//! -> 0x08000ab6 <+8>:     ldr     r0, [r0, #0]
-//!    0x0800066c <+10>:    str     r0, [sp, #12]
+//!    0x08000ab8 <+10>:    str     r0, [sp, #12]
-//!    0x0800066e <+12>:    ldr     r0, [sp, #12]
+//!    0x08000aba <+12>:    ldr     r0, [sp, #12]
-//!    0x08000670 <+14>:    str     r1, [sp, #4]
+//!    0x08000abc <+14>:    str     r1, [sp, #4]
-//!    0x08000672 <+16>:    str     r0, [sp, #0]
+//!    0x08000abe <+16>:    str     r0, [sp, #0]
-//!    0x08000674 <+18>:    b.n     0x8000676 <core::ptr::read_volatile+20>
+//!    0x08000ac0 <+18>:    b.n     0x8000ac2 <core::ptr::read_volatile+20>
 //!
 //! 453     }
-//!    0x08000676 <+20>:    ldr     r0, [sp, #0]
+//!    0x08000ac2 <+20>:    ldr     r0, [sp, #0]
-//!    0x08000678 <+22>:    add     sp, #16
+//!    0x08000ac4 <+22>:    add     sp, #16
-//!    0x0800067a <+24>:    bx      lr
+//!    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.
+//!
 //! ---
 //!
 //! ```
@@ -76,40 +84,35 @@
 //! extern crate cortex_m;
 //! #[macro_use]
 //! extern crate cortex_m_rt as rt;
-//! extern crate panic_abort;
+//! extern crate panic_semihosting;
 //!
 //! use core::ptr;
 //!
-//! use cortex_m::asm;
 //! use rt::ExceptionFrame;
 //!
-//! main!(main);
+//! entry!(main);
 //!
-//! #[inline(always)]
 //! fn main() -> ! {
 //!     unsafe {
+//!         // read an address outside of the RAM region; causes a HardFault exception
 //!         ptr::read_volatile(0x2FFF_FFFF as *const u32);
 //!     }
 //!
 //!     loop {}
 //! }
 //!
-//! exception!(DefaultHandler, dh);
+//! // define the hard fault handler
+//! exception!(HardFault, hard_fault);
 //!
-//! #[inline(always)]
+//! fn hard_fault(ef: &ExceptionFrame) -> ! {
-//! fn dh(_nr: u8) {
+//!     panic!("HardFault at {:#?}", ef);
-//!     asm::bkpt();
 //! }
 //!
-//! exception!(HardFault, hf);
+//! // define the default exception handler
+//! exception!(*, default_handler);
 //!
-//! #[inline(always)]
+//! fn default_handler(irqn: i16) {
-//! fn hf(_ef: &ExceptionFrame) -> ! {
+//!     panic!("Unhandled exception (IRQn = {})", irqn);
-//!     asm::bkpt();
-//! 
-//!     loop {}
 //! }
-//! 
-//! interrupts!(DefaultHandler);
 //! ```
 // Auto-generated. Do not modify.

src/examples/_5_exception.rs

@@ -16,30 +16,31 @@
 //! #[macro_use]
 //! extern crate cortex_m_rt as rt;
 //! extern crate cortex_m_semihosting as sh;
-//! extern crate panic_abort;
+//! extern crate panic_semihosting;
 //!
 //! use core::fmt::Write;
 //!
 //! use cortex_m::peripheral::syst::SystClkSource;
-//! use cortex_m::{asm, Peripherals};
+//! use cortex_m::Peripherals;
 //! use rt::ExceptionFrame;
 //! use sh::hio::{self, HStdout};
 //!
-//! main!(main);
+//! 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); // 1s
+//!     syst.set_reload(8_000_000); // period = 1s
 //!     syst.enable_counter();
 //!     syst.enable_interrupt();
 //!
 //!     loop {}
 //! }
 //!
-//! // try commenting out this line: you'll end in `deh` instead of in `sys_tick`
+//! // 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>) {
@@ -52,22 +53,16 @@
 //!     }
 //! }
 //!
-//! exception!(DefaultHandler, deh);
+//! exception!(HardFault, hard_fault);
 //!
-//! #[inline(always)]
+//! fn hard_fault(ef: &ExceptionFrame) -> ! {
-//! fn deh(_nr: u8) {
+//!     panic!("HardFault at {:#?}", ef);
-//!     asm::bkpt();
 //! }
 //!
-//! exception!(HardFault, hf);
+//! exception!(*, default_handler);
 //!
-//! #[inline(always)]
+//! fn default_handler(irqn: i16) {
-//! fn hf(_ef: &ExceptionFrame) -> ! {
+//!     panic!("Unhandled exception (IRQn = {})", irqn);
-//!     asm::bkpt();
-//! 
-//!     loop {}
 //! }
-//! 
-//! interrupts!(DefaultHandler);
 //! ```
 // Auto-generated. Do not modify.

src/examples/_6_allocator.rs

@@ -13,6 +13,7 @@
 //!
 //! #![feature(alloc)]
 //! #![feature(global_allocator)]
+//! #![feature(lang_items)]
 //! #![no_main]
 //! #![no_std]
 //!
@@ -24,7 +25,7 @@
 //! #[macro_use]
 //! extern crate cortex_m_rt as rt;
 //! extern crate cortex_m_semihosting as sh;
-//! extern crate panic_abort;
+//! extern crate panic_semihosting;
 //!
 //! use core::fmt::Write;
 //!
@@ -33,15 +34,16 @@
 //! 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
 //!
-//! main!(main);
+//! entry!(main);
 //!
 //! fn main() -> ! {
-//!     // Initialize the allocator
+//!     // Initialize the allocator BEFORE you use it
 //!     unsafe { ALLOCATOR.init(rt::heap_start() as usize, HEAP_SIZE) }
 //!
 //!     // Growable array allocated on the heap
@@ -53,22 +55,25 @@
 //!     loop {}
 //! }
 //!
-//! exception!(DefaultHandler, dh);
+//! // define what happens in an Out Of Memory (OOM) condition
-//! 
+//! #[lang = "oom"]
-//! #[inline(always)]
+//! #[no_mangle]
-//! fn dh(_nr: u8) {
+//! pub fn rust_oom() -> ! {
-//!     asm::bkpt();
-//! }
-//! 
-//! exception!(HardFault, hf);
-//! 
-//! #[inline(always)]
-//! fn hf(_ef: &ExceptionFrame) -> ! {
 //!     asm::bkpt();
 //!
 //!     loop {}
 //! }
 //!
-//! interrupts!(DefaultHandler);
+//! 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

@@ -1,6 +1,6 @@
 //! Using a device crate
 //!
-//! Crates generated using [`svd2rust`] are referred to as device crates. These crates provides an
+//! 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
@@ -19,9 +19,6 @@
 //! version = "0.10.0"
 //! ```
 //!
-//! The `stm32f103xx` crate provides an `interrupts.x` file so you must remove the one in the root
-//! of this crate.
-//!
 //! ---
 //!
 //! ```
@@ -35,17 +32,16 @@
 //! extern crate cortex_m_semihosting as sh;
 //! #[macro_use]
 //! extern crate stm32f103xx;
-//! extern crate panic_abort;
+//! extern crate panic_semihosting;
 //!
 //! use core::fmt::Write;
 //!
-//! use cortex_m::asm;
 //! use cortex_m::peripheral::syst::SystClkSource;
 //! use rt::ExceptionFrame;
 //! use sh::hio::{self, HStdout};
 //! use stm32f103xx::Interrupt;
 //!
-//! main!(main);
+//! entry!(main);
 //!
 //! fn main() -> ! {
 //!     let p = cortex_m::Peripherals::take().unwrap();
@@ -55,6 +51,7 @@
 //!
 //!     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();
@@ -68,6 +65,7 @@
 //!     }
 //! }
 //!
+//! // 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>) {
@@ -80,22 +78,16 @@
 //!     }
 //! }
 //!
-//! exception!(DefaultHandler, deh);
+//! exception!(HardFault, hard_fault);
 //!
-//! #[inline(always)]
+//! fn hard_fault(ef: &ExceptionFrame) -> ! {
-//! fn deh(_nr: u8) {
+//!     panic!("HardFault at {:#?}", ef);
-//!     asm::bkpt();
 //! }
 //!
-//! exception!(HardFault, hf);
+//! exception!(*, default_handler);
 //!
-//! #[inline(always)]
+//! fn default_handler(irqn: i16) {
-//! fn hf(_ef: &ExceptionFrame) -> ! {
+//!     panic!("Unhandled exception (IRQn = {})", irqn);
-//!     asm::bkpt();
-//! 
-//!     loop {}
 //! }
-//! 
-//! interrupts!(DefaultHandler);
 //! ```
 // Auto-generated. Do not modify.

src/examples/mod.rs

@@ -1,4 +1,4 @@
-//! Examples
+//! Examples sorted in increasing degree of complexity
 // Auto-generated. Do not modify.
 pub mod _0_minimal;
 pub mod _1_hello;
@@ -6,5 +6,5 @@ pub mod _2_itm;
 pub mod _3_panic;
 pub mod _4_crash;
 pub mod _5_exception;
-pub mod _6_device;
+pub mod _6_allocator;
-pub mod _7_allocator;
+pub mod _7_device;

src/lib.rs

@@ -27,7 +27,7 @@
 //! 2) Clone this crate
 //!
 //! ``` text
-//! $ git clone https://github.com/japaric/cortex-m-quickstart --branch less-unstable
+//! $ git clone cortex-m-quickstart --vers 0.3.0
 //! ```
 //!
 //! 3) Change the crate name, author and version
@@ -43,8 +43,8 @@
 //! 4) Specify the memory layout of the target device
 //!
 //! **NOTE** board support crates sometimes provide this file for you (check the crate
-//! documentation). If you are using one that does then remove *both* the `memory.x` and `build.rs`
+//! documentation). If you are using one that does then remove *both* `memory.x` and `build.rs` from
-//! files.
+//! the root of this crate.
 //!
 //! ``` text
 //! $ cat >memory.x <<'EOF'
@@ -57,7 +57,8 @@
 //! EOF
 //! ```
 //!
-//! 5) 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'
@@ -113,7 +114,7 @@
 //!   Tag_ABI_FP_16bit_format: IEEE 754
 //! ```
 //!
-//! 9) Flash the program
+//! 9) Flash and debug the program
 //!
 //! ``` text
 //! $ # Launch OpenOCD on a terminal
@@ -166,12 +167,14 @@
 //! error: linking with `arm-none-eabi-ld` failed: exit code: 1
 //! |
 //! = 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.
+//! Solution: Specify your device memory layout in the `memory.x` linker script. See [Usage]
-//! See [Usage] section.
+//! section.
 //!
-//! ## Forgot to set a default build target
+//! ## Didn't set a default build target and forgot to pass `--target` to Cargo
 //!
 //! Error message:
 //!
@@ -183,9 +186,8 @@
 //! error: aborting due to previous error
 //! ```
 //!
-//! Solution: Set a default build target in the `.cargo/config` file
+//! Solution: Set a default build target in the `.cargo/config` file (see [Usage] section), or call
-//! (see [Usage] section), or call Cargo with `--target` flag:
+//! Cargo with `--target` flag: `cargo build --target thumbv7em-none-eabi`.
-//! `cargo build --target thumbv7em-none-eabi`.
 //!
 //! ## Overwrote the original `.cargo/config` file
 //!
@@ -209,11 +211,10 @@
 //! collect2: error: ld returned 1 exit status
 //! ```
 //!
-//! Solution: You probably overwrote the original `.cargo/config` instead of
+//! Solution: You probably overwrote the original `.cargo/config` instead of appending the default
-//! appending the default build target (e.g. `cat >` instead of `cat >>`). The
+//! build target (e.g. `cat >` instead of `cat >>`). The less error prone way to fix this is to
-//! less error prone way to fix this is to remove the `.cargo` directory, clone
+//! remove the `.cargo` directory, clone a new copy of the template and then copy the `.cargo`
-//! a new copy of the template and then copy the `.cargo` directory from that
+//! directory from that fresh template into your current project. Don't forget to *append* the
-//! fresh template into your current project. Don't forget to *append* the
 //! default build target to `.cargo/config`.
 //!
 //! ## Called OpenOCD with wrong arguments
@@ -228,9 +229,8 @@
 //! in procedure 'ocd_bouncer'
 //! ```
 //!
-//! Solution: Correct the OpenOCD arguments. Check the
+//! Solution: Correct the OpenOCD arguments. Check the `/usr/share/openocd/scripts` directory (exact
-//! `/usr/share/openocd/scripts` directory (exact location varies per
+//! location varies per distribution / OS) for a list of scripts that can be used.
-//! distribution / OS) for a list of scripts that can be used.
 //!
 //! ## Forgot to install the `rust-std` component
 //!
@@ -268,6 +268,8 @@
 //! ``` text
 //! $ cargo build
 //! error[E0463]: can't find crate for `core`
+//!   |
+//!   = note: the `thumbv7em-none-eabihf` target may not be installed
 //! ```
 //!
 //! Solution: We are not there yet! Switch to the nightly toolchain with `rustup default nightly`.