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

@@ -2,34 +2,38 @@
 runner = 'arm-none-eabi-gdb'
 rustflags = [
   "-C", "link-arg=-Tlink.x",
-  "-C", "linker=arm-none-eabi-ld",
-  "-Z", "linker-flavor=ld",
-  "-Z", "thinlto=no",
+  "-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",
-  "-Z", "thinlto=no",
+  "-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",
-  "-Z", "thinlto=no",
+  "-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",
-  "-Z", "thinlto=no",
+  "-C", "linker=lld",
+  "-Z", "linker-flavor=ld.lld",
+  # "-C", "linker=arm-none-eabi-ld",
+  # "-Z", "linker-flavor=ld",
 ]

.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,6 +5,18 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [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
@@ -137,7 +149,10 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 - Initial release
 
-[Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.4...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

Cargo.toml

@@ -6,31 +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.2.5"
+version = "0.2.7"
 
 [dependencies]
 cortex-m = "0.4.0"
+cortex-m-rt = "0.4.0"
 cortex-m-semihosting = "0.2.0"
-# alloc-cortex-m release doesn't use linked_list_allocator v0.5.0 yet.
+panic-abort = "0.1.1"
+panic-semihosting = "0.1.0"
 # Uncomment for the allocator example.
-#alloc-cortex-m = "0.3.2"
-
-[dependencies.cortex-m-rt]
-version = "0.3.12"
-# Comment for the panic example.
-features = ["abort-on-panic"]
+#alloc-cortex-m = "0.3.3"
 
 # Uncomment for the device example.
 # [dependencies.stm32f103xx]
 # features = ["rt"]
-# version = "0.8.0"
-
-# disable both incremental compilation and parallel codegen to reduce the chances of running into
-# rust-lang/rust#47074
-[profile.dev]
-codegen-units = 1
-incremental = false
+# version = "0.9.0"
 
 [profile.release]
 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,9 +0,0 @@
-[dependencies.core]
-stage = 0
-
-# [dependencies.alloc] # Uncomment for the alloc example.
-# stage = 0
-
-[dependencies.compiler_builtins]
-features = ["mem"]
-stage = 1

bors.toml

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

ci/install.sh

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

ci/script.sh

@@ -0,0 +1,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

@@ -1,22 +1,6 @@
 //! How to use the heap and a dynamic memory allocator
 //!
-//! To compile this example you'll need to build the alloc crate as part
-//! of the Xargo sysroot. To do that change the Xargo.toml file to look like
-//! this:
-//!
-//! ``` text
-//! [dependencies.core]
-//! stage = 0
-//!
-//! [dependencies.alloc] # NEW
-//! stage = 0
-//!
-//! [dependencies.compiler_builtins]
-//! stage = 1
-//! ```
-//!
-//! This example depends on the alloc-cortex-m crate so you'll have to add it
-//! to your Cargo.toml:
+//! This example depends on the alloc-cortex-m crate so you'll have to add it to your Cargo.toml:
 //!
 //! ``` text
 //! # or edit the Cargo.toml file manually
@@ -26,8 +10,8 @@
 //! ---
 
 #![feature(alloc)]
-#![feature(used)]
 #![feature(global_allocator)]
+#![feature(used)]
 #![no_std]
 
 // This is the allocator crate; you can use a different one
@@ -37,26 +21,27 @@ 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;
-use alloc_cortex_m::CortexMHeap;
 
 #[global_allocator]
 static ALLOCATOR: CortexMHeap = CortexMHeap::empty();
 
 extern "C" {
     static mut _sheap: u32;
-    static mut _eheap: u32;
 }
 
+const HEAP_SIZE: usize = 1024; // in bytes
+
 fn main() {
     // Initialize the allocator
     let start = unsafe { &mut _sheap as *mut u32 as usize };
-    let end = unsafe { &mut _eheap as *mut u32 as usize };
-    unsafe { ALLOCATOR.init(start, end - start) }
+    unsafe { ALLOCATOR.init(start, HEAP_SIZE) }
 
     // Growable array allocated on the heap
     let xs = vec![0, 1, 2];

examples/crash.rs

@@ -1,12 +1,11 @@
 //! 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:
 //!
 //! ``` text
 //! (gdb) # Exception frame = program state during the crash
@@ -63,6 +62,7 @@
 
 extern crate cortex_m;
 extern crate cortex_m_rt;
+extern crate panic_abort; // panicking behavior
 
 use core::ptr;
 

examples/device.rs

@@ -1,25 +1,22 @@
 //! Using a device crate
 //!
-//! Crates generated using [`svd2rust`] are referred to as device crates. These
-//! crates provides an API to access the peripherals of a device. When you
-//! depend on one of these crates and the "rt" feature is enabled you don't need
-//! link to the cortex-m-rt crate.
+//! Crates generated using [`svd2rust`] are referred to as device crates. These crates 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.
+//! 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.
+//! This example depends on the [`stm32f103xx`] crate so you'll have to add it to your Cargo.toml.
 //!
 //! [`stm32f103xx`]: https://crates.io/crates/stm32f103xx
 //!
 //! ```
-//! $ edit Cargo.toml && cat $_
+//! $ edit Cargo.toml && tail $_
 //! [dependencies.stm32f103xx]
 //! features = ["rt"]
-//! version = "0.8.0"
+//! version = "0.9.0"
 //! ```
 //!
 //! ---
@@ -29,9 +26,11 @@
 #![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;
@@ -41,11 +40,9 @@ 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 HSTDOUT: Mutex<RefCell<Option<HStdout>>> = Mutex::new(RefCell::new(None));
 
-static NVIC: Mutex<RefCell<Option<cortex_m::peripheral::NVIC>>> =
-    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();

examples/hello.rs

@@ -8,6 +8,7 @@
 extern crate cortex_m;
 extern crate cortex_m_rt;
 extern crate cortex_m_semihosting;
+extern crate panic_abort; // panicking behavior
 
 use core::fmt::Write;
 

examples/itm.rs

@@ -1,15 +1,14 @@
 //! 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 the `monitor` commands in the `.gdbinit` file.
+//! 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,6 +18,7 @@
 #[macro_use]
 extern crate cortex_m;
 extern crate cortex_m_rt;
+extern crate panic_abort; // panicking behavior
 
 use cortex_m::{asm, Peripherals};
 

examples/override-exception-handler.rs

@@ -4,8 +4,7 @@
 //!
 //! [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
+//! 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
 //!
@@ -17,6 +16,7 @@
 extern crate cortex_m;
 #[macro_use(exception)]
 extern crate cortex_m_rt;
+extern crate panic_abort; // panicking behavior
 
 use core::ptr;
 

examples/panic.rs

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

src/examples/_0_hello.rs

@@ -10,6 +10,7 @@
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
 //! extern crate cortex_m_semihosting;
+//! extern crate panic_abort; // panicking behavior
 //! 
 //! use core::fmt::Write;
 //! 

src/examples/_1_itm.rs

@@ -1,15 +1,14 @@
 //! 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 the `monitor` commands in the `.gdbinit` file.
+//! 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/
 //!
 //! ---
 //!
@@ -21,6 +20,7 @@
 //! #[macro_use]
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
+//! extern crate panic_abort; // panicking behavior
 //! 
 //! use cortex_m::{asm, Peripherals};
 //! 

src/examples/_2_panic.rs

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

src/examples/_3_crash.rs

@@ -1,12 +1,11 @@
 //! 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:
 //!
 //! ``` text
 //! (gdb) # Exception frame = program state during the crash
@@ -65,6 +64,7 @@
 //! 
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
+//! extern crate panic_abort; // panicking behavior
 //! 
 //! use core::ptr;
 //! 

src/examples/_4_override_exception_handler.rs

@@ -4,8 +4,7 @@
 //!
 //! [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
+//! 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
 //!
@@ -19,6 +18,7 @@
 //! extern crate cortex_m;
 //! #[macro_use(exception)]
 //! extern crate cortex_m_rt;
+//! extern crate panic_abort; // panicking behavior
 //! 
 //! use core::ptr;
 //! 

src/examples/_5_device.rs

@@ -1,25 +1,22 @@
 //! Using a device crate
 //!
-//! Crates generated using [`svd2rust`] are referred to as device crates. These
-//! crates provides an API to access the peripherals of a device. When you
-//! depend on one of these crates and the "rt" feature is enabled you don't need
-//! link to the cortex-m-rt crate.
+//! Crates generated using [`svd2rust`] are referred to as device crates. These crates 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.
+//! 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.
+//! This example depends on the [`stm32f103xx`] crate so you'll have to add it to your Cargo.toml.
 //!
 //! [`stm32f103xx`]: https://crates.io/crates/stm32f103xx
 //!
 //! ```
-//! $ edit Cargo.toml && cat $_
+//! $ edit Cargo.toml && tail $_
 //! [dependencies.stm32f103xx]
 //! features = ["rt"]
-//! version = "0.8.0"
+//! version = "0.9.0"
 //! ```
 //!
 //! ---
@@ -31,9 +28,11 @@
 //! #![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;
@@ -43,11 +42,9 @@
 //! use cortex_m_semihosting::hio::{self, HStdout};
 //! use stm32f103xx::Interrupt;
 //! 
-//! static HSTDOUT: Mutex<RefCell<Option<HStdout>>> =
-//!     Mutex::new(RefCell::new(None));
+//! 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));
+//! static NVIC: Mutex<RefCell<Option<cortex_m::peripheral::NVIC>>> = Mutex::new(RefCell::new(None));
 //! 
 //! fn main() {
 //!     let global_p = cortex_m::Peripherals::take().unwrap();

src/examples/_6_allocator.rs

@@ -1,22 +1,6 @@
 //! How to use the heap and a dynamic memory allocator
 //!
-//! To compile this example you'll need to build the alloc crate as part
-//! of the Xargo sysroot. To do that change the Xargo.toml file to look like
-//! this:
-//!
-//! ``` text
-//! [dependencies.core]
-//! stage = 0
-//!
-//! [dependencies.alloc] # NEW
-//! stage = 0
-//!
-//! [dependencies.compiler_builtins]
-//! stage = 1
-//! ```
-//!
-//! This example depends on the alloc-cortex-m crate so you'll have to add it
-//! to your Cargo.toml:
+//! This example depends on the alloc-cortex-m crate so you'll have to add it to your Cargo.toml:
 //!
 //! ``` text
 //! # or edit the Cargo.toml file manually
@@ -28,8 +12,8 @@
 //! ```
 //! 
 //! #![feature(alloc)]
-//! #![feature(used)]
 //! #![feature(global_allocator)]
+//! #![feature(used)]
 //! #![no_std]
 //! 
 //! // This is the allocator crate; you can use a different one
@@ -39,26 +23,27 @@
 //! 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;
-//! use alloc_cortex_m::CortexMHeap;
 //! 
 //! #[global_allocator]
 //! static ALLOCATOR: CortexMHeap = CortexMHeap::empty();
 //! 
 //! extern "C" {
 //!     static mut _sheap: u32;
-//!     static mut _eheap: u32;
 //! }
 //! 
+//! const HEAP_SIZE: usize = 1024; // in bytes
+//! 
 //! fn main() {
 //!     // Initialize the allocator
 //!     let start = unsafe { &mut _sheap as *mut u32 as usize };
-//!     let end = unsafe { &mut _eheap as *mut u32 as usize };
-//!     unsafe { ALLOCATOR.init(start, end - start) }
+//!     unsafe { ALLOCATOR.init(start, HEAP_SIZE) }
 //! 
 //!     // Growable array allocated on the heap
 //!     let xs = vec![0, 1, 2];

src/lib.rs

@@ -2,23 +2,35 @@
 //!
 //! # Dependencies
 //!
-//! - Nightly Rust toolchain: `rustup default nightly`
-//! - ARM linker: `sudo apt-get install binutils-arm-none-eabi` (on Ubuntu)
+//! - 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)
-//! - Xargo: `cargo install xargo`
+//! - [Optional] ARM linker: `sudo apt-get install binutils-arm-none-eabi` (on Ubuntu)
 //! - [Optional] Cargo `add` subcommand: `cargo install cargo-edit`
 //!
 //! # Usage
 //!
-//! 1) 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 $_
 //! ```
 //!
-//! 2) Change the crate name, author and version
+//! 3) Change the crate name, author and version
 //!
 //! ``` text
 //! $ edit Cargo.toml && head $_
@@ -28,23 +40,24 @@
 //! version = "0.1.0"
 //! ```
 //!
-//! 3) Specify the memory layout of the target device
+//! 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`
 //! 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
 //! }
+//! EOF
 //! ```
 //!
-//! 4) Optionally, set a default build target
+//! 5) Optionally, set a default build target
 //!
 //! ``` text
 //! $ cat >>.cargo/config <<'EOF'
@@ -53,30 +66,29 @@
 //! EOF
 //! ```
 //!
-//! 5) Depend on a device, HAL implementation or a board support crate.
+//! 6) Optionally, depend on a device, HAL implementation or a board support crate.
 //!
 //! ``` text
 //! $ # add a device crate, OR
 //! $ cargo add stm32f30x
 //!
 //! $ # add a HAL implementation crate, OR
-//! $ cargo add stm32f103xx-hal
+//! $ cargo add stm32f30x-hal
 //!
 //! $ # add a board support crate
 //! $ cargo add f3
 //! ```
 //!
-//! 6) 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
 //! ```
 //!
-//! 7) Build the application
+//! 8) Build the application
 //!
 //! ``` text
-//! $ # NOTE this command requires `arm-none-eabi-ld` to be in $PATH
-//! $ xargo build --release
+//! $ cargo build --release
 //!
 //! $ # sanity check
 //! $ arm-none-eabi-readelf -A target/thumbv7em-none-eabihf/release/demo
@@ -101,7 +113,27 @@
 //!   Tag_ABI_FP_16bit_format: IEEE 754
 //! ```
 //!
-//! 8) Flash the program
+//! **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
@@ -113,9 +145,7 @@
 //! $ arm-none-eabi-gdb target/thumbv7em-none-eabihf/release/demo
 //! ```
 //!
-//! **NOTE** As of nightly-2017-05-14 or so and cortex-m-quickstart v0.1.6 you can simply run `xargo
-//! run` or `xargo run --example $example` to build the program, *and* immediately start a debug
-//! session. IOW, it lets you omit the `arm-none-eabi-gdb` command.
+//! Alternatively, you can use `cargo run` to build, flash and debug the program in a single step.
 //!
 //! ``` text
 //! $ cargo run --example hello
@@ -151,11 +181,11 @@
 //! Error message:
 //!
 //! ``` text
-//! $ xargo build
+//! $ cargo build
 //! Compiling demo v0.1.0 (file:///home/japaric/tmp/demo)
 //! error: linking with `arm-none-eabi-ld` failed: exit code: 1
 //! |
-//! = note: "arm-none-eabi-ld" "-L" (..)
+//! = note: "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:
@@ -172,17 +202,17 @@
 //! Error message:
 //!
 //! ``` text
-//! $ xargo build
+//! $ cargo build
 //! (..)
-//! Compiling cortex-m-semihosting v0.1.3
+//! 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 Xargo with `--target` flag:
-//! `xargo build --target thumbv7em-none-eabi`.
+//! (see [Usage] section), or call Cargo with `--target` flag:
+//! `cargo build --target thumbv7em-none-eabi`.
 //!
 //! ## Overwrote the original `.cargo/config` file
 //!
@@ -229,7 +259,7 @@
 //! `/usr/share/openocd/scripts` directory (exact location varies per
 //! distribution / OS) for a list of scripts that can be used.
 //!
-//! ## Used Cargo instead of Xargo
+//! ## Used an old nightly
 //!
 //! Error message:
 //!
@@ -243,14 +273,14 @@
 //! error: aborting due to previous error
 //! ```
 //!
-//! Solution: Use `xargo build`.
+//! Solution: Use a more recent nightly
 //!
 //! ## Used the stable toolchain
 //!
 //! Error message:
 //!
 //! ``` text
-//! $ xargo build
+//! $ cargo build
 //! error: failed to run `rustc` to learn about target-specific information
 //!
 //! To learn more, run the command again with --verbose.
@@ -288,7 +318,7 @@
 //! Error message:
 //!
 //! ``` text
-//! $ xargo run [--example ..]
+//! $ cargo run [--example ..]
 //!
 //! Reading symbols from target/thumbv7em-none-eabihf/debug/cortex-m-quickstart...done.
 //! cortex_m_rt::reset_handler ()
@@ -300,13 +330,13 @@
 //! ```
 //!
 //! Note that when you reach this point OpenOCD will become unresponsive and you'll have to kill it
-//! and start a new OpenOCD process before you can invoke `xargo run` / start GDB.
+//! and start a new OpenOCD process before you can invoke `cargo run` / start GDB.
 //!
 //! Cause: You uncommented the `monitor tpiu ..` line in `.gdbinit` and are using a named pipe to
 //! receive the ITM data (i.e. you ran `mkfifo itm.fifo`). This error occurs when `itmdump -f
 //! itm.fifo` (or equivalent, e.g. `cat itm.fifo`) is not running.
 //!
-//! Solution: Run `itmdump -f itm.fifo` (or equivalently `cat itm.fifo`) *before* invoking `xargo
+//! Solution: Run `itmdump -f itm.fifo` (or equivalently `cat itm.fifo`) *before* invoking `cargo
 //! run` / starting GDB. Note that sometimes `itmdump` will exit when the GDB session ends. In that
 //! case you'll have to run `itmdump` before you start the next GDB session.
 //!