v0.1.7

document how to use the heap and a dynamic allocator

.cargo/config

@@ -1,4 +1,5 @@
 [target.thumbv6m-none-eabi]
+runner = 'arm-none-eabi-gdb'
 rustflags = [
   "-C", "link-arg=-Tlink.x",
   "-C", "linker=arm-none-eabi-ld",
@@ -6,6 +7,7 @@ rustflags = [
 ]
 
 [target.thumbv7m-none-eabi]
+runner = 'arm-none-eabi-gdb'
 rustflags = [
   "-C", "link-arg=-Tlink.x",
   "-C", "linker=arm-none-eabi-ld",
@@ -13,6 +15,7 @@ rustflags = [
 ]
 
 [target.thumbv7em-none-eabi]
+runner = 'arm-none-eabi-gdb'
 rustflags = [
   "-C", "link-arg=-Tlink.x",
   "-C", "linker=arm-none-eabi-ld",
@@ -20,6 +23,7 @@ rustflags = [
 ]
 
 [target.thumbv7em-none-eabihf]
+runner = 'arm-none-eabi-gdb'
 rustflags = [
   "-C", "link-arg=-Tlink.x",
   "-C", "linker=arm-none-eabi-ld",

CHANGELOG.md

@@ -5,8 +5,75 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [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
+
+### Changed
+
+- Bumped the version of the `cortex-m-rt` dependency to v0.2.0. NOTE that the
+  instantiation steps have slightly changed, the `memory.x` file changed,
+  because of this.
+
 ## v0.1.0 - 2017-04-25
 
 - Initial release
 
-[Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.7...HEAD
+[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

@@ -1,15 +1,17 @@
 [package]
 authors = ["Jorge Aparicio <jorge@japaric.io>"]
+categories = ["embedded", "no-std"]
 description = "A template for building applications for ARM Cortex-M microcontrollers"
 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.0"
+version = "0.1.7"
 
 [dependencies]
-cortex-m = "0.2.4"
-cortex-m-rt = "0.1.3"
+cortex-m = "0.2.7"
+cortex-m-rt = "0.2.2"
 
 [profile.release]
 lto = true
+debug = true

examples/allocator.rs

@@ -0,0 +1,71 @@
+//! How to use the heap and a dynamic memory allocator
+//!
+//! To compile this example you'll need to build the collections crate as part
+//! of the Xargo sysroot. To do that change the Xargo.toml file to look like
+//! this:
+//!
+//! ``` text
+//! [dependencies.core]
+//! [dependencies.collections] # new
+//!
+//! [dependencies.compiler_builtins]
+//! features = ["mem"]
+//! git = "https://github.com/rust-lang-nursery/compiler-builtins"
+//! stage = 1
+//! ```
+//!
+//! 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(collections)]
+#![feature(used)]
+#![no_std]
+
+// This is the allocator crate; you can use a different one
+extern crate alloc_cortex_m;
+#[macro_use]
+extern crate collections;
+#[macro_use]
+extern crate cortex_m;
+extern crate cortex_m_rt;
+
+use cortex_m::asm;
+
+fn main() {
+    // Initialize the allocator
+    unsafe {
+        extern "C" {
+            // Start of the heap
+            static mut _sheap: usize;
+        }
+
+        // Size of the heap in words (1 word = 4 bytes)
+        // WARNING: 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 as *mut _, _eheap);
+    }
+
+    // Growable array allocated on the heap
+    let xs = vec![0, 1, 2];
+    hprintln!("{:?}", xs);
+}
+
+// As we are not using interrupts, we just register a dummy catch all handler
+#[allow(dead_code)]
+#[used]
+#[link_section = ".rodata.interrupts"]
+static INTERRUPTS: [extern "C" fn(); 240] = [default_handler; 240];
+
+extern "C" fn default_handler() {
+    asm::bkpt();
+}

examples/crash.rs

@@ -27,7 +27,7 @@
 //! $2 = cortex_m::exception::Exception::HardFault
 //!
 //! (gdb) # Where did we come from?
-//! (gdb) print _e
+//! (gdb) backtrace
 //! ```
 
 #![feature(used)]

gen-examples.sh

@@ -11,6 +11,7 @@ main() {
         crash
         register-interrupt-handler
         override-exception-handler
+        allocator
     )
 
     rm -rf src/examples

memory.x

@@ -1,6 +1,12 @@
 MEMORY
 {
   /* NOTE K = KiBi = 1024 bytes */
+  /* TODO Adjust these memory regions to match your device memory layout */
   FLASH : ORIGIN = 0xBAAAAAAD, LENGTH = 0K
   RAM : ORIGIN = 0xBAAAAAAD, LENGTH = 0K
 }
+
+/* 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);

src/examples/_3_crash.rs

@@ -27,7 +27,7 @@
 //! $2 = cortex_m::exception::Exception::HardFault
 //!
 //! (gdb) # Where did we come from?
-//! (gdb) print _e
+//! (gdb) backtrace
 //! ```
 //!
 //! ```

src/examples/_6_allocator.rs

@@ -0,0 +1,75 @@
+//! How to use the heap and a dynamic memory allocator
+//!
+//! To compile this example you'll need to build the collections crate as part
+//! of the Xargo sysroot. To do that change the Xargo.toml file to look like
+//! this:
+//!
+//! ``` text
+//! [dependencies.core]
+//! [dependencies.collections] # new
+//!
+//! [dependencies.compiler_builtins]
+//! features = ["mem"]
+//! git = "https://github.com/rust-lang-nursery/compiler-builtins"
+//! stage = 1
+//! ```
+//!
+//! 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(collections)]
+//! #![feature(used)]
+//! #![no_std]
+//! 
+//! // This is the allocator crate; you can use a different one
+//! extern crate alloc_cortex_m;
+//! #[macro_use]
+//! extern crate collections;
+//! #[macro_use]
+//! extern crate cortex_m;
+//! extern crate cortex_m_rt;
+//! 
+//! use cortex_m::asm;
+//! 
+//! fn main() {
+//!     // Initialize the allocator
+//!     unsafe {
+//!         extern "C" {
+//!             // Start of the heap
+//!             static mut _sheap: usize;
+//!         }
+//! 
+//!         // Size of the heap in words (1 word = 4 bytes)
+//!         // WARNING: 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 as *mut _, _eheap);
+//!     }
+//! 
+//!     // Growable array allocated on the heap
+//!     let xs = vec![0, 1, 2];
+//!     hprintln!("{:?}", xs);
+//! }
+//! 
+//! // As we are not using interrupts, we just register a dummy catch all handler
+//! #[allow(dead_code)]
+//! #[used]
+//! #[link_section = ".rodata.interrupts"]
+//! 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

@@ -6,3 +6,4 @@ pub mod _2_panic;
 pub mod _3_crash;
 pub mod _4_register_interrupt_handler;
 pub mod _5_override_exception_handler;
+pub mod _6_allocator;

src/lib.rs

@@ -1,5 +1,15 @@
 //! A template for building applications for ARM Cortex-M microcontrollers
 //!
+//! # Dependencies
+//!
+//! - Nightly Rust toolchain: `rustup default nightly`
+//! - ARM linker: `sudo apt-get install binutils-arm-none-eabi`
+//! - Cargo `clone` subcommand: `cargo install cargo-clone`
+//! - GDB: `sudo apt-get install gdb-arm-none-eabi`
+//! - OpenOCD: `sudo apt-get install OpenOCD`
+//! - Xargo: `cargo install xargo`
+//! - [Optional] Cargo `add` subcommand: `cargo install cargo-edit`
+//!
 //! # Usage
 //!
 //! - Clone this crate
@@ -20,6 +30,10 @@
 //!
 //! - 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.)
+//!
 //! ``` text
 //! $ edit memory.x && cat $_
 //! MEMORY
@@ -28,6 +42,11 @@
 //!   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);
 //! ```
 //!
 //! - Optionally, set a default build target
@@ -45,7 +64,7 @@
 //! # add a device crate, or
 //! $ cargo add stm32f30x
 //!
-//! # add a BSP crate
+//! # add a board support crate
 //! $ cargo add f3
 //! ```
 //!
@@ -55,12 +74,16 @@
 //! $ rm -r src/* && cp examples/hello.rs src/main.rs
 //! ```
 //!
+//! - Disable incremental compilation. It doesn't work for embedded development.
+//!   You'll hit nonsensical linker errors if you use it.
+//!
+//! ``` text
+//! $ unset CARGO_INCREMENTAL
+//! ```
+//!
 //! - 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
 //!
@@ -86,9 +109,183 @@
 //!   Tag_ABI_FP_16bit_format: IEEE 754
 //! ```
 //!
+//! - Flash the program
+//!
+//! ``` text
+//! # Launch OpenOCD on a terminal
+//! $ openocd -f (..)
+//! ```
+//!
+//! ``` text
+//! # Start debug session
+//! $ arm-none-eabi-gdb target/..
+//! ```
+//!
+//! **NOTE** As of nightly-2017-05-14 or so and cortex-m-quickstart v0.1.6 you
+//! can simply run `cargo run` or `cargo run --example $example` to build the
+//! program, and immediately start a debug session. IOW, it lets you omit the
+//! `arm-none-eabi-gdb` command.
+//!
+//! ``` 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
+//! $ xargo build
+//! Compiling demo v0.1.0 (file:///home/japaric/tmp/demo)
+//! error: linking with `arm-none-eabi-ld` failed: exit code: 1
+//! |
+//! = note: "arm-none-eabi-ld" "-L" (..)
+//! = note: arm-none-eabi-ld: address 0xbaaab838 of hello section `.text' is ..
+//! arm-none-eabi-ld: address 0xbaaab838 of hello section `.text' is ..
+//! arm-none-eabi-ld:
+//! Invalid '.rodata.exceptions' section.
+//! Make sure to place a static with type `cortex_m::exception::Handlers`
+//! in that section (cf. #[link_section]) ONLY ONCE.
+//! ```
+//!
+//! 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
+//! $ xargo build
+//! (..)
+//! Compiling cortex-m-semihosting v0.1.3
+//! 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`.
+//!
+//! ## 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 Cargo instead of Xargo
+//!
+//! 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 `xargo build`.
+//!
+//! ## Used the stable toolchain
+//!
+//! Error message:
+//!
+//! ``` text
+//! $ xargo build
+//! error: failed to run `rustc` to learn about target-specific information
+//!
+//! To learn more, run the command again with --verbose.
+//! ```
+//!
+//! 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:
+//!
+//! ``` 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/..`
 
 #![no_std]