v0.1.4

add 'used stable toolchain' sub-section to the troubleshooting section

CHANGELOG.md

@@ -5,6 +5,26 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## 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
@@ -23,6 +43,8 @@ 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.1.4...HEAD
+[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,10 +6,10 @@ 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.1.4"
 
 [dependencies]
-cortex-m = "0.2.4"
+cortex-m = "0.2.6"
 cortex-m-rt = "0.2.0"
 
 [profile.release]

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)]

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
@@ -67,9 +77,6 @@
 //! - 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
 //!
@@ -95,9 +102,149 @@
 //!   Tag_ABI_FP_16bit_format: IEEE 754
 //! ```
 //!
+//! - Flash the program
+//!
+//! ```
+//! # Launch OpenOCD on a terminal
+//! $ openocd -f (..)
+//! ```
+//!
+//! ```
+//! # Start debug session
+//! $ arm-none-eabi-gdb target/..
+//! ```
+//!
 //! # 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 `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]