v0.2.5

Update examples

.cargo/config

@@ -4,6 +4,7 @@ rustflags = [
   "-C", "link-arg=-Tlink.x",
   "-C", "linker=arm-none-eabi-ld",
   "-Z", "linker-flavor=ld",
+  "-Z", "thinlto=no",
 ]
 
 [target.thumbv7m-none-eabi]
@@ -12,6 +13,7 @@ rustflags = [
   "-C", "link-arg=-Tlink.x",
   "-C", "linker=arm-none-eabi-ld",
   "-Z", "linker-flavor=ld",
+  "-Z", "thinlto=no",
 ]
 
 [target.thumbv7em-none-eabi]
@@ -20,6 +22,7 @@ rustflags = [
   "-C", "link-arg=-Tlink.x",
   "-C", "linker=arm-none-eabi-ld",
   "-Z", "linker-flavor=ld",
+  "-Z", "thinlto=no",
 ]
 
 [target.thumbv7em-none-eabihf]
@@ -28,4 +31,5 @@ rustflags = [
   "-C", "link-arg=-Tlink.x",
   "-C", "linker=arm-none-eabi-ld",
   "-Z", "linker-flavor=ld",
+  "-Z", "thinlto=no",
 ]

CHANGELOG.md

@@ -5,6 +5,47 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [v0.2.5] - 2018-02-26
+
+### Added
+
+- Comments to Cargo.toml and Xargo.toml to make it easier to try the examples.
+
+### Fixed
+
+- The `allocator` example to use the `#[global_allocator]` feature.
+
+## [v0.2.4] - 2018-01-26
+
+### Changed
+
+- Disable ThinLTO which causes extreme binary size bloat. See rust-lang/rust#47770 for details.
+
+## [v0.2.3] - 2018-01-20
+
+### Changed
+
+- Tweaked docs. Instruction steps are now numbered.
+
+### Removed
+
+- The `CARGO_INCREMENTAL=1` workaround has been removed since it's now controlled via Cargo.toml and
+  we have the setting disabled in the template.
+
+## [v0.2.2] - 2018-01-17
+
+### Added
+
+- Troubleshooting documentation: how to workaround the "Ignoring packet error, continuing..." GDB
+  error.
+
+### Changed
+
+- Disabled incremental compilation and parallel codegen on the dev profile to reduce the changes of
+  running into rust-lang/rust#47074.
+
+- Bumped the version of the `cortex-m-rt` dependency to v0.3.12.
+
 ## [v0.2.1] - 2017-07-14
 
 ### Added
@@ -96,7 +137,11 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 - Initial release
 
