Merge #28

28: bump the cortex-m-rt to v0.4.0 r=japaric a=japaric



Co-authored-by: Jorge Aparicio <jorge@japaric.io>

.cargo/config

@@ -1,27 +1,39 @@
 [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", "linker=lld",
+  "-Z", "linker-flavor=ld.lld",
+  # "-C", "linker=arm-none-eabi-ld",
+  # "-Z", "linker-flavor=ld",
 ]
 
 [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", "linker=lld",
+  "-Z", "linker-flavor=ld.lld",
+  # "-C", "linker=arm-none-eabi-ld",
+  # "-Z", "linker-flavor=ld",
 ]
 
 [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", "linker=lld",
+  "-Z", "linker-flavor=ld.lld",
+  # "-C", "linker=arm-none-eabi-ld",
+  # "-Z", "linker-flavor=ld",
 ]
 
 [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", "linker=lld",
+  "-Z", "linker-flavor=ld.lld",
+  # "-C", "linker=arm-none-eabi-ld",
+  # "-Z", "linker-flavor=ld",
 ]

.gdbinit

@@ -1,9 +1,21 @@
 target remote :3333
+
+# print demangled symbols by default
+set print asm-demangle on
+
 monitor arm semihosting enable
-# if using ITM
+
+# # send captured ITM to the file itm.fifo
+# # (the microcontroller SWO pin must be connected to the programmer SWO pin)
+# # 8000000 must match the core clock frequency
 # monitor tpiu config internal itm.fifo uart off 8000000
+
+# # OR: make the microcontroller SWO pin output compatible with UART (8N1)
+# # 2000000 is the frequency of the SWO pin
+# monitor tpiu config external uart off 8000000 2000000
+
+# # enable ITM port 0
 # monitor itm port 0 on
+
 load
-tbreak cortex_m_rt::reset_handler
-monitor reset halt
-continue
+step

.travis.yml

@@ -0,0 +1,64 @@
+language: rust
+
+matrix:
+  include:
+    - env: TARGET=thumbv6m-none-eabi
+      rust: nightly
+      addons:
+        apt:
+          sources:
+            - debian-sid
+          packages:
+            - binutils-arm-none-eabi
+
+    - env: TARGET=thumbv7m-none-eabi
+      rust: nightly
+      addons:
+        apt:
+          sources:
+            - debian-sid
+          packages:
+            - binutils-arm-none-eabi
+
+    - env: TARGET=thumbv7em-none-eabi
+      rust: nightly
+      addons:
+        apt:
+          sources:
+            - debian-sid
+          packages:
+            - binutils-arm-none-eabi
+
+    - env: TARGET=thumbv7em-none-eabihf
+      rust: nightly
+      addons:
+        apt:
+          sources:
+            - debian-sid
+          packages:
+            - binutils-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,13 +5,139 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
-## v0.1.2 - 2017-05-07
+## [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
+
+- Troubleshooting documentation: how to fix the error of overwriting the
+  `.cargo/config` file when you meant to append text to it.
+
+### Changed
+
+- Xargo.toml: Changed the source of the `compiler-builtins` crate from git to
+  the `rust-src` component.
+
+- Expanded the `device` example to do some I/O.
+
+## [v0.2.0] - 2017-07-07
+
+### Changed
+
+- [breaking-change] Bumped the cortex-m and cortex-m-rt versions to v0.3.0.
+
+## [v0.1.8] - 2017-05-30
+
+### Changed
+
+- Bumped the cortex-m-rt dependency to v0.2.3, and documented the `_stext`
+  symbol (see memory.x).
+
+## [v0.1.7] - 2017-05-27
+
+### Added
+
+- Documentation and an example about how to use the heap and a dynamic memory
+  allocator.
+
+### Changed
+
+- Bumped the `cortex-m-rt` dependency to v0.2.2
+- Bumped the `cortex-m` dependency to v0.2.7
+
+## [v0.1.6] - 2017-05-26
+
+### Added
+
+- Set the default runner in .cargo/config to `arm-none-eabi-gdb`. Now `xargo
+  run` will build the program and start a debug session.
+
+## [v0.1.5] - 2017-05-16
+
+### Added
+
+- A warning about using CARGO_INCREMENTAL to the how to use and the
+  troubleshooting sections.
+
+## [v0.1.4] - 2017-05-13
+
+### Added
+
+- A dependencies section to the documentation
+
+### Changed
+
+- Extend troubleshooting section
+
+## [v0.1.3] - 2017-05-13
+
+### Added
+
+- A troubleshooting section to the documentation
+
+### Changed
+
+- Bumped the cortex-m crate version to v0.2.6
+
+## [v0.1.2] - 2017-05-07
 
 ### Fixed
 
 - .gdbinit: jump to reset handler after loading the program.
 
-## v0.1.1 - 2017-04-27
+## [v0.1.1] - 2017-04-27
 
 ### Changed
 
@@ -23,6 +149,20 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 - Initial release
 
