v0.2.4

gdbinit: print demangled symbols by default

.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",
 ]

.gdbinit

@@ -1,5 +1,8 @@
 target remote :3333
 
+# print demangled symbols by default
+set print asm-demangle on
+
 monitor arm semihosting enable
 
 # # send captured ITM to the file itm.fifo

CHANGELOG.md

@@ -5,6 +5,37 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [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 +127,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,7 +6,7 @@ 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.1"
+version = "0.2.4"
 
 [dependencies]
 cortex-m = "0.3.0"
@@ -14,7 +14,13 @@ cortex-m-semihosting = "0.2.0"
 
 [dependencies.cortex-m-rt]
 features = ["abort-on-panic"]
-version = "0.3.3"
+version = "0.3.12"
+
+# 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
 
 [profile.release]
 debug = true

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`
-//! - OpenOCD: `sudo apt-get install OpenOCD`
+//! - GDB: `sudo apt-get install gdb-arm-none-eabi` (on Ubuntu)
+//! - 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
-//! 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 $_
@@ -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
-//! $ cargo add stm32f103xx
+//! $ # add a device crate, OR
+//! $ cargo add stm32f30x
 //!
-//! # add a board support crate
-//! $ cargo add blue-pill --git https://github.com/japaric/blue-pill
+//! $ # add a HAL implementation crate, OR
+//! $ 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.
-//!   You'll hit nonsensical linker errors if you use it.
+//! 7) Build the application
 //!
 //! ``` text
-//! $ unset CARGO_INCREMENTAL
-//! ```
-//!
-//! - Build the application
-//!
-//! ``` text
-//! # NOTE this command requires `arm-none-eabi-ld` to be in $PATH
+//! $ # 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
-//! $ arm-none-eabi-gdb target/..
+//! $ # Start a debug session in another terminal
+//! $ 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 `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.
+//! **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.
 //!
 //! ``` 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:
@@ -310,6 +282,37 @@
 //! ```
 //!
 //! Solution: Use `arm-none-eabi-gdb target/..`
+//!
+//! # Used a named piped for `itm.fifo`
+//!
+//! Error message:
+//!
+//! ``` text
+//! $ xargo 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 `xargo 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
+//! 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]