-[Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.4...HEAD
+[v0.2.4]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.3...v0.2.4
+[v0.2.3]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.2...v0.2.3
+[v0.2.2]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.1...v0.2.2
+[v0.2.1]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.0...v0.2.1
 [v0.2.0]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.8...v0.2.0
 [v0.1.8]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.7...v0.1.8
 [v0.1.7]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.6...v0.1.7

Cargo.toml

@@ -6,15 +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.2"
+version = "0.2.5"
 
 [dependencies]
-cortex-m = "0.3.0"
+cortex-m = "0.4.0"
 cortex-m-semihosting = "0.2.0"
+# alloc-cortex-m release doesn't use linked_list_allocator v0.5.0 yet.
+# Uncomment for the allocator example.
+#alloc-cortex-m = "0.3.2"
 
 [dependencies.cortex-m-rt]
-features = ["abort-on-panic"]
 version = "0.3.12"
+# Comment for the panic example.
+features = ["abort-on-panic"]
+
+# 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

Xargo.toml

@@ -1,6 +1,9 @@
 [dependencies.core]
 stage = 0
 
+# [dependencies.alloc] # Uncomment for the alloc example.
+# stage = 0
+
 [dependencies.compiler_builtins]
 features = ["mem"]
-stage = 1
+stage = 1

examples/allocator.rs

@@ -1,6 +1,6 @@
 //! How to use the heap and a dynamic memory allocator
 //!
-//! To compile this example you'll need to build the collections crate as part
+//! 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:
 //!
@@ -8,7 +8,7 @@
 //! [dependencies.core]
 //! stage = 0
 //!
-//! [dependencies.collections] # NEW
+//! [dependencies.alloc] # NEW
 //! stage = 0
 //!
 //! [dependencies.compiler_builtins]
@@ -25,15 +25,15 @@
 //!
 //! ---
 
-#[allow(deprecated)]
+#![feature(alloc)]
-#![feature(collections)]
 #![feature(used)]
+#![feature(global_allocator)]
 #![no_std]
 
 // This is the allocator crate; you can use a different one
 extern crate alloc_cortex_m;
 #[macro_use]
-extern crate collections;
+extern crate alloc;
 extern crate cortex_m;
 extern crate cortex_m_rt;
 extern crate cortex_m_semihosting;
@@ -42,25 +42,21 @@ use core::fmt::Write;
 
 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;
+}
 
 fn main() {
     // Initialize the allocator
-    unsafe {
+    let start = unsafe { &mut _sheap as *mut u32 as usize };
-        extern "C" {
+    let end = unsafe { &mut _eheap as *mut u32 as usize };
-            // Start of the heap
+    unsafe { ALLOCATOR.init(start, end - start) }
-            static mut _sheap: usize;
-        }
-
-        // Size of the heap in words (1 word = 4 bytes)
-        // NOTE The bigger the heap the greater the chance to run into a stack
-        // overflow (collision between the stack and the heap)
-        const SIZE: isize = 256;
-
-        // End of the heap
-        let _eheap = (&mut _sheap as *mut _).offset(SIZE);
-
-        alloc_cortex_m::init(&mut _sheap, _eheap);
-    }
 
     // Growable array allocated on the heap
     let xs = vec![0, 1, 2];

examples/device.rs

@@ -19,7 +19,7 @@
 //! $ edit Cargo.toml && cat $_
 //! [dependencies.stm32f103xx]
 //! features = ["rt"]
-//! version = "0.7.0"
+//! version = "0.8.0"
 //! ```
 //!
 //! ---
@@ -37,24 +37,29 @@ use core::cell::RefCell;
 use core::fmt::Write;
 
 use cortex_m::interrupt::{self, Mutex};
-use cortex_m::peripheral::SystClkSource;
+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 nvic = stm32f103xx::NVIC.borrow(cs);
+        let mut nvic = global_p.NVIC;
         nvic.enable(Interrupt::TIM2);
+        *NVIC.borrow(cs).borrow_mut() = Some(nvic);
 
-        let syst = stm32f103xx::SYST.borrow(cs);
+        let mut syst = global_p.SYST;
         syst.set_clock_source(SystClkSource::Core);
         syst.set_reload(8_000_000); // 1s
         syst.enable_counter();
@@ -71,9 +76,9 @@ fn tick() {
             writeln!(*hstdout, "Tick").ok();
         }
 
-        let nvic = stm32f103xx::NVIC.borrow(cs);
+        if let Some(nvic) = NVIC.borrow(cs).borrow_mut().as_mut() {
-
+            nvic.set_pending(Interrupt::TIM2);
-        nvic.set_pending(Interrupt::TIM2);
+        }
     });
 }
 

examples/itm.rs

@@ -20,14 +20,13 @@
 extern crate cortex_m;
 extern crate cortex_m_rt;
 
