document workaround for "Ignoring packet error"

gdbinit: print demangled symbols by default

.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,20 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [v0.2.1] - 2017-07-14
+
+### Added
+
+- Troubleshooting documentation: how to fix the error of overwriting the
+  `.cargo/config` file when you meant to append text to it.
+
+### Changed
+
+- Xargo.toml: Changed the source of the `compiler-builtins` crate from git to
+  the `rust-src` component.
+
+- Expanded the `device` example to do some I/O.
+
 ## [v0.2.0] - 2017-07-07
 
 ### Changed
@@ -82,7 +96,8 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 - Initial release
 
-[Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.8...HEAD
+[Unreleased]: https://github.com/japaric/cortex-m-quickstart/compare/v0.2.0...HEAD
+[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
 [v0.1.6]: https://github.com/japaric/cortex-m-quickstart/compare/v0.1.5...v0.1.6

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.0"
+version = "0.2.2"
 
 [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.2"
+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

Xargo.toml

@@ -2,5 +2,5 @@
 stage = 0
 
 [dependencies.compiler_builtins]
-git = "https://github.com/rust-lang-nursery/compiler-builtins"
+features = ["mem"]
 stage = 1

examples/allocator.rs

@@ -12,7 +12,6 @@
 //! stage = 0
 //!
 //! [dependencies.compiler_builtins]
-//! git = "https://github.com/rust-lang-nursery/compiler-builtins"
 //! stage = 1
 //! ```
 //!

examples/device.rs

@@ -24,28 +24,57 @@
 //!
 //! ---
 
+#![deny(warnings)]
+#![feature(const_fn)]
 #![no_std]
 
 extern crate cortex_m;
+extern crate cortex_m_semihosting;
 #[macro_use(exception, interrupt)]
 extern crate stm32f103xx;
 
-use cortex_m::interrupt;
+use core::cell::RefCell;
+use core::fmt::Write;
+
+use cortex_m::interrupt::{self, Mutex};
+use cortex_m::peripheral::SystClkSource;
+use cortex_m_semihosting::hio::{self, HStdout};
+use stm32f103xx::Interrupt;
+
+static HSTDOUT: Mutex<RefCell<Option<HStdout>>> =
+    Mutex::new(RefCell::new(None));
 
 fn main() {
     interrupt::free(|cs| {
-        let _gpioa = stm32f103xx::GPIOA.borrow(cs);
+        let hstdout = HSTDOUT.borrow(cs);
-        // do something with GPIOA
+        if let Ok(fd) = hio::hstdout() {
+            *hstdout.borrow_mut() = Some(fd);
+        }
+
+        let nvic = stm32f103xx::NVIC.borrow(cs);
+        nvic.enable(Interrupt::TIM2);
+
+        let syst = stm32f103xx::SYST.borrow(cs);
+        syst.set_clock_source(SystClkSource::Core);
+        syst.set_reload(8_000_000); // 1s
+        syst.enable_counter();
+        syst.enable_interrupt();
     });
 }
 
-exception!(SYS_TICK, tick, locals: {
+exception!(SYS_TICK, tick);
-    ticks: u32 = 0;
-});
 
-fn tick(l: &mut SYS_TICK::Locals) {
+fn tick() {
-    l.ticks += 1;
+    interrupt::free(|cs| {
-    // ..
+        let hstdout = HSTDOUT.borrow(cs);
+        if let Some(hstdout) = hstdout.borrow_mut().as_mut() {
+            writeln!(*hstdout, "Tick").ok();
+        }
+
+        let nvic = stm32f103xx::NVIC.borrow(cs);
+
+        nvic.set_pending(Interrupt::TIM2);
+    });
 }
 
 interrupt!(TIM2, tock, locals: {
@@ -54,5 +83,11 @@ interrupt!(TIM2, tock, locals: {
 
 fn tock(l: &mut TIM2::Locals) {
     l.tocks += 1;
-    // ..
+
+    interrupt::free(|cs| {
+        let hstdout = HSTDOUT.borrow(cs);
+        if let Some(hstdout) = hstdout.borrow_mut().as_mut() {
+            writeln!(*hstdout, "Tock ({})", l.tocks).ok();
+        }
+    });
 }

src/examples/_5_device.rs

@@ -26,28 +26,57 @@
 //!
 //! ```
 //! 
+//! #![deny(warnings)]
+//! #![feature(const_fn)]
 //! #![no_std]
 //! 
 //! extern crate cortex_m;
+//! extern crate cortex_m_semihosting;
 //! #[macro_use(exception, interrupt)]
 //! extern crate stm32f103xx;
 //! 
-//! use cortex_m::interrupt;
+//! use core::cell::RefCell;
+//! use core::fmt::Write;
+//! 
+//! use cortex_m::interrupt::{self, Mutex};
+//! use cortex_m::peripheral::SystClkSource;
+//! use cortex_m_semihosting::hio::{self, HStdout};
+//! use stm32f103xx::Interrupt;
+//! 
+//! static HSTDOUT: Mutex<RefCell<Option<HStdout>>> =
+//!     Mutex::new(RefCell::new(None));
 //! 
 //! fn main() {
 //!     interrupt::free(|cs| {
-//!         let _gpioa = stm32f103xx::GPIOA.borrow(cs);
+//!         let hstdout = HSTDOUT.borrow(cs);
-//!         // do something with GPIOA
+//!         if let Ok(fd) = hio::hstdout() {
+//!             *hstdout.borrow_mut() = Some(fd);
+//!         }
+//! 
+//!         let nvic = stm32f103xx::NVIC.borrow(cs);
+//!         nvic.enable(Interrupt::TIM2);
+//! 
+//!         let syst = stm32f103xx::SYST.borrow(cs);
+//!         syst.set_clock_source(SystClkSource::Core);
+//!         syst.set_reload(8_000_000); // 1s
+//!         syst.enable_counter();
+//!         syst.enable_interrupt();
 //!     });
 //! }
 //! 
-//! exception!(SYS_TICK, tick, locals: {
+//! exception!(SYS_TICK, tick);
-//!     ticks: u32 = 0;
-//! });
 //! 
-//! fn tick(l: &mut SYS_TICK::Locals) {
+//! fn tick() {
-//!     l.ticks += 1;
+//!     interrupt::free(|cs| {
-//!     // ..
+//!         let hstdout = HSTDOUT.borrow(cs);
+//!         if let Some(hstdout) = hstdout.borrow_mut().as_mut() {
+//!             writeln!(*hstdout, "Tick").ok();
+//!         }
+//! 
+//!         let nvic = stm32f103xx::NVIC.borrow(cs);
+//! 
+//!         nvic.set_pending(Interrupt::TIM2);
+//!     });
 //! }
 //! 
 //! interrupt!(TIM2, tock, locals: {
@@ -56,7 +85,13 @@
 //! 
 //! fn tock(l: &mut TIM2::Locals) {
 //!     l.tocks += 1;
-//!     // ..
+//! 
+//!     interrupt::free(|cs| {
+//!         let hstdout = HSTDOUT.borrow(cs);
+//!         if let Some(hstdout) = hstdout.borrow_mut().as_mut() {
+//!             writeln!(*hstdout, "Tock ({})", l.tocks).ok();
+//!         }
+//!     });
 //! }
 //! ```
 // Auto-generated. Do not modify.

src/examples/_6_allocator.rs

@@ -12,7 +12,6 @@
 //! stage = 0
 //!
 //! [dependencies.compiler_builtins]
-//! git = "https://github.com/rust-lang-nursery/compiler-builtins"
 //! stage = 1
 //! ```
 //!

src/lib.rs

@@ -188,6 +188,35 @@
 //! (see [Usage] section), or call Xargo with `--target` flag:
 //! `xargo build --target thumbv7em-none-eabi`.
 //!
+//! ## Overwrote the original `.cargo/config` file
+//!
+//! Error message:
+//!
+//! ``` text
+//! error: linking with `arm-none-eabi-gcc` failed: exit code: 1
+//!   |
+//!   = note: (..)
+//! (..)
+//! (..)/crt0.o: In function `_start':
+//! (.text+0x90): undefined reference to `memset'
+//! (..)/crt0.o: In function `_start':
+//! (.text+0xd0): undefined reference to `atexit'
+//! (..)/crt0.o: In function `_start':
+//! (.text+0xd4): undefined reference to `__libc_init_array'
+//! (..)/crt0.o: In function `_start':
+//! (.text+0xe4): undefined reference to `exit'
+//! (..)/crt0.o: In function `_start':
+//! (.text+0x100): undefined reference to `__libc_fini_array'
+//! collect2: error: ld returned 1 exit status
+//! ```
+//!
+//! Solution: You probably overwrote the original `.cargo/config` instead of
+//! appending the default build target (e.g. `cat >` instead of `cat >>`). The
+//! less error prone way to fix this is to remove the `.cargo` directory, clone
+//! a new copy of the template and then copy the `.cargo` directory from that
+//! fresh template into your current project. Don't forget to *append* the
+//! default build target to `.cargo/config`.
+//!
 //! ## Called OpenOCD with wrong arguments
 //!
 //! Error message:
@@ -281,6 +310,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]