-[Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.2...HEAD
+[Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.7...HEAD
+[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
+[v0.1.6]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.5...v0.1.6
+[v0.1.5]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.4...v0.1.5
+[v0.1.4]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.3...v0.1.4
+[v0.1.3]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.2...v0.1.3
 [v0.1.2]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.1...v0.1.2
 [v0.1.1]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.0...v0.1.1

Cargo.toml

@@ -6,12 +6,23 @@ 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.1.2"
+version = "0.2.7"
 
 [dependencies]
-cortex-m = "0.2.4"
-cortex-m-rt = "0.2.0"
+cortex-m = "0.4.0"
+cortex-m-rt = "0.4.0"
+cortex-m-semihosting = "0.2.0"
+panic-abort = "0.1.1"
+panic-semihosting = "0.1.0"
+# Uncomment for the allocator example.
+#alloc-cortex-m = "0.3.3"
+
+# Uncomment for the device example.
+# [dependencies.stm32f103xx]
+# features = ["rt"]
+# version = "0.9.0"
 
 [profile.release]
-lto = true
 debug = true
+lto = true
+opt-level = "s"

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]
-
-[dependencies.compiler_builtins]
-features = ["mem"]
-git = "https://github.com/rust-lang-nursery/compiler-builtins"
-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,72 @@
+set -euxo pipefail
+
+main() {
+    local td=$(mktemp -d)
+
+    git clone . $td
+    pushd $td
+
+    cat >memory.x <<'EOF'
+MEMORY
+{
+  /* NOTE K = KiBi = 1024 bytes */
+  FLASH : ORIGIN = 0x08000000, LENGTH = 256K
+  RAM : ORIGIN = 0x20000000, LENGTH = 40K
+}
+EOF
+
+    local examples=(
+        crash
+        hello
+        override-exception-handler
+        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.3"
+EOF
+
+    local ex=allocator
+    cargo build --target $TARGET --example $ex
+    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.9.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

@@ -0,0 +1,60 @@
+//! How to use the heap and a dynamic memory allocator
+//!
+//! 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
+//! $ cargo add alloc-cortex-m
+//! ```
+//!
+//! ---
+
+#![feature(alloc)]
+#![feature(global_allocator)]
+#![feature(used)]
+#![no_std]
+
+// This is the allocator crate; you can use a different one
+extern crate alloc_cortex_m;
+#[macro_use]
+extern crate alloc;
+extern crate cortex_m;
+extern crate cortex_m_rt;
+extern crate cortex_m_semihosting;
+extern crate panic_abort; // panicking behavior
+
+use core::fmt::Write;
+
+use alloc_cortex_m::CortexMHeap;
+use cortex_m::asm;
+use cortex_m_semihosting::hio;
+
+#[global_allocator]
+static ALLOCATOR: CortexMHeap = CortexMHeap::empty();
+
+extern "C" {
+    static mut _sheap: u32;
+}
+
+const HEAP_SIZE: usize = 1024; // in bytes
+
+fn main() {
+    // Initialize the allocator
+    let start = unsafe { &mut _sheap as *mut u32 as usize };
+    unsafe { ALLOCATOR.init(start, HEAP_SIZE) }
+
+    // Growable array allocated on the heap
+    let xs = vec![0, 1, 2];
+
+    let mut stdout = hio::hstdout().unwrap();
+    writeln!(stdout, "{:?}", xs).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();
+}

examples/crash.rs

@@ -1,40 +1,68 @@
 //! 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.
+//! 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:
+//! In you run the example below, you'll be able to inspect the state of your program under the
+//! debugger using these commands:
 //!
-//! ```
-//! (gdb) # Stacked registers = program state during the crash
-//! (gdb) print/x *_sr
-//! $1 = cortex_m::exception::StackedRegisters {
+//! ``` 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 = 0x8000443,
-//!   pc = 0x8000190,
-//!   xpsr = 0x61000200,
+//!   lr = 0x8000481,
+//!   pc = 0x8000460,
+//!   xpsr = 0x61000000,
 //! }
 //!
-//! (gdb) # What exception was triggered?
-//! (gdb) print _e
-//! $2 = cortex_m::exception::Exception::HardFault
-//!
 //! (gdb) # Where did we come from?
-//! (gdb) print _e
+//! (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;
+extern crate panic_abort; // panicking behavior
 
 use core::ptr;
 
@@ -48,9 +76,8 @@ fn main() {
 }
 
 // As we are not using interrupts, we just register a dummy catch all handler
-#[allow(dead_code)]
+#[link_section = ".vector_table.interrupts"]
 #[used]
-#[link_section = ".rodata.interrupts"]
 static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 
 extern "C" fn default_handler() {

examples/device.rs

@@ -0,0 +1,95 @@
+//! 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 && tail $_
+//! [dependencies.stm32f103xx]
+//! features = ["rt"]
+//! version = "0.9.0"
+//! ```
+//!
+//! ---
+
+#![deny(warnings)]
+#![feature(const_fn)]
+#![no_std]
+
+extern crate cortex_m;
+// extern crate cortex_m_rt; // included in the device crate
+extern crate cortex_m_semihosting;
+#[macro_use(exception, interrupt)]
+extern crate stm32f103xx;
+extern crate panic_abort; // panicking behavior
+
+use core::cell::RefCell;
+use core::fmt::Write;
+
+use cortex_m::interrupt::{self, Mutex};
+use cortex_m::peripheral::syst::SystClkSource;
+use cortex_m_semihosting::hio::{self, HStdout};
+use stm32f103xx::Interrupt;
+
+static HSTDOUT: Mutex<RefCell<Option<HStdout>>> = Mutex::new(RefCell::new(None));
+
+static NVIC: Mutex<RefCell<Option<cortex_m::peripheral::NVIC>>> = Mutex::new(RefCell::new(None));
+
+fn main() {
+    let global_p = cortex_m::Peripherals::take().unwrap();
+    interrupt::free(|cs| {
+        let hstdout = HSTDOUT.borrow(cs);
+        if let Ok(fd) = hio::hstdout() {
+            *hstdout.borrow_mut() = Some(fd);
+        }
+
+        let mut nvic = global_p.NVIC;
+        nvic.enable(Interrupt::TIM2);
+        *NVIC.borrow(cs).borrow_mut() = Some(nvic);
+
+        let mut syst = global_p.SYST;
+        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();
+        }
+
+        if let Some(nvic) = NVIC.borrow(cs).borrow_mut().as_mut() {
+            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();
+        }
+    });
+}

examples/hello.rs

@@ -1,22 +1,28 @@
 //! Prints "Hello, world!" on the OpenOCD console using semihosting
+//!
+//! ---
 
 #![feature(used)]
 #![no_std]
 
-#[macro_use]
 extern crate cortex_m;
 extern crate cortex_m_rt;
+extern crate cortex_m_semihosting;
+extern crate panic_abort; // panicking behavior
+
+use core::fmt::Write;
 
 use cortex_m::asm;
+use cortex_m_semihosting::hio;
 
 fn main() {
-    hprintln!("Hello, world!");
+    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
-#[allow(dead_code)]
+#[link_section = ".vector_table.interrupts"]
 #[used]
-#[link_section = ".rodata.interrupts"]
 static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 
 extern "C" fn default_handler() {

examples/itm.rs

@@ -1,15 +1,16 @@
 //! 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.
+//! **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 OpenOCD's ITM support in `.gdbinit`.
+//! 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/
+//! [`itmdump`]: https://docs.rs/itm/0.2.1/itm/
+//!
+//! ---
 
 #![feature(used)]
 #![no_std]
@@ -17,23 +18,20 @@
 #[macro_use]
 extern crate cortex_m;
 extern crate cortex_m_rt;
+extern crate panic_abort; // panicking behavior
 
-use cortex_m::{asm, interrupt, peripheral};
+use cortex_m::{asm, Peripherals};
 
 fn main() {
-    interrupt::free(
-        |cs| {
-            let itm = peripheral::ITM.borrow(&cs);
+    let p = Peripherals::take().unwrap();
+    let mut itm = p.ITM;
 
-            iprintln!(&itm.stim[0], "Hello, world!");
-        },
-    );
+    iprintln!(&mut itm.stim[0], "Hello, world!");
 }
 
 // As we are not using interrupts, we just register a dummy catch all handler
-#[allow(dead_code)]
+#[link_section = ".vector_table.interrupts"]
 #[used]
-#[link_section = ".rodata.interrupts"]
 static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 
 extern "C" fn default_handler() {

examples/override-exception-handler.rs

@@ -1,17 +1,26 @@
-//! Overriding an exception
+//! Overriding an exception handler
 //!
-//! **NOTE** You have to disable the `cortex-m-rt` crate's "exceptions" feature
-//! to make this work.
+//! 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;
+extern crate panic_abort; // panicking behavior
 
 use core::ptr;
 
-use cortex_m::{asm, exception};
+use cortex_m::asm;
 
 fn main() {
     unsafe {
@@ -20,25 +29,17 @@ fn main() {
     }
 }
 
-extern "C" fn hard_fault(_: exception::HardFault) {
+exception!(HARD_FAULT, handler);
+
+fn handler() {
     // You'll hit this breakpoint rather than the one in cortex-m-rt
     asm::bkpt()
 }
 
-// When the "exceptions" feature is disabled, you'll have to provide this symbol
-#[allow(dead_code)]
-#[used]
-#[link_section = ".rodata.exceptions"]
-static EXCEPTIONS: exception::Handlers = exception::Handlers {
-    // This is the exception handler override
-    hard_fault: hard_fault,
-    ..exception::DEFAULT_HANDLERS
-};
-
 // As we are not using interrupts, we just register a dummy catch all handler
 #[allow(dead_code)]
 #[used]
-#[link_section = ".rodata.interrupts"]
+#[link_section = ".vector_table.interrupts"]
 static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 
 extern "C" fn default_handler() {

examples/panic.rs

@@ -1,22 +1,19 @@
-//! Redirecting `panic!` messages
+//! Changing the panic handler
 //!
-//! The `cortex-m-rt` crate provides two options to redirect `panic!` messages
-//! through these two Cargo features:
+//! The easiest way to change the panic handler is to use a different [panic implementation
+//! crate][0].
 //!
-//! - `panic-over-semihosting`. `panic!` messages will be printed to the OpenOCD
-//!    console using semihosting. This is slow.
+//! [0]: https://crates.io/keywords/panic-impl
 //!
-//! - `panic-over-itm`. `panic!` messages will be send through the ITM port 0.
-//!   This is much faster but requires ITM support on the device.
-//!
-//! If neither of these options is specified then the `panic!` message will be
-//! lost. Note that all `panic!`s will trigger a debugger breakpoint.
+//! ---
 
 #![feature(used)]
 #![no_std]
 
 extern crate cortex_m;
 extern crate cortex_m_rt;
+// extern crate panic_abort;
+extern crate panic_semihosting; // reports panic messages to the host stderr using semihosting
 
 use cortex_m::asm;
 
@@ -25,9 +22,8 @@ fn main() {
 }
 
 // As we are not using interrupts, we just register a dummy catch all handler
-#[allow(dead_code)]
+#[link_section = ".vector_table.interrupts"]
 #[used]
-#[link_section = ".rodata.interrupts"]
 static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 
 extern "C" fn default_handler() {

examples/register-interrupt-handler.rs

@@ -1,36 +0,0 @@
-//! Register an interrupt handler
-//!
-//! NOTE Requires a device crate generated using `svd2rust`
-
-#![feature(used)]
-#![no_std]
-
-extern crate cortex_m;
-extern crate cortex_m_rt;
-// NOTE this is the device crate
-extern crate stm32f30x;
-
-use cortex_m::asm;
-use stm32f30x::interrupt;
-
-fn main() {}
-
-// NOTE each interrupt handler has a different signature
-extern "C" fn my_interrupt_handler(_ctxt: interrupt::Tim7) {
-    asm::bkpt();
-}
-
-extern "C" fn another_interrupt_handler(_ctxt: interrupt::Exti0) {
-    asm::bkpt();
-}
-
-// Here we override only two interrupt handlers, the rest of interrupt are
-// handled by the same interrupt handler
-#[allow(dead_code)]
-#[used]
-#[link_section = ".rodata.interrupts"]
-static INTERRUPTS: interrupt::Handlers = interrupt::Handlers {
-    Tim7: my_interrupt_handler,
-    Exti0: another_interrupt_handler,
-    ..interrupt::DEFAULT_HANDLERS
-};

gen-examples.sh

@@ -9,8 +9,9 @@ main() {
         itm
         panic
         crash
-        register-interrupt-handler
         override-exception-handler
+        device
+        allocator
     )
 
     rm -rf src/examples

memory.x

@@ -8,5 +8,16 @@ MEMORY
 
 /* This is where the call stack will be allocated. */
 /* The stack is of the full descending type. */
-/* NOTE Do NOT modify `_stack_start` unless you know what you are doing */
-_stack_start = ORIGIN(RAM) + LENGTH(RAM);
+/* You may want to use this variable to locate the call stack and static
+   variables in different memory regions. Below is shown the default value */
+/* _stack_start = ORIGIN(RAM) + LENGTH(RAM); */
+
+/* You can use this symbol to customize the location of the .text section */
+/* If omitted the .text section will be placed right after the .vector_table
+   section */
+/* 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,24 +1,30 @@
 //! Prints "Hello, world!" on the OpenOCD console using semihosting
 //!
+//! ---
+//!
 //! ```
 //! 
 //! #![feature(used)]
 //! #![no_std]
 //! 
-//! #[macro_use]
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
+//! extern crate cortex_m_semihosting;
+//! extern crate panic_abort; // panicking behavior
+//! 
+//! use core::fmt::Write;
 //! 
 //! use cortex_m::asm;
+//! use cortex_m_semihosting::hio;
 //! 
 //! fn main() {
-//!     hprintln!("Hello, world!");
+//!     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
-//! #[allow(dead_code)]
+//! #[link_section = ".vector_table.interrupts"]
 //! #[used]
-//! #[link_section = ".rodata.interrupts"]
 //! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 //! 
 //! extern "C" fn default_handler() {

src/examples/_1_itm.rs

@@ -1,15 +1,16 @@
 //! 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.
+//! **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 OpenOCD's ITM support in `.gdbinit`.
+//! 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/
+//! [`itmdump`]: https://docs.rs/itm/0.2.1/itm/
+//!
+//! ---
 //!
 //! ```
 //! 
@@ -19,23 +20,20 @@
 //! #[macro_use]
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
+//! extern crate panic_abort; // panicking behavior
 //! 
-//! use cortex_m::{asm, interrupt, peripheral};
+//! use cortex_m::{asm, Peripherals};
 //! 
 //! fn main() {
-//!     interrupt::free(
-//!         |cs| {
-//!             let itm = peripheral::ITM.borrow(&cs);
+//!     let p = Peripherals::take().unwrap();
+//!     let mut itm = p.ITM;
 //! 
-//!             iprintln!(&itm.stim[0], "Hello, world!");
-//!         },
-//!     );
+//!     iprintln!(&mut itm.stim[0], "Hello, world!");
 //! }
 //! 
 //! // As we are not using interrupts, we just register a dummy catch all handler
-//! #[allow(dead_code)]
+//! #[link_section = ".vector_table.interrupts"]
 //! #[used]
-//! #[link_section = ".rodata.interrupts"]
 //! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 //! 
 //! extern "C" fn default_handler() {

src/examples/_2_panic.rs

@@ -1,16 +1,11 @@
-//! Redirecting `panic!` messages
+//! Changing the panic handler
 //!
-//! The `cortex-m-rt` crate provides two options to redirect `panic!` messages
-//! through these two Cargo features:
+//! The easiest way to change the panic handler is to use a different [panic implementation
+//! crate][0].
 //!
-//! - `panic-over-semihosting`. `panic!` messages will be printed to the OpenOCD
-//!    console using semihosting. This is slow.
+//! [0]: https://crates.io/keywords/panic-impl
 //!
-//! - `panic-over-itm`. `panic!` messages will be send through the ITM port 0.
-//!   This is much faster but requires ITM support on the device.
-//!
-//! If neither of these options is specified then the `panic!` message will be
-//! lost. Note that all `panic!`s will trigger a debugger breakpoint.
+//! ---
 //!
 //! ```
 //! 
@@ -19,6 +14,8 @@
 //! 
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
+//! // extern crate panic_abort;
+//! extern crate panic_semihosting; // reports panic messages to the host stderr using semihosting
 //! 
 //! use cortex_m::asm;
 //! 
@@ -27,9 +24,8 @@
 //! }
 //! 
 //! // As we are not using interrupts, we just register a dummy catch all handler
-//! #[allow(dead_code)]
+//! #[link_section = ".vector_table.interrupts"]
 //! #[used]
-//! #[link_section = ".rodata.interrupts"]
 //! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 //! 
 //! extern "C" fn default_handler() {

src/examples/_3_crash.rs

@@ -1,35 +1,62 @@
 //! 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.
+//! 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:
+//! In you run the example below, you'll be able to inspect the state of your program under the
+//! debugger using these commands:
 //!
-//! ```
-//! (gdb) # Stacked registers = program state during the crash
-//! (gdb) print/x *_sr
-//! $1 = cortex_m::exception::StackedRegisters {
+//! ``` 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 = 0x8000443,
-//!   pc = 0x8000190,
-//!   xpsr = 0x61000200,
+//!   lr = 0x8000481,
+//!   pc = 0x8000460,
+//!   xpsr = 0x61000000,
 //! }
 //!
-//! (gdb) # What exception was triggered?
-//! (gdb) print _e
-//! $2 = cortex_m::exception::Exception::HardFault
-//!
 //! (gdb) # Where did we come from?
-//! (gdb) print _e
+//! (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)]
@@ -37,6 +64,7 @@
 //! 
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
+//! extern crate panic_abort; // panicking behavior
 //! 
 //! use core::ptr;
 //! 
@@ -50,9 +78,8 @@
 //! }
 //! 
 //! // As we are not using interrupts, we just register a dummy catch all handler
-//! #[allow(dead_code)]
+//! #[link_section = ".vector_table.interrupts"]
 //! #[used]
-//! #[link_section = ".rodata.interrupts"]
 //! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 //! 
 //! extern "C" fn default_handler() {

src/examples/_4_override_exception_handler.rs

@@ -1,7 +1,14 @@
-//! Overriding an exception
+//! Overriding an exception handler
 //!
-//! **NOTE** You have to disable the `cortex-m-rt` crate's "exceptions" feature
-//! to make this work.
+//! 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
+//!
+//! ---
 //!
 //! ```
 //! 
@@ -9,11 +16,13 @@
 //! #![no_std]
 //! 
 //! extern crate cortex_m;
+//! #[macro_use(exception)]
 //! extern crate cortex_m_rt;
+//! extern crate panic_abort; // panicking behavior
 //! 
 //! use core::ptr;
 //! 
-//! use cortex_m::{asm, exception};
+//! use cortex_m::asm;
 //! 
 //! fn main() {
 //!     unsafe {
@@ -22,25 +31,17 @@
 //!     }
 //! }
 //! 
-//! extern "C" fn hard_fault(_: exception::HardFault) {
+//! exception!(HARD_FAULT, handler);
+//! 
+//! fn handler() {
 //!     // You'll hit this breakpoint rather than the one in cortex-m-rt
 //!     asm::bkpt()
 //! }
 //! 
-//! // When the "exceptions" feature is disabled, you'll have to provide this symbol
-//! #[allow(dead_code)]
-//! #[used]
-//! #[link_section = ".rodata.exceptions"]
-//! static EXCEPTIONS: exception::Handlers = exception::Handlers {
-//!     // This is the exception handler override
-//!     hard_fault: hard_fault,
-//!     ..exception::DEFAULT_HANDLERS
-//! };
-//! 
 //! // As we are not using interrupts, we just register a dummy catch all handler
 //! #[allow(dead_code)]
 //! #[used]
-//! #[link_section = ".rodata.interrupts"]
+//! #[link_section = ".vector_table.interrupts"]
 //! static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
 //! 
 //! extern "C" fn default_handler() {

src/examples/_4_register_interrupt_handler.rs

@@ -1,40 +0,0 @@
-//! Register an interrupt handler
-//!
-//! NOTE Requires a device crate generated using `svd2rust`
-//!
-//! ```
-//! 
-//! #![feature(used)]
-//! #![no_std]
-//! 
-//! extern crate cortex_m;
-//! extern crate cortex_m_rt;
-//! // NOTE this is the device crate
-//! extern crate stm32f30x;
-//! 
-//! use cortex_m::asm;
-//! use stm32f30x::interrupt;
-//! 
-//! fn main() {}
-//! 
-//! // NOTE each interrupt handler has a different signature
-//! extern "C" fn my_interrupt_handler(_ctxt: interrupt::Tim7) {
-//!     asm::bkpt();
-//! }
-//! 
-//! extern "C" fn another_interrupt_handler(_ctxt: interrupt::Exti0) {
-//!     asm::bkpt();
-//! }
-//! 
-//! // Here we override only two interrupt handlers, the rest of interrupt are
-//! // handled by the same interrupt handler
-//! #[allow(dead_code)]
-//! #[used]
-//! #[link_section = ".rodata.interrupts"]
-//! static INTERRUPTS: interrupt::Handlers = interrupt::Handlers {
-//!     Tim7: my_interrupt_handler,
-//!     Exti0: another_interrupt_handler,
-//!     ..interrupt::DEFAULT_HANDLERS
-//! };
-//! ```
-// Auto-generated. Do not modify.

src/examples/_5_device.rs

@@ -0,0 +1,99 @@
+//! 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 && tail $_
+//! [dependencies.stm32f103xx]
+//! features = ["rt"]
+//! version = "0.9.0"
+//! ```
+//!
+//! ---
+//!
+//! ```
+//! 
+//! #![deny(warnings)]
+//! #![feature(const_fn)]
+//! #![no_std]
+//! 
+//! extern crate cortex_m;
+//! // extern crate cortex_m_rt; // included in the device crate
+//! extern crate cortex_m_semihosting;
+//! #[macro_use(exception, interrupt)]
+//! extern crate stm32f103xx;
+//! extern crate panic_abort; // panicking behavior
+//! 
+//! use core::cell::RefCell;
+//! use core::fmt::Write;
+//! 
+//! use cortex_m::interrupt::{self, Mutex};
+//! use cortex_m::peripheral::syst::SystClkSource;
+//! use cortex_m_semihosting::hio::{self, HStdout};
+//! use stm32f103xx::Interrupt;
+//! 
+//! static HSTDOUT: Mutex<RefCell<Option<HStdout>>> = Mutex::new(RefCell::new(None));
+//! 
+//! static NVIC: Mutex<RefCell<Option<cortex_m::peripheral::NVIC>>> = Mutex::new(RefCell::new(None));
+//! 
+//! fn main() {
+//!     let global_p = cortex_m::Peripherals::take().unwrap();
+//!     interrupt::free(|cs| {
+//!         let hstdout = HSTDOUT.borrow(cs);
+//!         if let Ok(fd) = hio::hstdout() {
+//!             *hstdout.borrow_mut() = Some(fd);
+//!         }
+//! 
+//!         let mut nvic = global_p.NVIC;
+//!         nvic.enable(Interrupt::TIM2);
+//!         *NVIC.borrow(cs).borrow_mut() = Some(nvic);
+//! 
+//!         let mut syst = global_p.SYST;
+//!         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();
+//!         }
+//! 
+//!         if let Some(nvic) = NVIC.borrow(cs).borrow_mut().as_mut() {
+//!             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/_6_allocator.rs

@@ -0,0 +1,64 @@
+//! How to use the heap and a dynamic memory allocator
+//!
+//! 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
+//! $ cargo add alloc-cortex-m
+//! ```
+//!
+//! ---
+//!
+//! ```
+//! 
+//! #![feature(alloc)]
+//! #![feature(global_allocator)]
+//! #![feature(used)]
+//! #![no_std]
+//! 
+//! // This is the allocator crate; you can use a different one
+//! extern crate alloc_cortex_m;
+//! #[macro_use]
+//! extern crate alloc;
+//! extern crate cortex_m;
+//! extern crate cortex_m_rt;
+//! extern crate cortex_m_semihosting;
+//! extern crate panic_abort; // panicking behavior
+//! 
+//! use core::fmt::Write;
+//! 
+//! use alloc_cortex_m::CortexMHeap;
+//! use cortex_m::asm;
+//! use cortex_m_semihosting::hio;
+//! 
+//! #[global_allocator]
+//! static ALLOCATOR: CortexMHeap = CortexMHeap::empty();
+//! 
+//! extern "C" {
+//!     static mut _sheap: u32;
+//! }
+//! 
+//! const HEAP_SIZE: usize = 1024; // in bytes
+//! 
+//! fn main() {
+//!     // Initialize the allocator
+//!     let start = unsafe { &mut _sheap as *mut u32 as usize };
+//!     unsafe { ALLOCATOR.init(start, HEAP_SIZE) }
+//! 
+//!     // Growable array allocated on the heap
+//!     let xs = vec![0, 1, 2];
+//! 
+//!     let mut stdout = hio::hstdout().unwrap();
+//!     writeln!(stdout, "{:?}", xs).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/mod.rs

@@ -4,5 +4,6 @@ pub mod _0_hello;
 pub mod _1_itm;
 pub mod _2_panic;
 pub mod _3_crash;
-pub mod _4_register_interrupt_handler;
-pub mod _5_override_exception_handler;
+pub mod _4_override_exception_handler;
+pub mod _5_device;
+pub mod _6_allocator;

src/lib.rs

@@ -1,14 +1,36 @@
 //! A template for building applications for ARM Cortex-M microcontrollers
 //!
+//! # Dependencies
+//!
+//! - 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` (on Ubuntu)
+//! - OpenOCD: `sudo apt-get install OpenOCD` (on Ubuntu)
+//! - [Optional] ARM linker: `sudo apt-get install binutils-arm-none-eabi` (on Ubuntu)
+//! - [Optional] Cargo `add` subcommand: `cargo install cargo-edit`
+//!
 //! # Usage
 //!
-//! - Clone this crate
+//! 0) Figure out the cross compilation *target* to use.
+//!
+//! - 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
+//! ```
+//!
+//! 2) Clone this crate
 //!
 //! ``` text
 //! $ cargo clone cortex-m-quickstart && cd $_
 //! ```
 //!
-//! - Change the crate name, author and version
+//! 3) Change the crate name, author and version
 //!
 //! ``` text
 //! $ edit Cargo.toml && head $_
@@ -18,28 +40,24 @@
 //! 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* the `memory.x` and `build.rs`
+//! files.
 //!
 //! ``` 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
 //! }
-//!
-//! /* This is where the call stack will be allocated. */
-//! /* The stack is of the full descending type. */
-//! /* NOTE Do NOT modify `_stack_start` unless you know what you are doing */
-//! _stack_start = ORIGIN(RAM) + LENGTH(RAM);
+//! EOF
 //! ```
 //!
-//! - Optionally, set a default build target
+//! 5) Optionally, set a default build target
 //!
 //! ``` text
 //! $ cat >>.cargo/config <<'EOF'
@@ -48,31 +66,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
+//! $ # add a device crate, OR
 //! $ cargo add stm32f30x
 //!
-//! # add a board support crate
+//! $ # 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
 //! ```
 //!
-//! - Build the application
+//! 8) Build the application
 //!
 //! ``` text
-//! # if not installed
-//! $ cargo install xargo
-//!
-//! # 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
@@ -95,9 +113,236 @@
 //!   Tag_ABI_FP_16bit_format: IEEE 754
 //! ```
 //!
+//! **NOTE** By default Cargo will use the LLD linker shipped with the Rust toolchain. If you
+//! encounter any linking error try to switch to the GNU linker by modifying the `.cargo/config`
+//! file as shown below:
+//!
+//! ``` text
+//!  runner = 'arm-none-eabi-gdb'
+//!  rustflags = [
+//!    "-C", "link-arg=-Tlink.x",
+//! -  "-C", "linker=lld",
+//! -  "-Z", "linker-flavor=ld.lld",
+//! -  # "-C", "linker=arm-none-eabi-ld",
+//! -  # "-Z", "linker-flavor=ld",
+//! +  # "-C", "linker=lld",
+//! +  # "-Z", "linker-flavor=ld.lld",
+//! +  "-C", "linker=arm-none-eabi-ld",
+//! +  "-Z", "linker-flavor=ld",
+//!    "-Z", "thinlto=no",
+//!  ]
+//! ```
+//!
+//! 9) Flash the program
+//!
+//! ``` text
+//! $ # Launch OpenOCD on a terminal
+//! $ openocd -f (..)
+//! ```
+//!
+//! ``` text
+//! $ # Start a debug session in another terminal
+//! $ arm-none-eabi-gdb target/thumbv7em-none-eabihf/release/demo
+//! ```
+//!
+//! Alternatively, you can use `cargo run` to build, flash and debug the program in a single step.
+//!
+//! ``` text
+//! $ cargo run --example hello
+//! > # drops you into a GDB session
+//! ```
+//!
 //! # Examples
 //!
 //! Check the [examples module](./examples/index.html)
+//!
+//! # Troubleshooting
+//!
+//! This section contains fixes for common errors encountered when the
+//! `cortex-m-quickstart` template is misused.
+//!
+//! ## Forgot to launch an OpenOCD instance
+//!
+//! Error message:
+//!
+//! ``` text
+//! $ arm-none-eabi-gdb target/..
+//! Reading symbols from hello...done.
+//! .gdbinit:1: Error in sourced command file:
+//! :3333: Connection timed out.
+//! ```
+//!
+//! Solution: Launch OpenOCD on other terminal. See [Usage] section.
+//!
+//! [Usage]: ./index.html#usage
+//!
+//! ## Didn't modify the `memory.x` linker script
+//!
+//! Error message:
+//!
+//! ``` text
+//! $ cargo build
+//! Compiling demo v0.1.0 (file:///home/japaric/tmp/demo)
+//! error: linking with `arm-none-eabi-ld` failed: exit code: 1
+//! |
+//! = note: "lld" "-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.
+//! ```
+//!
+//! Solution: Specify your device memory layout in the `memory.x` linker script.
+//! See [Usage] section.
+//!
+//! ## Forgot to set a default build target
+//!
+//! Error message:
+//!
+//! ``` text
+//! $ cargo build
+//! (..)
+//! Compiling cortex-m-semihosting v0.2.0
+//! error[E0463]: can't find crate for `std`
+//!
+//! error: aborting due to previous error
+//! ```
+//!
+//! 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
+//!
+//! Error message:
+//!
+//! ``` text
+//! error: linking with `arm-none-eabi-gcc` failed: exit code: 1
+//!   |
+//!   = note: (..)
+//! (..)
+//! (..)/crt0.o: In function `_start':
+//! (.text+0x90): undefined reference to `memset'
+//! (..)/crt0.o: In function `_start':
+//! (.text+0xd0): undefined reference to `atexit'
+//! (..)/crt0.o: In function `_start':
+//! (.text+0xd4): undefined reference to `__libc_init_array'
+//! (..)/crt0.o: In function `_start':
+//! (.text+0xe4): undefined reference to `exit'
+//! (..)/crt0.o: In function `_start':
+//! (.text+0x100): undefined reference to `__libc_fini_array'
+//! 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
+//! default build target to `.cargo/config`.
+//!
+//! ## Called OpenOCD with wrong arguments
+//!
+//! Error message:
+//!
+//! ``` text
+//! $ openocd -f ..
+//! (..)
+//! Error: open failed
+//! in procedure 'init'
+//! 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.
+//!
+//! ## Used an old nightly
+//!
+//! Error message:
+//!
+//! ``` text
+//! $ cargo build
+//! Compiling cortex-m-rt v0.2.0
+//! error[E0463]: can't find crate for `core`
+//! |
+//! = note: the `thumbv7em-none-eabihf` target may not be installed
+//!
+//! error: aborting due to previous error
+//! ```
+//!
+//! Solution: Use a more recent nightly
+//!
+//! ## Used the stable toolchain
+//!
+//! Error message:
+//!
+//! ``` text
+//! $ cargo build
+//! error: failed to run `rustc` to learn about target-specific information
+//!
+//! To learn more, run the command again with --verbose.
+//! ```
+//!
+//! Solution: Switch to the nightly toolchain with `rustup default nightly`.
+//!
+//! ## Used `gdb` instead of `arm-none-eabi-gdb`
+//!
+//! Error message:
+//!
+//! ``` text
+//! $ gdb target/..
+//! Reading symbols from hello...done.
+//! warning: Architecture rejected target-supplied description
+//! warning: Cannot convert floating-point register value to ..
+//! value has been optimized out
+//! Cannot write the dashboard
+//! Traceback (most recent call last):
+//! File "<string>", line 353, in render
+//! File "<string>", line 846, in lines
+//! gdb.error: Frame is invalid.
+//! 0x00000000 in ?? ()
+//! semihosting is enabled
+//! Loading section .text, size 0xd88 lma 0x8000000
+//! Start address 0x8000000, load size 3464
+//! .gdbinit:6: Error in sourced command file:
+//! Remote connection closed
+//! ```
+//!
+//! Solution: Use `arm-none-eabi-gdb target/..`
+//!
+//! # Used a named piped for `itm.fifo`
+//!
+//! Error message:
+//!
+//! ``` text
+//! $ cargo run [--example ..]
+//!
+//! Reading symbols from target/thumbv7em-none-eabihf/debug/cortex-m-quickstart...done.
+//! cortex_m_rt::reset_handler ()
+//!     at $REGISTRY/cortex-m-rt-0.3.12/src/lib.rs:330
+//! 330     unsafe extern "C" fn reset_handler() -> ! {
+//! semihosting is enabled
+//! Ignoring packet error, continuing...
+//! Ignoring packet error, continuing...
+//! ```
+//!
+//! 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 `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 `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.
+//!
+//! Alternative solution: Use a plain text file instead of a named pipe. In this scenario you omit
+//! the `mkfifo itm.dump` command. You can use `itmdump`'s *follow* mode (-F) to get named pipe like
+//! output.
 
 #![no_std]