-use cortex_m::{asm, interrupt, peripheral};
+use cortex_m::{asm, Peripherals};
 
 fn main() {
-    interrupt::free(|cs| {
+    let p = Peripherals::take().unwrap();
-        let itm = peripheral::ITM.borrow(&cs);
+    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

examples/panic.rs

@@ -29,7 +29,7 @@ fn main() {
 
 #[lang = "panic_fmt"]
 #[no_mangle]
-unsafe extern "C" fn rust_begin_unwind(
+pub unsafe extern "C" fn rust_begin_unwind(
     args: core::fmt::Arguments,
     file: &'static str,
     line: u32,
@@ -40,7 +40,7 @@ unsafe extern "C" fn rust_begin_unwind(
             .and_then(|_| {
                 stdout
                     .write_fmt(args)
-                    .and_then(|_| writeln!(stdout, "', {}:{}", file, line))
+                    .and_then(|_| writeln!(stdout, "', {}:{}:{}", file, line, col))
             })
             .ok();
     }

memory.x

@@ -18,3 +18,6 @@ MEMORY
 /* This is required only on microcontrollers that store some configuration right
    after the vector table */
 /* _stext = ORIGIN(FLASH) + 0x400; */
+
+/* Size of the heap (in bytes) */
+/* _heap_size = 1024; */

src/examples/_1_itm.rs

@@ -22,14 +22,13 @@
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
 //! 
-//! use cortex_m::{asm, interrupt, peripheral};
+//! use cortex_m::{asm, Peripherals};
 //! 
 //! fn main() {
-//!     interrupt::free(|cs| {
+//!     let p = Peripherals::take().unwrap();
-//!         let itm = peripheral::ITM.borrow(&cs);
+//!     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

src/examples/_2_panic.rs

@@ -31,7 +31,7 @@
 //! 
 //! #[lang = "panic_fmt"]
 //! #[no_mangle]
-//! unsafe extern "C" fn rust_begin_unwind(
+//! pub unsafe extern "C" fn rust_begin_unwind(
 //!     args: core::fmt::Arguments,
 //!     file: &'static str,
 //!     line: u32,
@@ -42,7 +42,7 @@
 //!             .and_then(|_| {
 //!                 stdout
 //!                     .write_fmt(args)
-//!                     .and_then(|_| writeln!(stdout, "', {}:{}", file, line))
+//!                     .and_then(|_| writeln!(stdout, "', {}:{}:{}", file, line, col))
 //!             })
 //!             .ok();
 //!     }

src/examples/_5_device.rs

@@ -19,7 +19,7 @@
 //! $ edit Cargo.toml && cat $_
 //! [dependencies.stm32f103xx]
 //! features = ["rt"]
-//! version = "0.7.0"
+//! version = "0.8.0"
 //! ```
 //!
 //! ---
@@ -39,24 +39,29 @@
 //! use core::fmt::Write;
 //! 
 //! use cortex_m::interrupt::{self, Mutex};
-//! use cortex_m::peripheral::SystClkSource;
+//! 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 nvic = stm32f103xx::NVIC.borrow(cs);
+//!         let mut nvic = global_p.NVIC;
 //!         nvic.enable(Interrupt::TIM2);
+//!         *NVIC.borrow(cs).borrow_mut() = Some(nvic);
 //! 
-//!         let syst = stm32f103xx::SYST.borrow(cs);
+//!         let mut syst = global_p.SYST;
 //!         syst.set_clock_source(SystClkSource::Core);
 //!         syst.set_reload(8_000_000); // 1s
 //!         syst.enable_counter();
@@ -73,9 +78,9 @@
 //!             writeln!(*hstdout, "Tick").ok();
 //!         }
 //! 
-//!         let nvic = stm32f103xx::NVIC.borrow(cs);
+//!         if let Some(nvic) = NVIC.borrow(cs).borrow_mut().as_mut() {
-//! 
+//!             nvic.set_pending(Interrupt::TIM2);
-//!         nvic.set_pending(Interrupt::TIM2);
+//!         }
 //!     });
 //! }
 //! 

src/examples/_6_allocator.rs

@@ -1,6 +1,6 @@
 //! How to use the heap and a dynamic memory allocator
 //!
-//! To compile this example you'll need to build the collections crate as part
+//! 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:
 //!
@@ -8,7 +8,7 @@
 //! [dependencies.core]
 //! stage = 0
 //!
-//! [dependencies.collections] # NEW
+//! [dependencies.alloc] # NEW
 //! stage = 0
 //!
 //! [dependencies.compiler_builtins]
@@ -27,15 +27,15 @@
 //!
 //! ```
 //! 
-//! #[allow(deprecated)]
+//! #![feature(alloc)]
-//! #![feature(collections)]
 //! #![feature(used)]
+//! #![feature(global_allocator)]
 //! #![no_std]
 //! 
 //! // This is the allocator crate; you can use a different one
 //! extern crate alloc_cortex_m;
 //! #[macro_use]
-//! extern crate collections;
+//! extern crate alloc;
 //! extern crate cortex_m;
 //! extern crate cortex_m_rt;
 //! extern crate cortex_m_semihosting;
@@ -44,25 +44,21 @@
 //! 
 //! 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;
+//! }
 //! 
 //! fn main() {
 //!     // Initialize the allocator
-//!     unsafe {
+//!     let start = unsafe { &mut _sheap as *mut u32 as usize };
-//!         extern "C" {
+//!     let end = unsafe { &mut _eheap as *mut u32 as usize };
-//!             // Start of the heap
+//!     unsafe { ALLOCATOR.init(start, end - start) }
-//!             static mut _sheap: usize;
-//!         }
-//! 
-//!         // Size of the heap in words (1 word = 4 bytes)
-//!         // NOTE The bigger the heap the greater the chance to run into a stack
-//!         // overflow (collision between the stack and the heap)
-//!         const SIZE: isize = 256;
-//! 
-//!         // End of the heap
-//!         let _eheap = (&mut _sheap as *mut _).offset(SIZE);
-//! 
-//!         alloc_cortex_m::init(&mut _sheap, _eheap);
-//!     }
 //! 
 //!     // Growable array allocated on the heap
 //!     let xs = vec![0, 1, 2];

src/lib.rs

@@ -3,22 +3,22 @@
 //! # Dependencies
 //!
 //! - Nightly Rust toolchain: `rustup default nightly`
-//! - ARM linker: `sudo apt-get install binutils-arm-none-eabi`
+//! - ARM linker: `sudo apt-get install binutils-arm-none-eabi` (on Ubuntu)
 //! - Cargo `clone` subcommand: `cargo install cargo-clone`
-//! - GDB: `sudo apt-get install gdb-arm-none-eabi`
+//! - GDB: `sudo apt-get install gdb-arm-none-eabi` (on Ubuntu)
-//! - OpenOCD: `sudo apt-get install OpenOCD`
+//! - OpenOCD: `sudo apt-get install OpenOCD` (on Ubuntu)
 //! - Xargo: `cargo install xargo`
 //! - [Optional] Cargo `add` subcommand: `cargo install cargo-edit`
 //!
 //! # Usage
 //!
-//! - Clone this crate
+//! 1) Clone this crate
 //!
 //! ``` text
 //! $ cargo clone cortex-m-quickstart && cd $_
 //! ```
 //!
-//! - Change the crate name, author and version
+//! 2) Change the crate name, author and version
 //!
 //! ``` text
 //! $ edit Cargo.toml && head $_
@@ -28,11 +28,11 @@
 //! version = "0.1.0"
 //! ```
 //!
-//! - Specify the memory layout of the target device
+//! 3) Specify the memory layout of the target device
 //!
-//! (Note that some board support crates may provide this file for you (check
+//! **NOTE** board support crates sometimes provide this file for you (check the crate
-//! the crate documentation). If you are using one that does that then remove
+//! documentation). If you are using one that does then remove *both* the `memory.x` and `build.rs`
-//! *both* the `memory.x` and `build.rs` files.)
+//! files.
 //!
 //! ``` text
 //! $ edit memory.x && cat $_
@@ -44,7 +44,7 @@
 //! }
 //! ```
 //!
-//! - Optionally, set a default build target
+//! 4) Optionally, set a default build target
 //!
 //! ``` text
 //! $ cat >>.cargo/config <<'EOF'
@@ -53,35 +53,32 @@
 //! EOF
 //! ```
 //!
-//! - Very likely, depend on a device or a BSP (Board Support Package) crate.
+//! 5) Depend on a device, HAL implementation or a board support crate.
 //!
 //! ``` text
-//! # add a device crate, or
+//! $ # add a device crate, OR
-//! $ cargo add stm32f103xx
+//! $ cargo add stm32f30x
 //!
-//! # add a board support crate
+//! $ # add a HAL implementation crate, OR
-//! $ cargo add blue-pill --git https://github.com/japaric/blue-pill
+//! $ cargo add stm32f103xx-hal
+//!
+//! $ # add a board support crate
+//! $ cargo add f3
 //! ```
 //!
-//! - Write the application or start from one of the examples
+//! 6) Write the application or start from one of the examples
 //!
 //! ``` text
 //! $ rm -r src/* && cp examples/hello.rs src/main.rs
 //! ```
 //!
-//! - Disable incremental compilation. It doesn't work for embedded development.
+//! 7) Build the application
-//!   You'll hit nonsensical linker errors if you use it.
 //!
 //! ``` text
-//! $ unset CARGO_INCREMENTAL
+//! $ # NOTE this command requires `arm-none-eabi-ld` to be in $PATH
-//! ```
-//!
-//! - Build the application
-//!
-//! ``` text
-//! # NOTE this command requires `arm-none-eabi-ld` to be in $PATH
 //! $ xargo build --release
 //!
+//! $ # sanity check
 //! $ arm-none-eabi-readelf -A target/thumbv7em-none-eabihf/release/demo
 //! Attribute Section: aeabi
 //! File Attributes
@@ -104,22 +101,21 @@
 //!   Tag_ABI_FP_16bit_format: IEEE 754
 //! ```
 //!
-//! - Flash the program
+//! 8) Flash the program
 //!
 //! ``` text
-//! # Launch OpenOCD on a terminal
+//! $ # Launch OpenOCD on a terminal
 //! $ openocd -f (..)
 //! ```
 //!
 //! ``` text
-//! # Start a debug session in another terminal
+//! $ # Start a debug session in another terminal
-//! $ arm-none-eabi-gdb target/..
+//! $ 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
+//! **NOTE** As of nightly-2017-05-14 or so and cortex-m-quickstart v0.1.6 you can simply run `xargo
-//! can simply run `cargo run` or `cargo run --example $example` to build the
+//! run` or `xargo run --example $example` to build the program, *and* immediately start a debug
-//! program, and immediately start a debug session. IOW, it lets you omit the
+//! session. IOW, it lets you omit the `arm-none-eabi-gdb` command.
-//! `arm-none-eabi-gdb` command.
 //!
 //! ``` text
 //! $ cargo run --example hello
@@ -262,30 +258,6 @@
 //!
 //! Solution: Switch to the nightly toolchain with `rustup default nightly`.
 //!
-//! ## Used `CARGO_INCREMENTAL=1`
-//!
-//! Error message:
-//!
-//! ``` text
-//! $ xargo build
-//! error: linking with `arm-none-eabi-ld` failed: exit code: 1
-//!     |
-//! = note: "arm-none-eabi-ld" (..)
-//!     = note: arm-none-eabi-ld:
-//! You must specify the exception handlers.
-//!     Create a non `pub` static variable with type
-//!     `cortex_m::exception::Handlers` and place it in the
-//!     '.rodata.exceptions' section. (cf. #[link_section]). Apply the
-//!     `#[used]` attribute to the variable to make it reach the linker.
-//!     arm-none-eabi-ld:
-//! Invalid '.rodata.exceptions' section.
-//!     Make sure to place a static with type `cortex_m::exception::Handlers`
-//!     in that section (cf. #[link_section]) ONLY ONCE.
-//! ```
-//!
-//! Solution: `$ unset CARGO_INCREMENAL`. And to be on the safe side, call
-//! `cargo clean` and thrash the Xargo sysroot: `$ rm -rf ~/.xargo`
-//!
 //! ## Used `gdb` instead of `arm-none-eabi-gdb`
 //!
 //! Error message: